chore!: remove legacy generators (#11421)

Author: anakin87

MIGRATION.md

@@ -437,3 +437,134 @@ builder = PromptBuilder(
 )
 builder.run(name="John")  # greeting renders as ""
 ```
+
+### Generators removed
+
+**What changed:** `OpenAIGenerator`, `AzureOpenAIGenerator`, `HuggingFaceAPIGenerator`, and `HuggingFaceLocalGenerator` have been removed.
+Generators living in Haystack Core Integrations will also be removed soon.
+Their chat counterparts (`OpenAIChatGenerator`, `AzureOpenAIChatGenerator`, `HuggingFaceAPIChatGenerator`, `HuggingFaceLocalChatGenerator`) are the replacement. As of Haystack 3.0, all ChatGenerators also accept a plain `str` as input, so the migration rarely requires structural changes.
+
+**Why:** Over time, Generators became shallow wrappers over the ChatGenerators, converting `str → ChatMessage → str` around the exact same model calls. All new features (tool calling, structured outputs, etc.) were introduced only in ChatGenerators, leaving the legacy classes behind. They were also a source of confusion for newcomers and an unnecessary duplication of code and tests.
+
+**How to migrate:**
+
+#### Direct usage (running a generator from Python code)
+
+Before (v2.x):
+```python
+from haystack.components.generators import OpenAIGenerator
+
+gen = OpenAIGenerator()
+result = gen.run("What is NLP?")
+text = result["replies"][0]   # str
+meta = result["meta"][0]      # dict with model metadata
+```
+
+After (v3.0):
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+
+gen = OpenAIChatGenerator()
+result = gen.run("What is NLP?")   # str input accepted directly
+reply = result["replies"][0]       # ChatMessage
+text = reply.text                  # str
+meta = reply.meta                  # dict with model metadata (now on the message)
+```
+
+#### System prompt
+
+Before (v2.x):
+```python
+from haystack.components.generators import OpenAIGenerator
+
+gen = OpenAIGenerator(system_prompt="You are concise.")
+result = gen.run("What is NLP?")
+```
+
+After (v3.0):
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.dataclasses import ChatMessage
+
+gen = OpenAIChatGenerator()
+result = gen.run([
+    ChatMessage.from_system("You are concise."),
+    ChatMessage.from_user("What is NLP?"),
+])
+```
+
+#### Pipeline usage
+
+Pipelines that connected `PromptBuilder` (output: `str`) to a legacy Generator continue to work unchanged when you swap in a ChatGenerator. The Haystack pipeline type system automatically converts `str` to `list[ChatMessage]` at the connection edge.
+
+Before (v2.x):
+```python
+from haystack.components.generators import OpenAIGenerator
+from haystack.components.builders import PromptBuilder
+
+pipeline.add_component("prompt_builder", PromptBuilder(template=prompt_template))
+pipeline.add_component("llm", OpenAIGenerator())
+pipeline.connect("prompt_builder", "llm")   # str → str
+```
+
+After (v3.0), minimal change (smart connection still works):
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders import PromptBuilder
+
+pipeline.add_component("prompt_builder", PromptBuilder(template=prompt_template))
+pipeline.add_component("llm", OpenAIChatGenerator())
+pipeline.connect("prompt_builder", "llm")   # str → list[ChatMessage], auto-converted
+```
+
+Alternatively, for an idiomatic v3 pipeline use `ChatPromptBuilder`:
+```python
+from haystack.components.generators.chat import OpenAIChatGenerator
+from haystack.components.builders import ChatPromptBuilder
+from haystack.dataclasses import ChatMessage
+
+template = [ChatMessage.from_user(prompt_template)]
+pipeline.add_component("prompt_builder", ChatPromptBuilder(template=template))
+pipeline.add_component("llm", OpenAIChatGenerator())
+pipeline.connect("prompt_builder.prompt", "llm.messages")
+```
+
+#### `meta` output socket removed
+
+Legacy Generators exposed a second output socket `meta: list[dict]`. ChatGenerators do not; per-reply metadata is embedded in each `ChatMessage.meta`. If you had a pipeline connection to `llm.meta`, remove it. `AnswerBuilder` already handles this automatically (it reads metadata from `ChatMessage.meta` when the replies are `list[ChatMessage]`).
+
+Before (v2.x):
+```python
+pipeline.connect("llm.replies", "answer_builder.replies")
+pipeline.connect("llm.meta", "answer_builder.meta")   # separate meta socket
+```
+
+After (v3.0):
+```python
+pipeline.connect("llm.replies", "answer_builder.replies")
+# no meta connection needed; AnswerBuilder reads it from ChatMessage.meta
+```
+
+### `DALLEImageGenerator` renamed to `OpenAIImageGenerator`
+
+**What changed:** `DALLEImageGenerator` has been renamed to `OpenAIImageGenerator` and moved to `haystack.components.generators.openai_image_generator`. The API and parameters are otherwise unchanged.
+
+**Why:** OpenAI retired the DALL-E model family. The new name reflects that the component works with the full OpenAI image generation API and is no longer tied to a specific model family.
+
+**How to migrate:**
+
+Before (v2.x):
+```python
+from haystack.components.generators import DALLEImageGenerator
+
+generator = DALLEImageGenerator(model="dall-e-3")
+result = generator.run("A photo of a red apple")
+```
+
+After (v3.0):
+```python
+from haystack.components.generators import OpenAIImageGenerator
+
+generator = OpenAIImageGenerator(model="gpt-image-2")
+result = generator.run("A photo of a red apple")
+```

e2e/pipelines/test_rag_pipelines_e2e.py

@@ -9,11 +9,12 @@
 
 from haystack import Document, Pipeline
 from haystack.components.builders.answer_builder import AnswerBuilder
-from haystack.components.builders.prompt_builder import PromptBuilder
+from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
 from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder
-from haystack.components.generators import OpenAIGenerator
+from haystack.components.generators.chat import OpenAIChatGenerator
 from haystack.components.retrievers.in_memory import InMemoryBM25Retriever, InMemoryEmbeddingRetriever
 from haystack.components.writers import DocumentWriter
+from haystack.dataclasses import ChatMessage
 from haystack.document_stores.in_memory import InMemoryDocumentStore
 
 
@@ -23,24 +24,21 @@
 )
 def test_bm25_rag_pipeline(tmp_path):
     # Create the RAG pipeline
