fix: better error message for llm metadata extractor (#11477)

Author: sjrl

docs-website/docs/pipeline-components/extractors/llmmetadataextractor.mdx

@@ -14,7 +14,7 @@ Extracts metadata from documents using a Large Language Model. The metadata is e
 |  |  |
 | --- | --- |
 | **Most common position in a pipeline** | After [PreProcessors](../preprocessors.mdx) in an indexing pipeline |
-| **Mandatory init variables** | `prompt`: The prompt to instruct the LLM on how to extract metadata from the document  <br /> <br />`chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object |
+| **Mandatory init variables** | `prompt`: The prompt to instruct the LLM on how to extract metadata from the document. It must contain exactly one variable, called `document`.  <br /> <br />`chat_generator`: A Chat Generator instance which represents the LLM configured to return a JSON object |
 | **Mandatory run variables** | `documents`: A list of documents |
 | **Output variables** | `documents`: A list of documents |
 | **API reference** | [Extractors](/reference/extractors-api) |
@@ -27,7 +27,7 @@ Extracts metadata from documents using a Large Language Model. The metadata is e
 
 The `LLMMetadataExtractor` extraction relies on an LLM and a prompt to perform the metadata extraction. At initialization time, it expects an LLM, a Haystack Generator, and a prompt describing the metadata extraction process.
 
-The prompt should have a variable called `document` that will point to a single document in the list of documents. So, to access the content of the document, you can use `{{ document.content }}` in the prompt.
+The prompt must have exactly one variable, called `document`, that points to a single document in the list of documents. So, to access the content of the document, you can use `{{ document.content }}` in the prompt. The component raises a `ValueError` at initialization if the prompt has no variables, more than one variable, or a variable with a different name.
 
 At runtime, it expects a list of documents and will run the LLM on each document in the list, extracting metadata from the document. The metadata will be added to the document's metadata field.
 

haystack/components/extractors/llm_metadata_extractor.py

@@ -32,8 +32,8 @@ class LLMMetadataExtractor:
 
     The metadata is extracted by providing a prompt to an LLM that generates the metadata.
 
-    This component expects as input a list of documents and a prompt. The prompt should have a variable called
-    `document` that will point to a single document in the list of documents. So to access the content of the document,
+    This component expects as input a list of documents and a prompt. The prompt must have exactly one variable, called
+    `document`, that points to a single document in the list of documents. So to access the content of the document,
     you can use `{{ document.content }}` in the prompt.
 
     The component will run the LLM on each document in the list and extract metadata from the document. The metadata
@@ -162,7 +162,9 @@ def __init__(
         """
         Initializes the LLMMetadataExtractor.
 
-        :param prompt: The prompt to be used for the LLM.
+        :param prompt: The prompt to be used for the LLM. It must contain exactly one variable, called `document`,
+            which points to a single document in the list of documents. For example, to access the content of the
+            document, use `{{ document.content }}` in the prompt.
         :param chat_generator: a ChatGenerator instance which represents the LLM. In order for the component to work,
             the LLM should be configured to return a JSON object. For example, when using the OpenAIChatGenerator, you
             should pass `{"response_format": {"type": "json_object"}}` in the `generation_kwargs`.
@@ -182,9 +184,10 @@ def __init__(
         ast = SandboxedEnvironment().parse(prompt)
         template_variables = meta.find_undeclared_variables(ast)
         variables = list(template_variables)
-        if len(variables) > 1 or variables[0] != "document":
+        if variables != ["document"]:
             raise ValueError(
-                f"Prompt must have exactly one variable called 'document'. Found {','.join(variables)} in the prompt."
+                f"Prompt must have exactly one variable called 'document'. "
+                f"Found {','.join(variables) or 'no variables'} in the prompt."
             )
         self.builder = PromptBuilder(prompt, required_variables=variables)
         self.raise_on_failure = raise_on_failure

releasenotes/notes/llm-metadata-extractor-prompt-error-a221148e1caf11bf.yaml

@@ -0,0 +1,7 @@
+---
+fixes:
+  - |
+    ``LLMMetadataExtractor`` now raises a clear ``ValueError`` when the ``prompt`` contains no
+    template variables. Previously this case raised an unhelpful ``IndexError: list index out of
+    range``. The error message now consistently explains that the prompt must contain exactly one
+    variable called ``document``.

test/components/extractors/test_llm_metadata_extractor.py

@@ -80,6 +80,20 @@ def test_init_missing_prompt_variable(self, monkeypatch):
                 prompt="prompt {{ wrong_variable }}", expected_keys=["key1", "key2"], chat_generator=chat_generator
             )
 
+    def test_init_no_prompt_variable(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-api-key")
+        chat_generator = OpenAIChatGenerator()
+
+        with pytest.raises(ValueError, match="exactly one variable called 'document'.*no variables"):
+            _ = LLMMetadataExtractor(prompt="prompt without variables", chat_generator=chat_generator)
+
+    def test_init_too_many_prompt_variables(self, monkeypatch):
+        monkeypatch.setenv("OPENAI_API_KEY", "test-api-key")
+        chat_generator = OpenAIChatGenerator()
+
+        with pytest.raises(ValueError, match="exactly one variable called 'document'"):
+            _ = LLMMetadataExtractor(prompt="prompt {{ document.content }} {{ extra }}", chat_generator=chat_generator)
+
     def test_init_fails_without_chat_generator(self, monkeypatch):
         monkeypatch.setenv("OPENAI_API_KEY", "test-api-key")
         with pytest.raises(TypeError):