chore: deprecate transformers components + update docs (#11570)

Author: anakin87

docs-website/docs/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx

@@ -17,9 +17,9 @@ Classifies the documents based on the provided labels and adds them to their met
 | **Mandatory init variables** | `model`: The name or path of a Hugging Face model for zero shot document classification  <br /> <br />`labels`: The set of possible class labels to classify each document into, for example, [`positive`, `negative`]. The labels depend on the selected model. |
 | **Mandatory run variables** | `documents`: A list of documents to classify |
 | **Output variables** | `documents`: A list of processed documents with an added `classification` metadata field |
-| **API reference** | [Classifiers](/reference/classifiers-api) |
-| **GitHub link** | https://github.com/deepset-ai/haystack/blob/main/haystack/components/classifiers/zero_shot_document_classifier.py |
-| **Package name** | `haystack-ai` |
+| **API reference** | [Transformers](/reference/integrations-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers |
+| **Package name** | `transformers-haystack` |
 
 </div>
 
@@ -42,11 +42,19 @@ Available models for the task of zero-shot-classification are:
 
 ## Usage
 
+Install the `transformers-haystack` package to use the `TransformersZeroShotDocumentClassifier`:
+
+```shell
+pip install transformers-haystack
+```
+
 ### On its own
 
 ```python
 from haystack import Document
-from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+from haystack_integrations.components.classifiers.transformers import (
+    TransformersZeroShotDocumentClassifier,
+)
 
 documents = [
     Document(id="0", content="Cats don't get teeth cavities."),
@@ -71,7 +79,9 @@ from haystack import Document
 from haystack.components.retrievers.in_memory import InMemoryBM25Retriever
 from haystack.document_stores.in_memory import InMemoryDocumentStore
 from haystack.core.pipeline import Pipeline
-from haystack.components.classifiers import TransformersZeroShotDocumentClassifier
+from haystack_integrations.components.classifiers.transformers import (
+    TransformersZeroShotDocumentClassifier,
+)
 
 documents = [
     Document(id="0", content="Today was a nice day!"),
@@ -88,8 +98,8 @@ document_classifier = TransformersZeroShotDocumentClassifier(
 document_store.write_documents(documents)
 
 pipeline = Pipeline()
-pipeline.add_component(retriever, name="retriever")
-pipeline.add_component(document_classifier, name="document_classifier")
+pipeline.add_component(name="retriever", instance=retriever)
+pipeline.add_component(name="document_classifier", instance=document_classifier)
 pipeline.connect("retriever", "document_classifier")
 
 queries = ["How was your day today?", "How was your day yesterday?"]

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

@@ -9,6 +9,12 @@ description: "This component extracts predefined entities out of a piece of text
 
 This component extracts predefined entities out of a piece of text and writes them into documents’ meta field.
 
+:::warning[Deprecated]
+
+`NamedEntityExtractor` is deprecated and will be removed in Haystack 3.0. It has moved to the `transformers-haystack` package and was renamed to `TransformersNamedEntityExtractor`. See [TransformersNamedEntityExtractor](transformersnamedentityextractor.mdx) for the updated documentation.
+
+:::
+
 <div className="key-value-table">
 
 |  |  |

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

@@ -0,0 +1,102 @@
+---
+title: "TransformersNamedEntityExtractor"
+id: transformersnamedentityextractor
+slug: "/transformersnamedentityextractor"
+description: "This component extracts predefined entities out of a piece of text and writes them into documents’ meta field."
+---
+
+# TransformersNamedEntityExtractor
+
+This component extracts predefined entities out of a piece of text and writes them into documents’ meta field.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | After the [PreProcessor](../preprocessors.mdx)  in an indexing pipeline or after a [Retriever](../retrievers.mdx)  in a query pipeline |
+| **Mandatory init variables** | `model`: Name or path of the model to use |
+| **Mandatory run variables** | `documents`: A list of documents |
+| **Output variables** | `documents`: A list of documents |
+| **API reference** | [Transformers](/reference/integrations-transformers) |
+| **GitHub link** | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers |
+| **Package name** | `transformers-haystack` |
+
+</div>
+
+## Overview
+
+`TransformersNamedEntityExtractor` looks for entities, which are spans in the text. The extractor automatically recognizes and groups them depending on their class, such as people's names, organizations, locations, and other types. The exact classes are determined by the model that you initialize the component with.
+
+`TransformersNamedEntityExtractor` takes a list of documents as input and returns a list of the same documents with their `meta` data enriched with `NamedEntityAnnotations`. A `NamedEntityAnnotation` consists of the type of the entity, the start and end of the span, and a score calculated by the model, for example: `NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.9)`.
+
+When the `TransformersNamedEntityExtractor` is initialized, you need to set a `model`. Optionally, you can set `pipeline_kwargs`, which are then passed on to the Hugging Face pipeline. You can additionally set the `device` that is used to run the component.
+
+Authentication with a Hugging Face API token is only required to access private or gated models. You can pass the token at initialization with `token`, or set the `HF_API_TOKEN` or `HF_TOKEN` environment variable.
+
+## Usage
+
+Install the `transformers-haystack` package to use the `TransformersNamedEntityExtractor`:
+
+```shell
+pip install transformers-haystack
+```
+
+The component works with any Hugging Face model that supports token classification or NER.
+
+`TransformersNamedEntityExtractor` accepts a list of `Documents` as its input. The extractor annotates the raw text in the documents and stores the annotations in the document's `meta` dictionary under the `named_entities` key.
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.extractors.transformers import (
+    TransformersNamedEntityExtractor,
+)
+
+extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
+
+documents = [
+    Document(content="My name is Clara and I live in Berkeley, California."),
+    Document(content="I'm Merlin, the happy pig!"),
+    Document(content="New York State is home to the Empire State Building."),
+]
+
+extractor.run(documents)
+print(documents)
+```
+
+Here is the example result:
+
+```python
+[Document(id=aec840d1b6c85609f4f16c3e222a5a25fd8c4c53bd981a40c1268ab9c72cee10, content: 'My name is Clara and I live in Berkeley, California.', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=11, end=16, score=0.99641764), NamedEntityAnnotation(entity='LOC', start=31, end=39, score=0.996198), NamedEntityAnnotation(entity='LOC', start=41, end=51, score=0.9990196)]}),
+Document(id=98f1dc5d0ccd9d9950cd191d1076db0f7af40c401dd7608f11c90cb3fc38c0c2, content: 'I'm Merlin, the happy pig!', meta: {'named_entities': [NamedEntityAnnotation(entity='PER', start=4, end=10, score=0.99054915)]}),
+Document(id=44948ea0eec018b33aceaaedde4616eb9e93ce075e0090ec1613fc145f84b4a9, content: 'New York State is home to the Empire State Building.', meta: {'named_entities': [NamedEntityAnnotation(entity='LOC', start=0, end=14, score=0.9989541), NamedEntityAnnotation(entity='LOC', start=30, end=51, score=0.95746297)]})]
+```
+
+### Get stored annotations
+
+This component includes the `get_stored_annotations` helper class method that allows you to retrieve the annotations stored in a `Document` transparently:
+
+```python
+from haystack.dataclasses import Document
+from haystack_integrations.components.extractors.transformers import (
+    TransformersNamedEntityExtractor,
+)
+
+extractor = TransformersNamedEntityExtractor(model="dslim/bert-base-NER")
+
+documents = [
+    Document(content="My name is Clara and I live in Berkeley, California."),
+    Document(content="I'm Merlin, the happy pig!"),
+    Document(content="New York State is home to the Empire State Building."),
+]
+
+extractor.run(documents)
+
+annotations = [
+    TransformersNamedEntityExtractor.get_stored_annotations(doc) for doc in documents
+]
+print(annotations)
+
+# If a Document doesn't contain any annotations, this returns None.
+new_doc = Document(content="In one of many possible worlds...")
+assert TransformersNamedEntityExtractor.get_stored_annotations(new_doc) is None
+```

docs-website/docs/pipeline-components/generators/huggingfacelocalchatgenerator.mdx

@@ -9,6 +9,12 @@ description: "Provides an interface for chat completion using a Hugging Face mod
 
 Provides an interface for chat completion using a Hugging Face model that runs locally.
 
+:::warning[Deprecated]
+
+`HuggingFaceLocalChatGenerator` is deprecated and will be removed in Haystack 3.0. It has moved to the `transformers-haystack` package and was renamed to `TransformersChatGenerator`. See [TransformersChatGenerator](transformerschatgenerator.mdx) for the updated documentation.
+
+:::
+
 <div className="key-value-table">
 
 |  |  |

docs-website/docs/pipeline-components/generators/transformerschatgenerator.mdx

@@ -0,0 +1,101 @@
+---
+title: "TransformersChatGenerator"
+id: transformerschatgenerator
+slug: "/transformerschatgenerator"
+description: "Provides an interface for chat completion using a Hugging Face model that runs locally."
+---
+
+# TransformersChatGenerator
+
+Provides an interface for chat completion using a Hugging Face model that runs locally.
+
+<div className="key-value-table">
+
+|  |  |
+| --- | --- |
+| **Most common position in a pipeline** | After a [ChatPromptBuilder](../builders/chatpromptbuilder.mdx)                                                         |
+| **Mandatory init variables**           | None                                                                                                          |
+| **Mandatory run variables**            | `messages`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects representing the chat or a plain string |
+| **Output variables**                   | `replies`: A list of [`ChatMessage`](../../concepts/data-classes/chatmessage.mdx) objects generated by the LLM |
+| **API reference**                      | [Transformers](/reference/integrations-transformers)                                                                |
+| **GitHub link**                        | https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/transformers |
+| **Package name** | `transformers-haystack` |
+
+</div>
+
+## Overview
+
+Keep in mind that if LLMs run locally, you may need a powerful machine to run them. This depends strongly on the model you select and its parameter count.
+
+If a string is passed to `messages`, it is converted into a list containing a single `ChatMessage` with the `user` role.
+
+Authentication with a Hugging Face API token is only required to access private or gated models. You can pass the token at initialization with `token`, or set the `HF_API_TOKEN` or `HF_TOKEN` environment variable:
+
+```python
+generator = TransformersChatGenerator(
+    token=Secret.from_token("<your-api-key>"),
+)
+```
+
+### Streaming
+
+This Generator supports [streaming](guides-to-generators/choosing-the-right-generator.mdx#streaming-support) the tokens from the LLM directly in output. To do so, pass a function to the `streaming_callback` init parameter.
+
+## Usage
+
+Install the `transformers-haystack` package to use the `TransformersChatGenerator`:
+
+```shell
+pip install transformers-haystack
+```
+
+### On its own
+
+```python
+from haystack_integrations.components.generators.transformers import (
+    TransformersChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+
+generator = TransformersChatGenerator(model="Qwen/Qwen3-0.6B")
+messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")]
+print(generator.run(messages))
+```
+
+### In a Pipeline
+
+```python
+from haystack import Pipeline
+from haystack.components.builders.prompt_builder import ChatPromptBuilder
+from haystack_integrations.components.generators.transformers import (
+    TransformersChatGenerator,
+)
+from haystack.dataclasses import ChatMessage
+from haystack.utils import Secret
+
+prompt_builder = ChatPromptBuilder()
+llm = TransformersChatGenerator(
+    model="Qwen/Qwen3-0.6B",
+    token=Secret.from_env_var("HF_API_TOKEN"),
+)
+
+pipe = Pipeline()
+pipe.add_component("prompt_builder", prompt_builder)
+pipe.add_component("llm", llm)
+pipe.connect("prompt_builder.prompt", "llm.messages")
+location = "Berlin"
+messages = [
+    ChatMessage.from_system(
+        "Always respond in German even if some input data is in other languages.",
+    ),
+    ChatMessage.from_user("Tell me about {{location}}"),
+]
+pipe.run(
+    data={
+        "prompt_builder": {
+            "template_variables": {"location": location},
+            "template": messages,
+        },
+    },
+)
+```

docs-website/docs/pipeline-components/readers/extractivereader.mdx

@@ -9,6 +9,12 @@ description: "Use this component in extractive question answering pipelines base
 
 Use this component in extractive question answering pipelines based on a query and a list of documents.
 
+:::warning[Deprecated]
+
+`ExtractiveReader` is deprecated and will be removed in Haystack 3.0. It has moved to the `transformers-haystack` package and was renamed to `TransformersExtractiveReader`. See [TransformersExtractiveReader](transformersextractivereader.mdx) for the updated documentation.
+
+:::
+
 <div className="key-value-table">
 
 |  |  |