-    prompt_template = """
-    Given these documents, answer the question.\nDocuments:
-    {% for doc in documents %}
-        {{ doc.content }}
-    {% endfor %}
-
-    \nQuestion: {{question}}
-    \nAnswer:
-    """
+    prompt_template = [
+        ChatMessage.from_user(
+            "Given these documents, answer the question.\nDocuments:\n"
+            "{% for doc in documents %}\n    {{ doc.content }}\n{% endfor %}\n"
+            "\nQuestion: {{question}}\nAnswer:"
+        )
+    ]
     rag_pipeline = Pipeline()
     rag_pipeline.add_component(instance=InMemoryBM25Retriever(document_store=InMemoryDocumentStore()), name="retriever")
-    rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
-    rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+    rag_pipeline.add_component(instance=ChatPromptBuilder(template=prompt_template), name="prompt_builder")
+    rag_pipeline.add_component(instance=OpenAIChatGenerator(), name="llm")
     rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
     rag_pipeline.connect("retriever", "prompt_builder.documents")
-    rag_pipeline.connect("prompt_builder", "llm")
+    rag_pipeline.connect("prompt_builder.prompt", "llm.messages")
     rag_pipeline.connect("llm.replies", "answer_builder.replies")
-    rag_pipeline.connect("llm.meta", "answer_builder.meta")
     rag_pipeline.connect("retriever", "answer_builder.documents")
 
     # Serialize the pipeline to YAML
@@ -86,30 +84,27 @@ def test_bm25_rag_pipeline(tmp_path):
 )
 def test_embedding_retrieval_rag_pipeline(tmp_path):
     # Create the RAG pipeline
-    prompt_template = """
-    Given these documents, answer the question.\nDocuments:
-    {% for doc in documents %}
-        {{ doc.content }}
-    {% endfor %}
-
-    \nQuestion: {{question}}
-    \nAnswer:
-    """
+    prompt_template = [
+        ChatMessage.from_user(
+            "Given these documents, answer the question.\nDocuments:\n"
+            "{% for doc in documents %}\n    {{ doc.content }}\n{% endfor %}\n"
+            "\nQuestion: {{question}}\nAnswer:"
+        )
+    ]
     rag_pipeline = Pipeline()
     rag_pipeline.add_component(
         instance=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"), name="text_embedder"
     )
     rag_pipeline.add_component(
         instance=InMemoryEmbeddingRetriever(document_store=InMemoryDocumentStore()), name="retriever"
     )
-    rag_pipeline.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
-    rag_pipeline.add_component(instance=OpenAIGenerator(), name="llm")
+    rag_pipeline.add_component(instance=ChatPromptBuilder(template=prompt_template), name="prompt_builder")
+    rag_pipeline.add_component(instance=OpenAIChatGenerator(), name="llm")
     rag_pipeline.add_component(instance=AnswerBuilder(), name="answer_builder")
     rag_pipeline.connect("text_embedder", "retriever")
     rag_pipeline.connect("retriever", "prompt_builder.documents")
-    rag_pipeline.connect("prompt_builder", "llm")
+    rag_pipeline.connect("prompt_builder.prompt", "llm.messages")
     rag_pipeline.connect("llm.replies", "answer_builder.replies")
-    rag_pipeline.connect("llm.meta", "answer_builder.meta")
     rag_pipeline.connect("retriever", "answer_builder.documents")
 
     # Serialize the pipeline to JSON

haystack/components/builders/prompt_builder.py

@@ -44,11 +44,11 @@ class PromptBuilder:
     #### In a Pipeline
 
     This is an example of a RAG pipeline where PromptBuilder renders a custom prompt template and fills it
-    with the contents of the retrieved documents and a query. The rendered prompt is then sent to a Generator.
+    with the contents of the retrieved documents and a query. The rendered prompt is then sent to a ChatGenerator.
     ```python
     from haystack import Pipeline, Document
     from haystack.utils import Secret
-    from haystack.components.generators import OpenAIGenerator
+    from haystack.components.generators.chat import OpenAIChatGenerator
     from haystack.components.builders.prompt_builder import PromptBuilder
 
     # in a real world use case documents could come from a retriever, web, or any other source
@@ -65,7 +65,7 @@ class PromptBuilder:
         \"\"\"
     p = Pipeline()
     p.add_component(instance=PromptBuilder(template=prompt_template), name="prompt_builder")
-    p.add_component(instance=OpenAIGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
+    p.add_component(instance=OpenAIChatGenerator(api_key=Secret.from_env_var("OPENAI_API_KEY")), name="llm")
     p.connect("prompt_builder", "llm")
 
     question = "Where does Joe live?"

haystack/components/generators/__init__.py

@@ -7,20 +7,10 @@
 
 from lazy_imports import LazyImporter
 
-_import_structure = {
-    "openai": ["OpenAIGenerator"],
-    "azure": ["AzureOpenAIGenerator"],
-    "hugging_face_local": ["HuggingFaceLocalGenerator"],
-    "hugging_face_api": ["HuggingFaceAPIGenerator"],
-    "openai_dalle": ["DALLEImageGenerator"],
-}
+_import_structure = {"openai_image_generator": ["OpenAIImageGenerator"]}
 
 if TYPE_CHECKING:
-    from .azure import AzureOpenAIGenerator as AzureOpenAIGenerator
-    from .hugging_face_api import HuggingFaceAPIGenerator as HuggingFaceAPIGenerator
-    from .hugging_face_local import HuggingFaceLocalGenerator as HuggingFaceLocalGenerator
-    from .openai import OpenAIGenerator as OpenAIGenerator
-    from .openai_dalle import DALLEImageGenerator as DALLEImageGenerator
+    from .openai_image_generator import OpenAIImageGenerator as OpenAIImageGenerator
 
 else:
     sys.modules[__name__] = LazyImporter(name=__name__, module_file=__file__, import_structure=_import_structure)