From 51eeb696bd753d08c56f5f8fda0e38583d9601e1 Mon Sep 17 00:00:00 2001 From: Haystack Bot <73523382+HaystackBot@users.noreply.github.com> Date: Tue, 11 Nov 2025 15:43:32 +0100 Subject: [PATCH 1/9] Update unstable version to 2.21.0-rc0 (#10056) Co-authored-by: github-actions[bot] --- VERSION.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VERSION.txt b/VERSION.txt index f0ebba684f..ca6de38cbb 100644 --- a/VERSION.txt +++ b/VERSION.txt @@ -1 +1 @@ -2.20.0-rc0 +2.21.0-rc0 From bf4b7eefa4493d2f664e24548e93c2728ac95b01 Mon Sep 17 00:00:00 2001 From: Haystack Bot <73523382+HaystackBot@users.noreply.github.com> Date: Tue, 11 Nov 2025 16:03:47 +0100 Subject: [PATCH 2/9] docs: create unstable docs for Haystack 2.20 (#10057) * Create unstable docs for Haystack 2.20 * fix versions page --------- Co-authored-by: vblagoje <458335+vblagoje@users.noreply.github.com> Co-authored-by: anakin87 --- docs-website/docusaurus.config.js | 4 +- .../experimental_agents_api.md | 852 ++++++ .../experimental_chatmessage_store_api.md | 120 + .../experimental_generators_api.md | 152 ++ .../experimental_preprocessors_api.md | 154 ++ .../experiments-api/experimental_query_api.md | 144 + .../experimental_retrievers_api.md | 388 +++ .../experimental_summarizer_api.md | 198 ++ .../experimental_supercomponents_api.md | 106 + .../experimental_writers_api.md | 106 + .../haystack-api/agents_api.md | 420 +++ .../haystack-api/audio_api.md | 267 ++ .../haystack-api/builders_api.md | 556 ++++ .../haystack-api/cachings_api.md | 110 + .../haystack-api/classifiers_api.md | 262 ++ .../haystack-api/connectors_api.md | 247 ++ .../haystack-api/converters_api.md | 1633 +++++++++++ .../haystack-api/data_classes_api.md | 1331 +++++++++ .../haystack-api/document_stores_api.md | 382 +++ .../haystack-api/document_writers_api.md | 140 + .../haystack-api/embedders_api.md | 1784 ++++++++++++ .../haystack-api/evaluation_api.md | 110 + .../haystack-api/evaluators_api.md | 1296 +++++++++ .../haystack-api/extractors_api.md | 648 +++++ .../haystack-api/fetchers_api.md | 144 + .../haystack-api/generators_api.md | 2419 +++++++++++++++++ .../haystack-api/image_converters_api.md | 375 +++ .../haystack-api/joiners_api.md | 625 +++++ .../haystack-api/pipeline_api.md | 1528 +++++++++++ .../haystack-api/preprocessors_api.md | 801 ++++++ .../haystack-api/rankers_api.md | 1087 ++++++++ .../haystack-api/readers_api.md | 210 ++ .../haystack-api/retrievers_api.md | 781 ++++++ .../haystack-api/routers_api.md | 1241 +++++++++ .../haystack-api/samplers_api.md | 88 + .../haystack-api/tool_components_api.md | 324 +++ .../haystack-api/tools_api.md | 933 +++++++ .../haystack-api/utils_api.md | 1298 +++++++++ .../haystack-api/validators_api.md | 145 + .../haystack-api/websearch_api.md | 228 ++ .../version-2.20-unstable/index.mdx | 21 + .../integrations-api/aimlapi.md | 209 ++ .../integrations-api/amazon_bedrock.md | 1637 +++++++++++ .../integrations-api/amazon_sagemaker.md | 149 + .../integrations-api/anthropic.md | 465 ++++ .../integrations-api/astra.md | 388 +++ .../integrations-api/azure_ai_search.md | 307 +++ .../integrations-api/chroma.md | 699 +++++ .../integrations-api/cohere.md | 987 +++++++ .../integrations-api/deepeval.md | 193 ++ .../integrations-api/elasticsearch.md | 642 +++++ .../integrations-api/fastembed.md | 620 +++++ .../integrations-api/github.md | 687 +++++ .../integrations-api/google_ai.md | 345 +++ .../integrations-api/google_genai.md | 641 +++++ .../integrations-api/google_vertex.md | 1221 +++++++++ .../integrations-api/hanlp.md | 158 ++ .../integrations-api/jina.md | 598 ++++ .../integrations-api/langfuse.md | 485 ++++ .../integrations-api/llama_cpp.md | 83 + .../integrations-api/llama_stack.md | 137 + .../integrations-api/mcp.md | 1055 +++++++ .../integrations-api/meta_llama.md | 111 + .../integrations-api/mistral.md | 476 ++++ .../integrations-api/mongodb_atlas.md | 725 +++++ .../integrations-api/nvidia.md | 670 +++++ .../integrations-api/ollama.md | 531 ++++ .../integrations-api/openrouter.md | 129 + .../integrations-api/opensearch.md | 1079 ++++++++ .../integrations-api/optimum.md | 630 +++++ .../integrations-api/pgvector.md | 666 +++++ .../integrations-api/pinecone.md | 414 +++ .../integrations-api/qdrant.md | 1071 ++++++++ .../integrations-api/ragas.md | 96 + .../integrations-api/snowflake.md | 207 ++ .../integrations-api/stackit.md | 468 ++++ .../integrations-api/togetherai.md | 287 ++ .../integrations-api/unstructured.md | 135 + .../integrations-api/watsonx.md | 685 +++++ .../integrations-api/weaviate.md | 635 +++++ .../integrations-api/weights_and_bias.md | 271 ++ .../version-2.20-unstable-sidebars.json | 51 + docs-website/reference_versions.json | 6 +- docs-website/src/pages/versions.js | 27 +- .../_templates/component-template.mdx | 43 + .../_templates/document-store-template.mdx | 30 + .../version-2.20-unstable/concepts/agents.mdx | 205 ++ .../concepts/agents/state.mdx | 511 ++++ .../concepts/components.mdx | 61 + .../concepts/components/custom-components.mdx | 125 + .../concepts/components/supercomponents.mdx | 180 ++ .../concepts/concepts-overview.mdx | 56 + .../concepts/data-classes.mdx | 280 ++ .../concepts/data-classes/chatmessage.mdx | 335 +++ .../concepts/device-management.mdx | 122 + .../concepts/document-store.mdx | 100 + .../choosing-a-document-store.mdx | 110 + .../creating-custom-document-stores.mdx | 153 ++ .../concepts/experimental-package.mdx | 68 + .../concepts/integrations.mdx | 58 + .../concepts/jinja-templates.mdx | 58 + .../concepts/metadata-filtering.mdx | 145 + .../concepts/pipelines.mdx | 108 + .../concepts/pipelines/asyncpipeline.mdx | 136 + .../concepts/pipelines/creating-pipelines.mdx | 247 ++ .../pipelines/debugging-pipelines.mdx | 99 + .../pipelines/pipeline-breakpoints.mdx | 170 ++ .../concepts/pipelines/pipeline-templates.mdx | 108 + .../concepts/pipelines/serialization.mdx | 184 ++ .../pipelines/visualizing-pipelines.mdx | 89 + .../concepts/secret-management.mdx | 190 ++ .../development/deployment.mdx | 35 + .../development/deployment/docker.mdx | 117 + .../development/deployment/kubernetes.mdx | 269 ++ .../development/deployment/openshift.mdx | 73 + .../development/enabling-gpu-acceleration.mdx | 43 + .../external-integrations-development.mdx | 18 + .../development/hayhooks.mdx | 308 +++ .../development/logging.mdx | 90 + .../development/tracing.mdx | 324 +++ .../document-stores/astradocumentstore.mdx | 83 + .../azureaisearchdocumentstore.mdx | 66 + .../document-stores/chromadocumentstore.mdx | 95 + .../elasticsearch-document-store.mdx | 66 + .../document-stores/inmemorydocumentstore.mdx | 27 + .../mongodbatlasdocumentstore.mdx | 57 + .../opensearch-document-store.mdx | 73 + .../document-stores/pgvectordocumentstore.mdx | 77 + .../pinecone-document-store.mdx | 66 + .../document-stores/qdrant-document-store.mdx | 99 + .../document-stores/weaviatedocumentstore.mdx | 148 + .../version-2.20-unstable/intro.mdx | 31 + .../optimization/advanced-rag-techniques.mdx | 19 + .../hypothetical-document-embeddings-hyde.mdx | 107 + .../optimization/evaluation.mdx | 64 + .../evaluation/model-based-evaluation.mdx | 121 + .../evaluation/statistical-evaluation.mdx | 49 + .../overview/breaking-change-policy.mdx | 88 + .../version-2.20-unstable/overview/faq.mdx | 38 + .../overview/get-started.mdx | 111 + .../overview/installation.mdx | 77 + .../overview/migration.mdx | 487 ++++ .../overview/telemetry.mdx | 76 + .../pipeline-components/agents-1/agent.mdx | 200 ++ .../pipeline-components/audio.mdx | 15 + .../audio/external-integrations-audio.mdx | 15 + .../audio/localwhispertranscriber.mdx | 81 + .../audio/remotewhispertranscriber.mdx | 89 + .../pipeline-components/builders.mdx | 13 + .../builders/answerbuilder.mdx | 90 + .../builders/chatpromptbuilder.mdx | 359 +++ .../builders/promptbuilder.mdx | 258 ++ .../caching/cachechecker.mdx | 83 + .../pipeline-components/classifiers.mdx | 15 + .../documentlanguageclassifier.mdx | 101 + ...transformerszeroshotdocumentclassifier.mdx | 99 + .../pipeline-components/connectors.mdx | 24 + .../external-integrations-connectors.mdx | 18 + .../connectors/githubfileeditor.mdx | 104 + .../connectors/githubissuecommenter.mdx | 128 + .../connectors/githubissueviewer.mdx | 126 + .../connectors/githubprcreator.mdx | 78 + .../connectors/githubrepoforker.mdx | 70 + .../connectors/githubrepoviewer.mdx | 91 + .../connectors/jinareaderconnector.mdx | 160 ++ .../connectors/langfuseconnector.mdx | 205 ++ .../connectors/openapiconnector.mdx | 101 + .../connectors/openapiserviceconnector.mdx | 111 + .../connectors/weaveconnector.mdx | 171 ++ .../pipeline-components/converters.mdx | 35 + .../converters/azureocrdocumentconverter.mdx | 83 + .../converters/csvtodocument.mdx | 68 + .../converters/documenttoimagecontent.mdx | 146 + .../converters/docxtodocument.mdx | 75 + .../external-integrations-converters.mdx | 14 + .../converters/htmltodocument.mdx | 67 + .../converters/imagefiletodocument.mdx | 100 + .../converters/imagefiletoimagecontent.mdx | 129 + .../converters/jsonconverter.mdx | 114 + .../converters/markdowntodocument.mdx | 74 + .../mistralocrdocumentconverter.mdx | 172 ++ .../converters/msgtodocument.mdx | 74 + .../converters/multifileconverter.mdx | 79 + .../converters/openapiservicetofunctions.mdx | 109 + .../converters/outputadapter.mdx | 126 + .../converters/pdfminertodocument.mdx | 76 + .../converters/pdftoimagecontent.mdx | 117 + .../converters/pptxtodocument.mdx | 72 + .../converters/pypdftodocument.mdx | 75 + .../converters/textfiletodocument.mdx | 69 + .../converters/tikadocumentconverter.mdx | 76 + .../converters/unstructuredfileconverter.mdx | 107 + .../converters/xlsxtodocument.mdx | 73 + .../downloaders/s3downloader.mdx | 284 ++ .../pipeline-components/embedders.mdx | 59 + .../amazonbedrockdocumentembedder.mdx | 153 ++ .../amazonbedrockdocumentimageembedder.mdx | 145 + .../embedders/amazonbedrocktextembedder.mdx | 123 + .../embedders/azureopenaidocumentembedder.mdx | 118 + .../embedders/azureopenaitextembedder.mdx | 99 + .../embedders/choosing-the-right-embedder.mdx | 61 + .../embedders/coheredocumentembedder.mdx | 124 + .../embedders/coheredocumentimageembedder.mdx | 166 ++ .../embedders/coheretextembedder.mdx | 98 + .../external-integrations-embedders.mdx | 15 + .../embedders/fastembeddocumentembedder.mdx | 160 ++ .../fastembedsparsedocumentembedder.mdx | 174 ++ .../embedders/fastembedsparsetextembedder.mdx | 143 + .../embedders/fastembedtextembedder.mdx | 138 + .../embedders/googlegenaidocumentembedder.mdx | 160 ++ .../embedders/googlegenaitextembedder.mdx | 137 + .../huggingfaceapidocumentembedder.mdx | 175 ++ .../embedders/huggingfaceapitextembedder.mdx | 158 ++ .../embedders/jinadocumentembedder.mdx | 128 + .../embedders/jinadocumentimageembedder.mdx | 170 ++ .../embedders/jinatextembedder.mdx | 106 + .../embedders/mistraldocumentembedder.mdx | 100 + .../embedders/mistraltextembedder.mdx | 143 + .../embedders/nvidiadocumentembedder.mdx | 127 + .../embedders/nvidiatextembedder.mdx | 127 + .../embedders/ollamadocumentembedder.mdx | 120 + .../embedders/ollamatextembedder.mdx | 102 + .../embedders/openaidocumentembedder.mdx | 114 + .../embedders/openaitextembedder.mdx | 95 + .../embedders/optimumdocumentembedder.mdx | 107 + .../embedders/optimumtextembedder.mdx | 106 + .../sentencetransformersdocumentembedder.mdx | 132 + ...tencetransformersdocumentimageembedder.mdx | 168 ++ ...encetransformerssparsedocumentembedder.mdx | 186 ++ ...sentencetransformerssparsetextembedder.mdx | 173 ++ .../sentencetransformerstextembedder.mdx | 117 + .../embedders/stackitdocumentembedder.mdx | 101 + .../embedders/stackittextembedder.mdx | 98 + .../embedders/vertexaidocumentembedder.mdx | 107 + .../embedders/vertexaitextembedder.mdx | 107 + .../embedders/watsonxdocumentembedder.mdx | 133 + .../embedders/watsonxtextembedder.mdx | 108 + .../pipeline-components/evaluators.mdx | 21 + .../evaluators/answerexactmatchevaluator.mdx | 89 + .../evaluators/contextrelevanceevaluator.mdx | 122 + .../evaluators/deepevalevaluator.mdx | 92 + .../evaluators/documentmapevaluator.mdx | 97 + .../evaluators/documentmrrevaluator.mdx | 97 + .../evaluators/documentndcgevaluator.mdx | 83 + .../evaluators/documentrecallevaluator.mdx | 102 + .../external-integrations-evaluators.mdx | 11 + .../evaluators/faithfulnessevaluator.mdx | 122 + .../evaluators/llmevaluator.mdx | 125 + .../evaluators/ragasevaluator.mdx | 124 + .../evaluators/sasevaluator.mdx | 93 + .../pipeline-components/extractors.mdx | 13 + .../llmdocumentcontentextractor.mdx | 181 ++ .../extractors/llmmetadataextractor.mdx | 147 + .../extractors/namedentityextractor.mdx | 95 + .../pipeline-components/fetchers.mdx | 14 + .../external-integrations-fetchers.mdx | 16 + .../fetchers/linkcontentfetcher.mdx | 75 + .../pipeline-components/generators.mdx | 56 + .../generators/amazonbedrockchatgenerator.mdx | 140 + .../generators/amazonbedrockgenerator.mdx | 121 + .../generators/anthropicchatgenerator.mdx | 198 ++ .../generators/anthropicgenerator.mdx | 89 + .../anthropicvertexchatgenerator.mdx | 156 ++ .../generators/azureopenaichatgenerator.mdx | 195 ++ .../generators/azureopenaigenerator.mdx | 141 + .../generators/coherechatgenerator.mdx | 134 + .../generators/coheregenerator.mdx | 123 + .../generators/dalleimagegenerator.mdx | 97 + .../external-integrations-generators.mdx | 17 + .../generators/fallbackchatgenerator.mdx | 218 ++ .../googleaigeminichatgenerator.mdx | 170 ++ .../generators/googleaigeminigenerator.mdx | 152 ++ .../generators/googlegenaichatgenerator.mdx | 249 ++ .../choosing-the-right-generator.mdx | 180 ++ .../guides-to-generators/function-calling.mdx | 133 + .../generators-vs-chat-generators.mdx | 127 + .../huggingfaceapichatgenerator.mdx | 200 ++ .../generators/huggingfaceapigenerator.mdx | 184 ++ .../huggingfacelocalchatgenerator.mdx | 78 + .../generators/huggingfacelocalgenerator.mdx | 122 + .../generators/llamacppchatgenerator.mdx | 313 +++ .../generators/llamacppgenerator.mdx | 244 ++ .../generators/llamastackchatgenerator.mdx | 147 + .../generators/metallamachatgenerator.mdx | 199 ++ .../generators/mistralchatgenerator.mdx | 169 ++ .../generators/nvidiachatgenerator.mdx | 138 + .../generators/nvidiagenerator.mdx | 144 + .../generators/ollamachatgenerator.mdx | 236 ++ .../generators/ollamagenerator.mdx | 147 + .../generators/openaichatgenerator.mdx | 236 ++ .../generators/openaigenerator.mdx | 139 + .../generators/openrouterchatgenerator.mdx | 157 ++ .../generators/sagemakergenerator.mdx | 107 + .../generators/stackitchatgenerator.mdx | 113 + .../generators/togetheraichatgenerator.mdx | 141 + .../generators/togetheraigenerator.mdx | 148 + .../generators/vertexaicodegenerator.mdx | 99 + .../vertexaigeminichatgenerator.mdx | 170 ++ .../generators/vertexaigeminigenerator.mdx | 159 ++ .../generators/vertexaiimagecaptioner.mdx | 82 + .../generators/vertexaiimagegenerator.mdx | 76 + .../generators/vertexaiimageqa.mdx | 79 + .../generators/vertexaitextgenerator.mdx | 87 + .../generators/watsonxchatgenerator.mdx | 114 + .../generators/watsonxgenerator.mdx | 100 + .../pipeline-components/joiners.mdx | 15 + .../joiners/answerjoiner.mdx | 63 + .../joiners/branchjoiner.mdx | 203 ++ .../joiners/documentjoiner.mdx | 140 + .../joiners/listjoiner.mdx | 94 + .../joiners/stringjoiner.mdx | 52 + .../pipeline-components/preprocessors.mdx | 22 + .../preprocessors/chinesedocumentsplitter.mdx | 190 ++ .../preprocessors/csvdocumentcleaner.mdx | 86 + .../preprocessors/csvdocumentsplitter.mdx | 117 + .../preprocessors/documentcleaner.mdx | 86 + .../preprocessors/documentpreprocessor.mdx | 79 + .../preprocessors/documentsplitter.mdx | 92 + .../hierarchicaldocumentsplitter.mdx | 97 + .../preprocessors/recursivesplitter.mdx | 98 + .../preprocessors/textcleaner.mdx | 97 + .../pipeline-components/rankers.mdx | 25 + .../rankers/amazonbedrockranker.mdx | 96 + .../rankers/choosing-the-right-ranker.mdx | 60 + .../rankers/cohereranker.mdx | 98 + .../rankers/external-integrations-rankers.mdx | 14 + .../rankers/fastembedranker.mdx | 111 + .../rankers/huggingfaceteiranker.mdx | 99 + .../rankers/jinaranker.mdx | 99 + .../rankers/lostinthemiddleranker.mdx | 106 + .../rankers/metafieldgroupingranker.mdx | 121 + .../rankers/metafieldranker.mdx | 82 + .../rankers/nvidiaranker.mdx | 111 + .../sentencetransformersdiversityranker.mdx | 82 + .../sentencetransformerssimilarityranker.mdx | 107 + .../rankers/transformerssimilarityranker.mdx | 109 + .../pipeline-components/readers.mdx | 12 + .../readers/extractivereader.mdx | 99 + .../pipeline-components/retrievers.mdx | 160 ++ .../retrievers/astraretriever.mdx | 99 + .../retrievers/automergingretriever.mdx | 146 + .../retrievers/azureaisearchbm25retriever.mdx | 130 + .../azureaisearchembeddingretriever.mdx | 125 + .../azureaisearchhybridretriever.mdx | 120 + .../retrievers/chromaembeddingretriever.mdx | 101 + .../retrievers/chromaqueryretriever.mdx | 92 + .../retrievers/elasticsearchbm25retriever.mdx | 150 + .../elasticsearchembeddingretriever.mdx | 104 + .../retrievers/filterretriever.mdx | 124 + .../retrievers/inmemorybm25retriever.mdx | 141 + .../retrievers/inmemoryembeddingretriever.mdx | 69 + .../mongodbatlasembeddingretriever.mdx | 125 + .../mongodbatlasfulltextretriever.mdx | 152 ++ .../retrievers/opensearchbm25retriever.mdx | 143 + .../opensearchembeddingretriever.mdx | 108 + .../retrievers/opensearchhybridretriever.mdx | 134 + .../retrievers/pgvectorembeddingretriever.mdx | 110 + .../retrievers/pgvectorkeywordretriever.mdx | 143 + .../retrievers/pineconedenseretriever.mdx | 106 + .../retrievers/qdrantembeddingretriever.mdx | 103 + .../retrievers/qdranthybridretriever.mdx | 164 ++ .../qdrantsparseembeddingretriever.mdx | 137 + .../retrievers/sentencewindowretrieval.mdx | 81 + .../retrievers/snowflaketableretriever.mdx | 80 + .../retrievers/weaviatebm25retriever.mdx | 132 + .../retrievers/weaviateembeddingretriever.mdx | 116 + .../retrievers/weaviatehybridretriever.mdx | 161 ++ .../pipeline-components/routers.mdx | 22 + .../routers/conditionalrouter.mdx | 171 ++ .../routers/documentlengthrouter.mdx | 155 ++ .../routers/documenttyperouter.mdx | 167 ++ .../routers/filetyperouter.mdx | 67 + .../routers/llmmessagesrouter.mdx | 211 ++ .../routers/metadatarouter.mdx | 94 + .../routers/textlanguagerouter.mdx | 62 + .../routers/transformerstextrouter.mdx | 95 + .../transformerszeroshottextrouter.mdx | 116 + .../samplers/toppsampler.mdx | 124 + .../pipeline-components/tools/toolinvoker.mdx | 202 ++ .../validators/jsonschemavalidator.mdx | 78 + .../pipeline-components/websearch.mdx | 15 + .../external-integrations-websearch.mdx | 14 + .../websearch/searchapiwebsearch.mdx | 98 + .../websearch/serperdevwebsearch.mdx | 104 + .../writers/documentwriter.mdx | 87 + .../tools/componenttool.mdx | 128 + .../version-2.20-unstable/tools/mcptool.mdx | 169 ++ .../tools/mcptoolset.mdx | 135 + .../tools/pipelinetool.mdx | 196 ++ .../ready-made-tools/githubfileeditortool.mdx | 110 + .../githubissuecommentertool.mdx | 97 + .../githubissueviewertool.mdx | 105 + .../ready-made-tools/githubprcreatortool.mdx | 99 + .../ready-made-tools/githubrepoviewertool.mdx | 133 + .../version-2.20-unstable/tools/tool.mdx | 404 +++ .../version-2.20-unstable/tools/toolset.mdx | 202 ++ .../version-2.20-unstable-sidebars.json | 664 +++++ docs-website/versions.json | 5 +- 398 files changed, 82278 insertions(+), 19 deletions(-) create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_agents_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_chatmessage_store_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_generators_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_preprocessors_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_query_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_retrievers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_summarizer_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_supercomponents_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_writers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/agents_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/audio_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/builders_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/cachings_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/classifiers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/connectors_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/converters_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/data_classes_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_stores_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_writers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/embedders_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluation_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluators_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/extractors_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/fetchers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/generators_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/image_converters_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/joiners_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/pipeline_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/preprocessors_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/rankers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/readers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/retrievers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/routers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/samplers_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tool_components_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tools_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/utils_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/validators_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/websearch_api.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/index.mdx create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/aimlapi.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_bedrock.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_sagemaker.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/anthropic.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/astra.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/azure_ai_search.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/chroma.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/cohere.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/deepeval.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/elasticsearch.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/fastembed.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/github.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_ai.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_genai.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_vertex.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/hanlp.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/jina.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/langfuse.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_cpp.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_stack.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mcp.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/meta_llama.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mistral.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mongodb_atlas.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/nvidia.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ollama.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/openrouter.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/opensearch.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/optimum.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pgvector.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pinecone.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/qdrant.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ragas.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/snowflake.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/stackit.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/togetherai.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/unstructured.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/watsonx.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weaviate.md create mode 100644 docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weights_and_bias.md create mode 100644 docs-website/reference_versioned_sidebars/version-2.20-unstable-sidebars.json create mode 100644 docs-website/versioned_docs/version-2.20-unstable/_templates/component-template.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/_templates/document-store-template.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/agents.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/agents/state.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/components.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/components/custom-components.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/components/supercomponents.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/concepts-overview.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/data-classes.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/data-classes/chatmessage.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/device-management.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/choosing-a-document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/document-store/creating-custom-document-stores.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/experimental-package.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/integrations.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/jinja-templates.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/metadata-filtering.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/asyncpipeline.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/creating-pipelines.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/debugging-pipelines.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/pipeline-breakpoints.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/pipeline-templates.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/serialization.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/pipelines/visualizing-pipelines.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/concepts/secret-management.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/deployment.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/deployment/docker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/deployment/kubernetes.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/deployment/openshift.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/enabling-gpu-acceleration.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/external-integrations-development.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/hayhooks.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/logging.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/development/tracing.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/astradocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/azureaisearchdocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/chromadocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/elasticsearch-document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/inmemorydocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/mongodbatlasdocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/opensearch-document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/pgvectordocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/pinecone-document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/qdrant-document-store.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/document-stores/weaviatedocumentstore.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/intro.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/optimization/advanced-rag-techniques/hypothetical-document-embeddings-hyde.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation/model-based-evaluation.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/optimization/evaluation/statistical-evaluation.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/breaking-change-policy.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/faq.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/get-started.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/installation.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/migration.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/overview/telemetry.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/agents-1/agent.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/external-integrations-audio.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/localwhispertranscriber.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/audio/remotewhispertranscriber.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/answerbuilder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/chatpromptbuilder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/builders/promptbuilder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/caching/cachechecker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers/documentlanguageclassifier.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/classifiers/transformerszeroshotdocumentclassifier.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/external-integrations-connectors.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubfileeditor.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissuecommenter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubissueviewer.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubprcreator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoforker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/githubrepoviewer.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/jinareaderconnector.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/langfuseconnector.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiconnector.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/openapiserviceconnector.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/connectors/weaveconnector.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/azureocrdocumentconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/csvtodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/documenttoimagecontent.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/docxtodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/external-integrations-converters.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/htmltodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/imagefiletoimagecontent.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/jsonconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/markdowntodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/mistralocrdocumentconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/msgtodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/multifileconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/openapiservicetofunctions.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/outputadapter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdfminertodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pdftoimagecontent.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pptxtodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/pypdftodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/textfiletodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/tikadocumentconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/unstructuredfileconverter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/converters/xlsxtodocument.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/downloaders/s3downloader.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrockdocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrockdocumentimageembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/amazonbedrocktextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/azureopenaidocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/azureopenaitextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/choosing-the-right-embedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/coheredocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/coheredocumentimageembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/coheretextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/external-integrations-embedders.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembeddocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsedocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedsparsetextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/fastembedtextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/googlegenaidocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/googlegenaitextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/huggingfaceapidocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/huggingfaceapitextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/jinadocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/jinadocumentimageembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/jinatextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/mistraldocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/mistraltextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/nvidiadocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/nvidiatextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/ollamadocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/ollamatextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/openaidocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/openaitextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/optimumdocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/optimumtextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformersdocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformersdocumentimageembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerssparsedocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerssparsetextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/sentencetransformerstextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/stackitdocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/stackittextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaidocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/vertexaitextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/watsonxdocumentembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/embedders/watsonxtextembedder.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/answerexactmatchevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/contextrelevanceevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/deepevalevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmapevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentmrrevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentndcgevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/documentrecallevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/external-integrations-evaluators.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/faithfulnessevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/llmevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/ragasevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/evaluators/sasevaluator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmdocumentcontentextractor.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/llmmetadataextractor.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/extractors/namedentityextractor.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/external-integrations-fetchers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/fetchers/linkcontentfetcher.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/amazonbedrockgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/anthropicvertexchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/azureopenaichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/azureopenaigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/coherechatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/coheregenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/dalleimagegenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/external-integrations-generators.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/fallbackchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/googleaigeminichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/googleaigeminigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/googlegenaichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/guides-to-generators/choosing-the-right-generator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/guides-to-generators/function-calling.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/guides-to-generators/generators-vs-chat-generators.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/huggingfaceapichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/huggingfaceapigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/huggingfacelocalchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/huggingfacelocalgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamacppchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamacppgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/llamastackchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/metallamachatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/mistralchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiachatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/nvidiagenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/ollamachatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/ollamagenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openaichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openaigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/openrouterchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/sagemakergenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/stackitchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/togetheraigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaicodegenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminichatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaigeminigenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagecaptioner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimagegenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaiimageqa.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/vertexaitextgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxchatgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/generators/watsonxgenerator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/answerjoiner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/branchjoiner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/documentjoiner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/listjoiner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/joiners/stringjoiner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/chinesedocumentsplitter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentcleaner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/csvdocumentsplitter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentcleaner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentpreprocessor.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/documentsplitter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/hierarchicaldocumentsplitter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/recursivesplitter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/preprocessors/textcleaner.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/amazonbedrockranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/choosing-the-right-ranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/cohereranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/external-integrations-rankers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/fastembedranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/huggingfaceteiranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/jinaranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/lostinthemiddleranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldgroupingranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/metafieldranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/nvidiaranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/sentencetransformersdiversityranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/sentencetransformerssimilarityranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/rankers/transformerssimilarityranker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/readers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/readers/extractivereader.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/astraretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/automergingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchbm25retriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/azureaisearchhybridretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/chromaqueryretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchbm25retriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/elasticsearchembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/filterretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemorybm25retriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/inmemoryembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/mongodbatlasfulltextretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchbm25retriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/opensearchhybridretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pgvectorkeywordretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/pineconedenseretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdranthybridretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/qdrantsparseembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/sentencewindowretrieval.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/snowflaketableretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviatebm25retriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviateembeddingretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/retrievers/weaviatehybridretriever.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/conditionalrouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documentlengthrouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/documenttyperouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/filetyperouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/llmmessagesrouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/metadatarouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/textlanguagerouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerstextrouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/routers/transformerszeroshottextrouter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/samplers/toppsampler.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/tools/toolinvoker.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/validators/jsonschemavalidator.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/websearch.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/websearch/external-integrations-websearch.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/websearch/searchapiwebsearch.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/websearch/serperdevwebsearch.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/pipeline-components/writers/documentwriter.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/componenttool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/mcptool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/mcptoolset.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/pipelinetool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/ready-made-tools/githubfileeditortool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/ready-made-tools/githubissuecommentertool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/ready-made-tools/githubissueviewertool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/ready-made-tools/githubprcreatortool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/ready-made-tools/githubrepoviewertool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/tool.mdx create mode 100644 docs-website/versioned_docs/version-2.20-unstable/tools/toolset.mdx create mode 100644 docs-website/versioned_sidebars/version-2.20-unstable-sidebars.json diff --git a/docs-website/docusaurus.config.js b/docs-website/docusaurus.config.js index 4d64c8a331..29a03e7a04 100644 --- a/docs-website/docusaurus.config.js +++ b/docs-website/docusaurus.config.js @@ -48,7 +48,7 @@ const config = { beforeDefaultRemarkPlugins: [require('./src/remark/versionedReferenceLinks')], versions: { current: { - label: '2.20-unstable', + label: '2.21-unstable', path: 'next', banner: 'unreleased', }, @@ -88,7 +88,7 @@ const config = { exclude: ['**/_templates/**'], versions: { current: { - label: '2.20-unstable', + label: '2.21-unstable', path: 'next', banner: 'unreleased', }, diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_agents_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_agents_api.md new file mode 100644 index 0000000000..1a2fba201f --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_agents_api.md @@ -0,0 +1,852 @@ +--- +title: "Agents" +id: experimental-agents-api +description: "Tool-using agents with provider-agnostic chat model support." +slug: "/experimental-agents-api" +--- + + + +## Module haystack\_experimental.components.agents.agent + + + +### Agent + +A Haystack component that implements a tool-using agent with provider-agnostic chat model support. + +NOTE: This class extends Haystack's Agent component to add support for human-in-the-loop confirmation strategies. + +The component processes messages and executes tools until an exit condition is met. +The exit condition can be triggered either by a direct text response or by invoking a specific designated tool. +Multiple exit conditions can be specified. + +When you call an Agent without tools, it acts as a ChatGenerator, produces one response, then exits. + +### Usage example +```python +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.tools.tool import Tool + +from haystack_experimental.components.agents import Agent +from haystack_experimental.components.agents.human_in_the_loop import ( + HumanInTheLoopStrategy, + AlwaysAskPolicy, + NeverAskPolicy, + SimpleConsoleUI, +) + +calculator_tool = Tool(name="calculator", description="A tool for performing mathematical calculations.", ...) +search_tool = Tool(name="search", description="A tool for searching the web.", ...) + +agent = Agent( + chat_generator=OpenAIChatGenerator(), + tools=[calculator_tool, search_tool], + confirmation_strategies={ + calculator_tool.name: HumanInTheLoopStrategy( + confirmation_policy=NeverAskPolicy(), confirmation_ui=SimpleConsoleUI() + ), + search_tool.name: HumanInTheLoopStrategy( + confirmation_policy=AlwaysAskPolicy(), confirmation_ui=SimpleConsoleUI() + ), + }, +) + +# Run the agent +result = agent.run( + messages=[ChatMessage.from_user("Find information about Haystack")] +) + +assert "messages" in result # Contains conversation history +``` + + + +#### Agent.\_\_init\_\_ + +```python +def __init__(*, + chat_generator: ChatGenerator, + tools: Optional[ToolsType] = None, + system_prompt: Optional[str] = None, + exit_conditions: Optional[list[str]] = None, + state_schema: Optional[dict[str, Any]] = None, + max_agent_steps: int = 100, + streaming_callback: Optional[StreamingCallbackT] = None, + raise_on_tool_invocation_failure: bool = False, + confirmation_strategies: Optional[dict[ + str, ConfirmationStrategy]] = None, + tool_invoker_kwargs: Optional[dict[str, Any]] = None) -> None +``` + +Initialize the agent component. + +**Arguments**: + +- `chat_generator`: An instance of the chat generator that your agent should use. It must support tools. +- `tools`: List of Tool objects or a Toolset that the agent can use. +- `system_prompt`: System prompt for the agent. +- `exit_conditions`: List of conditions that will cause the agent to return. +Can include "text" if the agent should return when it generates a message without tool calls, +or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"]. +- `state_schema`: The schema for the runtime state used by the tools. +- `max_agent_steps`: Maximum number of steps the agent will run before stopping. Defaults to 100. +If the agent exceeds this number of steps, it will stop and return the current state. +- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM. +The same callback can be configured to emit tool results when a tool is called. +- `raise_on_tool_invocation_failure`: Should the agent raise an exception when a tool invocation fails? +If set to False, the exception will be turned into a chat message and passed to the LLM. +- `tool_invoker_kwargs`: Additional keyword arguments to pass to the ToolInvoker. + +**Raises**: + +- `TypeError`: If the chat_generator does not support tools parameter in its run method. +- `ValueError`: If the exit_conditions are not valid. + + + +#### Agent.run + +```python +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + break_point: Optional[AgentBreakpoint] = None, + snapshot: Optional[AgentSnapshot] = None, + system_prompt: Optional[str] = None, + tools: Optional[Union[ToolsType, list[str]]] = None, + **kwargs: Any) -> dict[str, Any] +``` + +Process messages and execute tools until an exit condition is met. + +**Arguments**: + +- `messages`: List of Haystack ChatMessage objects to process. +- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM. +The same callback can be configured to emit tool results when a tool is called. +- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint +for "tool_invoker". +- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains +the relevant information to restart the Agent execution from where it left off. +- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt. +- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run. +When passing tool names, tools are selected from the Agent's originally configured tools. +- `kwargs`: Additional data to pass to the State schema used by the Agent. +The keys must match the schema defined in the Agent's `state_schema`. + +**Raises**: + +- `RuntimeError`: If the Agent component wasn't warmed up before calling `run()`. +- `BreakpointException`: If an agent breakpoint is triggered. + +**Returns**: + +A dictionary with the following keys: +- "messages": List of all messages exchanged during the agent's run. +- "last_message": The last message exchanged during the agent's run. +- Any additional keys defined in the `state_schema`. + + + +#### Agent.run\_async + +```python +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + break_point: Optional[AgentBreakpoint] = None, + snapshot: Optional[AgentSnapshot] = None, + system_prompt: Optional[str] = None, + tools: Optional[Union[ToolsType, list[str]]] = None, + **kwargs: Any) -> dict[str, Any] +``` + +Asynchronously process messages and execute tools until the exit condition is met. + +This is the asynchronous version of the `run` method. It follows the same logic but uses +asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator +if available. + +**Arguments**: + +- `messages`: List of Haystack ChatMessage objects to process. +- `streaming_callback`: An asynchronous callback that will be invoked when a response is streamed from the +LLM. The same callback can be configured to emit tool results when a tool is called. +- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint +for "tool_invoker". +- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains +the relevant information to restart the Agent execution from where it left off. +- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt. +- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run. +- `kwargs`: Additional data to pass to the State schema used by the Agent. +The keys must match the schema defined in the Agent's `state_schema`. + +**Raises**: + +- `RuntimeError`: If the Agent component wasn't warmed up before calling `run_async()`. +- `BreakpointException`: If an agent breakpoint is triggered. + +**Returns**: + +A dictionary with the following keys: +- "messages": List of all messages exchanged during the agent's run. +- "last_message": The last message exchanged during the agent's run. +- Any additional keys defined in the `state_schema`. + + + +#### Agent.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data + + + +#### Agent.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Agent" +``` + +Deserialize the agent from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from + +**Returns**: + +Deserialized agent + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.breakpoint + + + +#### get\_tool\_calls\_and\_descriptions\_from\_snapshot + +```python +def get_tool_calls_and_descriptions_from_snapshot( + agent_snapshot: AgentSnapshot, + breakpoint_tool_only: bool = True +) -> tuple[list[dict], dict[str, str]] +``` + +Extract tool calls and tool descriptions from an AgentSnapshot. + +By default, only the tool call that caused the breakpoint is processed and its arguments are reconstructed. +This is useful for scenarios where you want to present the relevant tool call and its description +to a human for confirmation before execution. + +**Arguments**: + +- `agent_snapshot`: The AgentSnapshot from which to extract tool calls and descriptions. +- `breakpoint_tool_only`: If True, only the tool call that caused the breakpoint is returned. If False, all tool +calls are returned. + +**Returns**: + +A tuple containing a list of tool call dictionaries and a dictionary of tool descriptions + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.dataclasses + + + +### ConfirmationUIResult + +Result of the confirmation UI interaction. + +**Arguments**: + +- `action`: The action taken by the user such as "confirm", "reject", or "modify". +This action type is not enforced to allow for custom actions to be implemented. +- `feedback`: Optional feedback message from the user. For example, if the user rejects the tool execution, +they might provide a reason for the rejection. +- `new_tool_params`: Optional set of new parameters for the tool. For example, if the user chooses to modify the tool parameters, +they can provide a new set of parameters here. + + + +#### action + +"confirm", "reject", "modify" + + + +### ToolExecutionDecision + +Decision made regarding tool execution. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `execute`: A boolean indicating whether to execute the tool with the provided parameters. +- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate the decision with a +specific tool invocation. +- `feedback`: Optional feedback message. +For example, if the tool execution is rejected, this can contain the reason. Or if the tool parameters were +modified, this can contain the modification details. +- `final_tool_params`: Optional final parameters for the tool if execution is confirmed or modified. + + + +#### ToolExecutionDecision.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert the ToolExecutionDecision to a dictionary representation. + +**Returns**: + +A dictionary containing the tool execution decision details. + + + +#### ToolExecutionDecision.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ToolExecutionDecision" +``` + +Populate the ToolExecutionDecision from a dictionary representation. + +**Arguments**: + +- `data`: A dictionary containing the tool execution decision details. + +**Returns**: + +An instance of ToolExecutionDecision. + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.errors + + + +### HITLBreakpointException + +Exception raised when a tool execution is paused by a ConfirmationStrategy (e.g. BreakpointConfirmationStrategy). + + + +#### HITLBreakpointException.\_\_init\_\_ + +```python +def __init__(message: str, + tool_name: str, + snapshot_file_path: str, + tool_call_id: Optional[str] = None) -> None +``` + +Initialize the HITLBreakpointException. + +**Arguments**: + +- `message`: The exception message. +- `tool_name`: The name of the tool whose execution is paused. +- `snapshot_file_path`: The file path to the saved pipeline snapshot. +- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate +the decision with a specific tool invocation. + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.policies + + + +### AlwaysAskPolicy + +Always ask for confirmation. + + + +#### AlwaysAskPolicy.should\_ask + +```python +def should_ask(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> bool +``` + +Always ask for confirmation before executing the tool. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. + +**Returns**: + +Always returns True, indicating confirmation is needed. + + + +### NeverAskPolicy + +Never ask for confirmation. + + + +#### NeverAskPolicy.should\_ask + +```python +def should_ask(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> bool +``` + +Never ask for confirmation, always proceed with tool execution. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. + +**Returns**: + +Always returns False, indicating no confirmation is needed. + + + +### AskOncePolicy + +Ask only once per tool with specific parameters. + + + +#### AskOncePolicy.should\_ask + +```python +def should_ask(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> bool +``` + +Ask for confirmation only once per tool with specific parameters. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. + +**Returns**: + +True if confirmation is needed, False if already asked with the same parameters. + + + +#### AskOncePolicy.update\_after\_confirmation + +```python +def update_after_confirmation( + tool_name: str, tool_description: str, tool_params: dict[str, Any], + confirmation_result: ConfirmationUIResult) -> None +``` + +Store the tool and parameters if the action was "confirm" to avoid asking again. + +This method updates the internal state to remember that the user has already confirmed the execution of the +tool with the given parameters. + +**Arguments**: + +- `tool_name`: The name of the tool that was executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters that were passed to the tool. +- `confirmation_result`: The result from the confirmation UI. + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.strategies + + + +### BlockingConfirmationStrategy + +Confirmation strategy that blocks execution to gather user feedback. + + + +#### BlockingConfirmationStrategy.\_\_init\_\_ + +```python +def __init__(confirmation_policy: ConfirmationPolicy, + confirmation_ui: ConfirmationUI) -> None +``` + +Initialize the BlockingConfirmationStrategy with a confirmation policy and UI. + +**Arguments**: + +- `confirmation_policy`: The confirmation policy to determine when to ask for user confirmation. +- `confirmation_ui`: The user interface to interact with the user for confirmation. + + + +#### BlockingConfirmationStrategy.run + +```python +def run(tool_name: str, + tool_description: str, + tool_params: dict[str, Any], + tool_call_id: Optional[str] = None) -> ToolExecutionDecision +``` + +Run the human-in-the-loop strategy for a given tool and its parameters. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. +- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate the decision with a +specific tool invocation. + +**Returns**: + +A ToolExecutionDecision indicating whether to execute the tool with the given parameters, or a +feedback message if rejected. + + + +#### BlockingConfirmationStrategy.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the BlockingConfirmationStrategy to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### BlockingConfirmationStrategy.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "BlockingConfirmationStrategy" +``` + +Deserializes the BlockingConfirmationStrategy from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized BlockingConfirmationStrategy. + + + +### BreakpointConfirmationStrategy + +Confirmation strategy that raises a tool breakpoint exception to pause execution and gather user feedback. + +This strategy is designed for scenarios where immediate user interaction is not possible. +When a tool execution requires confirmation, it raises an `HITLBreakpointException`, which is caught by the Agent. +The Agent then serialize its current state, including the tool call details. This information can then be used to +notify a user to review and confirm the tool execution. + + + +#### BreakpointConfirmationStrategy.\_\_init\_\_ + +```python +def __init__(snapshot_file_path: str) -> None +``` + +Initialize the BreakpointConfirmationStrategy. + +**Arguments**: + +- `snapshot_file_path`: The path to the directory that the snapshot should be saved. + + + +#### BreakpointConfirmationStrategy.run + +```python +def run(tool_name: str, + tool_description: str, + tool_params: dict[str, Any], + tool_call_id: Optional[str] = None) -> ToolExecutionDecision +``` + +Run the breakpoint confirmation strategy for a given tool and its parameters. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. +- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate the decision with a +specific tool invocation. + +**Raises**: + +- `HITLBreakpointException`: Always raises an `HITLBreakpointException` exception to signal that user confirmation is required. + +**Returns**: + +This method does not return; it always raises an exception. + + + +#### BreakpointConfirmationStrategy.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the BreakpointConfirmationStrategy to a dictionary. + + + +#### BreakpointConfirmationStrategy.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "BreakpointConfirmationStrategy" +``` + +Deserializes the BreakpointConfirmationStrategy from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized BreakpointConfirmationStrategy. + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.types + + + +### ConfirmationUI + +Base class for confirmation UIs. + + + +#### ConfirmationUI.get\_user\_confirmation + +```python +def get_user_confirmation(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> ConfirmationUIResult +``` + +Get user confirmation for tool execution. + + + +#### ConfirmationUI.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the UI to a dictionary. + + + +#### ConfirmationUI.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ConfirmationUI" +``` + +Deserialize the ConfirmationUI from a dictionary. + + + +### ConfirmationPolicy + +Base class for confirmation policies. + + + +#### ConfirmationPolicy.should\_ask + +```python +def should_ask(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> bool +``` + +Determine whether to ask for confirmation. + + + +#### ConfirmationPolicy.update\_after\_confirmation + +```python +def update_after_confirmation( + tool_name: str, tool_description: str, tool_params: dict[str, Any], + confirmation_result: ConfirmationUIResult) -> None +``` + +Update the policy based on the confirmation UI result. + + + +#### ConfirmationPolicy.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the policy to a dictionary. + + + +#### ConfirmationPolicy.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ConfirmationPolicy" +``` + +Deserialize the policy from a dictionary. + + + +### ConfirmationStrategy + + + +#### ConfirmationStrategy.run + +```python +def run(tool_name: str, + tool_description: str, + tool_params: dict[str, Any], + tool_call_id: Optional[str] = None) -> ToolExecutionDecision +``` + +Run the confirmation strategy for a given tool and its parameters. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. +- `tool_call_id`: Optional unique identifier for the tool call. This can be used to track and correlate +the decision with a specific tool invocation. + +**Returns**: + +The result of the confirmation strategy (e.g., tool output, rejection message, etc.). + + + +#### ConfirmationStrategy.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the strategy to a dictionary. + + + +#### ConfirmationStrategy.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ConfirmationStrategy" +``` + +Deserialize the strategy from a dictionary. + + + +## Module haystack\_experimental.components.agents.human\_in\_the\_loop.user\_interfaces + + + +### RichConsoleUI + +Rich console interface for user interaction. + + + +#### RichConsoleUI.get\_user\_confirmation + +```python +def get_user_confirmation(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> ConfirmationUIResult +``` + +Get user confirmation for tool execution via rich console prompts. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. + +**Returns**: + +ConfirmationUIResult based on user input. + + + +#### RichConsoleUI.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the RichConsoleConfirmationUI to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +### SimpleConsoleUI + +Simple console interface using standard input/output. + + + +#### SimpleConsoleUI.get\_user\_confirmation + +```python +def get_user_confirmation(tool_name: str, tool_description: str, + tool_params: dict[str, Any]) -> ConfirmationUIResult +``` + +Get user confirmation for tool execution via simple console prompts. + +**Arguments**: + +- `tool_name`: The name of the tool to be executed. +- `tool_description`: The description of the tool. +- `tool_params`: The parameters to be passed to the tool. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_chatmessage_store_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_chatmessage_store_api.md new file mode 100644 index 0000000000..40e4283424 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_chatmessage_store_api.md @@ -0,0 +1,120 @@ +--- +title: "ChatMessage Store" +id: experimental-chatmessage-store-api +description: "Storage for the chat messages." +slug: "/experimental-chatmessage-store-api" +--- + + + +## Module haystack\_experimental.chat\_message\_stores.in\_memory + + + +### InMemoryChatMessageStore + +Stores chat messages in-memory. + + + +#### InMemoryChatMessageStore.\_\_init\_\_ + +```python +def __init__() +``` + +Initializes the InMemoryChatMessageStore. + + + +#### InMemoryChatMessageStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### InMemoryChatMessageStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "InMemoryChatMessageStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### InMemoryChatMessageStore.count\_messages + +```python +def count_messages() -> int +``` + +Returns the number of chat messages stored. + +**Returns**: + +The number of messages. + + + +#### InMemoryChatMessageStore.write\_messages + +```python +def write_messages(messages: List[ChatMessage]) -> int +``` + +Writes chat messages to the ChatMessageStore. + +**Arguments**: + +- `messages`: A list of ChatMessages to write. + +**Raises**: + +- `ValueError`: If messages is not a list of ChatMessages. + +**Returns**: + +The number of messages written. + + + +#### InMemoryChatMessageStore.delete\_messages + +```python +def delete_messages() -> None +``` + +Deletes all stored chat messages. + + + +#### InMemoryChatMessageStore.retrieve + +```python +def retrieve() -> List[ChatMessage] +``` + +Retrieves all stored chat messages. + +**Returns**: + +A list of chat messages. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_generators_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_generators_api.md new file mode 100644 index 0000000000..da33af41a0 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_generators_api.md @@ -0,0 +1,152 @@ +--- +title: "Generators" +id: experimental-generators-api +description: "Enables text generation using LLMs." +slug: "/experimental-generators-api" +--- + + + +## Module haystack\_experimental.components.generators.chat.openai + + + +### OpenAIChatGenerator + +An OpenAI chat-based text generator component that supports hallucination risk scoring. + +This is based on the paper +[LLMs are Bayesian, in Expectation, not in Realization](https://arxiv.org/abs/2507.11768). + +## Usage Example: + + ```python + from haystack.dataclasses import ChatMessage + + from haystack_experimental.utils.hallucination_risk_calculator.dataclasses import HallucinationScoreConfig + from haystack_experimental.components.generators.chat.openai import OpenAIChatGenerator + + # Evidence-based Example + llm = OpenAIChatGenerator(model="gpt-4o") + rag_result = llm.run( + messages=[ + ChatMessage.from_user( + text="Task: Answer strictly based on the evidence provided below. +" + "Question: Who won the Nobel Prize in Physics in 2019? +" + "Evidence: +" + "- Nobel Prize press release (2019): James Peebles (1/2); Michel Mayor & Didier Queloz (1/2). +" + "Constraints: If evidence is insufficient or conflicting, refuse." + ) + ], + hallucination_score_config=HallucinationScoreConfig(skeleton_policy="evidence_erase"), + ) + print(f"Decision: {rag_result['replies'][0].meta['hallucination_decision']}") + print(f"Risk bound: {rag_result['replies'][0].meta['hallucination_risk']:.3f}") + print(f"Rationale: {rag_result['replies'][0].meta['hallucination_rationale']}") + print(f"Answer: +{rag_result['replies'][0].text}") + print("---") + ``` + + + +#### OpenAIChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run( + messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None, + hallucination_score_config: Optional[HallucinationScoreConfig] = None +) -> dict[str, list[ChatMessage]] +``` + +Invokes chat completion based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. +- `hallucination_score_config`: If provided, the generator will evaluate the hallucination risk of its responses using +the OpenAIPlanner and annotate each response with hallucination metrics. +This involves generating multiple samples and analyzing their consistency, which may increase +latency and cost. Use this option when you need to assess the reliability of the generated content +in scenarios where accuracy is critical. +For details, see the [research paper](https://arxiv.org/abs/2507.11768) + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. If hallucination +scoring is enabled, each message will include additional metadata: + - `hallucination_decision`: "ANSWER" if the model decided to answer, "REFUSE" if it abstained. + - `hallucination_risk`: The EDFL hallucination risk bound. + - `hallucination_rationale`: The rationale behind the hallucination decision. + + + +#### OpenAIChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async( + messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None, + hallucination_score_config: Optional[HallucinationScoreConfig] = None +) -> dict[str, list[ChatMessage]] +``` + +Asynchronously invokes chat completion based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. +- `hallucination_score_config`: If provided, the generator will evaluate the hallucination risk of its responses using +the OpenAIPlanner and annotate each response with hallucination metrics. +This involves generating multiple samples and analyzing their consistency, which may increase +latency and cost. Use this option when you need to assess the reliability of the generated content +in scenarios where accuracy is critical. +For details, see the [research paper](https://arxiv.org/abs/2507.11768) + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. If hallucination +scoring is enabled, each message will include additional metadata: + - `hallucination_decision`: "ANSWER" if the model decided to answer, "REFUSE" if it abstained. + - `hallucination_risk`: The EDFL hallucination risk bound. + - `hallucination_rationale`: The rationale behind the hallucination decision. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_preprocessors_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_preprocessors_api.md new file mode 100644 index 0000000000..58434eada3 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_preprocessors_api.md @@ -0,0 +1,154 @@ +--- +title: "Preprocessors" +id: experimental-preprocessors-api +description: "Pipelines wrapped as components." +slug: "/experimental-preprocessors-api" +--- + + + +## Module haystack\_experimental.components.preprocessors.embedding\_based\_document\_splitter + + + +### EmbeddingBasedDocumentSplitter + +Splits documents based on embedding similarity using cosine distances between sequential sentence groups. + +This component first splits text into sentences, optionally groups them, calculates embeddings for each group, +and then uses cosine distance between sequential embeddings to determine split points. Any distance above +the specified percentile is treated as a break point. The component also tracks page numbers based on form feed +characters (` `) in the original document. + +This component is inspired by [5 Levels of Text Splitting]( + https://github.com/FullStackRetrieval-com/RetrievalTutorials/blob/main/tutorials/LevelsOfTextSplitting/5_Levels_Of_Text_Splitting.ipynb +) by Greg Kamradt. + +### Usage example + +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersDocumentEmbedder +from haystack_experimental.components.preprocessors import EmbeddingBasedDocumentSplitter + +# Create a document with content that has a clear topic shift +doc = Document( + content="This is a first sentence. This is a second sentence. This is a third sentence. " + "Completely different topic. The same completely different topic." +) + +# Initialize the embedder to calculate semantic similarities +embedder = SentenceTransformersDocumentEmbedder() + +# Configure the splitter with parameters that control splitting behavior +splitter = EmbeddingBasedDocumentSplitter( + document_embedder=embedder, + sentences_per_group=2, # Group 2 sentences before calculating embeddings + percentile=0.95, # Split when cosine distance exceeds 95th percentile + min_length=50, # Merge splits shorter than 50 characters + max_length=1000 # Further split chunks longer than 1000 characters +) +splitter.warm_up() +result = splitter.run(documents=[doc]) + +# The result contains a list of Document objects, each representing a semantic chunk +# Each split document includes metadata: source_id, split_id, and page_number +print(f"Original document split into {len(result['documents'])} chunks") +for i, split_doc in enumerate(result['documents']): + print(f"Chunk {i}: {split_doc.content[:50]}...") +``` + + + +#### EmbeddingBasedDocumentSplitter.\_\_init\_\_ + +```python +def __init__(*, + document_embedder: DocumentEmbedder, + sentences_per_group: int = 3, + percentile: float = 0.95, + min_length: int = 50, + max_length: int = 1000, + language: Language = "en", + use_split_rules: bool = True, + extend_abbreviations: bool = True) +``` + +Initialize EmbeddingBasedDocumentSplitter. + +**Arguments**: + +- `document_embedder`: The DocumentEmbedder to use for calculating embeddings. +- `sentences_per_group`: Number of sentences to group together before embedding. +- `percentile`: Percentile threshold for cosine distance. Distances above this percentile +are treated as break points. +- `min_length`: Minimum length of splits in characters. Splits below this length will be merged. +- `max_length`: Maximum length of splits in characters. Splits above this length will be recursively split. +- `language`: Language for sentence tokenization. +- `use_split_rules`: Whether to use additional split rules for sentence tokenization. Applies additional +split rules from SentenceSplitter to the sentence spans. +- `extend_abbreviations`: If True, the abbreviations used by NLTK's PunktTokenizer are extended by a list +of curated abbreviations. Currently supported languages are: en, de. +If False, the default abbreviations are used. + + + +#### EmbeddingBasedDocumentSplitter.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the component by initializing the sentence splitter. + + + +#### EmbeddingBasedDocumentSplitter.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Split documents based on embedding similarity. + +**Arguments**: + +- `documents`: The documents to split. + +**Raises**: + +- `None`: - `RuntimeError`: If the component wasn't warmed up. +- `TypeError`: If the input is not a list of Documents. +- `ValueError`: If the document content is None or empty. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of documents with the split texts. Each document includes: +- A metadata field `source_id` to track the original document. +- A metadata field `split_id` to track the split number. +- A metadata field `page_number` to track the original page number. +- All other metadata copied from the original document. + + + +#### EmbeddingBasedDocumentSplitter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + + + +#### EmbeddingBasedDocumentSplitter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "EmbeddingBasedDocumentSplitter" +``` + +Deserializes the component from a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_query_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_query_api.md new file mode 100644 index 0000000000..bd2ebe70e4 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_query_api.md @@ -0,0 +1,144 @@ +--- +title: "Query" +id: experimental-query-api +description: "Components for query processing and expansion." +slug: "/experimental-query-api" +--- + + + +## Module haystack\_experimental.components.query.query\_expander + + + +### QueryExpander + +A component that returns a list of semantically similar queries to improve retrieval recall in RAG systems. + +The component uses a chat generator to expand queries. The chat generator is expected to return a JSON response +with the following structure: + +### Usage example + +```json +{"queries": ["expanded query 1", "expanded query 2", "expanded query 3"]} +``` +```python +from haystack.components.generators.chat.openai import OpenAIChatGenerator +from haystack_experimental.components.query import QueryExpander + +expander = QueryExpander( + chat_generator=OpenAIChatGenerator(model="gpt-4.1-mini"), + n_expansions=3 +) + +result = expander.run(query="green energy sources") +print(result["queries"]) +# Output: ['alternative query 1', 'alternative query 2', 'alternative query 3', 'green energy sources'] +# Note: Up to 3 additional queries + 1 original query (if include_original_query=True) + +# To control total number of queries: +expander = QueryExpander(n_expansions=2, include_original_query=True) # Up to 3 total +# or +expander = QueryExpander(n_expansions=3, include_original_query=False) # Exactly 3 total +``` + + + +#### QueryExpander.\_\_init\_\_ + +```python +def __init__(*, + chat_generator: Optional[ChatGenerator] = None, + prompt_template: Optional[str] = None, + n_expansions: int = 4, + include_original_query: bool = True) +``` + +Initialize the QueryExpander component. + +**Arguments**: + +- `chat_generator`: The chat generator component to use for query expansion. +If None, a default OpenAIChatGenerator with gpt-4.1-mini model is used. +- `prompt_template`: Custom [PromptBuilder](https://docs.haystack.deepset.ai/docs/promptbuilder) +template for query expansion. The template should instruct the LLM to return a JSON response with the +structure: `{"queries": ["query1", "query2", "query3"]}`. The template should include 'query' and +'n_expansions' variables. +- `n_expansions`: Number of alternative queries to generate (default: 4). +- `include_original_query`: Whether to include the original query in the output. + + + +#### QueryExpander.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### QueryExpander.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "QueryExpander" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +Deserialized component. + + + +#### QueryExpander.run + +```python +@component.output_types(queries=List[str]) +def run(query: str, + n_expansions: Optional[int] = None) -> Dict[str, List[str]] +``` + +Expand the input query into multiple semantically similar queries. + +The language of the original query is preserved in the expanded queries. + +**Arguments**: + +- `query`: The original query to expand. +- `n_expansions`: Number of additional queries to generate (not including the original). +If None, uses the value from initialization. Can be 0 to generate no additional queries. + +**Raises**: + +- `ValueError`: If n_expansions is not positive (less than or equal to 0). +- `RuntimeError`: If the component is not warmed up and the chat generator does not support warm up. + +**Returns**: + +Dictionary with "queries" key containing the list of expanded queries. +If include_original_query=True, the original query will be included in addition +to the n_expansions alternative queries. + + + +#### QueryExpander.warm\_up + +```python +def warm_up() +``` + +Warm up the underlying LLM if it supports it. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_retrievers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_retrievers_api.md new file mode 100644 index 0000000000..9eff1f32de --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_retrievers_api.md @@ -0,0 +1,388 @@ +--- +title: "Retrievers" +id: experimental-retrievers-api +description: "Sweep through Document Stores and return a set of candidate documents that are relevant to the query." +slug: "/experimental-retrievers-api" +--- + + + +## Module haystack\_experimental.components.retrievers.chat\_message\_retriever + + + +### ChatMessageRetriever + +Retrieves chat messages from the underlying ChatMessageStore. + +Usage example: +```python +from haystack.dataclasses import ChatMessage +from haystack_experimental.components.retrievers import ChatMessageRetriever +from haystack_experimental.chat_message_stores.in_memory import InMemoryChatMessageStore + +messages = [ + ChatMessage.from_assistant("Hello, how can I help you?"), + ChatMessage.from_user("Hi, I have a question about Python. What is a Protocol?"), +] + +message_store = InMemoryChatMessageStore() +message_store.write_messages(messages) +retriever = ChatMessageRetriever(message_store) + +result = retriever.run() + +print(result["messages"]) +``` + + + +#### ChatMessageRetriever.\_\_init\_\_ + +```python +def __init__(message_store: ChatMessageStore, last_k: int = 10) +``` + +Create the ChatMessageRetriever component. + +**Arguments**: + +- `message_store`: An instance of a ChatMessageStore. +- `last_k`: The number of last messages to retrieve. Defaults to 10 messages if not specified. + + + +#### ChatMessageRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ChatMessageRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChatMessageRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### ChatMessageRetriever.run + +```python +@component.output_types(messages=List[ChatMessage]) +def run(last_k: Optional[int] = None) -> Dict[str, List[ChatMessage]] +``` + +Run the ChatMessageRetriever + +**Arguments**: + +- `last_k`: The number of last messages to retrieve. This parameter takes precedence over the last_k +parameter passed to the ChatMessageRetriever constructor. If unspecified, the last_k parameter passed +to the constructor will be used. + +**Raises**: + +- `ValueError`: If last_k is not None and is less than 1 + +**Returns**: + +- `messages` - The retrieved chat messages. + + + +## Module haystack\_experimental.components.retrievers.multi\_query\_embedding\_retriever + + + +### MultiQueryEmbeddingRetriever + +A component that retrieves documents using multiple queries in parallel with an embedding-based retriever. + +This component takes a list of text queries, converts them to embeddings using a query embedder, +and then uses an embedding-based retriever to find relevant documents for each query in parallel. +The results are combined and sorted by relevance score. + +### Usage example + +```python +from haystack import Document +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.document_stores.types import DuplicatePolicy +from haystack.components.embedders import SentenceTransformersTextEmbedder +from haystack.components.embedders import SentenceTransformersDocumentEmbedder +from haystack.components.retrievers import InMemoryEmbeddingRetriever +from haystack.components.writers import DocumentWriter +from haystack_experimental.components.retrievers import MultiQueryEmbeddingRetriever + +documents = [ + Document(content="Renewable energy is energy that is collected from renewable resources."), + Document(content="Solar energy is a type of green energy that is harnessed from the sun."), + Document(content="Wind energy is another type of green energy that is generated by wind turbines."), + Document(content="Geothermal energy is heat that comes from the sub-surface of the earth."), + Document(content="Biomass energy is produced from organic materials, such as plant and animal waste."), + Document(content="Fossil fuels, such as coal, oil, and natural gas, are non-renewable energy sources."), +] + +# Populate the document store +doc_store = InMemoryDocumentStore() +doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") +doc_embedder.warm_up() +doc_writer = DocumentWriter(document_store=doc_store, policy=DuplicatePolicy.SKIP) +documents = doc_embedder.run(documents)["documents"] +doc_writer.run(documents=documents) + +# Run the multi-query retriever +in_memory_retriever = InMemoryEmbeddingRetriever(document_store=doc_store, top_k=1) +query_embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") + +multi_query_retriever = MultiQueryEmbeddingRetriever( + retriever=in_memory_retriever, + query_embedder=query_embedder, + max_workers=3 +) + +queries = ["Geothermal energy", "natural gas", "turbines"] +result = multi_query_retriever.run(queries=queries) +for doc in result["documents"]: + print(f"Content: {doc.content}, Score: {doc.score}") +>> Content: Geothermal energy is heat that comes from the sub-surface of the earth., Score: 0.8509603046266574 +>> Content: Renewable energy is energy that is collected from renewable resources., Score: 0.42763211298893034 +>> Content: Solar energy is a type of green energy that is harnessed from the sun., Score: 0.40077417016494354 +>> Content: Fossil fuels, such as coal, oil, and natural gas, are non-renewable energy sources., Score: 0.3774863680995796 +>> Content: Wind energy is another type of green energy that is generated by wind turbines., Score: 0.3091423972562246 +>> Content: Biomass energy is produced from organic materials, such as plant and animal waste., Score: 0.25173074243668087 +``` + + + +#### MultiQueryEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + retriever: EmbeddingRetriever, + query_embedder: TextEmbedder, + max_workers: int = 3) +``` + +Initialize MultiQueryEmbeddingRetriever. + +**Arguments**: + +- `retriever`: The embedding-based retriever to use for document retrieval. +- `query_embedder`: The query embedder to convert text queries to embeddings. +- `max_workers`: Maximum number of worker threads for parallel processing. + + + +#### MultiQueryEmbeddingRetriever.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the query embedder and the retriever if any has a warm_up method. + + + +#### MultiQueryEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(queries: List[str], + retriever_kwargs: Optional[dict[str, Any]] = None) -> dict[str, Any] +``` + +Retrieve documents using multiple queries in parallel. + +**Arguments**: + +- `queries`: List of text queries to process. +- `retriever_kwargs`: Optional dictionary of arguments to pass to the retriever's run method. + +**Returns**: + +A dictionary containing: +- `documents`: List of retrieved documents sorted by relevance score. + + + +#### MultiQueryEmbeddingRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +A dictionary representing the serialized component. + + + +#### MultiQueryEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "MultiQueryEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module haystack\_experimental.components.retrievers.multi\_query\_text\_retriever + + + +### MultiQueryTextRetriever + +A component that retrieves documents using multiple queries in parallel with a text-based retriever. + +This component takes a list of text queries and uses a text-based retriever to find relevant documents for each +query in parallel, using a thread pool to manage concurrent execution. The results are combined and sorted by +relevance score. + +You can use this component in combination with QueryExpander component to enhance the retrieval process. + +### Usage example +```python +from haystack import Document +from haystack.components.writers import DocumentWriter +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.document_stores.types import DuplicatePolicy +from haystack.components.retrievers import InMemoryBM25Retriever +from haystack_experimental.components.query import QueryExpander +from haystack_experimental.components.retrievers.multi_query_text_retriever import MultiQueryTextRetriever + +documents = [ + Document(content="Renewable energy is energy that is collected from renewable resources."), + Document(content="Solar energy is a type of green energy that is harnessed from the sun."), + Document(content="Wind energy is another type of green energy that is generated by wind turbines."), + Document(content="Hydropower is a form of renewable energy using the flow of water to generate electricity."), + Document(content="Geothermal energy is heat that comes from the sub-surface of the earth.") +] + +document_store = InMemoryDocumentStore() +doc_writer = DocumentWriter(document_store=document_store, policy=DuplicatePolicy.SKIP) +doc_writer.run(documents=documents) + +in_memory_retriever = InMemoryBM25Retriever(document_store=document_store, top_k=1) +multiquery_retriever = MultiQueryTextRetriever(retriever=in_memory_retriever) +results = multiquery_retriever.run(queries=["renewable energy?", "Geothermal", "Hydropower"]) +for doc in results["documents"]: + print(f"Content: {doc.content}, Score: {doc.score}") +>> +>> Content: Geothermal energy is heat that comes from the sub-surface of the earth., Score: 1.6474448833731097 +>> Content: Hydropower is a form of renewable energy using the flow of water to generate electricity., Score: 1.6157822790079805 +>> Content: Renewable energy is energy that is collected from renewable resources., Score: 1.5255309812344944 +``` + + + +#### MultiQueryTextRetriever.\_\_init\_\_ + +```python +def __init__(retriever: TextRetriever, max_workers: int = 3) +``` + +Initialize MultiQueryTextRetriever. + +**Arguments**: + +- `retriever`: The text-based retriever to use for document retrieval. +- `max_workers`: Maximum number of worker threads for parallel processing. Default is 3. + + + +#### MultiQueryTextRetriever.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the retriever if it has a warm_up method. + + + +#### MultiQueryTextRetriever.run + +```python +@component.output_types(documents=list[Document]) +def run(queries: List[str], + retriever_kwargs: Optional[dict[str, Any]] = None) -> dict[str, Any] +``` + +Retrieve documents using multiple queries in parallel. + +**Arguments**: + +- `queries`: List of text queries to process. +- `retriever_kwargs`: Optional dictionary of arguments to pass to the retriever's run method. + +**Returns**: + +A dictionary containing: +`documents`: List of retrieved documents sorted by relevance score. + + + +#### MultiQueryTextRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### MultiQueryTextRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "MultiQueryTextRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_summarizer_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_summarizer_api.md new file mode 100644 index 0000000000..ab42a08132 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_summarizer_api.md @@ -0,0 +1,198 @@ +--- +title: "Summarizers" +id: experimental-summarizers-api +description: "Components that summarize texts into concise versions." +slug: "/experimental-summarizers-api" +--- + + + +## Module haystack\_experimental.components.summarizers.llm\_summarizer + + + +### LLMSummarizer + +Summarizes text using a language model. + +It's inspired by code from the OpenAI blog post: https://cookbook.openai.com/examples/summarizing_long_documents + +Example +```python +from haystack_experimental.components.summarizers.summarizer import Summarizer +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack import Document + +text = ("Machine learning is a subset of artificial intelligence that provides systems " + "the ability to automatically learn and improve from experience without being " + "explicitly programmed. The process of learning begins with observations or data. " + "Supervised learning algorithms build a mathematical model of sample data, known as " + "training data, in order to make predictions or decisions. Unsupervised learning " + "algorithms take a set of data that contains only inputs and find structure in the data. " + "Reinforcement learning is an area of machine learning where an agent learns to behave " + "in an environment by performing actions and seeing the results. Deep learning uses " + "artificial neural networks to model complex patterns in data. Neural networks consist " + "of layers of connected nodes, each performing a simple computation.") + +doc = Document(content=text) +chat_generator = OpenAIChatGenerator(model="gpt-4") +summarizer = Summarizer(chat_generator=chat_generator) +summarizer.run(documents=[doc]) +``` + + + +#### LLMSummarizer.\_\_init\_\_ + +```python +def __init__( + chat_generator: ChatGenerator, + system_prompt: Optional[str] = "Rewrite this text in summarized form.", + summary_detail: float = 0, + minimum_chunk_size: Optional[int] = 500, + chunk_delimiter: str = ".", + summarize_recursively: bool = False, + split_overlap: int = 0) +``` + +Initialize the Summarizer component. + +:param chat_generator: A ChatGenerator instance to use for summarization. + :param system_prompt: The prompt to instruct the LLM to summarise text, if not given defaults to: + "Rewrite this text in summarized form." + :param summary_detail: The level of detail for the summary (0-1), defaults to 0. + This parameter controls the trade-off between conciseness and completeness by adjusting how many + chunks the text is divided into. At detail=0, the text is processed as a single chunk (or very few + chunks), producing the most concise summary. At detail=1, the text is split into the maximum number + of chunks allowed by minimum_chunk_size, enabling more granular analysis and detailed summaries. + The formula uses linear interpolation: num_chunks = 1 + detail * (max_chunks - 1), where max_chunks + is determined by dividing the document length by minimum_chunk_size. + :param minimum_chunk_size: The minimum token count per chunk, defaults to 500 + :param chunk_delimiter: The character used to determine separator priority. + "." uses sentence-based splitting, " +" uses paragraph-based splitting, defaults to "." + :param summarize_recursively: Whether to use previous summaries as context, defaults to False. + :param split_overlap: Number of tokens to overlap between consecutive chunks, defaults to 0. + + + + +#### LLMSummarizer.warm\_up + +```python +def warm_up() +``` + +Warm up the chat generator and document splitter components. + + + +#### LLMSummarizer.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### LLMSummarizer.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LLMSummarizer" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +An instance of the component. + + + +#### LLMSummarizer.num\_tokens + +```python +def num_tokens(text: str) -> int +``` + +Estimates the token count for a given text. + +Uses the RecursiveDocumentSplitter's tokenization logic for consistency. + +**Arguments**: + +- `text`: The text to tokenize + +**Returns**: + +The estimated token count + + + +#### LLMSummarizer.summarize + +```python +def summarize(text: str, + detail: float, + minimum_chunk_size: int, + summarize_recursively: bool = False) -> str +``` + +Summarizes text by splitting it into optimally-sized chunks and processing each with an LLM. + +**Arguments**: + +- `text`: Text to summarize +- `detail`: Detail level (0-1) where 0 is most concise and 1 is most detailed +- `minimum_chunk_size`: Minimum token count per chunk +- `summarize_recursively`: Whether to use previous summaries as context + +**Raises**: + +- `ValueError`: If detail is not between 0 and 1 + +**Returns**: + +The textual content summarized by the LLM. + + + +#### LLMSummarizer.run + +```python +@component.output_types(summary=list[Document]) +def run(*, + documents: list[Document], + detail: Optional[float] = None, + minimum_chunk_size: Optional[int] = None, + summarize_recursively: Optional[bool] = None, + system_prompt: Optional[str] = None) -> dict[str, list[Document]] +``` + +Run the summarizer on a list of documents. + +**Arguments**: + +- `documents`: List of documents to summarize +- `detail`: The level of detail for the summary (0-1), defaults to 0 overwriting the component's default. +- `minimum_chunk_size`: The minimum token count per chunk, defaults to 500 overwriting the +component's default. +- `system_prompt`: If given it will overwrite prompt given at init time or the default one. +- `summarize_recursively`: Whether to use previous summaries as context, defaults to False overwriting the +component's default. + +**Raises**: + +- `RuntimeError`: If the component wasn't warmed up. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_supercomponents_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_supercomponents_api.md new file mode 100644 index 0000000000..a88a314d57 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_supercomponents_api.md @@ -0,0 +1,106 @@ +--- +title: "SuperComponents" +id: experimental-supercomponents-api +description: "Pipelines wrapped as components." +slug: "/experimental-supercomponents-api" +--- + + + +## Module haystack\_experimental.super\_components.indexers.sentence\_transformers\_document\_indexer + + + +### SentenceTransformersDocumentIndexer + +A document indexer that takes a list of documents, embeds them using SentenceTransformers, and stores them. + +Usage: + +```python +>>> from haystack import Document +>>> from haystack.document_stores.in_memory import InMemoryDocumentStore +>>> document_store = InMemoryDocumentStore() +>>> doc = Document(content="I love pizza!") +>>> indexer = SentenceTransformersDocumentIndexer(document_store=document_store) +>>> indexer.warm_up() +>>> result = indexer.run(documents=[doc]) +>>> print(result) +{'documents_written': 1} +>>> document_store.count_documents() +1 +``` + + + +#### SentenceTransformersDocumentIndexer.\_\_init\_\_ + +```python +def __init__( + document_store: DocumentStore, + model: str = "sentence-transformers/all-mpnet-base-v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + normalize_embeddings: bool = False, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + trust_remote_code: bool = False, + truncate_dim: Optional[int] = None, + model_kwargs: Optional[Dict[str, Any]] = None, + tokenizer_kwargs: Optional[Dict[str, Any]] = None, + config_kwargs: Optional[Dict[str, Any]] = None, + precision: Literal["float32", "int8", "uint8", "binary", + "ubinary"] = "float32", + duplicate_policy: DuplicatePolicy = DuplicatePolicy.OVERWRITE) -> None +``` + +Initialize the SentenceTransformersDocumentIndexer component. + +**Arguments**: + +- `document_store`: The document store where the documents should be stored. +- `model`: The embedding model to use (local path or Hugging Face model ID). +- `device`: The device to use for loading the model. +- `token`: The API token to download private models from Hugging Face. +- `prefix`: String to add at the beginning of each document text. +- `suffix`: String to add at the end of each document text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If True, shows a progress bar when embedding documents. +- `normalize_embeddings`: If True, embeddings are L2 normalized. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate metadata fields to document text. +- `trust_remote_code`: If True, allows custom models and scripts. +- `truncate_dim`: Dimension to truncate sentence embeddings to. +- `model_kwargs`: Additional keyword arguments for model initialization. +- `tokenizer_kwargs`: Additional keyword arguments for tokenizer initialization. +- `config_kwargs`: Additional keyword arguments for model configuration. +- `precision`: The precision to use for the embeddings. +- `duplicate_policy`: The duplicate policy to use when writing documents. + + + +#### SentenceTransformersDocumentIndexer.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this instance to a dictionary. + + + +#### SentenceTransformersDocumentIndexer.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, + Any]) -> "SentenceTransformersDocumentIndexer" +``` + +Load an instance of this component from a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_writers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_writers_api.md new file mode 100644 index 0000000000..65fee6b87d --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/experiments-api/experimental_writers_api.md @@ -0,0 +1,106 @@ +--- +title: "Writers" +id: experimental-writers-api +description: "Writers for Haystack." +slug: "/experimental-writers-api" +--- + + + +## Module haystack\_experimental.components.writers.chat\_message\_writer + + + +### ChatMessageWriter + +Writes chat messages to an underlying ChatMessageStore. + +Usage example: +```python +from haystack.dataclasses import ChatMessage +from haystack_experimental.components.writers import ChatMessageWriter +from haystack_experimental.chat_message_stores.in_memory import InMemoryChatMessageStore + +messages = [ + ChatMessage.from_assistant("Hello, how can I help you?"), + ChatMessage.from_user("I have a question about Python."), +] +message_store = InMemoryChatMessageStore() +writer = ChatMessageWriter(message_store) +writer.run(messages) +``` + + + +#### ChatMessageWriter.\_\_init\_\_ + +```python +def __init__(message_store: ChatMessageStore) +``` + +Create a ChatMessageWriter component. + +**Arguments**: + +- `message_store`: The ChatMessageStore where the chat messages are to be written. + + + +#### ChatMessageWriter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ChatMessageWriter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChatMessageWriter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Raises**: + +- `DeserializationError`: If the message store is not properly specified in the serialization data or its type cannot be imported. + +**Returns**: + +The deserialized component. + + + +#### ChatMessageWriter.run + +```python +@component.output_types(messages_written=int) +def run(messages: List[ChatMessage]) -> Dict[str, int] +``` + +Run the ChatMessageWriter on the given input data. + +**Arguments**: + +- `messages`: A list of chat messages to write to the store. + +**Raises**: + +- `ValueError`: If the specified message store is not found. + +**Returns**: + +- `messages_written`: Number of messages written to the ChatMessageStore. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/agents_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/agents_api.md new file mode 100644 index 0000000000..bb6e5751b4 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/agents_api.md @@ -0,0 +1,420 @@ +--- +title: "Agents" +id: agents-api +description: "Tool-using agents with provider-agnostic chat model support." +slug: "/agents-api" +--- + + + +## Module agent + + + +### Agent + +A Haystack component that implements a tool-using agent with provider-agnostic chat model support. + +The component processes messages and executes tools until an exit condition is met. +The exit condition can be triggered either by a direct text response or by invoking a specific designated tool. +Multiple exit conditions can be specified. + +When you call an Agent without tools, it acts as a ChatGenerator, produces one response, then exits. + +### Usage example +```python +from haystack.components.agents import Agent +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.tools import Tool + +# Tool functions - in practice, these would have real implementations +def search(query: str) -> str: + '''Search for information on the web.''' + # Placeholder: would call actual search API + return "In France, a 15% service charge is typically included, but leaving 5-10% extra is appreciated." + +def calculator(operation: str, a: float, b: float) -> float: + '''Perform mathematical calculations.''' + if operation == "multiply": + return a * b + elif operation == "percentage": + return (a / 100) * b + return 0 + +# Define tools with JSON Schema +tools = [ + Tool( + name="search", + description="Searches for information on the web", + parameters={ + "type": "object", + "properties": { + "query": {"type": "string", "description": "The search query"} + }, + "required": ["query"] + }, + function=search + ), + Tool( + name="calculator", + description="Performs mathematical calculations", + parameters={ + "type": "object", + "properties": { + "operation": {"type": "string", "description": "Operation: multiply, percentage"}, + "a": {"type": "number", "description": "First number"}, + "b": {"type": "number", "description": "Second number"} + }, + "required": ["operation", "a", "b"] + }, + function=calculator + ) +] + +# Create and run the agent +agent = Agent( + chat_generator=OpenAIChatGenerator(), + tools=tools +) + +result = agent.run( + messages=[ChatMessage.from_user("Calculate the appropriate tip for an €85 meal in France")] +) + +# The agent will: +# 1. Search for tipping customs in France +# 2. Use calculator to compute tip based on findings +# 3. Return the final answer with context +print(result["messages"][-1].text) +``` + + + +#### Agent.\_\_init\_\_ + +```python +def __init__(*, + chat_generator: ChatGenerator, + tools: Optional[ToolsType] = None, + system_prompt: Optional[str] = None, + exit_conditions: Optional[list[str]] = None, + state_schema: Optional[dict[str, Any]] = None, + max_agent_steps: int = 100, + streaming_callback: Optional[StreamingCallbackT] = None, + raise_on_tool_invocation_failure: bool = False, + tool_invoker_kwargs: Optional[dict[str, Any]] = None) -> None +``` + +Initialize the agent component. + +**Arguments**: + +- `chat_generator`: An instance of the chat generator that your agent should use. It must support tools. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset that the agent can use. +- `system_prompt`: System prompt for the agent. +- `exit_conditions`: List of conditions that will cause the agent to return. +Can include "text" if the agent should return when it generates a message without tool calls, +or tool names that will cause the agent to return once the tool was executed. Defaults to ["text"]. +- `state_schema`: The schema for the runtime state used by the tools. +- `max_agent_steps`: Maximum number of steps the agent will run before stopping. Defaults to 100. +If the agent exceeds this number of steps, it will stop and return the current state. +- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM. +The same callback can be configured to emit tool results when a tool is called. +- `raise_on_tool_invocation_failure`: Should the agent raise an exception when a tool invocation fails? +If set to False, the exception will be turned into a chat message and passed to the LLM. +- `tool_invoker_kwargs`: Additional keyword arguments to pass to the ToolInvoker. + +**Raises**: + +- `TypeError`: If the chat_generator does not support tools parameter in its run method. +- `ValueError`: If the exit_conditions are not valid. + + + +#### Agent.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the Agent. + + + +#### Agent.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data + + + +#### Agent.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Agent" +``` + +Deserialize the agent from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from + +**Returns**: + +Deserialized agent + + + +#### Agent.run + +```python +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + generation_kwargs: Optional[dict[str, Any]] = None, + break_point: Optional[AgentBreakpoint] = None, + snapshot: Optional[AgentSnapshot] = None, + system_prompt: Optional[str] = None, + tools: Optional[Union[ToolsType, list[str]]] = None, + **kwargs: Any) -> dict[str, Any] +``` + +Process messages and execute tools until an exit condition is met. + +**Arguments**: + +- `messages`: List of Haystack ChatMessage objects to process. +- `streaming_callback`: A callback that will be invoked when a response is streamed from the LLM. +The same callback can be configured to emit tool results when a tool is called. +- `generation_kwargs`: Additional keyword arguments for LLM. These parameters will +override the parameters passed during component initialization. +- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint +for "tool_invoker". +- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains +the relevant information to restart the Agent execution from where it left off. +- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt. +- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run. +When passing tool names, tools are selected from the Agent's originally configured tools. +- `kwargs`: Additional data to pass to the State schema used by the Agent. +The keys must match the schema defined in the Agent's `state_schema`. + +**Raises**: + +- `RuntimeError`: If the Agent component wasn't warmed up before calling `run()`. +- `BreakpointException`: If an agent breakpoint is triggered. + +**Returns**: + +A dictionary with the following keys: +- "messages": List of all messages exchanged during the agent's run. +- "last_message": The last message exchanged during the agent's run. +- Any additional keys defined in the `state_schema`. + + + +#### Agent.run\_async + +```python +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + generation_kwargs: Optional[dict[str, Any]] = None, + break_point: Optional[AgentBreakpoint] = None, + snapshot: Optional[AgentSnapshot] = None, + system_prompt: Optional[str] = None, + tools: Optional[Union[ToolsType, list[str]]] = None, + **kwargs: Any) -> dict[str, Any] +``` + +Asynchronously process messages and execute tools until the exit condition is met. + +This is the asynchronous version of the `run` method. It follows the same logic but uses +asynchronous operations where possible, such as calling the `run_async` method of the ChatGenerator +if available. + +**Arguments**: + +- `messages`: List of Haystack ChatMessage objects to process. +- `streaming_callback`: An asynchronous callback that will be invoked when a response is streamed from the +LLM. The same callback can be configured to emit tool results when a tool is called. +- `generation_kwargs`: Additional keyword arguments for LLM. These parameters will +override the parameters passed during component initialization. +- `break_point`: An AgentBreakpoint, can be a Breakpoint for the "chat_generator" or a ToolBreakpoint +for "tool_invoker". +- `snapshot`: A dictionary containing a snapshot of a previously saved agent execution. The snapshot contains +the relevant information to restart the Agent execution from where it left off. +- `system_prompt`: System prompt for the agent. If provided, it overrides the default system prompt. +- `tools`: Optional list of Tool objects, a Toolset, or list of tool names to use for this run. +- `kwargs`: Additional data to pass to the State schema used by the Agent. +The keys must match the schema defined in the Agent's `state_schema`. + +**Raises**: + +- `RuntimeError`: If the Agent component wasn't warmed up before calling `run_async()`. +- `BreakpointException`: If an agent breakpoint is triggered. + +**Returns**: + +A dictionary with the following keys: +- "messages": List of all messages exchanged during the agent's run. +- "last_message": The last message exchanged during the agent's run. +- Any additional keys defined in the `state_schema`. + + + +## Module state/state + + + +### State + +State is a container for storing shared information during the execution of an Agent and its tools. + +For instance, State can be used to store documents, context, and intermediate results. + +Internally it wraps a `_data` dictionary defined by a `schema`. Each schema entry has: +```json + "parameter_name": { + "type": SomeType, # expected type + "handler": Optional[Callable[[Any, Any], Any]] # merge/update function + } + ``` + +Handlers control how values are merged when using the `set()` method: +- For list types: defaults to `merge_lists` (concatenates lists) +- For other types: defaults to `replace_values` (overwrites existing value) + +A `messages` field with type `list[ChatMessage]` is automatically added to the schema. + +This makes it possible for the Agent to read from and write to the same context. + +### Usage example +```python +from haystack.components.agents.state import State + +my_state = State( + schema={"gh_repo_name": {"type": str}, "user_name": {"type": str}}, + data={"gh_repo_name": "my_repo", "user_name": "my_user_name"} +) +``` + + + +#### State.\_\_init\_\_ + +```python +def __init__(schema: dict[str, Any], data: Optional[dict[str, Any]] = None) +``` + +Initialize a State object with a schema and optional data. + +**Arguments**: + +- `schema`: Dictionary mapping parameter names to their type and handler configs. +Type must be a valid Python type, and handler must be a callable function or None. +If handler is None, the default handler for the type will be used. The default handlers are: + - For list types: `haystack.agents.state.state_utils.merge_lists` + - For all other types: `haystack.agents.state.state_utils.replace_values` +- `data`: Optional dictionary of initial data to populate the state + + + +#### State.get + +```python +def get(key: str, default: Any = None) -> Any +``` + +Retrieve a value from the state by key. + +**Arguments**: + +- `key`: Key to look up in the state +- `default`: Value to return if key is not found + +**Returns**: + +Value associated with key or default if not found + + + +#### State.set + +```python +def set(key: str, + value: Any, + handler_override: Optional[Callable[[Any, Any], Any]] = None) -> None +``` + +Set or merge a value in the state according to schema rules. + +Value is merged or overwritten according to these rules: + - if handler_override is given, use that + - else use the handler defined in the schema for 'key' + +**Arguments**: + +- `key`: Key to store the value under +- `value`: Value to store or merge +- `handler_override`: Optional function to override the default merge behavior + + + +#### State.data + +```python +@property +def data() +``` + +All current data of the state. + + + +#### State.has + +```python +def has(key: str) -> bool +``` + +Check if a key exists in the state. + +**Arguments**: + +- `key`: Key to check for existence + +**Returns**: + +True if key exists in state, False otherwise + + + +#### State.to\_dict + +```python +def to_dict() +``` + +Convert the State object to a dictionary. + + + +#### State.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) +``` + +Convert a dictionary back to a State object. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/audio_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/audio_api.md new file mode 100644 index 0000000000..6a44c02d79 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/audio_api.md @@ -0,0 +1,267 @@ +--- +title: "Audio" +id: audio-api +description: "Transcribes audio files." +slug: "/audio-api" +--- + + + +## Module whisper\_local + + + +### LocalWhisperTranscriber + +Transcribes audio files using OpenAI's Whisper model on your local machine. + +For the supported audio formats, languages, and other parameters, see the +[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper +[GitHub repository](https://github.com/openai/whisper). + +### Usage example + +```python +from haystack.components.audio import LocalWhisperTranscriber + +whisper = LocalWhisperTranscriber(model="small") +whisper.warm_up() +transcription = whisper.run(sources=["path/to/audio/file"]) +``` + + + +#### LocalWhisperTranscriber.\_\_init\_\_ + +```python +def __init__(model: WhisperLocalModel = "large", + device: Optional[ComponentDevice] = None, + whisper_params: Optional[dict[str, Any]] = None) +``` + +Creates an instance of the LocalWhisperTranscriber component. + +**Arguments**: + +- `model`: The name of the model to use. Set to one of the following models: +"tiny", "base", "small", "medium", "large" (default). +For details on the models and their modifications, see the +[Whisper documentation](https://github.com/openai/whisper?tab=readme-ov-file#available-models-and-languages). +- `device`: The device for loading the model. If `None`, automatically selects the default device. + + + +#### LocalWhisperTranscriber.warm\_up + +```python +def warm_up() -> None +``` + +Loads the model in memory. + + + +#### LocalWhisperTranscriber.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### LocalWhisperTranscriber.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LocalWhisperTranscriber" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### LocalWhisperTranscriber.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + whisper_params: Optional[dict[str, Any]] = None) +``` + +Transcribes a list of audio files into a list of documents. + +**Arguments**: + +- `sources`: A list of paths or binary streams to transcribe. +- `whisper_params`: For the supported audio formats, languages, and other parameters, see the +[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper +[GitHup repo](https://github.com/openai/whisper). + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents where each document is a transcribed audio file. The content of +the document is the transcription text, and the document's metadata contains the values returned by +the Whisper model, such as the alignment data and the path to the audio file used +for the transcription. + + + +#### LocalWhisperTranscriber.transcribe + +```python +def transcribe(sources: list[Union[str, Path, ByteStream]], + **kwargs) -> list[Document] +``` + +Transcribes the audio files into a list of Documents, one for each input file. + +For the supported audio formats, languages, and other parameters, see the +[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text) and the official Whisper +[github repo](https://github.com/openai/whisper). + +**Arguments**: + +- `sources`: A list of paths or binary streams to transcribe. + +**Returns**: + +A list of Documents, one for each file. + + + +## Module whisper\_remote + + + +### RemoteWhisperTranscriber + +Transcribes audio files using the OpenAI's Whisper API. + +The component requires an OpenAI API key, see the +[OpenAI documentation](https://platform.openai.com/docs/api-reference/authentication) for more details. +For the supported audio formats, languages, and other parameters, see the +[Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text). + +### Usage example + +```python +from haystack.components.audio import RemoteWhisperTranscriber + +whisper = RemoteWhisperTranscriber(api_key=Secret.from_token(""), model="tiny") +transcription = whisper.run(sources=["path/to/audio/file"]) +``` + + + +#### RemoteWhisperTranscriber.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "whisper-1", + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + http_client_kwargs: Optional[dict[str, Any]] = None, + **kwargs) +``` + +Creates an instance of the RemoteWhisperTranscriber component. + +**Arguments**: + +- `api_key`: OpenAI API key. +You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter +during initialization. +- `model`: Name of the model to use. Currently accepts only `whisper-1`. +- `organization`: Your OpenAI organization ID. See OpenAI's documentation on +[Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `api_base`: An optional URL to use as the API base. For details, see the +OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio). +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). +- `kwargs`: Other optional parameters for the model. These are sent directly to the OpenAI +endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/audio) for more details. +Some of the supported parameters are: +- `language`: The language of the input audio. + Provide the input language in ISO-639-1 format + to improve transcription accuracy and latency. +- `prompt`: An optional text to guide the model's + style or continue a previous audio segment. + The prompt should match the audio language. +- `response_format`: The format of the transcript + output. This component only supports `json`. +- `temperature`: The sampling temperature, between 0 +and 1. Higher values like 0.8 make the output more +random, while lower values like 0.2 make it more +focused and deterministic. If set to 0, the model +uses log probability to automatically increase the +temperature until certain thresholds are hit. + + + +#### RemoteWhisperTranscriber.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### RemoteWhisperTranscriber.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "RemoteWhisperTranscriber" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### RemoteWhisperTranscriber.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]]) +``` + +Transcribes the list of audio files into a list of documents. + +**Arguments**: + +- `sources`: A list of file paths or `ByteStream` objects containing the audio files to transcribe. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents, one document for each file. +The content of each document is the transcribed text. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/builders_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/builders_api.md new file mode 100644 index 0000000000..6d5f767178 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/builders_api.md @@ -0,0 +1,556 @@ +--- +title: "Builders" +id: builders-api +description: "Extract the output of a Generator to an Answer format, and build prompts." +slug: "/builders-api" +--- + + + +## Module answer\_builder + + + +### AnswerBuilder + +Converts a query and Generator replies into a `GeneratedAnswer` object. + +AnswerBuilder parses Generator replies using custom regular expressions. +Check out the usage example below to see how it works. +Optionally, it can also take documents and metadata from the Generator to add to the `GeneratedAnswer` object. +AnswerBuilder works with both non-chat and chat Generators. + +### Usage example + + +### Usage example with documents and reference pattern + +```python +from haystack.components.builders import AnswerBuilder + +builder = AnswerBuilder(pattern="Answer: (.*)") +builder.run(query="What's the answer?", replies=["This is an argument. Answer: This is the answer."]) +``` +```python +from haystack import Document +from haystack.components.builders import AnswerBuilder + +replies = ["The capital of France is Paris [2]."] + +docs = [ + Document(content="Berlin is the capital of Germany."), + Document(content="Paris is the capital of France."), + Document(content="Rome is the capital of Italy."), +] + +builder = AnswerBuilder(reference_pattern="\[(\d+)\]", return_only_referenced_documents=False) +result = builder.run(query="What is the capital of France?", replies=replies, documents=docs)["answers"][0] + +print(f"Answer: {result.data}") +print("References:") +for doc in result.documents: + if doc.meta["referenced"]: + print(f"[{doc.meta['source_index']}] {doc.content}") +print("Other sources:") +for doc in result.documents: + if not doc.meta["referenced"]: + print(f"[{doc.meta['source_index']}] {doc.content}") + +# Answer: The capital of France is Paris +# References: +# [2] Paris is the capital of France. +# Other sources: +# [1] Berlin is the capital of Germany. +# [3] Rome is the capital of Italy. +``` + + + +#### AnswerBuilder.\_\_init\_\_ + +```python +def __init__(pattern: Optional[str] = None, + reference_pattern: Optional[str] = None, + last_message_only: bool = False, + *, + return_only_referenced_documents: bool = True) +``` + +Creates an instance of the AnswerBuilder component. + +**Arguments**: + +- `pattern`: The regular expression pattern to extract the answer text from the Generator. +If not specified, the entire response is used as the answer. +The regular expression can have one capture group at most. +If present, the capture group text +is used as the answer. If no capture group is present, the whole match is used as the answer. +Examples: + `[^\n]+$` finds "this is an answer" in a string "this is an argument.\nthis is an answer". + `Answer: (.*)` finds "this is an answer" in a string "this is an argument. Answer: this is an answer". +- `reference_pattern`: The regular expression pattern used for parsing the document references. +If not specified, no parsing is done, and all documents are returned. +References need to be specified as indices of the input documents and start at [1]. +Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]". +If this parameter is provided, documents metadata will contain a "referenced" key with a boolean value. +- `last_message_only`: If False (default value), all messages are used as the answer. +If True, only the last message is used as the answer. +- `return_only_referenced_documents`: To be used in conjunction with `reference_pattern`. +If True (default value), only the documents that were actually referenced in `replies` are returned. +If False, all documents are returned. +If `reference_pattern` is not provided, this parameter has no effect, and all documents are returned. + + + +#### AnswerBuilder.run + +```python +@component.output_types(answers=list[GeneratedAnswer]) +def run(query: str, + replies: Union[list[str], list[ChatMessage]], + meta: Optional[list[dict[str, Any]]] = None, + documents: Optional[list[Document]] = None, + pattern: Optional[str] = None, + reference_pattern: Optional[str] = None) +``` + +Turns the output of a Generator into `GeneratedAnswer` objects using regular expressions. + +**Arguments**: + +- `query`: The input query used as the Generator prompt. +- `replies`: The output of the Generator. Can be a list of strings or a list of `ChatMessage` objects. +- `meta`: The metadata returned by the Generator. If not specified, the generated answer will contain no metadata. +- `documents`: The documents used as the Generator inputs. If specified, they are added to +the `GeneratedAnswer` objects. +Each Document.meta includes a "source_index" key, representing its 1-based position in the input list. +When `reference_pattern` is provided: +- "referenced" key is added to the Document.meta, indicating if the document was referenced in the output. +- `return_only_referenced_documents` init parameter controls if all or only referenced documents are +returned. +- `pattern`: The regular expression pattern to extract the answer text from the Generator. +If not specified, the entire response is used as the answer. +The regular expression can have one capture group at most. +If present, the capture group text +is used as the answer. If no capture group is present, the whole match is used as the answer. + Examples: + `[^\n]+$` finds "this is an answer" in a string "this is an argument.\nthis is an answer". + `Answer: (.*)` finds "this is an answer" in a string + "this is an argument. Answer: this is an answer". +- `reference_pattern`: The regular expression pattern used for parsing the document references. +If not specified, no parsing is done, and all documents are returned. +References need to be specified as indices of the input documents and start at [1]. +Example: `\[(\d+)\]` finds "1" in a string "this is an answer[1]". + +**Returns**: + +A dictionary with the following keys: +- `answers`: The answers received from the output of the Generator. + + + +## Module prompt\_builder + + + +### PromptBuilder + +Renders a prompt filling in any variables so that it can send it to a Generator. + +The prompt uses Jinja2 template syntax. +The variables in the default template are used as PromptBuilder's input and are all optional. +If they're not provided, they're replaced with an empty string in the rendered prompt. +To try out different prompts, you can replace the prompt template at runtime by +providing a template for each pipeline run invocation. + +### Usage examples + +#### On its own + +This example uses PromptBuilder to render a prompt template and fill it with `target_language` +and `snippet`. PromptBuilder returns a prompt with the string "Translate the following context to Spanish. +Context: I can't speak Spanish.; Translation:". +```python +from haystack.components.builders import PromptBuilder + +template = "Translate the following context to {{ target_language }}. Context: {{ snippet }}; Translation:" +builder = PromptBuilder(template=template) +builder.run(target_language="spanish", snippet="I can't speak spanish.") +``` + +#### 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. +```python +from haystack import Pipeline, Document +from haystack.utils import Secret +from haystack.components.generators import OpenAIGenerator +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 +documents = [Document(content="Joe lives in Berlin"), Document(content="Joe is a software engineer")] +prompt_template = """ + Given these documents, answer the question. + Documents: + {% for doc in documents %} + {{ doc.content }} + {% endfor %} + + Question: {{query}} + Answer: + """ +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.connect("prompt_builder", "llm") + +question = "Where does Joe live?" +result = p.run({"prompt_builder": {"documents": documents, "query": question}}) +print(result) +``` + +#### Changing the template at runtime (prompt engineering) + +You can change the prompt template of an existing pipeline, like in this example: +```python +documents = [ + Document(content="Joe lives in Berlin", meta={"name": "doc1"}), + Document(content="Joe is a software engineer", meta={"name": "doc1"}), +] +new_template = """ + You are a helpful assistant. + Given these documents, answer the question. + Documents: + {% for doc in documents %} + Document {{ loop.index }}: + Document name: {{ doc.meta['name'] }} + {{ doc.content }} + {% endfor %} + + Question: {{ query }} + Answer: + """ +p.run({ + "prompt_builder": { + "documents": documents, + "query": question, + "template": new_template, + }, +}) +``` +To replace the variables in the default template when testing your prompt, +pass the new variables in the `variables` parameter. + +#### Overwriting variables at runtime + +To overwrite the values of variables, use `template_variables` during runtime: +```python +language_template = """ +You are a helpful assistant. +Given these documents, answer the question. +Documents: +{% for doc in documents %} + Document {{ loop.index }}: + Document name: {{ doc.meta['name'] }} + {{ doc.content }} +{% endfor %} + +Question: {{ query }} +Please provide your answer in {{ answer_language | default('English') }} +Answer: +""" +p.run({ + "prompt_builder": { + "documents": documents, + "query": question, + "template": language_template, + "template_variables": {"answer_language": "German"}, + }, +}) +``` +Note that `language_template` introduces variable `answer_language` which is not bound to any pipeline variable. +If not set otherwise, it will use its default value 'English'. +This example overwrites its value to 'German'. +Use `template_variables` to overwrite pipeline variables (such as documents) as well. + + + +#### PromptBuilder.\_\_init\_\_ + +```python +def __init__(template: str, + required_variables: Optional[Union[list[str], + Literal["*"]]] = None, + variables: Optional[list[str]] = None) +``` + +Constructs a PromptBuilder component. + +**Arguments**: + +- `template`: A prompt template that uses Jinja2 syntax to add variables. For example: +`"Summarize this document: {{ documents[0].content }}\nSummary:"` +It's used to render the prompt. +The variables in the default template are input for PromptBuilder and are all optional, +unless explicitly specified. +If an optional variable is not provided, it's replaced with an empty string in the rendered prompt. +- `required_variables`: List variables that must be provided as input to PromptBuilder. +If a variable listed as required is not provided, an exception is raised. +If set to "*", all variables found in the prompt are required. Optional. +- `variables`: List input variables to use in prompt templates instead of the ones inferred from the +`template` parameter. For example, to use more variables during prompt engineering than the ones present +in the default template, you can provide them here. + + + +#### PromptBuilder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of the component. + +**Returns**: + +Serialized dictionary representation of the component. + + + +#### PromptBuilder.run + +```python +@component.output_types(prompt=str) +def run(template: Optional[str] = None, + template_variables: Optional[dict[str, Any]] = None, + **kwargs) +``` + +Renders the prompt template with the provided variables. + +It applies the template variables to render the final prompt. You can provide variables via pipeline kwargs. +In order to overwrite the default template, you can set the `template` parameter. +In order to overwrite pipeline kwargs, you can set the `template_variables` parameter. + +**Arguments**: + +- `template`: An optional string template to overwrite PromptBuilder's default template. If None, the default template +provided at initialization is used. +- `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables. +- `kwargs`: Pipeline variables used for rendering the prompt. + +**Raises**: + +- `ValueError`: If any of the required template variables is not provided. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The updated prompt text after rendering the prompt template. + + + +## Module chat\_prompt\_builder + + + +### ChatPromptBuilder + +Renders a chat prompt from a template using Jinja2 syntax. + +A template can be a list of `ChatMessage` objects, or a special string, as shown in the usage examples. + +It constructs prompts using static or dynamic templates, which you can update for each pipeline run. + +Template variables in the template are optional unless specified otherwise. +If an optional variable isn't provided, it defaults to an empty string. Use `variable` and `required_variables` +to define input types and required variables. + +### Usage examples + +#### Static ChatMessage prompt template + +```python +template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")] +builder = ChatPromptBuilder(template=template) +builder.run(target_language="spanish", snippet="I can't speak spanish.") +``` + +#### Overriding static ChatMessage template at runtime + +```python +template = [ChatMessage.from_user("Translate to {{ target_language }}. Context: {{ snippet }}; Translation:")] +builder = ChatPromptBuilder(template=template) +builder.run(target_language="spanish", snippet="I can't speak spanish.") + +msg = "Translate to {{ target_language }} and summarize. Context: {{ snippet }}; Summary:" +summary_template = [ChatMessage.from_user(msg)] +builder.run(target_language="spanish", snippet="I can't speak spanish.", template=summary_template) +``` + +#### Dynamic ChatMessage prompt template + +```python +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack import Pipeline +from haystack.utils import Secret + +# no parameter init, we don't use any runtime template variables +prompt_builder = ChatPromptBuilder() +llm = OpenAIChatGenerator(api_key=Secret.from_token(""), model="gpt-4o-mini") + +pipe = Pipeline() +pipe.add_component("prompt_builder", prompt_builder) +pipe.add_component("llm", llm) +pipe.connect("prompt_builder.prompt", "llm.messages") + +location = "Berlin" +language = "English" +system_message = ChatMessage.from_system("You are an assistant giving information to tourists in {{language}}") +messages = [system_message, ChatMessage.from_user("Tell me about {{location}}")] + +res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "language": language}, + "template": messages}}) +print(res) + +>> {'llm': {'replies': [ChatMessage(_role=, _content=[TextContent(text= +"Berlin is the capital city of Germany and one of the most vibrant +and diverse cities in Europe. Here are some key things to know...Enjoy your time exploring the vibrant and dynamic +capital of Germany!")], _name=None, _meta={'model': 'gpt-4o-mini', +'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 27, 'completion_tokens': 681, 'total_tokens': +708}})]}} + +messages = [system_message, ChatMessage.from_user("What's the weather forecast for {{location}} in the next +{{day_count}} days?")] + +res = pipe.run(data={"prompt_builder": {"template_variables": {"location": location, "day_count": "5"}, + "template": messages}}) + +print(res) +>> {'llm': {'replies': [ChatMessage(_role=, _content=[TextContent(text= +"Here is the weather forecast for Berlin in the next 5 +days:\n\nDay 1: Mostly cloudy with a high of 22°C (72°F) and...so it's always a good idea to check for updates +closer to your visit.")], _name=None, _meta={'model': 'gpt-4o-mini', +'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 37, 'completion_tokens': 201, +'total_tokens': 238}})]}} +``` + +#### String prompt template +```python +from haystack.components.builders import ChatPromptBuilder +from haystack.dataclasses.image_content import ImageContent + +template = """ +{% message role="system" %} +You are a helpful assistant. +{% endmessage %} + +{% message role="user" %} +Hello! I am {{user_name}}. What's the difference between the following images? +{% for image in images %} +{{ image | templatize_part }} +{% endfor %} +{% endmessage %} +""" + +images = [ImageContent.from_file_path("apple.jpg"), ImageContent.from_file_path("orange.jpg")] + +builder = ChatPromptBuilder(template=template) +builder.run(user_name="John", images=images) +``` + + + +#### ChatPromptBuilder.\_\_init\_\_ + +```python +def __init__(template: Optional[Union[list[ChatMessage], str]] = None, + required_variables: Optional[Union[list[str], + Literal["*"]]] = None, + variables: Optional[list[str]] = None) +``` + +Constructs a ChatPromptBuilder component. + +**Arguments**: + +- `template`: A list of `ChatMessage` objects or a string template. The component looks for Jinja2 template syntax and +renders the prompt with the provided variables. Provide the template in either +the `init` method` or the `run` method. +- `required_variables`: List variables that must be provided as input to ChatPromptBuilder. +If a variable listed as required is not provided, an exception is raised. +If set to "*", all variables found in the prompt are required. Optional. +- `variables`: List input variables to use in prompt templates instead of the ones inferred from the +`template` parameter. For example, to use more variables during prompt engineering than the ones present +in the default template, you can provide them here. + + + +#### ChatPromptBuilder.run + +```python +@component.output_types(prompt=list[ChatMessage]) +def run(template: Optional[Union[list[ChatMessage], str]] = None, + template_variables: Optional[dict[str, Any]] = None, + **kwargs) +``` + +Renders the prompt template with the provided variables. + +It applies the template variables to render the final prompt. You can provide variables with pipeline kwargs. +To overwrite the default template, you can set the `template` parameter. +To overwrite pipeline kwargs, you can set the `template_variables` parameter. + +**Arguments**: + +- `template`: An optional list of `ChatMessage` objects or string template to overwrite ChatPromptBuilder's default +template. +If `None`, the default template provided at initialization is used. +- `template_variables`: An optional dictionary of template variables to overwrite the pipeline variables. +- `kwargs`: Pipeline variables used for rendering the prompt. + +**Raises**: + +- `ValueError`: If `chat_messages` is empty or contains elements that are not instances of `ChatMessage`. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The updated list of `ChatMessage` objects after rendering the templates. + + + +#### ChatPromptBuilder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of the component. + +**Returns**: + +Serialized dictionary representation of the component. + + + +#### ChatPromptBuilder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ChatPromptBuilder" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize and create the component. + +**Returns**: + +The deserialized component. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/cachings_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/cachings_api.md new file mode 100644 index 0000000000..8463379ee2 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/cachings_api.md @@ -0,0 +1,110 @@ +--- +title: "Caching" +id: caching-api +description: "Checks if any document coming from the given URL is already present in the store." +slug: "/caching-api" +--- + + + +## Module cache\_checker + + + +### CacheChecker + +Checks for the presence of documents in a Document Store based on a specified field in each document's metadata. + +If matching documents are found, they are returned as "hits". If not found in the cache, the items +are returned as "misses". + +### Usage example + +```python +from haystack import Document +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.caching.cache_checker import CacheChecker + +docstore = InMemoryDocumentStore() +documents = [ + Document(content="doc1", meta={"url": "https://example.com/1"}), + Document(content="doc2", meta={"url": "https://example.com/2"}), + Document(content="doc3", meta={"url": "https://example.com/1"}), + Document(content="doc4", meta={"url": "https://example.com/2"}), +] +docstore.write_documents(documents) +checker = CacheChecker(docstore, cache_field="url") +results = checker.run(items=["https://example.com/1", "https://example.com/5"]) +assert results == {"hits": [documents[0], documents[2]], "misses": ["https://example.com/5"]} +``` + + + +#### CacheChecker.\_\_init\_\_ + +```python +def __init__(document_store: DocumentStore, cache_field: str) +``` + +Creates a CacheChecker component. + +**Arguments**: + +- `document_store`: Document Store to check for the presence of specific documents. +- `cache_field`: Name of the document's metadata field +to check for cache hits. + + + +#### CacheChecker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CacheChecker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "CacheChecker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### CacheChecker.run + +```python +@component.output_types(hits=list[Document], misses=list) +def run(items: list[Any]) +``` + +Checks if any document associated with the specified cache field is already present in the store. + +**Arguments**: + +- `items`: Values to be checked against the cache field. + +**Returns**: + +A dictionary with two keys: +- `hits` - Documents that matched with at least one of the items. +- `misses` - Items that were not present in any documents. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/classifiers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/classifiers_api.md new file mode 100644 index 0000000000..3c4904bbdc --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/classifiers_api.md @@ -0,0 +1,262 @@ +--- +title: "Classifiers" +id: classifiers-api +description: "Classify documents based on the provided labels." +slug: "/classifiers-api" +--- + + + +## Module document\_language\_classifier + + + +### DocumentLanguageClassifier + +Classifies the language of each document and adds it to its metadata. + +Provide a list of languages during initialization. If the document's text doesn't match any of the +specified languages, the metadata value is set to "unmatched". +To route documents based on their language, use the MetadataRouter component after DocumentLanguageClassifier. +For routing plain text, use the TextLanguageRouter component instead. + +### Usage example + +```python +from haystack import Document, Pipeline +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.classifiers import DocumentLanguageClassifier +from haystack.components.routers import MetadataRouter +from haystack.components.writers import DocumentWriter + +docs = [Document(id="1", content="This is an English document"), + Document(id="2", content="Este es un documento en español")] + +document_store = InMemoryDocumentStore() + +p = Pipeline() +p.add_component(instance=DocumentLanguageClassifier(languages=["en"]), name="language_classifier") +p.add_component(instance=MetadataRouter(rules={"en": {"language": {"$eq": "en"}}}), name="router") +p.add_component(instance=DocumentWriter(document_store=document_store), name="writer") +p.connect("language_classifier.documents", "router.documents") +p.connect("router.en", "writer.documents") + +p.run({"language_classifier": {"documents": docs}}) + +written_docs = document_store.filter_documents() +assert len(written_docs) == 1 +assert written_docs[0] == Document(id="1", content="This is an English document", meta={"language": "en"}) +``` + + + +#### DocumentLanguageClassifier.\_\_init\_\_ + +```python +def __init__(languages: Optional[list[str]] = None) +``` + +Initializes the DocumentLanguageClassifier component. + +**Arguments**: + +- `languages`: A list of ISO language codes. +See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages). +If not specified, defaults to ["en"]. + + + +#### DocumentLanguageClassifier.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Classifies the language of each document and adds it to its metadata. + +If the document's text doesn't match any of the languages specified at initialization, +sets the metadata value to "unmatched". + +**Arguments**: + +- `documents`: A list of documents for language classification. + +**Raises**: + +- `TypeError`: if the input is not a list of Documents. + +**Returns**: + +A dictionary with the following key: +- `documents`: A list of documents with an added `language` metadata field. + + + +## Module zero\_shot\_document\_classifier + + + +### TransformersZeroShotDocumentClassifier + +Performs zero-shot classification of documents based on given labels and adds the predicted label to their metadata. + +The component uses a Hugging Face pipeline for zero-shot classification. +Provide the model and the set of labels to be used for categorization during initialization. +Additionally, you can configure the component to allow multiple labels to be true. + +Classification is run on the document's content field by default. If you want it to run on another field, set the +`classification_field` to one of the document's metadata fields. + +Available models for the task of zero-shot-classification include: + - `valhalla/distilbart-mnli-12-3` + - `cross-encoder/nli-distilroberta-base` + - `cross-encoder/nli-deberta-v3-xsmall` + +### Usage example + +The following is a pipeline that classifies documents based on predefined classification labels +retrieved from a search pipeline: + +```python +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 + +documents = [Document(id="0", content="Today was a nice day!"), + Document(id="1", content="Yesterday was a bad day!")] + +document_store = InMemoryDocumentStore() +retriever = InMemoryBM25Retriever(document_store=document_store) +document_classifier = TransformersZeroShotDocumentClassifier( + model="cross-encoder/nli-deberta-v3-xsmall", + labels=["positive", "negative"], +) + +document_store.write_documents(documents) + +pipeline = Pipeline() +pipeline.add_component(instance=retriever, name="retriever") +pipeline.add_component(instance=document_classifier, name="document_classifier") +pipeline.connect("retriever", "document_classifier") + +queries = ["How was your day today?", "How was your day yesterday?"] +expected_predictions = ["positive", "negative"] + +for idx, query in enumerate(queries): + result = pipeline.run({"retriever": {"query": query, "top_k": 1}}) + assert result["document_classifier"]["documents"][0].to_dict()["id"] == str(idx) + assert (result["document_classifier"]["documents"][0].to_dict()["classification"]["label"] + == expected_predictions[idx]) +``` + + + +#### TransformersZeroShotDocumentClassifier.\_\_init\_\_ + +```python +def __init__(model: str, + labels: list[str], + multi_label: bool = False, + classification_field: Optional[str] = None, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None) +``` + +Initializes the TransformersZeroShotDocumentClassifier. + +See the Hugging Face [website](https://huggingface.co/models?pipeline_tag=zero-shot-classification&sort=downloads&search=nli) +for the full list of zero-shot classification models (NLI) models. + +**Arguments**: + +- `model`: The name or path of a Hugging Face model for zero shot document classification. +- `labels`: The set of possible class labels to classify each document into, for example, +["positive", "negative"]. The labels depend on the selected model. +- `multi_label`: Whether or not multiple candidate labels can be true. +If `False`, the scores are normalized such that +the sum of the label likelihoods for each sequence is 1. If `True`, the labels are considered +independent and probabilities are normalized for each candidate by doing a softmax of the entailment +score vs. the contradiction score. +- `classification_field`: Name of document's meta field to be used for classification. +If not set, `Document.content` is used by default. +- `device`: The device on which the model is loaded. If `None`, the default device is automatically +selected. If a device/device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter. +- `token`: The Hugging Face token to use as HTTP bearer authorization. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). +- `huggingface_pipeline_kwargs`: Dictionary containing keyword arguments used to initialize the +Hugging Face pipeline for text classification. + + + +#### TransformersZeroShotDocumentClassifier.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### TransformersZeroShotDocumentClassifier.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### TransformersZeroShotDocumentClassifier.from\_dict + +```python +@classmethod +def from_dict( + cls, data: dict[str, Any]) -> "TransformersZeroShotDocumentClassifier" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### TransformersZeroShotDocumentClassifier.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document], batch_size: int = 1) +``` + +Classifies the documents based on the provided labels and adds them to their metadata. + +The classification results are stored in the `classification` dict within +each document's metadata. If `multi_label` is set to `True`, the scores for each label are available under +the `details` key within the `classification` dictionary. + +**Arguments**: + +- `documents`: Documents to process. +- `batch_size`: Batch size used for processing the content in each document. + +**Returns**: + +A dictionary with the following key: +- `documents`: A list of documents with an added metadata field called `classification`. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/connectors_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/connectors_api.md new file mode 100644 index 0000000000..1ec9902011 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/connectors_api.md @@ -0,0 +1,247 @@ +--- +title: "Connectors" +id: connectors-api +description: "Various connectors to integrate with external services." +slug: "/connectors-api" +--- + + + +## Module openapi\_service + + + +### OpenAPIServiceConnector + +A component which connects the Haystack framework to OpenAPI services. + +The `OpenAPIServiceConnector` component connects the Haystack framework to OpenAPI services, enabling it to call +operations as defined in the OpenAPI specification of the service. + +It integrates with `ChatMessage` dataclass, where the payload in messages is used to determine the method to be +called and the parameters to be passed. The message payload should be an OpenAI JSON formatted function calling +string consisting of the method name and the parameters to be passed to the method. The method name and parameters +are then used to invoke the method on the OpenAPI service. The response from the service is returned as a +`ChatMessage`. + +Before using this component, users usually resolve service endpoint parameters with a help of +`OpenAPIServiceToFunctions` component. + +The example below demonstrates how to use the `OpenAPIServiceConnector` to invoke a method on a https://serper.dev/ +service specified via OpenAPI specification. + +Note, however, that `OpenAPIServiceConnector` is usually not meant to be used directly, but rather as part of a +pipeline that includes the `OpenAPIServiceToFunctions` component and an `OpenAIChatGenerator` component using LLM +with the function calling capabilities. In the example below we use the function calling payload directly, but in a +real-world scenario, the function calling payload would usually be generated by the `OpenAIChatGenerator` component. + +Usage example: + +```python +import json +import requests + +from haystack.components.connectors import OpenAPIServiceConnector +from haystack.dataclasses import ChatMessage + + +fc_payload = [{'function': {'arguments': '{"q": "Why was Sam Altman ousted from OpenAI?"}', 'name': 'search'}, + 'id': 'call_PmEBYvZ7mGrQP5PUASA5m9wO', 'type': 'function'}] + +serper_token = +serperdev_openapi_spec = json.loads(requests.get("https://bit.ly/serper_dev_spec").text) +service_connector = OpenAPIServiceConnector() +result = service_connector.run(messages=[ChatMessage.from_assistant(json.dumps(fc_payload))], + service_openapi_spec=serperdev_openapi_spec, service_credentials=serper_token) +print(result) + +>> {'service_response': [ChatMessage(_role=, _content=[TextContent(text= +>> '{"searchParameters": {"q": "Why was Sam Altman ousted from OpenAI?", +>> "type": "search", "engine": "google"}, "answerBox": {"snippet": "Concerns over AI safety and OpenAI's role +>> in protecting were at the center of Altman's brief ouster from the company."... +``` + + + +#### OpenAPIServiceConnector.\_\_init\_\_ + +```python +def __init__(ssl_verify: Optional[Union[bool, str]] = None) +``` + +Initializes the OpenAPIServiceConnector instance + +**Arguments**: + +- `ssl_verify`: Decide if to use SSL verification to the requests or not, +in case a string is passed, will be used as the CA. + + + +#### OpenAPIServiceConnector.run + +```python +@component.output_types(service_response=dict[str, Any]) +def run( + messages: list[ChatMessage], + service_openapi_spec: dict[str, Any], + service_credentials: Optional[Union[dict, str]] = None +) -> dict[str, list[ChatMessage]] +``` + +Processes a list of chat messages to invoke a method on an OpenAPI service. + +It parses the last message in the list, expecting it to contain tool calls. + +**Arguments**: + +- `messages`: A list of `ChatMessage` objects containing the messages to be processed. The last message +should contain the tool calls. +- `service_openapi_spec`: The OpenAPI JSON specification object of the service to be invoked. All the refs +should already be resolved. +- `service_credentials`: The credentials to be used for authentication with the service. +Currently, only the http and apiKey OpenAPI security schemes are supported. + +**Raises**: + +- `ValueError`: If the last message is not from the assistant or if it does not contain tool calls. + +**Returns**: + +A dictionary with the following keys: +- `service_response`: a list of `ChatMessage` objects, each containing the response from the service. The +response is in JSON format, and the `content` attribute of the `ChatMessage` contains +the JSON string. + + + +#### OpenAPIServiceConnector.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenAPIServiceConnector.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAPIServiceConnector" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module openapi + + + +### OpenAPIConnector + +OpenAPIConnector enables direct invocation of REST endpoints defined in an OpenAPI specification. + +The OpenAPIConnector serves as a bridge between Haystack pipelines and any REST API that follows +the OpenAPI(formerly Swagger) specification. It dynamically interprets the API specification and +provides an interface for executing API operations. It is usually invoked by passing input +arguments to it from a Haystack pipeline run method or by other components in a pipeline that +pass input arguments to this component. + +**Example**: + +```python +from haystack.utils import Secret +from haystack.components.connectors.openapi import OpenAPIConnector + +connector = OpenAPIConnector( + openapi_spec="https://bit.ly/serperdev_openapi", + credentials=Secret.from_env_var("SERPERDEV_API_KEY"), + service_kwargs={"config_factory": my_custom_config_factory} +) +response = connector.run( + operation_id="search", + arguments={"q": "Who was Nikola Tesla?"} +) +``` + +**Notes**: + + - The `parameters` argument is required for this component. + - The `service_kwargs` argument is optional, it can be used to pass additional options to the OpenAPIClient. + + + +#### OpenAPIConnector.\_\_init\_\_ + +```python +def __init__(openapi_spec: str, + credentials: Optional[Secret] = None, + service_kwargs: Optional[dict[str, Any]] = None) +``` + +Initialize the OpenAPIConnector with a specification and optional credentials. + +**Arguments**: + +- `openapi_spec`: URL, file path, or raw string of the OpenAPI specification +- `credentials`: Optional API key or credentials for the service wrapped in a Secret +- `service_kwargs`: Additional keyword arguments passed to OpenAPIClient.from_spec() +For example, you can pass a custom config_factory or other configuration options. + + + +#### OpenAPIConnector.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + + + +#### OpenAPIConnector.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAPIConnector" +``` + +Deserialize this component from a dictionary. + + + +#### OpenAPIConnector.run + +```python +@component.output_types(response=dict[str, Any]) +def run(operation_id: str, + arguments: Optional[dict[str, Any]] = None) -> dict[str, Any] +``` + +Invokes a REST endpoint specified in the OpenAPI specification. + +**Arguments**: + +- `operation_id`: The operationId from the OpenAPI spec to invoke +- `arguments`: Optional parameters for the endpoint (query, path, or body parameters) + +**Returns**: + +Dictionary containing the service response + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/converters_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/converters_api.md new file mode 100644 index 0000000000..3528e5edba --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/converters_api.md @@ -0,0 +1,1633 @@ +--- +title: "Converters" +id: converters-api +description: "Various converters to transform data from one format to another." +slug: "/converters-api" +--- + + + +## Module azure + + + +### AzureOCRDocumentConverter + +Converts files to documents using Azure's Document Intelligence service. + +Supported file formats are: PDF, JPEG, PNG, BMP, TIFF, DOCX, XLSX, PPTX, and HTML. + +To use this component, you need an active Azure account +and a Document Intelligence or Cognitive Services resource. For help with setting up your resource, see +[Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/quickstarts/get-started-sdks-rest-api). + +### Usage example + +```python +from haystack.components.converters import AzureOCRDocumentConverter +from haystack.utils import Secret + +converter = AzureOCRDocumentConverter(endpoint="", api_key=Secret.from_token("")) +results = converter.run(sources=["path/to/doc_with_images.pdf"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the PDF file.' +``` + + + +#### AzureOCRDocumentConverter.\_\_init\_\_ + +```python +def __init__(endpoint: str, + api_key: Secret = Secret.from_env_var("AZURE_AI_API_KEY"), + model_id: str = "prebuilt-read", + preceding_context_len: int = 3, + following_context_len: int = 3, + merge_multiple_column_headers: bool = True, + page_layout: Literal["natural", "single_column"] = "natural", + threshold_y: Optional[float] = 0.05, + store_full_path: bool = False) +``` + +Creates an AzureOCRDocumentConverter component. + +**Arguments**: + +- `endpoint`: The endpoint of your Azure resource. +- `api_key`: The API key of your Azure resource. +- `model_id`: The ID of the model you want to use. For a list of available models, see [Azure documentation] +(https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/choose-model-feature). +- `preceding_context_len`: Number of lines before a table to include as preceding context +(this will be added to the metadata). +- `following_context_len`: Number of lines after a table to include as subsequent context ( +this will be added to the metadata). +- `merge_multiple_column_headers`: If `True`, merges multiple column header rows into a single row. +- `page_layout`: The type reading order to follow. Possible options: +- `natural`: Uses the natural reading order determined by Azure. +- `single_column`: Groups all lines with the same height on the page based on a threshold +determined by `threshold_y`. +- `threshold_y`: Only relevant if `single_column` is set to `page_layout`. +The threshold, in inches, to determine if two recognized PDF elements are grouped into a +single line. This is crucial for section headers or numbers which may be spatially separated +from the remaining text on the horizontal axis. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### AzureOCRDocumentConverter.run + +```python +@component.output_types(documents=list[Document], + raw_azure_response=list[dict]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Convert a list of files to Documents using Azure's Document Intelligence service. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will be +zipped. If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of created Documents +- `raw_azure_response`: List of raw Azure responses used to create the Documents + + + +#### AzureOCRDocumentConverter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AzureOCRDocumentConverter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AzureOCRDocumentConverter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module csv + + + +### CSVToDocument + +Converts CSV files to Documents. + +By default, it uses UTF-8 encoding when converting files but +you can also set a custom encoding. +It can attach metadata to the resulting documents. + +### Usage example + +```python +from haystack.components.converters.csv import CSVToDocument +converter = CSVToDocument() +results = converter.run(sources=["sample.csv"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'col1,col2\nrow1,row1\nrow2,row2\n' +``` + + + +#### CSVToDocument.\_\_init\_\_ + +```python +def __init__(encoding: str = "utf-8", + store_full_path: bool = False, + *, + conversion_mode: Literal["file", "row"] = "file", + delimiter: str = ",", + quotechar: str = '"') +``` + +Creates a CSVToDocument component. + +**Arguments**: + +- `encoding`: The encoding of the csv files to convert. +If the encoding is specified in the metadata of a source ByteStream, +it overrides this value. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. +- `conversion_mode`: - "file" (default): one Document per CSV file whose content is the raw CSV text. +- "row": convert each CSV row to its own Document (requires `content_column` in `run()`). +- `delimiter`: CSV delimiter used when parsing in row mode (passed to ``csv.DictReader``). +- `quotechar`: CSV quote character used when parsing in row mode (passed to ``csv.DictReader``). + + + +#### CSVToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + *, + content_column: Optional[str] = None, + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts CSV files to a Document (file mode) or to one Document per row (row mode). + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `content_column`: **Required when** ``conversion_mode="row"``. +The column name whose values become ``Document.content`` for each row. +The column must exist in the CSV header. +- `meta`: Optional metadata to attach to the documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created documents + + + +## Module docx + + + +### DOCXMetadata + +Describes the metadata of Docx file. + +**Arguments**: + +- `author`: The author +- `category`: The category +- `comments`: The comments +- `content_status`: The content status +- `created`: The creation date (ISO formatted string) +- `identifier`: The identifier +- `keywords`: Available keywords +- `language`: The language of the document +- `last_modified_by`: User who last modified the document +- `last_printed`: The last printed date (ISO formatted string) +- `modified`: The last modification date (ISO formatted string) +- `revision`: The revision number +- `subject`: The subject +- `title`: The title +- `version`: The version + + + +### DOCXTableFormat + +Supported formats for storing DOCX tabular data in a Document. + + + +#### DOCXTableFormat.from\_str + +```python +@staticmethod +def from_str(string: str) -> "DOCXTableFormat" +``` + +Convert a string to a DOCXTableFormat enum. + + + +### DOCXLinkFormat + +Supported formats for storing DOCX link information in a Document. + + + +#### DOCXLinkFormat.from\_str + +```python +@staticmethod +def from_str(string: str) -> "DOCXLinkFormat" +``` + +Convert a string to a DOCXLinkFormat enum. + + + +### DOCXToDocument + +Converts DOCX files to Documents. + +Uses `python-docx` library to convert the DOCX file to a document. +This component does not preserve page breaks in the original document. + +Usage example: +```python +from haystack.components.converters.docx import DOCXToDocument, DOCXTableFormat, DOCXLinkFormat + +converter = DOCXToDocument(table_format=DOCXTableFormat.CSV, link_format=DOCXLinkFormat.MARKDOWN) +results = converter.run(sources=["sample.docx"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the DOCX file.' +``` + + + +#### DOCXToDocument.\_\_init\_\_ + +```python +def __init__(table_format: Union[str, DOCXTableFormat] = DOCXTableFormat.CSV, + link_format: Union[str, DOCXLinkFormat] = DOCXLinkFormat.NONE, + store_full_path: bool = False) +``` + +Create a DOCXToDocument component. + +**Arguments**: + +- `table_format`: The format for table output. Can be either DOCXTableFormat.MARKDOWN, +DOCXTableFormat.CSV, "markdown", or "csv". +- `link_format`: The format for link output. Can be either: +DOCXLinkFormat.MARKDOWN or "markdown" to get `[text](address)`, +DOCXLinkFormat.PLAIN or "plain" to get text (address), +DOCXLinkFormat.NONE or "none" to get text without links. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### DOCXToDocument.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### DOCXToDocument.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DOCXToDocument" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### DOCXToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts DOCX files to Documents. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents + + + +## Module html + + + +### HTMLToDocument + +Converts an HTML file to a Document. + +Usage example: +```python +from haystack.components.converters import HTMLToDocument + +converter = HTMLToDocument() +results = converter.run(sources=["path/to/sample.html"]) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the HTML file.' +``` + + + +#### HTMLToDocument.\_\_init\_\_ + +```python +def __init__(extraction_kwargs: Optional[dict[str, Any]] = None, + store_full_path: bool = False) +``` + +Create an HTMLToDocument component. + +**Arguments**: + +- `extraction_kwargs`: A dictionary containing keyword arguments to customize the extraction process. These +are passed to the underlying Trafilatura `extract` function. For the full list of available arguments, see +the [Trafilatura documentation](https://trafilatura.readthedocs.io/en/latest/corefunctions.html#extract). +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### HTMLToDocument.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HTMLToDocument.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HTMLToDocument" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### HTMLToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None, + extraction_kwargs: Optional[dict[str, Any]] = None) +``` + +Converts a list of HTML files to Documents. + +**Arguments**: + +- `sources`: List of HTML file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. +- `extraction_kwargs`: Additional keyword arguments to customize the extraction process. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents + + + +## Module json + + + +### JSONConverter + +Converts one or more JSON files into a text document. + +### Usage examples + +```python +import json + +from haystack.components.converters import JSONConverter +from haystack.dataclasses import ByteStream + +source = ByteStream.from_string(json.dumps({"text": "This is the content of my document"})) + +converter = JSONConverter(content_key="text") +results = converter.run(sources=[source]) +documents = results["documents"] +print(documents[0].content) +# 'This is the content of my document' +``` + +Optionally, you can also provide a `jq_schema` string to filter the JSON source files and `extra_meta_fields` +to extract from the filtered data: + +```python +import json + +from haystack.components.converters import JSONConverter +from haystack.dataclasses import ByteStream + +data = { + "laureates": [ + { + "firstname": "Enrico", + "surname": "Fermi", + "motivation": "for his demonstrations of the existence of new radioactive elements produced " + "by neutron irradiation, and for his related discovery of nuclear reactions brought about by" + " slow neutrons", + }, + { + "firstname": "Rita", + "surname": "Levi-Montalcini", + "motivation": "for their discoveries of growth factors", + }, + ], +} +source = ByteStream.from_string(json.dumps(data)) +converter = JSONConverter( + jq_schema=".laureates[]", content_key="motivation", extra_meta_fields={"firstname", "surname"} +) + +results = converter.run(sources=[source]) +documents = results["documents"] +print(documents[0].content) +# 'for his demonstrations of the existence of new radioactive elements produced by +# neutron irradiation, and for his related discovery of nuclear reactions brought +# about by slow neutrons' + +print(documents[0].meta) +# {'firstname': 'Enrico', 'surname': 'Fermi'} + +print(documents[1].content) +# 'for their discoveries of growth factors' + +print(documents[1].meta) +# {'firstname': 'Rita', 'surname': 'Levi-Montalcini'} +``` + + + +#### JSONConverter.\_\_init\_\_ + +```python +def __init__(jq_schema: Optional[str] = None, + content_key: Optional[str] = None, + extra_meta_fields: Optional[Union[set[str], Literal["*"]]] = None, + store_full_path: bool = False) +``` + +Creates a JSONConverter component. + +An optional `jq_schema` can be provided to extract nested data in the JSON source files. +See the [official jq documentation](https://jqlang.github.io/jq/) for more info on the filters syntax. +If `jq_schema` is not set, whole JSON source files will be used to extract content. + +Optionally, you can provide a `content_key` to specify which key in the extracted object must +be set as the document's content. + +If both `jq_schema` and `content_key` are set, the component will search for the `content_key` in +the JSON object extracted by `jq_schema`. If the extracted data is not a JSON object, it will be skipped. + +If only `jq_schema` is set, the extracted data must be a scalar value. If it's a JSON object or array, +it will be skipped. + +If only `content_key` is set, the source JSON file must be a JSON object, else it will be skipped. + +`extra_meta_fields` can either be set to a set of strings or a literal `"*"` string. +If it's a set of strings, it must specify fields in the extracted objects that must be set in +the extracted documents. If a field is not found, the meta value will be `None`. +If set to `"*"`, all fields that are not `content_key` found in the filtered JSON object will +be saved as metadata. + +Initialization will fail if neither `jq_schema` nor `content_key` are set. + +**Arguments**: + +- `jq_schema`: Optional jq filter string to extract content. +If not specified, whole JSON object will be used to extract information. +- `content_key`: Optional key to extract document content. +If `jq_schema` is specified, the `content_key` will be extracted from that object. +- `extra_meta_fields`: An optional set of meta keys to extract from the content. +If `jq_schema` is specified, all keys will be extracted from that object. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### JSONConverter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JSONConverter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "JSONConverter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JSONConverter.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts a list of JSON files to documents. + +**Arguments**: + +- `sources`: A list of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, the length of the list must match the number of sources. +If `sources` contain ByteStream objects, their `meta` will be added to the output documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of created documents. + + + +## Module markdown + + + +### MarkdownToDocument + +Converts a Markdown file into a text Document. + +Usage example: +```python +from haystack.components.converters import MarkdownToDocument +from datetime import datetime + +converter = MarkdownToDocument() +results = converter.run(sources=["path/to/sample.md"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the markdown file.' +``` + + + +#### MarkdownToDocument.\_\_init\_\_ + +```python +def __init__(table_to_single_line: bool = False, + progress_bar: bool = True, + store_full_path: bool = False) +``` + +Create a MarkdownToDocument component. + +**Arguments**: + +- `table_to_single_line`: If True converts table contents into a single line. +- `progress_bar`: If True shows a progress bar when running. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### MarkdownToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts a list of Markdown files to Documents. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of created Documents + + + +## Module msg + + + +### MSGToDocument + +Converts Microsoft Outlook .msg files into Haystack Documents. + +This component extracts email metadata (such as sender, recipients, CC, BCC, subject) and body content from .msg +files and converts them into structured Haystack Documents. Additionally, any file attachments within the .msg +file are extracted as ByteStream objects. + +### Example Usage + +```python +from haystack.components.converters.msg import MSGToDocument +from datetime import datetime + +converter = MSGToDocument() +results = converter.run(sources=["sample.msg"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +attachments = results["attachments"] +print(documents[0].content) +``` + + + +#### MSGToDocument.\_\_init\_\_ + +```python +def __init__(store_full_path: bool = False) -> None +``` + +Creates a MSGToDocument component. + +**Arguments**: + +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### MSGToDocument.run + +```python +@component.output_types(documents=list[Document], attachments=list[ByteStream]) +def run( + sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None +) -> dict[str, Union[list[Document], list[ByteStream]]] +``` + +Converts MSG files to Documents. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents. +- `attachments`: Created ByteStream objects from file attachments. + + + +## Module multi\_file\_converter + + + +### MultiFileConverter + +A file converter that handles conversion of multiple file types. + +The MultiFileConverter handles the following file types: +- CSV +- DOCX +- HTML +- JSON +- MD +- TEXT +- PDF (no OCR) +- PPTX +- XLSX + +Usage example: +``` +from haystack.super_components.converters import MultiFileConverter + +converter = MultiFileConverter() +converter.run(sources=["test.txt", "test.pdf"], meta={}) +``` + + + +#### MultiFileConverter.\_\_init\_\_ + +```python +def __init__(encoding: str = "utf-8", + json_content_key: str = "content") -> None +``` + +Initialize the MultiFileConverter. + +**Arguments**: + +- `encoding`: The encoding to use when reading files. +- `json_content_key`: The key to use in a content field in a document when converting JSON files. + + + +## Module openapi\_functions + + + +### OpenAPIServiceToFunctions + +Converts OpenAPI service definitions to a format suitable for OpenAI function calling. + +The definition must respect OpenAPI specification 3.0.0 or higher. +It can be specified in JSON or YAML format. +Each function must have: + - unique operationId + - description + - requestBody and/or parameters + - schema for the requestBody and/or parameters +For more details on OpenAPI specification see the [official documentation](https://github.com/OAI/OpenAPI-Specification). +For more details on OpenAI function calling see the [official documentation](https://platform.openai.com/docs/guides/function-calling). + +Usage example: +```python +from haystack.components.converters import OpenAPIServiceToFunctions + +converter = OpenAPIServiceToFunctions() +result = converter.run(sources=["path/to/openapi_definition.yaml"]) +assert result["functions"] +``` + + + +#### OpenAPIServiceToFunctions.\_\_init\_\_ + +```python +def __init__() +``` + +Create an OpenAPIServiceToFunctions component. + + + +#### OpenAPIServiceToFunctions.run + +```python +@component.output_types(functions=list[dict[str, Any]], + openapi_specs=list[dict[str, Any]]) +def run(sources: list[Union[str, Path, ByteStream]]) -> dict[str, Any] +``` + +Converts OpenAPI definitions in OpenAI function calling format. + +**Arguments**: + +- `sources`: File paths or ByteStream objects of OpenAPI definitions (in JSON or YAML format). + +**Raises**: + +- `RuntimeError`: If the OpenAPI definitions cannot be downloaded or processed. +- `ValueError`: If the source type is not recognized or no functions are found in the OpenAPI definitions. + +**Returns**: + +A dictionary with the following keys: +- functions: Function definitions in JSON object format +- openapi_specs: OpenAPI specs in JSON/YAML object format with resolved references + + + +## Module output\_adapter + + + +### OutputAdaptationException + +Exception raised when there is an error during output adaptation. + + + +### OutputAdapter + +Adapts output of a Component using Jinja templates. + +Usage example: +```python +from haystack import Document +from haystack.components.converters import OutputAdapter + +adapter = OutputAdapter(template="{{ documents[0].content }}", output_type=str) +documents = [Document(content="Test content"] +result = adapter.run(documents=documents) + +assert result["output"] == "Test content" +``` + + + +#### OutputAdapter.\_\_init\_\_ + +```python +def __init__(template: str, + output_type: TypeAlias, + custom_filters: Optional[dict[str, Callable]] = None, + unsafe: bool = False) +``` + +Create an OutputAdapter component. + +**Arguments**: + +- `template`: A Jinja template that defines how to adapt the input data. +The variables in the template define the input of this instance. +e.g. +With this template: +``` +{{ documents[0].content }} +``` +The Component input will be `documents`. +- `output_type`: The type of output this instance will return. +- `custom_filters`: A dictionary of custom Jinja filters used in the template. +- `unsafe`: Enable execution of arbitrary code in the Jinja template. +This should only be used if you trust the source of the template as it can be lead to remote code execution. + + + +#### OutputAdapter.run + +```python +def run(**kwargs) +``` + +Renders the Jinja template with the provided inputs. + +**Arguments**: + +- `kwargs`: Must contain all variables used in the `template` string. + +**Raises**: + +- `OutputAdaptationException`: If template rendering fails. + +**Returns**: + +A dictionary with the following keys: +- `output`: Rendered Jinja template. + + + +#### OutputAdapter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OutputAdapter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OutputAdapter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module pdfminer + + + +#### CID\_PATTERN + +regex pattern to detect CID characters + + + +### PDFMinerToDocument + +Converts PDF files to Documents. + +Uses `pdfminer` compatible converters to convert PDF files to Documents. https://pdfminersix.readthedocs.io/en/latest/ + +Usage example: +```python +from haystack.components.converters.pdfminer import PDFMinerToDocument + +converter = PDFMinerToDocument() +results = converter.run(sources=["sample.pdf"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the PDF file.' +``` + + + +#### PDFMinerToDocument.\_\_init\_\_ + +```python +def __init__(line_overlap: float = 0.5, + char_margin: float = 2.0, + line_margin: float = 0.5, + word_margin: float = 0.1, + boxes_flow: Optional[float] = 0.5, + detect_vertical: bool = True, + all_texts: bool = False, + store_full_path: bool = False) -> None +``` + +Create a PDFMinerToDocument component. + +**Arguments**: + +- `line_overlap`: This parameter determines whether two characters are considered to be on +the same line based on the amount of overlap between them. +The overlap is calculated relative to the minimum height of both characters. +- `char_margin`: Determines whether two characters are part of the same line based on the distance between them. +If the distance is less than the margin specified, the characters are considered to be on the same line. +The margin is calculated relative to the width of the character. +- `word_margin`: Determines whether two characters on the same line are part of the same word +based on the distance between them. If the distance is greater than the margin specified, +an intermediate space will be added between them to make the text more readable. +The margin is calculated relative to the width of the character. +- `line_margin`: This parameter determines whether two lines are part of the same paragraph based on +the distance between them. If the distance is less than the margin specified, +the lines are considered to be part of the same paragraph. +The margin is calculated relative to the height of a line. +- `boxes_flow`: This parameter determines the importance of horizontal and vertical position when +determining the order of text boxes. A value between -1.0 and +1.0 can be set, +with -1.0 indicating that only horizontal position matters and +1.0 indicating +that only vertical position matters. Setting the value to 'None' will disable advanced +layout analysis, and text boxes will be ordered based on the position of their bottom left corner. +- `detect_vertical`: This parameter determines whether vertical text should be considered during layout analysis. +- `all_texts`: If layout analysis should be performed on text in figures. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### PDFMinerToDocument.detect\_undecoded\_cid\_characters + +```python +def detect_undecoded_cid_characters(text: str) -> dict[str, Any] +``` + +Look for character sequences of CID, i.e.: characters that haven't been properly decoded from their CID format. + +This is useful to detect if the text extractor is not able to extract the text correctly, e.g. if the PDF uses +non-standard fonts. + +A PDF font may include a ToUnicode map (mapping from character code to Unicode) to support operations like +searching strings or copy & paste in a PDF viewer. This map immediately provides the mapping the text extractor +needs. If that map is not available the text extractor cannot decode the CID characters and will return them +as is. + +see: https://pdfminersix.readthedocs.io/en/latest/faq.html#why-are-there-cid-x-values-in-the-textual-output + +:param: text: The text to check for undecoded CID characters +:returns: + A dictionary containing detection results + + + + +#### PDFMinerToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts PDF files to Documents. + +**Arguments**: + +- `sources`: List of PDF file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents + + + +## Module pptx + + + +### PPTXToDocument + +Converts PPTX files to Documents. + +Usage example: +```python +from haystack.components.converters.pptx import PPTXToDocument + +converter = PPTXToDocument() +results = converter.run(sources=["sample.pptx"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is the text from the PPTX file.' +``` + + + +#### PPTXToDocument.\_\_init\_\_ + +```python +def __init__(store_full_path: bool = False) +``` + +Create an PPTXToDocument component. + +**Arguments**: + +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### PPTXToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts PPTX files to Documents. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents + + + +## Module pypdf + + + +### PyPDFExtractionMode + +The mode to use for extracting text from a PDF. + + + +#### PyPDFExtractionMode.\_\_str\_\_ + +```python +def __str__() -> str +``` + +Convert a PyPDFExtractionMode enum to a string. + + + +#### PyPDFExtractionMode.from\_str + +```python +@staticmethod +def from_str(string: str) -> "PyPDFExtractionMode" +``` + +Convert a string to a PyPDFExtractionMode enum. + + + +### PyPDFToDocument + +Converts PDF files to documents your pipeline can query. + +This component uses the PyPDF library. +You can attach metadata to the resulting documents. + +### Usage example + +```python +from haystack.components.converters.pypdf import PyPDFToDocument + +converter = PyPDFToDocument() +results = converter.run(sources=["sample.pdf"], meta={"date_added": datetime.now().isoformat()}) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the PDF file.' +``` + + + +#### PyPDFToDocument.\_\_init\_\_ + +```python +def __init__(*, + extraction_mode: Union[ + str, PyPDFExtractionMode] = PyPDFExtractionMode.PLAIN, + plain_mode_orientations: tuple = (0, 90, 180, 270), + plain_mode_space_width: float = 200.0, + layout_mode_space_vertically: bool = True, + layout_mode_scale_weight: float = 1.25, + layout_mode_strip_rotated: bool = True, + layout_mode_font_height_weight: float = 1.0, + store_full_path: bool = False) +``` + +Create an PyPDFToDocument component. + +**Arguments**: + +- `extraction_mode`: The mode to use for extracting text from a PDF. +Layout mode is an experimental mode that adheres to the rendered layout of the PDF. +- `plain_mode_orientations`: Tuple of orientations to look for when extracting text from a PDF in plain mode. +Ignored if `extraction_mode` is `PyPDFExtractionMode.LAYOUT`. +- `plain_mode_space_width`: Forces default space width if not extracted from font. +Ignored if `extraction_mode` is `PyPDFExtractionMode.LAYOUT`. +- `layout_mode_space_vertically`: Whether to include blank lines inferred from y distance + font height. +Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. +- `layout_mode_scale_weight`: Multiplier for string length when calculating weighted average character width. +Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. +- `layout_mode_strip_rotated`: Layout mode does not support rotated text. Set to `False` to include rotated text anyway. +If rotated text is discovered, layout will be degraded and a warning will be logged. +Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. +- `layout_mode_font_height_weight`: Multiplier for font height when calculating blank line height. +Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### PyPDFToDocument.to\_dict + +```python +def to_dict() +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PyPDFToDocument.from\_dict + +```python +@classmethod +def from_dict(cls, data) +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +Deserialized component. + + + +#### PyPDFToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts PDF files to documents. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects to convert. +- `meta`: Optional metadata to attach to the documents. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, its length must match the number of sources, as they are zipped together. +For ByteStream objects, their `meta` is added to the output documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of converted documents. + + + +## Module tika + + + +### XHTMLParser + +Custom parser to extract pages from Tika XHTML content. + + + +#### XHTMLParser.handle\_starttag + +```python +def handle_starttag(tag: str, attrs: list[tuple]) +``` + +Identify the start of a page div. + + + +#### XHTMLParser.handle\_endtag + +```python +def handle_endtag(tag: str) +``` + +Identify the end of a page div. + + + +#### XHTMLParser.handle\_data + +```python +def handle_data(data: str) +``` + +Populate the page content. + + + +### TikaDocumentConverter + +Converts files of different types to Documents. + +This component uses [Apache Tika](https://tika.apache.org/) for parsing the files and, therefore, +requires a running Tika server. +For more options on running Tika, +see the [official documentation](https://github.com/apache/tika-docker/blob/main/README.md#usage). + +Usage example: +```python +from haystack.components.converters.tika import TikaDocumentConverter + +converter = TikaDocumentConverter() +results = converter.run( + sources=["sample.docx", "my_document.rtf", "archive.zip"], + meta={"date_added": datetime.now().isoformat()} +) +documents = results["documents"] +print(documents[0].content) +# 'This is a text from the docx file.' +``` + + + +#### TikaDocumentConverter.\_\_init\_\_ + +```python +def __init__(tika_url: str = "http://localhost:9998/tika", + store_full_path: bool = False) +``` + +Create a TikaDocumentConverter component. + +**Arguments**: + +- `tika_url`: Tika server URL. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### TikaDocumentConverter.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts files to Documents. + +**Arguments**: + +- `sources`: List of HTML file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output Documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created Documents + + + +## Module txt + + + +### TextFileToDocument + +Converts text files to documents your pipeline can query. + +By default, it uses UTF-8 encoding when converting files but +you can also set custom encoding. +It can attach metadata to the resulting documents. + +### Usage example + +```python +from haystack.components.converters.txt import TextFileToDocument + +converter = TextFileToDocument() +results = converter.run(sources=["sample.txt"]) +documents = results["documents"] +print(documents[0].content) +# 'This is the content from the txt file.' +``` + + + +#### TextFileToDocument.\_\_init\_\_ + +```python +def __init__(encoding: str = "utf-8", store_full_path: bool = False) +``` + +Creates a TextFileToDocument component. + +**Arguments**: + +- `encoding`: The encoding of the text files to convert. +If the encoding is specified in the metadata of a source ByteStream, +it overrides this value. +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### TextFileToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None) +``` + +Converts text files to documents. + +**Arguments**: + +- `sources`: List of text file paths or ByteStream objects to convert. +- `meta`: Optional metadata to attach to the documents. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, its length must match the number of sources as they're zipped together. +For ByteStream objects, their `meta` is added to the output documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of converted documents. + + + +## Module xlsx + + + +### XLSXToDocument + +Converts XLSX (Excel) files into Documents. + + Supports reading data from specific sheets or all sheets in the Excel file. If all sheets are read, a Document is + created for each sheet. The content of the Document is the table which can be saved in CSV or Markdown format. + + ### Usage example + + ```python + from haystack.components.converters.xlsx import XLSXToDocument + + converter = XLSXToDocument() + results = converter.run(sources=["sample.xlsx"], meta={"date_added": datetime.now().isoformat()}) + documents = results["documents"] + print(documents[0].content) + # ",A,B +1,col_a,col_b +2,1.5,test +" + ``` + + + +#### XLSXToDocument.\_\_init\_\_ + +```python +def __init__(table_format: Literal["csv", "markdown"] = "csv", + sheet_name: Union[str, int, list[Union[str, int]], None] = None, + read_excel_kwargs: Optional[dict[str, Any]] = None, + table_format_kwargs: Optional[dict[str, Any]] = None, + *, + store_full_path: bool = False) +``` + +Creates a XLSXToDocument component. + +**Arguments**: + +- `table_format`: The format to convert the Excel file to. +- `sheet_name`: The name of the sheet to read. If None, all sheets are read. +- `read_excel_kwargs`: Additional arguments to pass to `pandas.read_excel`. +See https://pandas.pydata.org/docs/reference/api/pandas.read_excel.html#pandas-read-excel +- `table_format_kwargs`: Additional keyword arguments to pass to the table format function. +- If `table_format` is "csv", these arguments are passed to `pandas.DataFrame.to_csv`. + See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_csv.html#pandas-dataframe-to-csv +- If `table_format` is "markdown", these arguments are passed to `pandas.DataFrame.to_markdown`. + See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html#pandas-dataframe-to-markdown +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### XLSXToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run( + sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None +) -> dict[str, list[Document]] +``` + +Converts a XLSX file to a Document. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects. +- `meta`: Optional metadata to attach to the documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, the length of the list must match the number of sources, because the two lists will +be zipped. +If `sources` contains ByteStream objects, their `meta` will be added to the output documents. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Created documents + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/data_classes_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/data_classes_api.md new file mode 100644 index 0000000000..b0f3b9ff62 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/data_classes_api.md @@ -0,0 +1,1331 @@ +--- +title: "Data Classes" +id: data-classes-api +description: "Core classes that carry data through the system." +slug: "/data-classes-api" +--- + + + +## Module answer + + + +### ExtractedAnswer + + + +#### ExtractedAnswer.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the object to a dictionary. + +**Returns**: + +Serialized dictionary representation of the object. + + + +#### ExtractedAnswer.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ExtractedAnswer" +``` + +Deserialize the object from a dictionary. + +**Arguments**: + +- `data`: Dictionary representation of the object. + +**Returns**: + +Deserialized object. + + + +### GeneratedAnswer + + + +#### GeneratedAnswer.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the object to a dictionary. + +**Returns**: + +Serialized dictionary representation of the object. + + + +#### GeneratedAnswer.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "GeneratedAnswer" +``` + +Deserialize the object from a dictionary. + +**Arguments**: + +- `data`: Dictionary representation of the object. + +**Returns**: + +Deserialized object. + + + +## Module byte\_stream + + + +### ByteStream + +Base data class representing a binary object in the Haystack API. + +**Arguments**: + +- `data`: The binary data stored in Bytestream. +- `meta`: Additional metadata to be stored with the ByteStream. +- `mime_type`: The mime type of the binary data. + + + +#### ByteStream.to\_file + +```python +def to_file(destination_path: Path) -> None +``` + +Write the ByteStream to a file. Note: the metadata will be lost. + +**Arguments**: + +- `destination_path`: The path to write the ByteStream to. + + + +#### ByteStream.from\_file\_path + +```python +@classmethod +def from_file_path(cls, + filepath: Path, + mime_type: Optional[str] = None, + meta: Optional[dict[str, Any]] = None, + guess_mime_type: bool = False) -> "ByteStream" +``` + +Create a ByteStream from the contents read from a file. + +**Arguments**: + +- `filepath`: A valid path to a file. +- `mime_type`: The mime type of the file. +- `meta`: Additional metadata to be stored with the ByteStream. +- `guess_mime_type`: Whether to guess the mime type from the file. + + + +#### ByteStream.from\_string + +```python +@classmethod +def from_string(cls, + text: str, + encoding: str = "utf-8", + mime_type: Optional[str] = None, + meta: Optional[dict[str, Any]] = None) -> "ByteStream" +``` + +Create a ByteStream encoding a string. + +**Arguments**: + +- `text`: The string to encode +- `encoding`: The encoding used to convert the string into bytes +- `mime_type`: The mime type of the file. +- `meta`: Additional metadata to be stored with the ByteStream. + + + +#### ByteStream.to\_string + +```python +def to_string(encoding: str = "utf-8") -> str +``` + +Convert the ByteStream to a string, metadata will not be included. + +**Arguments**: + +- `encoding`: The encoding used to convert the bytes to a string. Defaults to "utf-8". + +**Raises**: + +- `None`: UnicodeDecodeError: If the ByteStream data cannot be decoded with the specified encoding. + +**Returns**: + +The string representation of the ByteStream. + + + +#### ByteStream.\_\_repr\_\_ + +```python +def __repr__() -> str +``` + +Return a string representation of the ByteStream, truncating the data to 100 bytes. + + + +#### ByteStream.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert the ByteStream to a dictionary representation. + +**Returns**: + +A dictionary with keys 'data', 'meta', and 'mime_type'. + + + +#### ByteStream.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ByteStream" +``` + +Create a ByteStream from a dictionary representation. + +**Arguments**: + +- `data`: A dictionary with keys 'data', 'meta', and 'mime_type'. + +**Returns**: + +A ByteStream instance. + + + +## Module chat\_message + + + +### ChatRole + +Enumeration representing the roles within a chat. + + + +#### USER + +The user role. A message from the user contains only text. + + + +#### SYSTEM + +The system role. A message from the system contains only text. + + + +#### ASSISTANT + +The assistant role. A message from the assistant can contain text and Tool calls. It can also store metadata. + + + +#### TOOL + +The tool role. A message from a tool contains the result of a Tool invocation. + + + +#### ChatRole.from\_str + +```python +@staticmethod +def from_str(string: str) -> "ChatRole" +``` + +Convert a string to a ChatRole enum. + + + +### ToolCall + +Represents a Tool call prepared by the model, usually contained in an assistant message. + +**Arguments**: + +- `id`: The ID of the Tool call. +- `tool_name`: The name of the Tool to call. +- `arguments`: The arguments to call the Tool with. +- `extra`: Dictionary of extra information about the Tool call. Use to store provider-specific +information. To avoid serialization issues, values should be JSON serializable. + + + +#### id + +noqa: A003 + + + +#### ToolCall.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert ToolCall into a dictionary. + +**Returns**: + +A dictionary with keys 'tool_name', 'arguments', 'id', and 'extra'. + + + +#### ToolCall.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ToolCall" +``` + +Creates a new ToolCall object from a dictionary. + +**Arguments**: + +- `data`: The dictionary to build the ToolCall object. + +**Returns**: + +The created object. + + + +### ToolCallResult + +Represents the result of a Tool invocation. + +**Arguments**: + +- `result`: The result of the Tool invocation. +- `origin`: The Tool call that produced this result. +- `error`: Whether the Tool invocation resulted in an error. + + + +#### ToolCallResult.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Converts ToolCallResult into a dictionary. + +**Returns**: + +A dictionary with keys 'result', 'origin', and 'error'. + + + +#### ToolCallResult.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ToolCallResult" +``` + +Creates a ToolCallResult from a dictionary. + +**Arguments**: + +- `data`: The dictionary to build the ToolCallResult object. + +**Returns**: + +The created object. + + + +### TextContent + +The textual content of a chat message. + +**Arguments**: + +- `text`: The text content of the message. + + + +#### TextContent.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert TextContent into a dictionary. + + + +#### TextContent.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "TextContent" +``` + +Create a TextContent from a dictionary. + + + +### ReasoningContent + +Represents the optional reasoning content prepared by the model, usually contained in an assistant message. + +**Arguments**: + +- `reasoning_text`: The reasoning text produced by the model. +- `extra`: Dictionary of extra information about the reasoning content. Use to store provider-specific +information. To avoid serialization issues, values should be JSON serializable. + + + +#### ReasoningContent.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert ReasoningContent into a dictionary. + +**Returns**: + +A dictionary with keys 'reasoning_text', and 'extra'. + + + +#### ReasoningContent.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ReasoningContent" +``` + +Creates a new ReasoningContent object from a dictionary. + +**Arguments**: + +- `data`: The dictionary to build the ReasoningContent object. + +**Returns**: + +The created object. + + + +### ChatMessage + +Represents a message in a LLM chat conversation. + +Use the `from_assistant`, `from_user`, `from_system`, and `from_tool` class methods to create a ChatMessage. + + + +#### ChatMessage.\_\_new\_\_ + +```python +def __new__(cls, *args, **kwargs) +``` + +This method is reimplemented to make the changes to the `ChatMessage` dataclass more visible. + + + +#### ChatMessage.\_\_getattribute\_\_ + +```python +def __getattribute__(name) +``` + +This method is reimplemented to make the `content` attribute removal more visible. + + + +#### ChatMessage.role + +```python +@property +def role() -> ChatRole +``` + +Returns the role of the entity sending the message. + + + +#### ChatMessage.meta + +```python +@property +def meta() -> dict[str, Any] +``` + +Returns the metadata associated with the message. + + + +#### ChatMessage.name + +```python +@property +def name() -> Optional[str] +``` + +Returns the name associated with the message. + + + +#### ChatMessage.texts + +```python +@property +def texts() -> list[str] +``` + +Returns the list of all texts contained in the message. + + + +#### ChatMessage.text + +```python +@property +def text() -> Optional[str] +``` + +Returns the first text contained in the message. + + + +#### ChatMessage.tool\_calls + +```python +@property +def tool_calls() -> list[ToolCall] +``` + +Returns the list of all Tool calls contained in the message. + + + +#### ChatMessage.tool\_call + +```python +@property +def tool_call() -> Optional[ToolCall] +``` + +Returns the first Tool call contained in the message. + + + +#### ChatMessage.tool\_call\_results + +```python +@property +def tool_call_results() -> list[ToolCallResult] +``` + +Returns the list of all Tool call results contained in the message. + + + +#### ChatMessage.tool\_call\_result + +```python +@property +def tool_call_result() -> Optional[ToolCallResult] +``` + +Returns the first Tool call result contained in the message. + + + +#### ChatMessage.images + +```python +@property +def images() -> list[ImageContent] +``` + +Returns the list of all images contained in the message. + + + +#### ChatMessage.image + +```python +@property +def image() -> Optional[ImageContent] +``` + +Returns the first image contained in the message. + + + +#### ChatMessage.reasonings + +```python +@property +def reasonings() -> list[ReasoningContent] +``` + +Returns the list of all reasoning contents contained in the message. + + + +#### ChatMessage.reasoning + +```python +@property +def reasoning() -> Optional[ReasoningContent] +``` + +Returns the first reasoning content contained in the message. + + + +#### ChatMessage.is\_from + +```python +def is_from(role: Union[ChatRole, str]) -> bool +``` + +Check if the message is from a specific role. + +**Arguments**: + +- `role`: The role to check against. + +**Returns**: + +True if the message is from the specified role, False otherwise. + + + +#### ChatMessage.from\_user + +```python +@classmethod +def from_user( + cls, + text: Optional[str] = None, + meta: Optional[dict[str, Any]] = None, + name: Optional[str] = None, + *, + content_parts: Optional[Sequence[Union[TextContent, str, + ImageContent]]] = None +) -> "ChatMessage" +``` + +Create a message from the user. + +**Arguments**: + +- `text`: The text content of the message. Specify this or content_parts. +- `meta`: Additional metadata associated with the message. +- `name`: An optional name for the participant. This field is only supported by OpenAI. +- `content_parts`: A list of content parts to include in the message. Specify this or text. + +**Returns**: + +A new ChatMessage instance. + + + +#### ChatMessage.from\_system + +```python +@classmethod +def from_system(cls, + text: str, + meta: Optional[dict[str, Any]] = None, + name: Optional[str] = None) -> "ChatMessage" +``` + +Create a message from the system. + +**Arguments**: + +- `text`: The text content of the message. +- `meta`: Additional metadata associated with the message. +- `name`: An optional name for the participant. This field is only supported by OpenAI. + +**Returns**: + +A new ChatMessage instance. + + + +#### ChatMessage.from\_assistant + +```python +@classmethod +def from_assistant( + cls, + text: Optional[str] = None, + meta: Optional[dict[str, Any]] = None, + name: Optional[str] = None, + tool_calls: Optional[list[ToolCall]] = None, + *, + reasoning: Optional[Union[str, + ReasoningContent]] = None) -> "ChatMessage" +``` + +Create a message from the assistant. + +**Arguments**: + +- `text`: The text content of the message. +- `meta`: Additional metadata associated with the message. +- `name`: An optional name for the participant. This field is only supported by OpenAI. +- `tool_calls`: The Tool calls to include in the message. +- `reasoning`: The reasoning content to include in the message. + +**Returns**: + +A new ChatMessage instance. + + + +#### ChatMessage.from\_tool + +```python +@classmethod +def from_tool(cls, + tool_result: str, + origin: ToolCall, + error: bool = False, + meta: Optional[dict[str, Any]] = None) -> "ChatMessage" +``` + +Create a message from a Tool. + +**Arguments**: + +- `tool_result`: The result of the Tool invocation. +- `origin`: The Tool call that produced this result. +- `error`: Whether the Tool invocation resulted in an error. +- `meta`: Additional metadata associated with the message. + +**Returns**: + +A new ChatMessage instance. + + + +#### ChatMessage.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Converts ChatMessage into a dictionary. + +**Returns**: + +Serialized version of the object. + + + +#### ChatMessage.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ChatMessage" +``` + +Creates a new ChatMessage object from a dictionary. + +**Arguments**: + +- `data`: The dictionary to build the ChatMessage object. + +**Returns**: + +The created object. + + + +#### ChatMessage.to\_openai\_dict\_format + +```python +def to_openai_dict_format( + require_tool_call_ids: bool = True) -> dict[str, Any] +``` + +Convert a ChatMessage to the dictionary format expected by OpenAI's Chat API. + +**Arguments**: + +- `require_tool_call_ids`: If True (default), enforces that each Tool Call includes a non-null `id` attribute. +Set to False to allow Tool Calls without `id`, which may be suitable for shallow OpenAI-compatible APIs. + +**Raises**: + +- `ValueError`: If the message format is invalid, or if `require_tool_call_ids` is True and any Tool Call is missing an +`id` attribute. + +**Returns**: + +The ChatMessage in the format expected by OpenAI's Chat API. + + + +#### ChatMessage.from\_openai\_dict\_format + +```python +@classmethod +def from_openai_dict_format(cls, message: dict[str, Any]) -> "ChatMessage" +``` + +Create a ChatMessage from a dictionary in the format expected by OpenAI's Chat API. + +NOTE: While OpenAI's API requires `tool_call_id` in both tool calls and tool messages, this method +accepts messages without it to support shallow OpenAI-compatible APIs. +If you plan to use the resulting ChatMessage with OpenAI, you must include `tool_call_id` or you'll +encounter validation errors. + +**Arguments**: + +- `message`: The OpenAI dictionary to build the ChatMessage object. + +**Raises**: + +- `ValueError`: If the message dictionary is missing required fields. + +**Returns**: + +The created ChatMessage object. + + + +## Module document + + + +### \_BackwardCompatible + +Metaclass that handles Document backward compatibility. + + + +#### \_BackwardCompatible.\_\_call\_\_ + +```python +def __call__(cls, *args, **kwargs) +``` + +Called before Document.__init__, handles legacy fields. + +Embedding was stored as NumPy arrays in 1.x, so we convert it to a list of floats. +Other legacy fields are removed. + + + +### Document + +Base data class containing some data to be queried. + +Can contain text snippets and file paths to images or audios. Documents can be sorted by score and saved +to/from dictionary and JSON. + +**Arguments**: + +- `id`: Unique identifier for the document. When not set, it's generated based on the Document fields' values. +- `content`: Text of the document, if the document contains text. +- `blob`: Binary data associated with the document, if the document has any binary data associated with it. +- `meta`: Additional custom metadata for the document. Must be JSON-serializable. +- `score`: Score of the document. Used for ranking, usually assigned by retrievers. +- `embedding`: dense vector representation of the document. +- `sparse_embedding`: sparse vector representation of the document. + + + +#### Document.\_\_eq\_\_ + +```python +def __eq__(other) +``` + +Compares Documents for equality. + +Two Documents are considered equals if their dictionary representation is identical. + + + +#### Document.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Generate the ID based on the init parameters. + + + +#### Document.to\_dict + +```python +def to_dict(flatten: bool = True) -> dict[str, Any] +``` + +Converts Document into a dictionary. + +`blob` field is converted to a JSON-serializable type. + +**Arguments**: + +- `flatten`: Whether to flatten `meta` field or not. Defaults to `True` to be backward-compatible with Haystack 1.x. + + + +#### Document.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Document" +``` + +Creates a new Document object from a dictionary. + +The `blob` field is converted to its original type. + + + +#### Document.content\_type + +```python +@property +def content_type() +``` + +Returns the type of the content for the document. + +This is necessary to keep backward compatibility with 1.x. + + + +## Module image\_content + + + +### ImageContent + +The image content of a chat message. + +**Arguments**: + +- `base64_image`: A base64 string representing the image. +- `mime_type`: The MIME type of the image (e.g. "image/png", "image/jpeg"). +Providing this value is recommended, as most LLM providers require it. +If not provided, the MIME type is guessed from the base64 string, which can be slow and not always reliable. +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +- `meta`: Optional metadata for the image. +- `validation`: If True (default), a validation process is performed: +- Check whether the base64 string is valid; +- Guess the MIME type if not provided; +- Check if the MIME type is a valid image MIME type. +Set to False to skip validation and speed up initialization. + + + +#### ImageContent.\_\_repr\_\_ + +```python +def __repr__() -> str +``` + +Return a string representation of the ImageContent, truncating the base64_image to 100 bytes. + + + +#### ImageContent.show + +```python +def show() -> None +``` + +Shows the image. + + + +#### ImageContent.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert ImageContent into a dictionary. + + + +#### ImageContent.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ImageContent" +``` + +Create an ImageContent from a dictionary. + + + +#### ImageContent.from\_file\_path + +```python +@classmethod +def from_file_path(cls, + file_path: Union[str, Path], + *, + size: Optional[tuple[int, int]] = None, + detail: Optional[Literal["auto", "high", "low"]] = None, + meta: Optional[dict[str, Any]] = None) -> "ImageContent" +``` + +Create an ImageContent object from a file path. + +It exposes similar functionality as the `ImageFileToImageContent` component. For PDF to ImageContent conversion, +use the `PDFToImageContent` component. + +**Arguments**: + +- `file_path`: The path to the image file. PDF files are not supported. For PDF to ImageContent conversion, use the +`PDFToImageContent` component. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +- `meta`: Additional metadata for the image. + +**Returns**: + +An ImageContent object. + + + +#### ImageContent.from\_url + +```python +@classmethod +def from_url(cls, + url: str, + *, + retry_attempts: int = 2, + timeout: int = 10, + size: Optional[tuple[int, int]] = None, + detail: Optional[Literal["auto", "high", "low"]] = None, + meta: Optional[dict[str, Any]] = None) -> "ImageContent" +``` + +Create an ImageContent object from a URL. The image is downloaded and converted to a base64 string. + +For PDF to ImageContent conversion, use the `PDFToImageContent` component. + +**Arguments**: + +- `url`: The URL of the image. PDF files are not supported. For PDF to ImageContent conversion, use the +`PDFToImageContent` component. +- `retry_attempts`: The number of times to retry to fetch the URL's content. +- `timeout`: Timeout in seconds for the request. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +- `meta`: Additional metadata for the image. + +**Raises**: + +- `ValueError`: If the URL does not point to an image or if it points to a PDF file. + +**Returns**: + +An ImageContent object. + + + +## Module sparse\_embedding + + + +### SparseEmbedding + +Class representing a sparse embedding. + +**Arguments**: + +- `indices`: List of indices of non-zero elements in the embedding. +- `values`: List of values of non-zero elements in the embedding. + + + +#### SparseEmbedding.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Checks if the indices and values lists are of the same length. + +Raises a ValueError if they are not. + + + +#### SparseEmbedding.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert the SparseEmbedding object to a dictionary. + +**Returns**: + +Serialized sparse embedding. + + + +#### SparseEmbedding.from\_dict + +```python +@classmethod +def from_dict(cls, sparse_embedding_dict: dict[str, Any]) -> "SparseEmbedding" +``` + +Deserializes the sparse embedding from a dictionary. + +**Arguments**: + +- `sparse_embedding_dict`: Dictionary to deserialize from. + +**Returns**: + +Deserialized sparse embedding. + + + +## Module streaming\_chunk + + + +### ToolCallDelta + +Represents a Tool call prepared by the model, usually contained in an assistant message. + +**Arguments**: + +- `index`: The index of the Tool call in the list of Tool calls. +- `tool_name`: The name of the Tool to call. +- `arguments`: Either the full arguments in JSON format or a delta of the arguments. +- `id`: The ID of the Tool call. +- `extra`: Dictionary of extra information about the Tool call. Use to store provider-specific +information. To avoid serialization issues, values should be JSON serializable. + + + +#### ToolCallDelta.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of the ToolCallDelta. + +**Returns**: + +A dictionary with keys 'index', 'tool_name', 'arguments', 'id', and 'extra'. + + + +#### ToolCallDelta.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ToolCallDelta" +``` + +Creates a ToolCallDelta from a serialized representation. + +**Arguments**: + +- `data`: Dictionary containing ToolCallDelta's attributes. + +**Returns**: + +A ToolCallDelta instance. + + + +### ComponentInfo + +The `ComponentInfo` class encapsulates information about a component. + +**Arguments**: + +- `type`: The type of the component. +- `name`: The name of the component assigned when adding it to a pipeline. + + + +#### ComponentInfo.from\_component + +```python +@classmethod +def from_component(cls, component: Component) -> "ComponentInfo" +``` + +Create a `ComponentInfo` object from a `Component` instance. + +**Arguments**: + +- `component`: The `Component` instance. + +**Returns**: + +The `ComponentInfo` object with the type and name of the given component. + + + +#### ComponentInfo.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of ComponentInfo. + +**Returns**: + +A dictionary with keys 'type' and 'name'. + + + +#### ComponentInfo.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ComponentInfo" +``` + +Creates a ComponentInfo from a serialized representation. + +**Arguments**: + +- `data`: Dictionary containing ComponentInfo's attributes. + +**Returns**: + +A ComponentInfo instance. + + + +### StreamingChunk + +The `StreamingChunk` class encapsulates a segment of streamed content along with associated metadata. + +This structure facilitates the handling and processing of streamed data in a systematic manner. + +**Arguments**: + +- `content`: The content of the message chunk as a string. +- `meta`: A dictionary containing metadata related to the message chunk. +- `component_info`: A `ComponentInfo` object containing information about the component that generated the chunk, +such as the component name and type. +- `index`: An optional integer index representing which content block this chunk belongs to. +- `tool_calls`: An optional list of ToolCallDelta object representing a tool call associated with the message +chunk. +- `tool_call_result`: An optional ToolCallResult object representing the result of a tool call. +- `start`: A boolean indicating whether this chunk marks the start of a content block. +- `finish_reason`: An optional value indicating the reason the generation finished. +Standard values follow OpenAI's convention: "stop", "length", "tool_calls", "content_filter", +plus Haystack-specific value "tool_call_results". +- `reasoning`: An optional ReasoningContent object representing the reasoning content associated +with the message chunk. + + + +#### StreamingChunk.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of the StreamingChunk. + +**Returns**: + +Serialized dictionary representation of the calling object. + + + +#### StreamingChunk.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "StreamingChunk" +``` + +Creates a deserialized StreamingChunk instance from a serialized representation. + +**Arguments**: + +- `data`: Dictionary containing the StreamingChunk's attributes. + +**Returns**: + +A StreamingChunk instance. + + + +#### select\_streaming\_callback + +```python +def select_streaming_callback( + init_callback: Optional[StreamingCallbackT], + runtime_callback: Optional[StreamingCallbackT], + requires_async: bool) -> Optional[StreamingCallbackT] +``` + +Picks the correct streaming callback given an optional initial and runtime callback. + +The runtime callback takes precedence over the initial callback. + +**Arguments**: + +- `init_callback`: The initial callback. +- `runtime_callback`: The runtime callback. +- `requires_async`: Whether the selected callback must be async compatible. + +**Returns**: + +The selected callback. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_stores_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_stores_api.md new file mode 100644 index 0000000000..6cf2a11286 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_stores_api.md @@ -0,0 +1,382 @@ +--- +title: "Document Stores" +id: document-stores-api +description: "Stores your texts and meta data and provides them to the Retriever at query time." +slug: "/document-stores-api" +--- + + + +## Module document\_store + + + +### BM25DocumentStats + +A dataclass for managing document statistics for BM25 retrieval. + +**Arguments**: + +- `freq_token`: A Counter of token frequencies in the document. +- `doc_len`: Number of tokens in the document. + + + +### InMemoryDocumentStore + +Stores data in-memory. It's ephemeral and cannot be saved to disk. + + + +#### InMemoryDocumentStore.\_\_init\_\_ + +```python +def __init__(bm25_tokenization_regex: str = r"(?u)\b\w\w+\b", + bm25_algorithm: Literal["BM25Okapi", "BM25L", + "BM25Plus"] = "BM25L", + bm25_parameters: Optional[dict] = None, + embedding_similarity_function: Literal["dot_product", + "cosine"] = "dot_product", + index: Optional[str] = None, + async_executor: Optional[ThreadPoolExecutor] = None, + return_embedding: bool = True) +``` + +Initializes the DocumentStore. + +**Arguments**: + +- `bm25_tokenization_regex`: The regular expression used to tokenize the text for BM25 retrieval. +- `bm25_algorithm`: The BM25 algorithm to use. One of "BM25Okapi", "BM25L", or "BM25Plus". +- `bm25_parameters`: Parameters for BM25 implementation in a dictionary format. +For example: `{'k1':1.5, 'b':0.75, 'epsilon':0.25}` +You can learn more about these parameters by visiting https://github.com/dorianbrown/rank_bm25. +- `embedding_similarity_function`: The similarity function used to compare Documents embeddings. +One of "dot_product" (default) or "cosine". To choose the most appropriate function, look for information +about your embedding model. +- `index`: A specific index to store the documents. If not specified, a random UUID is used. +Using the same index allows you to store documents across multiple InMemoryDocumentStore instances. +- `async_executor`: Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded +executor will be initialized and used. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. Default is True. + + + +#### InMemoryDocumentStore.\_\_del\_\_ + +```python +def __del__() +``` + +Cleanup when the instance is being destroyed. + + + +#### InMemoryDocumentStore.shutdown + +```python +def shutdown() +``` + +Explicitly shutdown the executor if we own it. + + + +#### InMemoryDocumentStore.storage + +```python +@property +def storage() -> dict[str, Document] +``` + +Utility property that returns the storage used by this instance of InMemoryDocumentStore. + + + +#### InMemoryDocumentStore.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### InMemoryDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "InMemoryDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### InMemoryDocumentStore.save\_to\_disk + +```python +def save_to_disk(path: str) -> None +``` + +Write the database and its' data to disk as a JSON file. + +**Arguments**: + +- `path`: The path to the JSON file. + + + +#### InMemoryDocumentStore.load\_from\_disk + +```python +@classmethod +def load_from_disk(cls, path: str) -> "InMemoryDocumentStore" +``` + +Load the database and its' data from disk as a JSON file. + +**Arguments**: + +- `path`: The path to the JSON file. + +**Returns**: + +The loaded InMemoryDocumentStore. + + + +#### InMemoryDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns the number of how many documents are present in the DocumentStore. + + + +#### InMemoryDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[dict[str, Any]] = None) -> list[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, refer to the DocumentStore.filter_documents() protocol +documentation. + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### InMemoryDocumentStore.write\_documents + +```python +def write_documents(documents: list[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Refer to the DocumentStore.write_documents() protocol documentation. + +If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`. + + + +#### InMemoryDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: list[str]) -> None +``` + +Deletes all documents with matching document_ids from the DocumentStore. + +**Arguments**: + +- `document_ids`: The object_ids to delete. + + + +#### InMemoryDocumentStore.bm25\_retrieval + +```python +def bm25_retrieval(query: str, + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False) -> list[Document] +``` + +Retrieves documents that are most relevant to the query using BM25 algorithm. + +**Arguments**: + +- `query`: The query string. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The number of top documents to retrieve. Default is 10. +- `scale_score`: Whether to scale the scores of the retrieved documents. Default is False. + +**Returns**: + +A list of the top_k documents most relevant to the query. + + + +#### InMemoryDocumentStore.embedding\_retrieval + +```python +def embedding_retrieval( + query_embedding: list[float], + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False, + return_embedding: Optional[bool] = False) -> list[Document] +``` + +Retrieves documents that are most similar to the query embedding using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The number of top documents to retrieve. Default is 10. +- `scale_score`: Whether to scale the scores of the retrieved Documents. Default is False. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +If not provided, the value of the `return_embedding` parameter set at component +initialization will be used. Default is False. + +**Returns**: + +A list of the top_k documents most relevant to the query. + + + +#### InMemoryDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Returns the number of how many documents are present in the DocumentStore. + + + +#### InMemoryDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[dict[str, Any]] = None) -> list[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, refer to the DocumentStore.filter_documents() protocol +documentation. + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### InMemoryDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: list[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Refer to the DocumentStore.write_documents() protocol documentation. + +If `policy` is set to `DuplicatePolicy.NONE` defaults to `DuplicatePolicy.FAIL`. + + + +#### InMemoryDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: list[str]) -> None +``` + +Deletes all documents with matching document_ids from the DocumentStore. + +**Arguments**: + +- `document_ids`: The object_ids to delete. + + + +#### InMemoryDocumentStore.bm25\_retrieval\_async + +```python +async def bm25_retrieval_async(query: str, + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False) -> list[Document] +``` + +Retrieves documents that are most relevant to the query using BM25 algorithm. + +**Arguments**: + +- `query`: The query string. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The number of top documents to retrieve. Default is 10. +- `scale_score`: Whether to scale the scores of the retrieved documents. Default is False. + +**Returns**: + +A list of the top_k documents most relevant to the query. + + + +#### InMemoryDocumentStore.embedding\_retrieval\_async + +```python +async def embedding_retrieval_async( + query_embedding: list[float], + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False, + return_embedding: bool = False) -> list[Document] +``` + +Retrieves documents that are most similar to the query embedding using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The number of top documents to retrieve. Default is 10. +- `scale_score`: Whether to scale the scores of the retrieved Documents. Default is False. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. Default is False. + +**Returns**: + +A list of the top_k documents most relevant to the query. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_writers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_writers_api.md new file mode 100644 index 0000000000..f6393052b1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/document_writers_api.md @@ -0,0 +1,140 @@ +--- +title: "Document Writers" +id: document-writers-api +description: "Writes Documents to a DocumentStore." +slug: "/document-writers-api" +--- + + + +## Module document\_writer + + + +### DocumentWriter + +Writes documents to a DocumentStore. + +### Usage example +```python +from haystack import Document +from haystack.components.writers import DocumentWriter +from haystack.document_stores.in_memory import InMemoryDocumentStore +docs = [ + Document(content="Python is a popular programming language"), +] +doc_store = InMemoryDocumentStore() +writer = DocumentWriter(document_store=doc_store) +writer.run(docs) +``` + + + +#### DocumentWriter.\_\_init\_\_ + +```python +def __init__(document_store: DocumentStore, + policy: DuplicatePolicy = DuplicatePolicy.NONE) +``` + +Create a DocumentWriter component. + +**Arguments**: + +- `document_store`: The instance of the document store where you want to store your documents. +- `policy`: The policy to apply when a Document with the same ID already exists in the DocumentStore. +- `DuplicatePolicy.NONE`: Default policy, relies on the DocumentStore settings. +- `DuplicatePolicy.SKIP`: Skips documents with the same ID and doesn't write them to the DocumentStore. +- `DuplicatePolicy.OVERWRITE`: Overwrites documents with the same ID. +- `DuplicatePolicy.FAIL`: Raises an error if a Document with the same ID is already in the DocumentStore. + + + +#### DocumentWriter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### DocumentWriter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DocumentWriter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Raises**: + +- `DeserializationError`: If the document store is not properly specified in the serialization data or its type cannot be imported. + +**Returns**: + +The deserialized component. + + + +#### DocumentWriter.run + +```python +@component.output_types(documents_written=int) +def run(documents: list[Document], policy: Optional[DuplicatePolicy] = None) +``` + +Run the DocumentWriter on the given input data. + +**Arguments**: + +- `documents`: A list of documents to write to the document store. +- `policy`: The policy to use when encountering duplicate documents. + +**Raises**: + +- `ValueError`: If the specified document store is not found. + +**Returns**: + +Number of documents written to the document store. + + + +#### DocumentWriter.run\_async + +```python +@component.output_types(documents_written=int) +async def run_async(documents: list[Document], + policy: Optional[DuplicatePolicy] = None) +``` + +Asynchronously run the DocumentWriter on the given input data. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `documents`: A list of documents to write to the document store. +- `policy`: The policy to use when encountering duplicate documents. + +**Raises**: + +- `ValueError`: If the specified document store is not found. +- `TypeError`: If the specified document store does not implement `write_documents_async`. + +**Returns**: + +Number of documents written to the document store. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/embedders_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/embedders_api.md new file mode 100644 index 0000000000..81711e3490 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/embedders_api.md @@ -0,0 +1,1784 @@ +--- +title: "Embedders" +id: embedders-api +description: "Transforms queries into vectors to look for similar or relevant Documents." +slug: "/embedders-api" +--- + + + +## Module azure\_document\_embedder + + + +### AzureOpenAIDocumentEmbedder + +Calculates document embeddings using OpenAI models deployed on Azure. + +### Usage example + +```python +from haystack import Document +from haystack.components.embedders import AzureOpenAIDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = AzureOpenAIDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### AzureOpenAIDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(azure_endpoint: Optional[str] = None, + api_version: Optional[str] = "2023-05-15", + azure_deployment: str = "text-embedding-ada-002", + dimensions: Optional[int] = None, + api_key: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_API_KEY", strict=False), + azure_ad_token: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_AD_TOKEN", strict=False), + organization: Optional[str] = None, + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + *, + default_headers: Optional[dict[str, str]] = None, + azure_ad_token_provider: Optional[AzureADTokenProvider] = None, + http_client_kwargs: Optional[dict[str, Any]] = None, + raise_on_failure: bool = False) +``` + +Creates an AzureOpenAIDocumentEmbedder component. + +**Arguments**: + +- `azure_endpoint`: The endpoint of the model deployed on Azure. +- `api_version`: The version of the API to use. +- `azure_deployment`: The name of the model deployed on Azure. The default model is text-embedding-ada-002. +- `dimensions`: The number of dimensions of the resulting embeddings. Only supported in text-embedding-3 +and later models. +- `api_key`: The Azure OpenAI API key. +You can set it with an environment variable `AZURE_OPENAI_API_KEY`, or pass with this +parameter during initialization. +- `azure_ad_token`: Microsoft Entra ID token, see Microsoft's +[Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) +documentation for more information. You can set it with an environment variable +`AZURE_OPENAI_AD_TOKEN`, or pass with this parameter during initialization. +Previously called Azure Active Directory. +- `organization`: Your organization ID. See OpenAI's +[Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization) +for more information. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when running. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `timeout`: The timeout for `AzureOpenAI` client calls, in seconds. +If not set, defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact AzureOpenAI after an internal error. +If not set, defaults to either the `OPENAI_MAX_RETRIES` environment variable or to 5 retries. +- `default_headers`: Default headers to send to the AzureOpenAI client. +- `azure_ad_token_provider`: A function that returns an Azure Active Directory token, will be invoked on +every request. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). +- `raise_on_failure`: Whether to raise an exception if the embedding request fails. If `False`, the component will log the error +and continue processing the remaining documents. If `True`, it will raise an exception on failure. + + + +#### AzureOpenAIDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AzureOpenAIDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AzureOpenAIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AzureOpenAIDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +def run(documents: list[Document]) +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +#### AzureOpenAIDocumentEmbedder.run\_async + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +async def run_async(documents: list[Document]) +``` + +Embeds a list of documents asynchronously. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +## Module azure\_text\_embedder + + + +### AzureOpenAITextEmbedder + +Embeds strings using OpenAI models deployed on Azure. + +### Usage example + +```python +from haystack.components.embedders import AzureOpenAITextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = AzureOpenAITextEmbedder() + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +# 'meta': {'model': 'text-embedding-ada-002-v2', +# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}} +``` + + + +#### AzureOpenAITextEmbedder.\_\_init\_\_ + +```python +def __init__(azure_endpoint: Optional[str] = None, + api_version: Optional[str] = "2023-05-15", + azure_deployment: str = "text-embedding-ada-002", + dimensions: Optional[int] = None, + api_key: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_API_KEY", strict=False), + azure_ad_token: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_AD_TOKEN", strict=False), + organization: Optional[str] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + prefix: str = "", + suffix: str = "", + *, + default_headers: Optional[dict[str, str]] = None, + azure_ad_token_provider: Optional[AzureADTokenProvider] = None, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an AzureOpenAITextEmbedder component. + +**Arguments**: + +- `azure_endpoint`: The endpoint of the model deployed on Azure. +- `api_version`: The version of the API to use. +- `azure_deployment`: The name of the model deployed on Azure. The default model is text-embedding-ada-002. +- `dimensions`: The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 +and later models. +- `api_key`: The Azure OpenAI API key. +You can set it with an environment variable `AZURE_OPENAI_API_KEY`, or pass with this +parameter during initialization. +- `azure_ad_token`: Microsoft Entra ID token, see Microsoft's +[Entra ID](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id) +documentation for more information. You can set it with an environment variable +`AZURE_OPENAI_AD_TOKEN`, or pass with this parameter during initialization. +Previously called Azure Active Directory. +- `organization`: Your organization ID. See OpenAI's +[Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization) +for more information. +- `timeout`: The timeout for `AzureOpenAI` client calls, in seconds. +If not set, defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact AzureOpenAI after an internal error. +If not set, defaults to either the `OPENAI_MAX_RETRIES` environment variable, or to 5 retries. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `default_headers`: Default headers to send to the AzureOpenAI client. +- `azure_ad_token_provider`: A function that returns an Azure Active Directory token, will be invoked on +every request. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### AzureOpenAITextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AzureOpenAITextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AzureOpenAITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AzureOpenAITextEmbedder.run + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +def run(text: str) +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +#### AzureOpenAITextEmbedder.run\_async + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +async def run_async(text: str) +``` + +Asynchronously embed a single string. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +## Module hugging\_face\_api\_document\_embedder + + + +### HuggingFaceAPIDocumentEmbedder + +Embeds documents using Hugging Face APIs. + +Use it with the following Hugging Face APIs: +- [Free Serverless Inference API](https://huggingface.co/inference-api) +- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints) +- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference) + + +### Usage examples + +#### With free serverless inference API + +```python +from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder +from haystack.utils import Secret +from haystack.dataclasses import Document + +doc = Document(content="I love pizza!") + +doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="serverless_inference_api", + api_params={"model": "BAAI/bge-small-en-v1.5"}, + token=Secret.from_token("")) + +result = document_embedder.run([doc]) +print(result["documents"][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + +#### With paid inference endpoints + +```python +from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder +from haystack.utils import Secret +from haystack.dataclasses import Document + +doc = Document(content="I love pizza!") + +doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="inference_endpoints", + api_params={"url": ""}, + token=Secret.from_token("")) + +result = document_embedder.run([doc]) +print(result["documents"][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + +#### With self-hosted text embeddings inference + +```python +from haystack.components.embedders import HuggingFaceAPIDocumentEmbedder +from haystack.dataclasses import Document + +doc = Document(content="I love pizza!") + +doc_embedder = HuggingFaceAPIDocumentEmbedder(api_type="text_embeddings_inference", + api_params={"url": "http://localhost:8080"}) + +result = document_embedder.run([doc]) +print(result["documents"][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### HuggingFaceAPIDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(api_type: Union[HFEmbeddingAPIType, str], + api_params: dict[str, str], + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + truncate: Optional[bool] = True, + normalize: Optional[bool] = False, + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n") +``` + +Creates a HuggingFaceAPIDocumentEmbedder component. + +**Arguments**: + +- `api_type`: The type of Hugging Face API to use. +- `api_params`: A dictionary with the following keys: +- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`. +- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or +`TEXT_EMBEDDINGS_INFERENCE`. +- `token`: The Hugging Face token to use as HTTP bearer authorization. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `truncate`: Truncates the input text to the maximum length supported by the model. +Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS` +if the backend uses Text Embeddings Inference. +If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored. +- `normalize`: Normalizes the embeddings to unit length. +Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS` +if the backend uses Text Embeddings Inference. +If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored. +- `batch_size`: Number of documents to process at once. +- `progress_bar`: If `True`, shows a progress bar when running. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. + + + +#### HuggingFaceAPIDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HuggingFaceAPIDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### HuggingFaceAPIDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. + + + +#### HuggingFaceAPIDocumentEmbedder.run\_async + +```python +@component.output_types(documents=list[Document]) +async def run_async(documents: list[Document]) +``` + +Embeds a list of documents asynchronously. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. + + + +## Module hugging\_face\_api\_text\_embedder + + + +### HuggingFaceAPITextEmbedder + +Embeds strings using Hugging Face APIs. + +Use it with the following Hugging Face APIs: +- [Free Serverless Inference API](https://huggingface.co/inference-api) +- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints) +- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference) + +### Usage examples + +#### With free serverless inference API + +```python +from haystack.components.embedders import HuggingFaceAPITextEmbedder +from haystack.utils import Secret + +text_embedder = HuggingFaceAPITextEmbedder(api_type="serverless_inference_api", + api_params={"model": "BAAI/bge-small-en-v1.5"}, + token=Secret.from_token("")) + +print(text_embedder.run("I love pizza!")) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +``` + +#### With paid inference endpoints + +```python +from haystack.components.embedders import HuggingFaceAPITextEmbedder +from haystack.utils import Secret +text_embedder = HuggingFaceAPITextEmbedder(api_type="inference_endpoints", + api_params={"model": "BAAI/bge-small-en-v1.5"}, + token=Secret.from_token("")) + +print(text_embedder.run("I love pizza!")) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +``` + +#### With self-hosted text embeddings inference + +```python +from haystack.components.embedders import HuggingFaceAPITextEmbedder +from haystack.utils import Secret + +text_embedder = HuggingFaceAPITextEmbedder(api_type="text_embeddings_inference", + api_params={"url": "http://localhost:8080"}) + +print(text_embedder.run("I love pizza!")) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +``` + + + +#### HuggingFaceAPITextEmbedder.\_\_init\_\_ + +```python +def __init__(api_type: Union[HFEmbeddingAPIType, str], + api_params: dict[str, str], + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + truncate: Optional[bool] = True, + normalize: Optional[bool] = False) +``` + +Creates a HuggingFaceAPITextEmbedder component. + +**Arguments**: + +- `api_type`: The type of Hugging Face API to use. +- `api_params`: A dictionary with the following keys: +- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`. +- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or +`TEXT_EMBEDDINGS_INFERENCE`. +- `token`: The Hugging Face token to use as HTTP bearer authorization. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `truncate`: Truncates the input text to the maximum length supported by the model. +Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS` +if the backend uses Text Embeddings Inference. +If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored. +- `normalize`: Normalizes the embeddings to unit length. +Applicable when `api_type` is `TEXT_EMBEDDINGS_INFERENCE`, or `INFERENCE_ENDPOINTS` +if the backend uses Text Embeddings Inference. +If `api_type` is `SERVERLESS_INFERENCE_API`, this parameter is ignored. + + + +#### HuggingFaceAPITextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HuggingFaceAPITextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### HuggingFaceAPITextEmbedder.run + +```python +@component.output_types(embedding=list[float]) +def run(text: str) +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. + + + +#### HuggingFaceAPITextEmbedder.run\_async + +```python +@component.output_types(embedding=list[float]) +async def run_async(text: str) +``` + +Embeds a single string asynchronously. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. + + + +## Module openai\_document\_embedder + + + +### OpenAIDocumentEmbedder + +Computes document embeddings using OpenAI models. + +### Usage example + +```python +from haystack import Document +from haystack.components.embedders import OpenAIDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = OpenAIDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### OpenAIDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "text-embedding-ada-002", + dimensions: Optional[int] = None, + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[dict[str, Any]] = None, + *, + raise_on_failure: bool = False) +``` + +Creates an OpenAIDocumentEmbedder component. + +Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' +environment variables to override the `timeout` and `max_retries` parameters respectively +in the OpenAI client. + +**Arguments**: + +- `api_key`: The OpenAI API key. +You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter +during initialization. +- `model`: The name of the model to use for calculating embeddings. +The default model is `text-embedding-ada-002`. +- `dimensions`: The number of dimensions of the resulting embeddings. Only `text-embedding-3` and +later models support this parameter. +- `api_base_url`: Overrides the default base URL for all HTTP requests. +- `organization`: Your OpenAI organization ID. See OpenAI's +[Setting Up Your Organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization) +for more information. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when running. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or 5 retries. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). +- `raise_on_failure`: Whether to raise an exception if the embedding request fails. If `False`, the component will log the error +and continue processing the remaining documents. If `True`, it will raise an exception on failure. + + + +#### OpenAIDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenAIDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OpenAIDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +def run(documents: list[Document]) +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +#### OpenAIDocumentEmbedder.run\_async + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +async def run_async(documents: list[Document]) +``` + +Embeds a list of documents asynchronously. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +## Module openai\_text\_embedder + + + +### OpenAITextEmbedder + +Embeds strings using OpenAI models. + +You can use it to embed user query and send it to an embedding Retriever. + +### Usage example + +```python +from haystack.components.embedders import OpenAITextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = OpenAITextEmbedder() + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +# 'meta': {'model': 'text-embedding-ada-002-v2', +# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}} +``` + + + +#### OpenAITextEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "text-embedding-ada-002", + dimensions: Optional[int] = None, + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + prefix: str = "", + suffix: str = "", + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an OpenAITextEmbedder component. + +Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' +environment variables to override the `timeout` and `max_retries` parameters respectively +in the OpenAI client. + +**Arguments**: + +- `api_key`: The OpenAI API key. +You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter +during initialization. +- `model`: The name of the model to use for calculating embeddings. +The default model is `text-embedding-ada-002`. +- `dimensions`: The number of dimensions of the resulting embeddings. Only `text-embedding-3` and +later models support this parameter. +- `api_base_url`: Overrides default base URL for all HTTP requests. +- `organization`: Your organization ID. See OpenAI's +[production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization) +for more information. +- `prefix`: A string to add at the beginning of each text to embed. +- `suffix`: A string to add at the end of each text to embed. +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### OpenAITextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenAITextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OpenAITextEmbedder.run + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +def run(text: str) +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +#### OpenAITextEmbedder.run\_async + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +async def run_async(text: str) +``` + +Asynchronously embed a single string. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +## Module sentence\_transformers\_document\_embedder + + + +### SentenceTransformersDocumentEmbedder + +Calculates document embeddings using Sentence Transformers models. + +It stores the embeddings in the `embedding` metadata field of each document. +You can also embed documents' metadata. +Use this component in indexing pipelines to embed input documents +and send them to DocumentWriter to write a into a Document Store. + +### Usage example: + +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersDocumentEmbedder +doc = Document(content="I love pizza!") +doc_embedder = SentenceTransformersDocumentEmbedder() +doc_embedder.warm_up() + +result = doc_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [-0.07804739475250244, 0.1498992145061493, ...] +``` + + + +#### SentenceTransformersDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "sentence-transformers/all-mpnet-base-v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + normalize_embeddings: bool = False, + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + trust_remote_code: bool = False, + local_files_only: bool = False, + truncate_dim: Optional[int] = None, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + precision: Literal["float32", "int8", "uint8", "binary", + "ubinary"] = "float32", + encode_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch", + revision: Optional[str] = None) +``` + +Creates a SentenceTransformersDocumentEmbedder component. + +**Arguments**: + +- `model`: The model to use for calculating embeddings. +Pass a local path or ID of the model on Hugging Face. +- `device`: The device to use for loading the model. +Overrides the default device. +- `token`: The API token to download private models from Hugging Face. +- `prefix`: A string to add at the beginning of each document text. +Can be used to prepend the text with an instruction, as required by some embedding models, +such as E5 and bge. +- `suffix`: A string to add at the end of each document text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when embedding documents. +- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures. +If `True`, allows custom models and scripts. +- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files. +- `truncate_dim`: The dimension to truncate sentence embeddings to. `None` does no truncation. +If the model wasn't trained with Matryoshka Representation Learning, +truncating embeddings can significantly affect performance. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `precision`: The precision to use for the embeddings. +All non-float32 precisions are quantized embeddings. +Quantized embeddings are smaller and faster to compute, but may have a lower accuracy. +They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks. +- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding documents. +This parameter is provided for fine customization. Be careful not to clash with already set parameters and +avoid passing parameters that change the output type. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. +- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id, +for a stored model on Hugging Face. + + + +#### SentenceTransformersDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, + Any]) -> "SentenceTransformersDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SentenceTransformersDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Embed a list of documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + + + +## Module sentence\_transformers\_text\_embedder + + + +### SentenceTransformersTextEmbedder + +Embeds strings using Sentence Transformers models. + +You can use it to embed user query and send it to an embedding retriever. + +Usage example: +```python +from haystack.components.embedders import SentenceTransformersTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = SentenceTransformersTextEmbedder() +text_embedder.warm_up() + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]} +``` + + + +#### SentenceTransformersTextEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "sentence-transformers/all-mpnet-base-v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + normalize_embeddings: bool = False, + trust_remote_code: bool = False, + local_files_only: bool = False, + truncate_dim: Optional[int] = None, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + precision: Literal["float32", "int8", "uint8", "binary", + "ubinary"] = "float32", + encode_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch", + revision: Optional[str] = None) +``` + +Create a SentenceTransformersTextEmbedder component. + +**Arguments**: + +- `model`: The model to use for calculating embeddings. +Specify the path to a local model or the ID of the model on Hugging Face. +- `device`: Overrides the default device used to load the model. +- `token`: An API token to use private models from Hugging Face. +- `prefix`: A string to add at the beginning of each text to be embedded. +You can use it to prepend the text with an instruction, as required by some embedding models, +such as E5 and bge. +- `suffix`: A string to add at the end of each text to embed. +- `batch_size`: Number of texts to embed at once. +- `progress_bar`: If `True`, shows a progress bar for calculating embeddings. +If `False`, disables the progress bar. +- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that the embeddings have a norm of 1. +- `trust_remote_code`: If `False`, permits only Hugging Face verified model architectures. +If `True`, permits custom models and scripts. +- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files. +- `truncate_dim`: The dimension to truncate sentence embeddings to. `None` does no truncation. +If the model has not been trained with Matryoshka Representation Learning, +truncation of embeddings can significantly affect performance. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `precision`: The precision to use for the embeddings. +All non-float32 precisions are quantized embeddings. +Quantized embeddings are smaller in size and faster to compute, but may have a lower accuracy. +They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks. +- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding texts. +This parameter is provided for fine customization. Be careful not to clash with already set parameters and +avoid passing parameters that change the output type. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. +- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id, +for a stored model on Hugging Face. + + + +#### SentenceTransformersTextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "SentenceTransformersTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SentenceTransformersTextEmbedder.run + +```python +@component.output_types(embedding=list[float]) +def run(text: str) +``` + +Embed a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. + + + +## Module sentence\_transformers\_sparse\_document\_embedder + + + +### SentenceTransformersSparseDocumentEmbedder + +Calculates document sparse embeddings using sparse embedding models from Sentence Transformers. + +It stores the sparse embeddings in the `sparse_embedding` metadata field of each document. +You can also embed documents' metadata. +Use this component in indexing pipelines to embed input documents +and send them to DocumentWriter to write a into a Document Store. + +### Usage example: + +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersSparseDocumentEmbedder + +doc = Document(content="I love pizza!") +doc_embedder = SentenceTransformersSparseDocumentEmbedder() +doc_embedder.warm_up() + +result = doc_embedder.run([doc]) +print(result['documents'][0].sparse_embedding) + +# SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...]) +``` + + + +#### SentenceTransformersSparseDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(*, + model: str = "prithivida/Splade_PP_en_v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + trust_remote_code: bool = False, + local_files_only: bool = False, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch", + revision: Optional[str] = None) +``` + +Creates a SentenceTransformersSparseDocumentEmbedder component. + +**Arguments**: + +- `model`: The model to use for calculating sparse embeddings. +Pass a local path or ID of the model on Hugging Face. +- `device`: The device to use for loading the model. +Overrides the default device. +- `token`: The API token to download private models from Hugging Face. +- `prefix`: A string to add at the beginning of each document text. +- `suffix`: A string to add at the end of each document text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when embedding documents. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures. +If `True`, allows custom models and scripts. +- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. +- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id, +for a stored model on Hugging Face. + + + +#### SentenceTransformersSparseDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersSparseDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict( + cls, data: dict[str, + Any]) -> "SentenceTransformersSparseDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersSparseDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SentenceTransformersSparseDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Embed a list of documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with sparse embeddings under the `sparse_embedding` field. + + + +## Module sentence\_transformers\_sparse\_text\_embedder + + + +### SentenceTransformersSparseTextEmbedder + +Embeds strings using sparse embedding models from Sentence Transformers. + +You can use it to embed user query and send it to a sparse embedding retriever. + +Usage example: +```python +from haystack.components.embedders import SentenceTransformersSparseTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = SentenceTransformersSparseTextEmbedder() +text_embedder.warm_up() + +print(text_embedder.run(text_to_embed)) + +# {'sparse_embedding': SparseEmbedding(indices=[999, 1045, ...], values=[0.918, 0.867, ...])} +``` + + + +#### SentenceTransformersSparseTextEmbedder.\_\_init\_\_ + +```python +def __init__(*, + model: str = "prithivida/Splade_PP_en_v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + prefix: str = "", + suffix: str = "", + trust_remote_code: bool = False, + local_files_only: bool = False, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + encode_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch", + revision: Optional[str] = None) +``` + +Create a SentenceTransformersSparseTextEmbedder component. + +**Arguments**: + +- `model`: The model to use for calculating sparse embeddings. +Specify the path to a local model or the ID of the model on Hugging Face. +- `device`: Overrides the default device used to load the model. +- `token`: An API token to use private models from Hugging Face. +- `prefix`: A string to add at the beginning of each text to be embedded. +- `suffix`: A string to add at the end of each text to embed. +- `trust_remote_code`: If `False`, permits only Hugging Face verified model architectures. +If `True`, permits custom models and scripts. +- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. +- `revision`: The specific model version to use. It can be a branch name, a tag name, or a commit id, +for a stored model on Hugging Face. + + + +#### SentenceTransformersSparseTextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersSparseTextEmbedder.from\_dict + +```python +@classmethod +def from_dict( + cls, data: dict[str, Any]) -> "SentenceTransformersSparseTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersSparseTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SentenceTransformersSparseTextEmbedder.run + +```python +@component.output_types(sparse_embedding=SparseEmbedding) +def run(text: str) +``` + +Embed a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `sparse_embedding`: The sparse embedding of the input text. + + + +## Module image/sentence\_transformers\_doc\_image\_embedder + + + +### SentenceTransformersDocumentImageEmbedder + +A component for computing Document embeddings based on images using Sentence Transformers models. + +The embedding of each Document is stored in the `embedding` field of the Document. + +### Usage example +```python +from haystack import Document +from haystack.components.embedders.image import SentenceTransformersDocumentImageEmbedder + +embedder = SentenceTransformersDocumentImageEmbedder(model="sentence-transformers/clip-ViT-B-32") +embedder.warm_up() + +documents = [ + Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}), + Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}), +] + +result = embedder.run(documents=documents) +documents_with_embeddings = result["documents"] +print(documents_with_embeddings) + +# [Document(id=..., +# content='A photo of a cat', +# meta={'file_path': 'cat.jpg', +# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}}, +# embedding=vector of size 512), +# ...] +``` + + + +#### SentenceTransformersDocumentImageEmbedder.\_\_init\_\_ + +```python +def __init__(*, + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + model: str = "sentence-transformers/clip-ViT-B-32", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + batch_size: int = 32, + progress_bar: bool = True, + normalize_embeddings: bool = False, + trust_remote_code: bool = False, + local_files_only: bool = False, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + precision: Literal["float32", "int8", "uint8", "binary", + "ubinary"] = "float32", + encode_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch") -> None +``` + +Creates a SentenceTransformersDocumentEmbedder component. + +**Arguments**: + +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `model`: The Sentence Transformers model to use for calculating embeddings. Pass a local path or ID of the model on +Hugging Face. To be used with this component, the model must be able to embed images and text into the same +vector space. Compatible models include: +- "sentence-transformers/clip-ViT-B-32" +- "sentence-transformers/clip-ViT-L-14" +- "sentence-transformers/clip-ViT-B-16" +- "sentence-transformers/clip-ViT-B-32-multilingual-v1" +- "jinaai/jina-embeddings-v4" +- "jinaai/jina-clip-v1" +- "jinaai/jina-clip-v2". +- `device`: The device to use for loading the model. +Overrides the default device. +- `token`: The API token to download private models from Hugging Face. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when embedding documents. +- `normalize_embeddings`: If `True`, the embeddings are normalized using L2 normalization, so that each embedding has a norm of 1. +- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures. +If `True`, allows custom models and scripts. +- `local_files_only`: If `True`, does not attempt to download the model from Hugging Face Hub and only looks at local files. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `precision`: The precision to use for the embeddings. +All non-float32 precisions are quantized embeddings. +Quantized embeddings are smaller and faster to compute, but may have a lower accuracy. +They are useful for reducing the size of the embeddings of a corpus for semantic search, among other tasks. +- `encode_kwargs`: Additional keyword arguments for `SentenceTransformer.encode` when embedding documents. +This parameter is provided for fine customization. Be careful not to clash with already set parameters and +avoid passing parameters that change the output type. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. + + + +#### SentenceTransformersDocumentImageEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersDocumentImageEmbedder.from\_dict + +```python +@classmethod +def from_dict( + cls, data: dict[str, + Any]) -> "SentenceTransformersDocumentImageEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersDocumentImageEmbedder.warm\_up + +```python +def warm_up() -> None +``` + +Initializes the component. + + + +#### SentenceTransformersDocumentImageEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Embed a list of documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluation_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluation_api.md new file mode 100644 index 0000000000..d18014721d --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluation_api.md @@ -0,0 +1,110 @@ +--- +title: "Evaluation" +id: evaluation-api +description: "Represents the results of evaluation." +slug: "/evaluation-api" +--- + + + +## Module eval\_run\_result + + + +### EvaluationRunResult + +Contains the inputs and the outputs of an evaluation pipeline and provides methods to inspect them. + + + +#### EvaluationRunResult.\_\_init\_\_ + +```python +def __init__(run_name: str, inputs: dict[str, list[Any]], + results: dict[str, dict[str, Any]]) +``` + +Initialize a new evaluation run result. + +**Arguments**: + +- `run_name`: Name of the evaluation run. +- `inputs`: Dictionary containing the inputs used for the run. Each key is the name of the input and its value is a list +of input values. The length of the lists should be the same. +- `results`: Dictionary containing the results of the evaluators used in the evaluation pipeline. Each key is the name +of the metric and its value is dictionary with the following keys: +- 'score': The aggregated score for the metric. +- 'individual_scores': A list of scores for each input sample. + + + +#### EvaluationRunResult.aggregated\_report + +```python +def aggregated_report( + output_format: Literal["json", "csv", "df"] = "json", + csv_file: Optional[str] = None +) -> Union[dict[str, list[Any]], "DataFrame", str] +``` + +Generates a report with aggregated scores for each metric. + +**Arguments**: + +- `output_format`: The output format for the report, "json", "csv", or "df", default to "json". +- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided. + +**Returns**: + +JSON or DataFrame with aggregated scores, in case the output is set to a CSV file, a message confirming the +successful write or an error message. + + + +#### EvaluationRunResult.detailed\_report + +```python +def detailed_report( + output_format: Literal["json", "csv", "df"] = "json", + csv_file: Optional[str] = None +) -> Union[dict[str, list[Any]], "DataFrame", str] +``` + +Generates a report with detailed scores for each metric. + +**Arguments**: + +- `output_format`: The output format for the report, "json", "csv", or "df", default to "json". +- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided. + +**Returns**: + +JSON or DataFrame with the detailed scores, in case the output is set to a CSV file, a message confirming +the successful write or an error message. + + + +#### EvaluationRunResult.comparative\_detailed\_report + +```python +def comparative_detailed_report( + other: "EvaluationRunResult", + keep_columns: Optional[list[str]] = None, + output_format: Literal["json", "csv", "df"] = "json", + csv_file: Optional[str] = None) -> Union[str, "DataFrame", None] +``` + +Generates a report with detailed scores for each metric from two evaluation runs for comparison. + +**Arguments**: + +- `other`: Results of another evaluation run to compare with. +- `keep_columns`: List of common column names to keep from the inputs of the evaluation runs to compare. +- `output_format`: The output format for the report, "json", "csv", or "df", default to "json". +- `csv_file`: Filepath to save CSV output if `output_format` is "csv", must be provided. + +**Returns**: + +JSON or DataFrame with a comparison of the detailed scores, in case the output is set to a CSV file, +a message confirming the successful write or an error message. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluators_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluators_api.md new file mode 100644 index 0000000000..45be3da5c4 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/evaluators_api.md @@ -0,0 +1,1296 @@ +--- +title: "Evaluators" +id: evaluators-api +description: "Evaluate your pipelines or individual components." +slug: "/evaluators-api" +--- + + + +## Module answer\_exact\_match + + + +### AnswerExactMatchEvaluator + +An answer exact match evaluator class. + +The evaluator that checks if the predicted answers matches any of the ground truth answers exactly. +The result is a number from 0.0 to 1.0, it represents the proportion of predicted answers +that matched one of the ground truth answers. +There can be multiple ground truth answers and multiple predicted answers as input. + + +Usage example: +```python +from haystack.components.evaluators import AnswerExactMatchEvaluator + +evaluator = AnswerExactMatchEvaluator() +result = evaluator.run( + ground_truth_answers=["Berlin", "Paris"], + predicted_answers=["Berlin", "Lyon"], +) + +print(result["individual_scores"]) +# [1, 0] +print(result["score"]) +# 0.5 +``` + + + +#### AnswerExactMatchEvaluator.run + +```python +@component.output_types(individual_scores=list[int], score=float) +def run(ground_truth_answers: list[str], + predicted_answers: list[str]) -> dict[str, Any] +``` + +Run the AnswerExactMatchEvaluator on the given inputs. + +The `ground_truth_answers` and `retrieved_answers` must have the same length. + +**Arguments**: + +- `ground_truth_answers`: A list of expected answers. +- `predicted_answers`: A list of predicted answers. + +**Returns**: + +A dictionary with the following outputs: +- `individual_scores` - A list of 0s and 1s, where 1 means that the predicted answer matched one of the + ground truth. +- `score` - A number from 0.0 to 1.0 that represents the proportion of questions where any predicted + answer matched one of the ground truth answers. + + + +## Module context\_relevance + + + +### ContextRelevanceEvaluator + +Evaluator that checks if a provided context is relevant to the question. + +An LLM breaks up a context into multiple statements and checks whether each statement +is relevant for answering a question. +The score for each context is either binary score of 1 or 0, where 1 indicates that the context is relevant +to the question and 0 indicates that the context is not relevant. +The evaluator also provides the relevant statements from the context and an average score over all the provided +input questions contexts pairs. + +Usage example: +```python +from haystack.components.evaluators import ContextRelevanceEvaluator + +questions = ["Who created the Python language?", "Why does Java needs a JVM?", "Is C++ better than Python?"] +contexts = [ + [( + "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming " + "language. Its design philosophy emphasizes code readability, and its language constructs aim to help " + "programmers write clear, logical code for both small and large-scale software projects." + )], + [( + "Java is a high-level, class-based, object-oriented programming language that is designed to have as few " + "implementation dependencies as possible. The JVM has two primary functions: to allow Java programs to run" + "on any device or operating system (known as the 'write once, run anywhere' principle), and to manage and" + "optimize program memory." + )], + [( + "C++ is a general-purpose programming language created by Bjarne Stroustrup as an extension of the C " + "programming language." + )], +] + +evaluator = ContextRelevanceEvaluator() +result = evaluator.run(questions=questions, contexts=contexts) +print(result["score"]) +# 0.67 +print(result["individual_scores"]) +# [1,1,0] +print(result["results"]) +# [{ +# 'relevant_statements': ['Python, created by Guido van Rossum in the late 1980s.'], +# 'score': 1.0 +# }, +# { +# 'relevant_statements': ['The JVM has two primary functions: to allow Java programs to run on any device or +# operating system (known as the "write once, run anywhere" principle), and to manage and +# optimize program memory'], +# 'score': 1.0 +# }, +# { +# 'relevant_statements': [], +# 'score': 0.0 +# }] +``` + + + +#### ContextRelevanceEvaluator.\_\_init\_\_ + +```python +def __init__(examples: Optional[list[dict[str, Any]]] = None, + progress_bar: bool = True, + raise_on_failure: bool = True, + chat_generator: Optional[ChatGenerator] = None) +``` + +Creates an instance of ContextRelevanceEvaluator. + +If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode. + +**Arguments**: + +- `examples`: Optional few-shot examples conforming to the expected input and output format of ContextRelevanceEvaluator. +Default examples will be used if none are provided. +Each example must be a dictionary with keys "inputs" and "outputs". +"inputs" must be a dictionary with keys "questions" and "contexts". +"outputs" must be a dictionary with "relevant_statements". +Expected format: +```python +[{ + "inputs": { + "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."], + }, + "outputs": { + "relevant_statements": ["Rome is the capital of Italy."], + }, +}] +``` +- `progress_bar`: Whether to show a progress bar during the evaluation. +- `raise_on_failure`: Whether to raise an exception if the API call fails. +- `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`. + + + +#### ContextRelevanceEvaluator.run + +```python +@component.output_types(score=float, results=list[dict[str, Any]]) +def run(**inputs) -> dict[str, Any] +``` + +Run the LLM evaluator. + +**Arguments**: + +- `questions`: A list of questions. +- `contexts`: A list of lists of contexts. Each list of contexts corresponds to one question. + +**Returns**: + +A dictionary with the following outputs: +- `score`: Mean context relevance score over all the provided input questions. +- `results`: A list of dictionaries with `relevant_statements` and `score` for each input context. + + + +#### ContextRelevanceEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +A dictionary with serialized data. + + + +#### ContextRelevanceEvaluator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ContextRelevanceEvaluator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### ContextRelevanceEvaluator.validate\_init\_parameters + +```python +@staticmethod +def validate_init_parameters(inputs: list[tuple[str, type[list]]], + outputs: list[str], examples: list[dict[str, + Any]]) +``` + +Validate the init parameters. + +**Arguments**: + +- `inputs`: The inputs to validate. +- `outputs`: The outputs to validate. +- `examples`: The examples to validate. + +**Raises**: + +- `ValueError`: If the inputs are not a list of tuples with a string and a type of list. +If the outputs are not a list of strings. +If the examples are not a list of dictionaries. +If any example does not have keys "inputs" and "outputs" with values that are dictionaries with string keys. + + + +#### ContextRelevanceEvaluator.prepare\_template + +```python +def prepare_template() -> str +``` + +Prepare the prompt template. + +Combine instructions, inputs, outputs, and examples into one prompt template with the following format: +Instructions: +`` + +Generate the response in JSON format with the following keys: +`` +Consider the instructions and the examples below to determine those values. + +Examples: +`` + +Inputs: +`` +Outputs: + +**Returns**: + +The prompt template. + + + +#### ContextRelevanceEvaluator.validate\_input\_parameters + +```python +@staticmethod +def validate_input_parameters(expected: dict[str, Any], + received: dict[str, Any]) -> None +``` + +Validate the input parameters. + +**Arguments**: + +- `expected`: The expected input parameters. +- `received`: The received input parameters. + +**Raises**: + +- `ValueError`: If not all expected inputs are present in the received inputs +If the received inputs are not lists or have different lengths + + + +#### ContextRelevanceEvaluator.is\_valid\_json\_and\_has\_expected\_keys + +```python +def is_valid_json_and_has_expected_keys(expected: list[str], + received: str) -> bool +``` + +Output must be a valid JSON with the expected keys. + +**Arguments**: + +- `expected`: Names of expected outputs +- `received`: Names of received outputs + +**Raises**: + +- `ValueError`: If the output is not a valid JSON with the expected keys: +- with `raise_on_failure` set to True a ValueError is raised. +- with `raise_on_failure` set to False a warning is issued and False is returned. + +**Returns**: + +True if the received output is a valid JSON with the expected keys, False otherwise. + + + +## Module document\_map + + + +### DocumentMAPEvaluator + +A Mean Average Precision (MAP) evaluator for documents. + +Evaluator that calculates the mean average precision of the retrieved documents, a metric +that measures how high retrieved documents are ranked. +Each question can have multiple ground truth documents and multiple retrieved documents. + +`DocumentMAPEvaluator` doesn't normalize its inputs, the `DocumentCleaner` component +should be used to clean and normalize the documents before passing them to this evaluator. + +Usage example: +```python +from haystack import Document +from haystack.components.evaluators import DocumentMAPEvaluator + +evaluator = DocumentMAPEvaluator() +result = evaluator.run( + ground_truth_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="9th")], + ], + retrieved_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="10th century"), Document(content="9th")], + ], +) + +print(result["individual_scores"]) +# [1.0, 0.8333333333333333] +print(result["score"]) +# 0.9166666666666666 +``` + + + +#### DocumentMAPEvaluator.run + +```python +@component.output_types(score=float, individual_scores=list[float]) +def run(ground_truth_documents: list[list[Document]], + retrieved_documents: list[list[Document]]) -> dict[str, Any] +``` + +Run the DocumentMAPEvaluator on the given inputs. + +All lists must have the same length. + +**Arguments**: + +- `ground_truth_documents`: A list of expected documents for each question. +- `retrieved_documents`: A list of retrieved documents for each question. + +**Returns**: + +A dictionary with the following outputs: +- `score` - The average of calculated scores. +- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents how high retrieved documents + are ranked. + + + +## Module document\_mrr + + + +### DocumentMRREvaluator + +Evaluator that calculates the mean reciprocal rank of the retrieved documents. + +MRR measures how high the first retrieved document is ranked. +Each question can have multiple ground truth documents and multiple retrieved documents. + +`DocumentMRREvaluator` doesn't normalize its inputs, the `DocumentCleaner` component +should be used to clean and normalize the documents before passing them to this evaluator. + +Usage example: +```python +from haystack import Document +from haystack.components.evaluators import DocumentMRREvaluator + +evaluator = DocumentMRREvaluator() +result = evaluator.run( + ground_truth_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="9th")], + ], + retrieved_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="10th century"), Document(content="9th")], + ], +) +print(result["individual_scores"]) +# [1.0, 1.0] +print(result["score"]) +# 1.0 +``` + + + +#### DocumentMRREvaluator.run + +```python +@component.output_types(score=float, individual_scores=list[float]) +def run(ground_truth_documents: list[list[Document]], + retrieved_documents: list[list[Document]]) -> dict[str, Any] +``` + +Run the DocumentMRREvaluator on the given inputs. + +`ground_truth_documents` and `retrieved_documents` must have the same length. + +**Arguments**: + +- `ground_truth_documents`: A list of expected documents for each question. +- `retrieved_documents`: A list of retrieved documents for each question. + +**Returns**: + +A dictionary with the following outputs: +- `score` - The average of calculated scores. +- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents how high the first retrieved + document is ranked. + + + +## Module document\_ndcg + + + +### DocumentNDCGEvaluator + +Evaluator that calculates the normalized discounted cumulative gain (NDCG) of retrieved documents. + +Each question can have multiple ground truth documents and multiple retrieved documents. +If the ground truth documents have relevance scores, the NDCG calculation uses these scores. +Otherwise, it assumes binary relevance of all ground truth documents. + +Usage example: +```python +from haystack import Document +from haystack.components.evaluators import DocumentNDCGEvaluator + +evaluator = DocumentNDCGEvaluator() +result = evaluator.run( + ground_truth_documents=[[Document(content="France", score=1.0), Document(content="Paris", score=0.5)]], + retrieved_documents=[[Document(content="France"), Document(content="Germany"), Document(content="Paris")]], +) +print(result["individual_scores"]) +# [0.8869] +print(result["score"]) +# 0.8869 +``` + + + +#### DocumentNDCGEvaluator.run + +```python +@component.output_types(score=float, individual_scores=list[float]) +def run(ground_truth_documents: list[list[Document]], + retrieved_documents: list[list[Document]]) -> dict[str, Any] +``` + +Run the DocumentNDCGEvaluator on the given inputs. + +`ground_truth_documents` and `retrieved_documents` must have the same length. +The list items within `ground_truth_documents` and `retrieved_documents` can differ in length. + +**Arguments**: + +- `ground_truth_documents`: Lists of expected documents, one list per question. Binary relevance is used if documents have no scores. +- `retrieved_documents`: Lists of retrieved documents, one list per question. + +**Returns**: + +A dictionary with the following outputs: +- `score` - The average of calculated scores. +- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents the NDCG for each question. + + + +#### DocumentNDCGEvaluator.validate\_inputs + +```python +@staticmethod +def validate_inputs(gt_docs: list[list[Document]], + ret_docs: list[list[Document]]) +``` + +Validate the input parameters. + +**Arguments**: + +- `gt_docs`: The ground_truth_documents to validate. +- `ret_docs`: The retrieved_documents to validate. + +**Raises**: + +- `ValueError`: If the ground_truth_documents or the retrieved_documents are an empty a list. +If the length of ground_truth_documents and retrieved_documents differs. +If any list of documents in ground_truth_documents contains a mix of documents with and without a score. + + + +#### DocumentNDCGEvaluator.calculate\_dcg + +```python +@staticmethod +def calculate_dcg(gt_docs: list[Document], ret_docs: list[Document]) -> float +``` + +Calculate the discounted cumulative gain (DCG) of the retrieved documents. + +**Arguments**: + +- `gt_docs`: The ground truth documents. +- `ret_docs`: The retrieved documents. + +**Returns**: + +The discounted cumulative gain (DCG) of the retrieved +documents based on the ground truth documents. + + + +#### DocumentNDCGEvaluator.calculate\_idcg + +```python +@staticmethod +def calculate_idcg(gt_docs: list[Document]) -> float +``` + +Calculate the ideal discounted cumulative gain (IDCG) of the ground truth documents. + +**Arguments**: + +- `gt_docs`: The ground truth documents. + +**Returns**: + +The ideal discounted cumulative gain (IDCG) of the ground truth documents. + + + +## Module document\_recall + + + +### RecallMode + +Enum for the mode to use for calculating the recall score. + + + +#### RecallMode.from\_str + +```python +@staticmethod +def from_str(string: str) -> "RecallMode" +``` + +Convert a string to a RecallMode enum. + + + +### DocumentRecallEvaluator + +Evaluator that calculates the Recall score for a list of documents. + +Returns both a list of scores for each question and the average. +There can be multiple ground truth documents and multiple predicted documents as input. + +Usage example: +```python +from haystack import Document +from haystack.components.evaluators import DocumentRecallEvaluator + +evaluator = DocumentRecallEvaluator() +result = evaluator.run( + ground_truth_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="9th")], + ], + retrieved_documents=[ + [Document(content="France")], + [Document(content="9th century"), Document(content="10th century"), Document(content="9th")], + ], +) +print(result["individual_scores"]) +# [1.0, 1.0] +print(result["score"]) +# 1.0 +``` + + + +#### DocumentRecallEvaluator.\_\_init\_\_ + +```python +def __init__(mode: Union[str, RecallMode] = RecallMode.SINGLE_HIT) +``` + +Create a DocumentRecallEvaluator component. + +**Arguments**: + +- `mode`: Mode to use for calculating the recall score. + + + +#### DocumentRecallEvaluator.run + +```python +@component.output_types(score=float, individual_scores=list[float]) +def run(ground_truth_documents: list[list[Document]], + retrieved_documents: list[list[Document]]) -> dict[str, Any] +``` + +Run the DocumentRecallEvaluator on the given inputs. + +`ground_truth_documents` and `retrieved_documents` must have the same length. + +**Arguments**: + +- `ground_truth_documents`: A list of expected documents for each question. +- `retrieved_documents`: A list of retrieved documents for each question. +A dictionary with the following outputs: +- `score` - The average of calculated scores. +- `individual_scores` - A list of numbers from 0.0 to 1.0 that represents the proportion of matching + documents retrieved. If the mode is `single_hit`, the individual scores are 0 or 1. + + + +#### DocumentRecallEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module faithfulness + + + +### FaithfulnessEvaluator + +Evaluator that checks if a generated answer can be inferred from the provided contexts. + +An LLM separates the answer into multiple statements and checks whether the statement can be inferred from the +context or not. The final score for the full answer is a number from 0.0 to 1.0. It represents the proportion of +statements that can be inferred from the provided contexts. + +Usage example: +```python +from haystack.components.evaluators import FaithfulnessEvaluator + +questions = ["Who created the Python language?"] +contexts = [ + [( + "Python, created by Guido van Rossum in the late 1980s, is a high-level general-purpose programming " + "language. Its design philosophy emphasizes code readability, and its language constructs aim to help " + "programmers write clear, logical code for both small and large-scale software projects." + )], +] +predicted_answers = [ + "Python is a high-level general-purpose programming language that was created by George Lucas." +] +evaluator = FaithfulnessEvaluator() +result = evaluator.run(questions=questions, contexts=contexts, predicted_answers=predicted_answers) + +print(result["individual_scores"]) +# [0.5] +print(result["score"]) +# 0.5 +print(result["results"]) +# [{'statements': ['Python is a high-level general-purpose programming language.', +'Python was created by George Lucas.'], 'statement_scores': [1, 0], 'score': 0.5}] +``` + + + +#### FaithfulnessEvaluator.\_\_init\_\_ + +```python +def __init__(examples: Optional[list[dict[str, Any]]] = None, + progress_bar: bool = True, + raise_on_failure: bool = True, + chat_generator: Optional[ChatGenerator] = None) +``` + +Creates an instance of FaithfulnessEvaluator. + +If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode. + +**Arguments**: + +- `examples`: Optional few-shot examples conforming to the expected input and output format of FaithfulnessEvaluator. +Default examples will be used if none are provided. +Each example must be a dictionary with keys "inputs" and "outputs". +"inputs" must be a dictionary with keys "questions", "contexts", and "predicted_answers". +"outputs" must be a dictionary with "statements" and "statement_scores". +Expected format: +```python +[{ + "inputs": { + "questions": "What is the capital of Italy?", "contexts": ["Rome is the capital of Italy."], + "predicted_answers": "Rome is the capital of Italy with more than 4 million inhabitants.", + }, + "outputs": { + "statements": ["Rome is the capital of Italy.", "Rome has more than 4 million inhabitants."], + "statement_scores": [1, 0], + }, +}] +``` +- `progress_bar`: Whether to show a progress bar during the evaluation. +- `raise_on_failure`: Whether to raise an exception if the API call fails. +- `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`. + + + +#### FaithfulnessEvaluator.run + +```python +@component.output_types(individual_scores=list[int], + score=float, + results=list[dict[str, Any]]) +def run(**inputs) -> dict[str, Any] +``` + +Run the LLM evaluator. + +**Arguments**: + +- `questions`: A list of questions. +- `contexts`: A nested list of contexts that correspond to the questions. +- `predicted_answers`: A list of predicted answers. + +**Returns**: + +A dictionary with the following outputs: +- `score`: Mean faithfulness score over all the provided input answers. +- `individual_scores`: A list of faithfulness scores for each input answer. +- `results`: A list of dictionaries with `statements` and `statement_scores` for each input answer. + + + +#### FaithfulnessEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +A dictionary with serialized data. + + + +#### FaithfulnessEvaluator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "FaithfulnessEvaluator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### FaithfulnessEvaluator.validate\_init\_parameters + +```python +@staticmethod +def validate_init_parameters(inputs: list[tuple[str, type[list]]], + outputs: list[str], examples: list[dict[str, + Any]]) +``` + +Validate the init parameters. + +**Arguments**: + +- `inputs`: The inputs to validate. +- `outputs`: The outputs to validate. +- `examples`: The examples to validate. + +**Raises**: + +- `ValueError`: If the inputs are not a list of tuples with a string and a type of list. +If the outputs are not a list of strings. +If the examples are not a list of dictionaries. +If any example does not have keys "inputs" and "outputs" with values that are dictionaries with string keys. + + + +#### FaithfulnessEvaluator.prepare\_template + +```python +def prepare_template() -> str +``` + +Prepare the prompt template. + +Combine instructions, inputs, outputs, and examples into one prompt template with the following format: +Instructions: +`` + +Generate the response in JSON format with the following keys: +`` +Consider the instructions and the examples below to determine those values. + +Examples: +`` + +Inputs: +`` +Outputs: + +**Returns**: + +The prompt template. + + + +#### FaithfulnessEvaluator.validate\_input\_parameters + +```python +@staticmethod +def validate_input_parameters(expected: dict[str, Any], + received: dict[str, Any]) -> None +``` + +Validate the input parameters. + +**Arguments**: + +- `expected`: The expected input parameters. +- `received`: The received input parameters. + +**Raises**: + +- `ValueError`: If not all expected inputs are present in the received inputs +If the received inputs are not lists or have different lengths + + + +#### FaithfulnessEvaluator.is\_valid\_json\_and\_has\_expected\_keys + +```python +def is_valid_json_and_has_expected_keys(expected: list[str], + received: str) -> bool +``` + +Output must be a valid JSON with the expected keys. + +**Arguments**: + +- `expected`: Names of expected outputs +- `received`: Names of received outputs + +**Raises**: + +- `ValueError`: If the output is not a valid JSON with the expected keys: +- with `raise_on_failure` set to True a ValueError is raised. +- with `raise_on_failure` set to False a warning is issued and False is returned. + +**Returns**: + +True if the received output is a valid JSON with the expected keys, False otherwise. + + + +## Module llm\_evaluator + + + +### LLMEvaluator + +Uses an LLM to evaluate inputs based on a prompt containing instructions and examples. + +The default API requires an OpenAI API key to be provided as an environment variable "OPENAI_API_KEY". +The inputs are lists that are user-defined depending on the desired metric. +The output is a dictionary with a key `results` containing a list of evaluation results. +Each result is a dictionary with user-defined keys and values of either 0 for FALSE or 1 for TRUE respectively. + +Usage example: +```python +from haystack.components.evaluators import LLMEvaluator +evaluator = LLMEvaluator( + instructions="Is this answer problematic for children?", + inputs=[("predicted_answers", list[str])], + outputs=["score"], + examples=[ + {"inputs": {"predicted_answers": "Damn, this is straight outta hell!!!"}, "outputs": {"score": 1}}, + {"inputs": {"predicted_answers": "Football is the most popular sport."}, "outputs": {"score": 0}}, + ], +) +predicted_answers = [ + "Football is the most popular sport with around 4 billion followers worldwide", + "Python language was created by Guido van Rossum.", +] +results = evaluator.run(predicted_answers=predicted_answers) +print(results) +# {'results': [{'score': 0}, {'score': 0}]} +``` + + + +#### LLMEvaluator.\_\_init\_\_ + +```python +def __init__(instructions: str, + inputs: list[tuple[str, type[list]]], + outputs: list[str], + examples: list[dict[str, Any]], + progress_bar: bool = True, + *, + raise_on_failure: bool = True, + chat_generator: Optional[ChatGenerator] = None) +``` + +Creates an instance of LLMEvaluator. + +If no LLM is specified using the `chat_generator` parameter, the component will use OpenAI in JSON mode. + +**Arguments**: + +- `instructions`: The prompt instructions to use for evaluation. +Should be a question about the inputs that can be answered with yes or no. +- `inputs`: The inputs that the component expects as incoming connections and that it evaluates. +Each input is a tuple of an input name and input type. Input types must be lists. +- `outputs`: Output names of the evaluation results. They correspond to keys in the output dictionary. +- `examples`: Few-shot examples conforming to the expected input and output format as defined in the `inputs` and +`outputs` parameters. +Each example is a dictionary with keys "inputs" and "outputs" +They contain the input and output as dictionaries respectively. +- `raise_on_failure`: If True, the component will raise an exception on an unsuccessful API call. +- `progress_bar`: Whether to show a progress bar during the evaluation. +- `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`. + + + +#### LLMEvaluator.validate\_init\_parameters + +```python +@staticmethod +def validate_init_parameters(inputs: list[tuple[str, type[list]]], + outputs: list[str], examples: list[dict[str, + Any]]) +``` + +Validate the init parameters. + +**Arguments**: + +- `inputs`: The inputs to validate. +- `outputs`: The outputs to validate. +- `examples`: The examples to validate. + +**Raises**: + +- `ValueError`: If the inputs are not a list of tuples with a string and a type of list. +If the outputs are not a list of strings. +If the examples are not a list of dictionaries. +If any example does not have keys "inputs" and "outputs" with values that are dictionaries with string keys. + + + +#### LLMEvaluator.run + +```python +@component.output_types(results=list[dict[str, Any]]) +def run(**inputs) -> dict[str, Any] +``` + +Run the LLM evaluator. + +**Arguments**: + +- `inputs`: The input values to evaluate. The keys are the input names and the values are lists of input values. + +**Raises**: + +- `ValueError`: Only in the case that `raise_on_failure` is set to True and the received inputs are not lists or have +different lengths, or if the output is not a valid JSON or doesn't contain the expected keys. + +**Returns**: + +A dictionary with a `results` entry that contains a list of results. +Each result is a dictionary containing the keys as defined in the `outputs` parameter of the LLMEvaluator +and the evaluation results as the values. If an exception occurs for a particular input value, the result +will be `None` for that entry. +If the API is "openai" and the response contains a "meta" key, the metadata from OpenAI will be included +in the output dictionary, under the key "meta". + + + +#### LLMEvaluator.prepare\_template + +```python +def prepare_template() -> str +``` + +Prepare the prompt template. + +Combine instructions, inputs, outputs, and examples into one prompt template with the following format: +Instructions: +`` + +Generate the response in JSON format with the following keys: +`` +Consider the instructions and the examples below to determine those values. + +Examples: +`` + +Inputs: +`` +Outputs: + +**Returns**: + +The prompt template. + + + +#### LLMEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### LLMEvaluator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LLMEvaluator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### LLMEvaluator.validate\_input\_parameters + +```python +@staticmethod +def validate_input_parameters(expected: dict[str, Any], + received: dict[str, Any]) -> None +``` + +Validate the input parameters. + +**Arguments**: + +- `expected`: The expected input parameters. +- `received`: The received input parameters. + +**Raises**: + +- `ValueError`: If not all expected inputs are present in the received inputs +If the received inputs are not lists or have different lengths + + + +#### LLMEvaluator.is\_valid\_json\_and\_has\_expected\_keys + +```python +def is_valid_json_and_has_expected_keys(expected: list[str], + received: str) -> bool +``` + +Output must be a valid JSON with the expected keys. + +**Arguments**: + +- `expected`: Names of expected outputs +- `received`: Names of received outputs + +**Raises**: + +- `ValueError`: If the output is not a valid JSON with the expected keys: +- with `raise_on_failure` set to True a ValueError is raised. +- with `raise_on_failure` set to False a warning is issued and False is returned. + +**Returns**: + +True if the received output is a valid JSON with the expected keys, False otherwise. + + + +## Module sas\_evaluator + + + +### SASEvaluator + +SASEvaluator computes the Semantic Answer Similarity (SAS) between a list of predictions and a one of ground truths. + +It's usually used in Retrieval Augmented Generation (RAG) pipelines to evaluate the quality of the generated +answers. The SAS is computed using a pre-trained model from the Hugging Face model hub. The model can be either a +Bi-Encoder or a Cross-Encoder. The choice of the model is based on the `model` parameter. + +Usage example: +```python +from haystack.components.evaluators.sas_evaluator import SASEvaluator + +evaluator = SASEvaluator(model="cross-encoder/ms-marco-MiniLM-L-6-v2") +evaluator.warm_up() +ground_truths = [ + "A construction budget of US $2.3 billion", + "The Eiffel Tower, completed in 1889, symbolizes Paris's cultural magnificence.", + "The Meiji Restoration in 1868 transformed Japan into a modernized world power.", +] +predictions = [ + "A construction budget of US $2.3 billion", + "The Eiffel Tower, completed in 1889, symbolizes Paris's cultural magnificence.", + "The Meiji Restoration in 1868 transformed Japan into a modernized world power.", +] +result = evaluator.run( + ground_truths_answers=ground_truths, predicted_answers=predictions +) + +print(result["score"]) +# 0.9999673763910929 + +print(result["individual_scores"]) +# [0.9999765157699585, 0.999968409538269, 0.9999572038650513] +``` + + + +#### SASEvaluator.\_\_init\_\_ + +```python +def __init__( + model: str = "sentence-transformers/paraphrase-multilingual-mpnet-base-v2", + batch_size: int = 32, + device: Optional[ComponentDevice] = None, + token: Secret = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], + strict=False)) +``` + +Creates a new instance of SASEvaluator. + +**Arguments**: + +- `model`: SentenceTransformers semantic textual similarity model, should be path or string pointing to a downloadable +model. +- `batch_size`: Number of prediction-label pairs to encode at once. +- `device`: The device on which the model is loaded. If `None`, the default device is automatically selected. +- `token`: The Hugging Face token for HTTP bearer authorization. +You can find your HF token in your [account settings](https://huggingface.co/settings/tokens) + + + +#### SASEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### SASEvaluator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "SASEvaluator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### SASEvaluator.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SASEvaluator.run + +```python +@component.output_types(score=float, individual_scores=list[float]) +def run(ground_truth_answers: list[str], + predicted_answers: list[str]) -> dict[str, Any] +``` + +SASEvaluator component run method. + +Run the SASEvaluator to compute the Semantic Answer Similarity (SAS) between a list of predicted answers +and a list of ground truth answers. Both must be list of strings of same length. + +**Arguments**: + +- `ground_truth_answers`: A list of expected answers for each question. +- `predicted_answers`: A list of generated answers for each question. + +**Returns**: + +A dictionary with the following outputs: +- `score`: Mean SAS score over all the predictions/ground-truth pairs. +- `individual_scores`: A list of similarity scores for each prediction/ground-truth pair. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/extractors_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/extractors_api.md new file mode 100644 index 0000000000..3aa6b3c60e --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/extractors_api.md @@ -0,0 +1,648 @@ +--- +title: "Extractors" +id: extractors-api +description: "Components to extract specific elements from textual data." +slug: "/extractors-api" +--- + + + +## Module named\_entity\_extractor + + + +### NamedEntityExtractorBackend + +NLP backend to use for Named Entity Recognition. + + + +#### HUGGING\_FACE + +Uses an Hugging Face model and pipeline. + + + +#### SPACY + +Uses a spaCy model and pipeline. + + + +#### NamedEntityExtractorBackend.from\_str + +```python +@staticmethod +def from_str(string: str) -> "NamedEntityExtractorBackend" +``` + +Convert a string to a NamedEntityExtractorBackend enum. + + + +### NamedEntityAnnotation + +Describes a single NER annotation. + +**Arguments**: + +- `entity`: Entity label. +- `start`: Start index of the entity in the document. +- `end`: End index of the entity in the document. +- `score`: Score calculated by the model. + + + +### NamedEntityExtractor + +Annotates named entities in a collection of documents. + +The component supports two backends: Hugging Face and spaCy. The +former can be used with any sequence classification model from the +[Hugging Face model hub](https://huggingface.co/models), while the +latter can be used with any [spaCy model](https://spacy.io/models) +that contains an NER component. Annotations are stored as metadata +in the documents. + +Usage example: +```python +from haystack import Document +from haystack.components.extractors.named_entity_extractor import NamedEntityExtractor + +documents = [ + Document(content="I'm Merlin, the happy pig!"), + Document(content="My name is Clara and I live in Berkeley, California."), +] +extractor = NamedEntityExtractor(backend="hugging_face", model="dslim/bert-base-NER") +extractor.warm_up() +results = extractor.run(documents=documents)["documents"] +annotations = [NamedEntityExtractor.get_stored_annotations(doc) for doc in results] +print(annotations) +``` + + + +#### NamedEntityExtractor.\_\_init\_\_ + +```python +def __init__( + *, + backend: Union[str, NamedEntityExtractorBackend], + model: str, + pipeline_kwargs: Optional[dict[str, Any]] = None, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], + strict=False) +) -> None +``` + +Create a Named Entity extractor component. + +**Arguments**: + +- `backend`: Backend to use for NER. +- `model`: Name of the model or a path to the model on +the local disk. Dependent on the backend. +- `pipeline_kwargs`: Keyword arguments passed to the pipeline. The +pipeline can override these arguments. Dependent on the backend. +- `device`: The device on which the model is loaded. If `None`, +the default device is automatically selected. If a +device/device map is specified in `pipeline_kwargs`, +it overrides this parameter (only applicable to the +HuggingFace backend). +- `token`: The API token to download private models from Hugging Face. + + + +#### NamedEntityExtractor.warm\_up + +```python +def warm_up() +``` + +Initialize the component. + +**Raises**: + +- `ComponentError`: If the backend fails to initialize successfully. + + + +#### NamedEntityExtractor.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document], batch_size: int = 1) -> dict[str, Any] +``` + +Annotate named entities in each document and store the annotations in the document's metadata. + +**Arguments**: + +- `documents`: Documents to process. +- `batch_size`: Batch size used for processing the documents. + +**Raises**: + +- `ComponentError`: If the backend fails to process a document. + +**Returns**: + +Processed documents. + + + +#### NamedEntityExtractor.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### NamedEntityExtractor.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "NamedEntityExtractor" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### NamedEntityExtractor.initialized + +```python +@property +def initialized() -> bool +``` + +Returns if the extractor is ready to annotate text. + + + +#### NamedEntityExtractor.get\_stored\_annotations + +```python +@classmethod +def get_stored_annotations( + cls, document: Document) -> Optional[list[NamedEntityAnnotation]] +``` + +Returns the document's named entity annotations stored in its metadata, if any. + +**Arguments**: + +- `document`: Document whose annotations are to be fetched. + +**Returns**: + +The stored annotations. + + + +## Module llm\_metadata\_extractor + + + +### LLMMetadataExtractor + +Extracts metadata from documents using a Large Language Model (LLM). + +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, +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 +will be added to the document's metadata field. If the LLM fails to extract metadata from a document, the document +will be added to the `failed_documents` list. The failed documents will have the keys `metadata_extraction_error` and +`metadata_extraction_response` in their metadata. These documents can be re-run with another extractor to +extract metadata by using the `metadata_extraction_response` and `metadata_extraction_error` in the prompt. + +```python +from haystack import Document +from haystack.components.extractors.llm_metadata_extractor import LLMMetadataExtractor +from haystack.components.generators.chat import OpenAIChatGenerator + +NER_PROMPT = ''' +-Goal- +Given text and a list of entity types, identify all entities of those types from the text. + +-Steps- +1. Identify all entities. For each identified entity, extract the following information: +- entity: Name of the entity +- entity_type: One of the following types: [organization, product, service, industry] +Format each entity as a JSON like: {"entity": , "entity_type": } + +2. Return output in a single list with all the entities identified in steps 1. + +-Examples- +###################### +Example 1: +entity_types: [organization, person, partnership, financial metric, product, service, industry, investment strategy, market trend] +text: Another area of strength is our co-brand issuance. Visa is the primary network partner for eight of the top +10 co-brand partnerships in the US today and we are pleased that Visa has finalized a multi-year extension of +our successful credit co-branded partnership with Alaska Airlines, a portfolio that benefits from a loyal customer +base and high cross-border usage. +We have also had significant co-brand momentum in CEMEA. First, we launched a new co-brand card in partnership +with Qatar Airways, British Airways and the National Bank of Kuwait. Second, we expanded our strong global +Marriott relationship to launch Qatar's first hospitality co-branded card with Qatar Islamic Bank. Across the +United Arab Emirates, we now have exclusive agreements with all the leading airlines marked by a recent +agreement with Emirates Skywards. +And we also signed an inaugural Airline co-brand agreement in Morocco with Royal Air Maroc. Now newer digital +issuers are equally +------------------------ +output: +{"entities": [{"entity": "Visa", "entity_type": "company"}, {"entity": "Alaska Airlines", "entity_type": "company"}, {"entity": "Qatar Airways", "entity_type": "company"}, {"entity": "British Airways", "entity_type": "company"}, {"entity": "National Bank of Kuwait", "entity_type": "company"}, {"entity": "Marriott", "entity_type": "company"}, {"entity": "Qatar Islamic Bank", "entity_type": "company"}, {"entity": "Emirates Skywards", "entity_type": "company"}, {"entity": "Royal Air Maroc", "entity_type": "company"}]} +############################# +-Real Data- +###################### +entity_types: [company, organization, person, country, product, service] +text: {{ document.content }} +###################### +output: +''' + +docs = [ + Document(content="deepset was founded in 2018 in Berlin, and is known for its Haystack framework"), + Document(content="Hugging Face is a company that was founded in New York, USA and is known for its Transformers library") +] + +chat_generator = OpenAIChatGenerator( + generation_kwargs={ + "max_completion_tokens": 500, + "temperature": 0.0, + "seed": 0, + "response_format": {"type": "json_object"}, + }, + max_retries=1, + timeout=60.0, +) + +extractor = LLMMetadataExtractor( + prompt=NER_PROMPT, + chat_generator=generator, + expected_keys=["entities"], + raise_on_failure=False, +) + +extractor.warm_up() +extractor.run(documents=docs) +>> {'documents': [ + Document(id=.., content: 'deepset was founded in 2018 in Berlin, and is known for its Haystack framework', + meta: {'entities': [{'entity': 'deepset', 'entity_type': 'company'}, {'entity': 'Berlin', 'entity_type': 'city'}, + {'entity': 'Haystack', 'entity_type': 'product'}]}), + Document(id=.., content: 'Hugging Face is a company that was founded in New York, USA and is known for its Transformers library', + meta: {'entities': [ + {'entity': 'Hugging Face', 'entity_type': 'company'}, {'entity': 'New York', 'entity_type': 'city'}, + {'entity': 'USA', 'entity_type': 'country'}, {'entity': 'Transformers', 'entity_type': 'product'} + ]}) + ] + 'failed_documents': [] + } +>> +``` + + + +#### LLMMetadataExtractor.\_\_init\_\_ + +```python +def __init__(prompt: str, + chat_generator: ChatGenerator, + expected_keys: Optional[list[str]] = None, + page_range: Optional[list[Union[str, int]]] = None, + raise_on_failure: bool = False, + max_workers: int = 3) +``` + +Initializes the LLMMetadataExtractor. + +**Arguments**: + +- `prompt`: The prompt to be used for the LLM. +- `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`. +- `expected_keys`: The keys expected in the JSON output from the LLM. +- `page_range`: A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract +metadata from the first and third pages of each document. It also accepts printable range strings, e.g.: +['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10,11, 12. +If None, metadata will be extracted from the entire document for each document in the documents list. +This parameter is optional and can be overridden in the `run` method. +- `raise_on_failure`: Whether to raise an error on failure during the execution of the Generator or +validation of the JSON output. +- `max_workers`: The maximum number of workers to use in the thread pool executor. + + + +#### LLMMetadataExtractor.warm\_up + +```python +def warm_up() +``` + +Warm up the LLM provider component. + + + +#### LLMMetadataExtractor.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### LLMMetadataExtractor.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LLMMetadataExtractor" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +An instance of the component. + + + +#### LLMMetadataExtractor.run + +```python +@component.output_types(documents=list[Document], + failed_documents=list[Document]) +def run(documents: list[Document], + page_range: Optional[list[Union[str, int]]] = None) +``` + +Extract metadata from documents using a Large Language Model. + +If `page_range` is provided, the metadata will be extracted from the specified range of pages. This component +will split the documents into pages and extract metadata from the specified range of pages. The metadata will be +extracted from the entire document if `page_range` is not provided. + +The original documents will be returned updated with the extracted metadata. + +**Arguments**: + +- `documents`: List of documents to extract metadata from. +- `page_range`: A range of pages to extract metadata from. For example, page_range=['1', '3'] will extract +metadata from the first and third pages of each document. It also accepts printable range +strings, e.g.: ['1-3', '5', '8', '10-12'] will extract metadata from pages 1, 2, 3, 5, 8, 10, +11, 12. +If None, metadata will be extracted from the entire document for each document in the +documents list. + +**Returns**: + +A dictionary with the keys: +- "documents": A list of documents that were successfully updated with the extracted metadata. +- "failed_documents": A list of documents that failed to extract metadata. These documents will have +"metadata_extraction_error" and "metadata_extraction_response" in their metadata. These documents can be +re-run with the extractor to extract metadata. + + + +## Module image/llm\_document\_content\_extractor + + + +### LLMDocumentContentExtractor + +Extracts textual content from image-based documents using a vision-enabled LLM (Large Language Model). + +This component converts each input document into an image using the DocumentToImageContent component, +uses a prompt to instruct the LLM on how to extract content, and uses a ChatGenerator to extract structured +textual content based on the provided prompt. + +The prompt must not contain variables; it should only include instructions for the LLM. Image data and the prompt +are passed together to the LLM as a chat message. + +Documents for which the LLM fails to extract content are returned in a separate `failed_documents` list. These +failed documents will have a `content_extraction_error` entry in their metadata. This metadata can be used for +debugging or for reprocessing the documents later. + +### Usage example +```python +from haystack import Document +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.extractors.image import LLMDocumentContentExtractor +chat_generator = OpenAIChatGenerator() +extractor = LLMDocumentContentExtractor(chat_generator=chat_generator) +documents = [ + Document(content="", meta={"file_path": "image.jpg"}), + Document(content="", meta={"file_path": "document.pdf", "page_number": 1}), +] +updated_documents = extractor.run(documents=documents)["documents"] +print(updated_documents) +# [Document(content='Extracted text from image.jpg', +# meta={'file_path': 'image.jpg'}), +# ...] +``` + + + +#### LLMDocumentContentExtractor.\_\_init\_\_ + +```python +def __init__(*, + chat_generator: ChatGenerator, + prompt: str = DEFAULT_PROMPT_TEMPLATE, + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, int]] = None, + raise_on_failure: bool = False, + max_workers: int = 3) +``` + +Initialize the LLMDocumentContentExtractor component. + +**Arguments**: + +- `chat_generator`: A ChatGenerator instance representing the LLM used to extract text. This generator must +support vision-based input and return a plain text response. +- `prompt`: Instructional text provided to the LLM. It must not contain Jinja variables. +The prompt should only contain instructions on how to extract the content of the image-based document. +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low". +This will be passed to chat_generator when processing the images. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `raise_on_failure`: If True, exceptions from the LLM are raised. If False, failed documents are logged +and returned. +- `max_workers`: Maximum number of threads used to parallelize LLM calls across documents using a +ThreadPoolExecutor. + + + +#### LLMDocumentContentExtractor.warm\_up + +```python +def warm_up() +``` + +Warm up the ChatGenerator if it has a warm_up method. + + + +#### LLMDocumentContentExtractor.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### LLMDocumentContentExtractor.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LLMDocumentContentExtractor" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +An instance of the component. + + + +#### LLMDocumentContentExtractor.run + +```python +@component.output_types(documents=list[Document], + failed_documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Run content extraction on a list of image-based documents using a vision-capable LLM. + +Each document is passed to the LLM along with a predefined prompt. The response is used to update the document's +content. If the extraction fails, the document is returned in the `failed_documents` list with metadata +describing the failure. + +**Arguments**: + +- `documents`: A list of image-based documents to process. Each must have a valid file path in its metadata. + +**Returns**: + +A dictionary with: +- "documents": Successfully processed documents, updated with extracted content. +- "failed_documents": Documents that failed processing, annotated with failure metadata. + + + +## Module regex\_text\_extractor + + + +### RegexTextExtractor + +Extracts text from chat message or string input using a regex pattern. + +RegexTextExtractor parses input text or ChatMessages using a provided regular expression pattern. +It can be configured to search through all messages or only the last message in a list of ChatMessages. + +### Usage example + +```python +from haystack_experimental.components.extractors import RegexTextExtractor +from haystack.dataclasses import ChatMessage + +# Using with a string +parser = RegexTextExtractor(regex_pattern='') +result = parser.run(text_or_messages='hahahah') +# result: {"captured_text": "github.com/hahahaha"} + +# Using with ChatMessages +messages = [ChatMessage.from_user('hahahah')] +result = parser.run(text_or_messages=messages) +# result: {"captured_text": "github.com/hahahaha"} +``` + + + +#### RegexTextExtractor.\_\_init\_\_ + +```python +def __init__(regex_pattern: str) +``` + +Creates an instance of the RegexTextExtractor component. + +**Arguments**: + +- `regex_pattern`: The regular expression pattern used to extract text. +The pattern should include a capture group to extract the desired text. +Example: `''` captures `'github.com/hahahaha'` from `''`. + + + +#### RegexTextExtractor.run + +```python +@component.output_types(captured_text=str, captured_texts=list[str]) +def run(text_or_messages: Union[str, list[ChatMessage]]) -> dict +``` + +Extracts text from input using the configured regex pattern. + +**Arguments**: + +- `text_or_messages`: Either a string or a list of ChatMessage objects to search through. + +**Raises**: + +- `None`: - ValueError: if receiving a list the last element is not a ChatMessage instance. + +**Returns**: + +- If match found: `{"captured_text": "matched text"}` +- If no match and `return_empty_on_no_match=True`: `{}` + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/fetchers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/fetchers_api.md new file mode 100644 index 0000000000..91aba1dd9c --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/fetchers_api.md @@ -0,0 +1,144 @@ +--- +title: "Fetchers" +id: fetchers-api +description: "Fetches content from a list of URLs and returns a list of extracted content streams." +slug: "/fetchers-api" +--- + + + +## Module link\_content + + + +### LinkContentFetcher + +Fetches and extracts content from URLs. + +It supports various content types, retries on failures, and automatic user-agent rotation for failed web +requests. Use it as the data-fetching step in your pipelines. + +You may need to convert LinkContentFetcher's output into a list of documents. Use HTMLToDocument +converter to do this. + +### Usage example + +```python +from haystack.components.fetchers.link_content import LinkContentFetcher + +fetcher = LinkContentFetcher() +streams = fetcher.run(urls=["https://www.google.com"])["streams"] + +assert len(streams) == 1 +assert streams[0].meta == {'content_type': 'text/html', 'url': 'https://www.google.com'} +assert streams[0].data +``` + +For async usage: + +```python +import asyncio +from haystack.components.fetchers import LinkContentFetcher + +async def fetch_async(): + fetcher = LinkContentFetcher() + result = await fetcher.run_async(urls=["https://www.google.com"]) + return result["streams"] + +streams = asyncio.run(fetch_async()) +``` + + + +#### LinkContentFetcher.\_\_init\_\_ + +```python +def __init__(raise_on_failure: bool = True, + user_agents: Optional[list[str]] = None, + retry_attempts: int = 2, + timeout: int = 3, + http2: bool = False, + client_kwargs: Optional[dict] = None, + request_headers: Optional[dict[str, str]] = None) +``` + +Initializes the component. + +**Arguments**: + +- `raise_on_failure`: If `True`, raises an exception if it fails to fetch a single URL. +For multiple URLs, it logs errors and returns the content it successfully fetched. +- `user_agents`: [User agents](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) +for fetching content. If `None`, a default user agent is used. +- `retry_attempts`: The number of times to retry to fetch the URL's content. +- `timeout`: Timeout in seconds for the request. +- `http2`: Whether to enable HTTP/2 support for requests. Defaults to False. +Requires the 'h2' package to be installed (via `pip install httpx[http2]`). +- `client_kwargs`: Additional keyword arguments to pass to the httpx client. +If `None`, default values are used. + + + +#### LinkContentFetcher.\_\_del\_\_ + +```python +def __del__() +``` + +Clean up resources when the component is deleted. + +Closes both the synchronous and asynchronous HTTP clients to prevent +resource leaks. + + + +#### LinkContentFetcher.run + +```python +@component.output_types(streams=list[ByteStream]) +def run(urls: list[str]) +``` + +Fetches content from a list of URLs and returns a list of extracted content streams. + +Each content stream is a `ByteStream` object containing the extracted content as binary data. +Each ByteStream object in the returned list corresponds to the contents of a single URL. +The content type of each stream is stored in the metadata of the ByteStream object under +the key "content_type". The URL of the fetched content is stored under the key "url". + +**Arguments**: + +- `urls`: A list of URLs to fetch content from. + +**Raises**: + +- `Exception`: If the provided list of URLs contains only a single URL, and `raise_on_failure` is set to +`True`, an exception will be raised in case of an error during content retrieval. +In all other scenarios, any retrieval errors are logged, and a list of successfully retrieved `ByteStream` + objects is returned. + +**Returns**: + +`ByteStream` objects representing the extracted content. + + + +#### LinkContentFetcher.run\_async + +```python +@component.output_types(streams=list[ByteStream]) +async def run_async(urls: list[str]) +``` + +Asynchronously fetches content from a list of URLs and returns a list of extracted content streams. + +This is the asynchronous version of the `run` method with the same parameters and return values. + +**Arguments**: + +- `urls`: A list of URLs to fetch content from. + +**Returns**: + +`ByteStream` objects representing the extracted content. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/generators_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/generators_api.md new file mode 100644 index 0000000000..cf56070d80 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/generators_api.md @@ -0,0 +1,2419 @@ +--- +title: "Generators" +id: generators-api +description: "Enables text generation using LLMs." +slug: "/generators-api" +--- + + + +## Module azure + + + +### AzureOpenAIGenerator + +Generates text using OpenAI's large language models (LLMs). + +It works with the gpt-4 - type models and supports streaming responses +from OpenAI API. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.ChatCompletion.create` will work here too. + + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). + + +### Usage example + +```python +from haystack.components.generators import AzureOpenAIGenerator +from haystack.utils import Secret +client = AzureOpenAIGenerator( + azure_endpoint="", + api_key=Secret.from_token(""), + azure_deployment="") +response = client.run("What's Natural Language Processing? Be brief.") +print(response) +``` + +``` +>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on +>> the interaction between computers and human language. It involves enabling computers to understand, interpret, +>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{'model': +>> 'gpt-4o-mini', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 16, +>> 'completion_tokens': 49, 'total_tokens': 65}}]} +``` + + + +#### AzureOpenAIGenerator.\_\_init\_\_ + +```python +def __init__(azure_endpoint: Optional[str] = None, + api_version: Optional[str] = "2023-05-15", + azure_deployment: Optional[str] = "gpt-4o-mini", + api_key: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_API_KEY", strict=False), + azure_ad_token: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_AD_TOKEN", strict=False), + organization: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + system_prompt: Optional[str] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[dict[str, Any]] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + default_headers: Optional[dict[str, str]] = None, + *, + azure_ad_token_provider: Optional[AzureADTokenProvider] = None) +``` + +Initialize the Azure OpenAI Generator. + +**Arguments**: + +- `azure_endpoint`: The endpoint of the deployed model, for example `https://example-resource.azure.openai.com/`. +- `api_version`: The version of the API to use. Defaults to 2023-05-15. +- `azure_deployment`: The deployment of the model, usually the model name. +- `api_key`: The API key to use for authentication. +- `azure_ad_token`: [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id). +- `organization`: Your organization ID, defaults to `None`. For help, see +[Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `streaming_callback`: A callback function called when a new token is received from the stream. +It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `system_prompt`: The system prompt to use for text generation. If not provided, the Generator +omits the system prompt and uses the default system prompt. +- `timeout`: Timeout for AzureOpenAI client. If not set, it is inferred from the +`OPENAI_TIMEOUT` environment variable or set to 30. +- `max_retries`: Maximum retries to establish contact with AzureOpenAI if it returns an internal error. +If not set, it is inferred from the `OPENAI_MAX_RETRIES` environment variable or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). +- `generation_kwargs`: Other parameters to use for the model, sent directly to +the OpenAI endpoint. See [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat) for +more details. +Some of the supported parameters: +- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion, + including visible output tokens and reasoning tokens. +- `temperature`: The sampling temperature to use. Higher values mean the model takes more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `n`: The number of completions to generate for each prompt. For example, with 3 prompts and n=2, + the LLM will generate two completions per prompt, resulting in 6 completions total. +- `stop`: One or more sequences after which the LLM should stop generating tokens. +- `presence_penalty`: The penalty applied if a token is already present. + Higher values make the model less likely to repeat the token. +- `frequency_penalty`: Penalty applied if a token has already been generated. + Higher values make the model less likely to repeat the token. +- `logit_bias`: Adds a logit bias to specific tokens. The keys of the dictionary are tokens, and the + values are the bias to add to that token. +- `default_headers`: Default headers to use for the AzureOpenAI client. +- `azure_ad_token_provider`: A function that returns an Azure Active Directory token, will be invoked on +every request. + + + +#### AzureOpenAIGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AzureOpenAIGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AzureOpenAIGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AzureOpenAIGenerator.run + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +def run(prompt: str, + system_prompt: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) +``` + +Invoke the text generation inference based on the provided messages and generation parameters. + +**Arguments**: + +- `prompt`: The string prompt to use for text generation. +- `system_prompt`: The system prompt to use for text generation. If this run time system prompt is omitted, the system +prompt, if defined at initialisation time, is used. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. For more details on the parameters supported by the OpenAI API, refer to +the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create). + +**Returns**: + +A list of strings containing the generated responses and a list of dictionaries containing the metadata +for each response. + + + +## Module hugging\_face\_local + + + +### HuggingFaceLocalGenerator + +Generates text using models from Hugging Face that run locally. + +LLMs running locally may need powerful hardware. + +### Usage example + +```python +from haystack.components.generators import HuggingFaceLocalGenerator + +generator = HuggingFaceLocalGenerator( + model="google/flan-t5-large", + task="text2text-generation", + generation_kwargs={"max_new_tokens": 100, "temperature": 0.9}) + +generator.warm_up() + +print(generator.run("Who is the best American actor?")) +# {'replies': ['John Cusack']} +``` + + + +#### HuggingFaceLocalGenerator.\_\_init\_\_ + +```python +def __init__(model: str = "google/flan-t5-base", + task: Optional[Literal["text-generation", + "text2text-generation"]] = None, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + generation_kwargs: Optional[dict[str, Any]] = None, + huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None, + stop_words: Optional[list[str]] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +Creates an instance of a HuggingFaceLocalGenerator. + +**Arguments**: + +- `model`: The Hugging Face text generation model name or path. +- `task`: The task for the Hugging Face pipeline. Possible options: +- `text-generation`: Supported by decoder models, like GPT. +- `text2text-generation`: Supported by encoder-decoder models, like T5. +If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored. +If not specified, the component calls the Hugging Face API to infer the task from the model name. +- `device`: The device for loading the model. If `None`, automatically selects the default device. +If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter. +- `token`: The token to use as HTTP bearer authorization for remote files. +If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored. +- `generation_kwargs`: A dictionary with keyword arguments to customize text generation. +Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`. +See Hugging Face's documentation for more information: +- [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation) +- [transformers.GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig) +- `huggingface_pipeline_kwargs`: Dictionary with keyword arguments to initialize the +Hugging Face pipeline for text generation. +These keyword arguments provide fine-grained control over the Hugging Face pipeline. +In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters. +For available kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task). +In this dictionary, you can also include `model_kwargs` to specify the kwargs for model initialization: +[transformers.PreTrainedModel.from_pretrained](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained) +- `stop_words`: If the model generates a stop word, the generation stops. +If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`. +For some chat models, the output includes both the new text and the original prompt. +In these cases, make sure your prompt has no stop words. +- `streaming_callback`: An optional callable for handling streaming responses. + + + +#### HuggingFaceLocalGenerator.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### HuggingFaceLocalGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HuggingFaceLocalGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceLocalGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### HuggingFaceLocalGenerator.run + +```python +@component.output_types(replies=list[str]) +def run(prompt: str, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) +``` + +Run the text generation model on the given prompt. + +**Arguments**: + +- `prompt`: A string representing the prompt. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. + +**Returns**: + +A dictionary containing the generated replies. +- replies: A list of strings representing the generated replies. + + + +## Module hugging\_face\_api + + + +### HuggingFaceAPIGenerator + +Generates text using Hugging Face APIs. + +Use it with the following Hugging Face APIs: +- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints) +- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference) + +**Note:** As of July 2025, the Hugging Face Inference API no longer offers generative models through the +`text_generation` endpoint. Generative models are now only available through providers supporting the +`chat_completion` endpoint. As a result, this component might no longer work with the Hugging Face Inference API. +Use the `HuggingFaceAPIChatGenerator` component, which supports the `chat_completion` endpoint. + +### Usage examples + +#### With Hugging Face Inference Endpoints + + +#### With self-hosted text generation inference + +#### With the free serverless inference API + +Be aware that this example might not work as the Hugging Face Inference API no longer offer models that support the +`text_generation` endpoint. Use the `HuggingFaceAPIChatGenerator` for generative models through the +`chat_completion` endpoint. + +```python +from haystack.components.generators import HuggingFaceAPIGenerator +from haystack.utils import Secret + +generator = HuggingFaceAPIGenerator(api_type="inference_endpoints", + api_params={"url": ""}, + token=Secret.from_token("")) + +result = generator.run(prompt="What's Natural Language Processing?") +print(result) +``` +```python +from haystack.components.generators import HuggingFaceAPIGenerator + +generator = HuggingFaceAPIGenerator(api_type="text_generation_inference", + api_params={"url": "http://localhost:8080"}) + +result = generator.run(prompt="What's Natural Language Processing?") +print(result) +``` +```python +from haystack.components.generators import HuggingFaceAPIGenerator +from haystack.utils import Secret + +generator = HuggingFaceAPIGenerator(api_type="serverless_inference_api", + api_params={"model": "HuggingFaceH4/zephyr-7b-beta"}, + token=Secret.from_token("")) + +result = generator.run(prompt="What's Natural Language Processing?") +print(result) +``` + + + +#### HuggingFaceAPIGenerator.\_\_init\_\_ + +```python +def __init__(api_type: Union[HFGenerationAPIType, str], + api_params: dict[str, str], + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + generation_kwargs: Optional[dict[str, Any]] = None, + stop_words: Optional[list[str]] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +Initialize the HuggingFaceAPIGenerator instance. + +**Arguments**: + +- `api_type`: The type of Hugging Face API to use. Available types: +- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference). +- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints). +- `serverless_inference_api`: See [Serverless Inference API](https://huggingface.co/inference-api). + This might no longer work due to changes in the models offered in the Hugging Face Inference API. + Please use the `HuggingFaceAPIChatGenerator` component instead. +- `api_params`: A dictionary with the following keys: +- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`. +- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or +`TEXT_GENERATION_INFERENCE`. +- Other parameters specific to the chosen API type, such as `timeout`, `headers`, `provider` etc. +- `token`: The Hugging Face token to use as HTTP bearer authorization. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). +- `generation_kwargs`: A dictionary with keyword arguments to customize text generation. Some examples: `max_new_tokens`, +`temperature`, `top_k`, `top_p`. +For details, see [Hugging Face documentation](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation) +for more information. +- `stop_words`: An optional list of strings representing the stop words. +- `streaming_callback`: An optional callable for handling streaming responses. + + + +#### HuggingFaceAPIGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +A dictionary containing the serialized component. + + + +#### HuggingFaceAPIGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIGenerator" +``` + +Deserialize this component from a dictionary. + + + +#### HuggingFaceAPIGenerator.run + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +def run(prompt: str, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) +``` + +Invoke the text generation inference for the given prompt and generation parameters. + +**Arguments**: + +- `prompt`: A string representing the prompt. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. + +**Returns**: + +A dictionary with the generated replies and metadata. Both are lists of length n. +- replies: A list of strings representing the generated replies. + + + +## Module openai + + + +### OpenAIGenerator + +Generates text using OpenAI's large language models (LLMs). + +It works with the gpt-4 and o-series models and supports streaming responses +from OpenAI API. It uses strings as input and output. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.ChatCompletion.create` will work here too. + + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). + +### Usage example + +```python +from haystack.components.generators import OpenAIGenerator +client = OpenAIGenerator() +response = client.run("What's Natural Language Processing? Be brief.") +print(response) + +>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on +>> the interaction between computers and human language. It involves enabling computers to understand, interpret, +>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{'model': +>> 'gpt-4o-mini', 'index': 0, 'finish_reason': 'stop', 'usage': {'prompt_tokens': 16, +>> 'completion_tokens': 49, 'total_tokens': 65}}]} +``` + + + +#### OpenAIGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "gpt-4o-mini", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + system_prompt: Optional[str] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an instance of OpenAIGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-4o-mini + +By setting the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' you can change the timeout and max_retries parameters +in the OpenAI client. + +**Arguments**: + +- `api_key`: The OpenAI API key to connect to OpenAI. +- `model`: The name of the model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: An optional base URL. +- `organization`: The Organization ID, defaults to `None`. +- `system_prompt`: The system prompt to use for text generation. If not provided, the system prompt is +omitted, and the default system prompt of the model is used. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for +more details. +Some of the supported parameters: +- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion, + including visible output tokens and reasoning tokens. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2, + it will generate two completions for each of the three prompts, ending up with 6 completions in total. +- `stop`: One or more sequences after which the LLM should stop generating tokens. +- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean + the model will be less likely to repeat the same token in the text. +- `frequency_penalty`: What penalty to apply if a token has already been generated in the text. + Bigger values mean the model will be less likely to repeat the same token in the text. +- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the + values are the bias to add to that token. +- `timeout`: Timeout for OpenAI Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment variable +or set to 30. +- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error, if not set it is inferred +from the `OPENAI_MAX_RETRIES` environment variable or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### OpenAIGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### OpenAIGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### OpenAIGenerator.run + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +def run(prompt: str, + system_prompt: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) +``` + +Invoke the text generation inference based on the provided messages and generation parameters. + +**Arguments**: + +- `prompt`: The string prompt to use for text generation. +- `system_prompt`: The system prompt to use for text generation. If this run time system prompt is omitted, the system +prompt, if defined at initialisation time, is used. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. For more details on the parameters supported by the OpenAI API, refer to +the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create). + +**Returns**: + +A list of strings containing the generated responses and a list of dictionaries containing the metadata +for each response. + + + +## Module openai\_dalle + + + +### DALLEImageGenerator + +Generates images using OpenAI's DALL-E model. + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/images/create). + +### Usage example + +```python +from haystack.components.generators import DALLEImageGenerator +image_generator = DALLEImageGenerator() +response = image_generator.run("Show me a picture of a black cat.") +print(response) +``` + + + +#### DALLEImageGenerator.\_\_init\_\_ + +```python +def __init__(model: str = "dall-e-3", + quality: Literal["standard", "hd"] = "standard", + size: Literal["256x256", "512x512", "1024x1024", "1792x1024", + "1024x1792"] = "1024x1024", + response_format: Literal["url", "b64_json"] = "url", + api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an instance of DALLEImageGenerator. Unless specified otherwise in `model`, uses OpenAI's dall-e-3. + +**Arguments**: + +- `model`: The model to use for image generation. Can be "dall-e-2" or "dall-e-3". +- `quality`: The quality of the generated image. Can be "standard" or "hd". +- `size`: The size of the generated images. +Must be one of 256x256, 512x512, or 1024x1024 for dall-e-2. +Must be one of 1024x1024, 1792x1024, or 1024x1792 for dall-e-3 models. +- `response_format`: The format of the response. Can be "url" or "b64_json". +- `api_key`: The OpenAI API key to connect to OpenAI. +- `api_base_url`: An optional base URL. +- `organization`: The Organization ID, defaults to `None`. +- `timeout`: Timeout for OpenAI Client calls. If not set, it is inferred from the `OPENAI_TIMEOUT` environment variable +or set to 30. +- `max_retries`: Maximum retries to establish contact with OpenAI if it returns an internal error. If not set, it is inferred +from the `OPENAI_MAX_RETRIES` environment variable or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### DALLEImageGenerator.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the OpenAI client. + + + +#### DALLEImageGenerator.run + +```python +@component.output_types(images=list[str], revised_prompt=str) +def run(prompt: str, + size: Optional[Literal["256x256", "512x512", "1024x1024", "1792x1024", + "1024x1792"]] = None, + quality: Optional[Literal["standard", "hd"]] = None, + response_format: Optional[Optional[Literal["url", + "b64_json"]]] = None) +``` + +Invokes the image generation inference based on the provided prompt and generation parameters. + +**Arguments**: + +- `prompt`: The prompt to generate the image. +- `size`: If provided, overrides the size provided during initialization. +- `quality`: If provided, overrides the quality provided during initialization. +- `response_format`: If provided, overrides the response format provided during initialization. + +**Returns**: + +A dictionary containing the generated list of images and the revised prompt. +Depending on the `response_format` parameter, the list of images can be URLs or base64 encoded JSON strings. +The revised prompt is the prompt that was used to generate the image, if there was any revision +to the prompt made by OpenAI. + + + +#### DALLEImageGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### DALLEImageGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DALLEImageGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +## Module chat/azure + + + +### AzureOpenAIChatGenerator + +Generates text using OpenAI's models on Azure. + +It works with the gpt-4 - type models and supports streaming responses +from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) +format in input and output. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.ChatCompletion.create` will work here too. + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). + +### Usage example + +```python +from haystack.components.generators.chat import AzureOpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = AzureOpenAIChatGenerator( + azure_endpoint="", + api_key=Secret.from_token(""), + azure_deployment="") +response = client.run(messages) +print(response) +``` + +``` +{'replies': + [ChatMessage(_role=, _content=[TextContent(text= + "Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on + enabling computers to understand, interpret, and generate human language in a way that is useful.")], + _name=None, + _meta={'model': 'gpt-4o-mini', 'index': 0, 'finish_reason': 'stop', + 'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})] +} +``` + + + +#### AzureOpenAIChatGenerator.\_\_init\_\_ + +```python +def __init__(azure_endpoint: Optional[str] = None, + api_version: Optional[str] = "2023-05-15", + azure_deployment: Optional[str] = "gpt-4o-mini", + api_key: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_API_KEY", strict=False), + azure_ad_token: Optional[Secret] = Secret.from_env_var( + "AZURE_OPENAI_AD_TOKEN", strict=False), + organization: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + default_headers: Optional[dict[str, str]] = None, + tools: Optional[ToolsType] = None, + tools_strict: bool = False, + *, + azure_ad_token_provider: Optional[Union[ + AzureADTokenProvider, AsyncAzureADTokenProvider]] = None, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Initialize the Azure OpenAI Chat Generator component. + +**Arguments**: + +- `azure_endpoint`: The endpoint of the deployed model, for example `"https://example-resource.azure.openai.com/"`. +- `api_version`: The version of the API to use. Defaults to 2023-05-15. +- `azure_deployment`: The deployment of the model, usually the model name. +- `api_key`: The API key to use for authentication. +- `azure_ad_token`: [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id). +- `organization`: Your organization ID, defaults to `None`. For help, see +[Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `streaming_callback`: A callback function called when a new token is received from the stream. +It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `generation_kwargs`: Other parameters to use for the model. These parameters are sent directly to +the OpenAI endpoint. For details, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). +Some of the supported parameters: +- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion, + including visible output tokens and reasoning tokens. +- `temperature`: The sampling temperature to use. Higher values mean the model takes more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: Nucleus sampling is an alternative to sampling with temperature, where the model considers + tokens with a top_p probability mass. For example, 0.1 means only the tokens comprising + the top 10% probability mass are considered. +- `n`: The number of completions to generate for each prompt. For example, with 3 prompts and n=2, + the LLM will generate two completions per prompt, resulting in 6 completions total. +- `stop`: One or more sequences after which the LLM should stop generating tokens. +- `presence_penalty`: The penalty applied if a token is already present. + Higher values make the model less likely to repeat the token. +- `frequency_penalty`: Penalty applied if a token has already been generated. + Higher values make the model less likely to repeat the token. +- `logit_bias`: Adds a logit bias to specific tokens. The keys of the dictionary are tokens, and the + values are the bias to add to that token. +- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + Notes: + - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o. + Older models only support basic version of structured outputs through `{"type": "json_object"}`. + For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode). + - For structured outputs with streaming, + the `response_format` must be a JSON schema and not a Pydantic model. +- `default_headers`: Default headers to use for the AzureOpenAI client. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +- `azure_ad_token_provider`: A function that returns an Azure Active Directory token, will be invoked on +every request. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### AzureOpenAIChatGenerator.warm\_up + +```python +def warm_up() +``` + +Warm up the Azure OpenAI chat generator. + +This will warm up the tools registered in the chat generator. +This method is idempotent and will only warm up the tools once. + + + +#### AzureOpenAIChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AzureOpenAIChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AzureOpenAIChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AzureOpenAIChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes chat completion based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### AzureOpenAIChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes chat completion based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module chat/azure\_responses + + + +### AzureOpenAIResponsesChatGenerator + +Completes chats using OpenAI's Responses API on Azure. + +It works with the gpt-5 and o-series models and supports streaming responses +from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) +format in input and output. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.Responses.create` will work here too. + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/responses). + +### Usage example + +```python +from haystack.components.generators.chat import AzureOpenAIResponsesChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = AzureOpenAIResponsesChatGenerator( + azure_endpoint="https://example-resource.azure.openai.com/", + generation_kwargs={"reasoning": {"effort": "low", "summary": "auto"}} +) +response = client.run(messages) +print(response) +``` + + + +#### AzureOpenAIResponsesChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Union[Secret, Callable[[], str], + Callable[[], + Awaitable[str]]] = Secret.from_env_var( + "AZURE_OPENAI_API_KEY", strict=False), + azure_endpoint: Optional[str] = None, + azure_deployment: str = "gpt-5-mini", + streaming_callback: Optional[StreamingCallbackT] = None, + organization: Optional[str] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + tools: Optional[ToolsType] = None, + tools_strict: bool = False, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Initialize the AzureOpenAIResponsesChatGenerator component. + +**Arguments**: + +- `api_key`: The API key to use for authentication. Can be: +- A `Secret` object containing the API key. +- A `Secret` object containing the [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id). +- A function that returns an Azure Active Directory token. +- `azure_endpoint`: The endpoint of the deployed model, for example `"https://example-resource.azure.openai.com/"`. +- `azure_deployment`: The deployment of the model, usually the model name. +- `organization`: Your organization ID, defaults to `None`. For help, see +[Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `streaming_callback`: A callback function called when a new token is received from the stream. +It accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `generation_kwargs`: Other parameters to use for the model. These parameters are sent +directly to the OpenAI endpoint. +See OpenAI [documentation](https://platform.openai.com/docs/api-reference/responses) for + more details. + Some of the supported parameters: + - `temperature`: What sampling temperature to use. Higher values like 0.8 will make the output more random, + while lower values like 0.2 will make it more focused and deterministic. + - `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens + comprising the top 10% probability mass are considered. + - `previous_response_id`: The ID of the previous response. + Use this to create multi-turn conversations. + - `text_format`: A Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + - `text`: A JSON schema that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + Notes: + - Both JSON Schema and Pydantic models are supported for latest models starting from GPT-4o. + - If both are provided, `text_format` takes precedence and json schema passed to `text` is ignored. + - Currently, this component doesn't support streaming for structured outputs. + - Older models only support basic version of structured outputs through `{"type": "json_object"}`. + For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode). + - `reasoning`: A dictionary of parameters for reasoning. For example: + - `summary`: The summary of the reasoning. + - `effort`: The level of effort to put into the reasoning. Can be `low`, `medium` or `high`. + - `generate_summary`: Whether to generate a summary of the reasoning. + Note: OpenAI does not return the reasoning tokens, but we can view summary if its enabled. + For details, see the [OpenAI Reasoning documentation](https://platform.openai.com/docs/guides/reasoning). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### AzureOpenAIResponsesChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AzureOpenAIResponsesChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, + Any]) -> "AzureOpenAIResponsesChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AzureOpenAIResponsesChatGenerator.warm\_up + +```python +def warm_up() +``` + +Warm up the OpenAI responses chat generator. + +This will warm up the tools registered in the chat generator. +This method is idempotent and will only warm up the tools once. + + + +#### AzureOpenAIResponsesChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + *, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[Union[ToolsType, list[dict]]] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes response generation based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create). +- `tools`: The tools that the model can use to prepare calls. If set, it will override the +`tools` parameter set during component initialization. This parameter can accept either a +mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of +OpenAI/MCP tool definitions. +Note: You cannot pass OpenAI/MCP tools and Haystack tools together. +For details on tool support, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools). +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `False`, the model may not exactly +follow the schema provided in the `parameters` field of the tool definition. In Response API, tool calls +are strict by default. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### AzureOpenAIResponsesChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + *, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[Union[ToolsType, list[dict]]] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes response generation based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create). +- `tools`: A list of tools or a Toolset for which the model can prepare calls. If set, it will override the +`tools` parameter set during component initialization. This parameter can accept either a list of +mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of +OpenAI/MCP tool definitions. +Note: You cannot pass OpenAI/MCP tools and Haystack tools together. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module chat/hugging\_face\_local + + + +#### default\_tool\_parser + +```python +def default_tool_parser(text: str) -> Optional[list[ToolCall]] +``` + +Default implementation for parsing tool calls from model output text. + +Uses DEFAULT_TOOL_PATTERN to extract tool calls. + +**Arguments**: + +- `text`: The text to parse for tool calls. + +**Returns**: + +A list containing a single ToolCall if a valid tool call is found, None otherwise. + + + +### HuggingFaceLocalChatGenerator + +Generates chat responses using models from Hugging Face that run locally. + +Use this component with chat-based models, +such as `HuggingFaceH4/zephyr-7b-beta` or `meta-llama/Llama-2-7b-chat-hf`. +LLMs running locally may need powerful hardware. + +### Usage example + +```python +from haystack.components.generators.chat import HuggingFaceLocalChatGenerator +from haystack.dataclasses import ChatMessage + +generator = HuggingFaceLocalChatGenerator(model="HuggingFaceH4/zephyr-7b-beta") +generator.warm_up() +messages = [ChatMessage.from_user("What's Natural Language Processing? Be brief.")] +print(generator.run(messages)) +``` + +``` +{'replies': + [ChatMessage(_role=, _content=[TextContent(text= + "Natural Language Processing (NLP) is a subfield of artificial intelligence that deals + with the interaction between computers and human language. It enables computers to understand, interpret, and + generate human language in a valuable way. NLP involves various techniques such as speech recognition, text + analysis, sentiment analysis, and machine translation. The ultimate goal is to make it easier for computers to + process and derive meaning from human language, improving communication between humans and machines.")], + _name=None, + _meta={'finish_reason': 'stop', 'index': 0, 'model': + 'mistralai/Mistral-7B-Instruct-v0.2', + 'usage': {'completion_tokens': 90, 'prompt_tokens': 19, 'total_tokens': 109}}) + ] +} +``` + + + +#### HuggingFaceLocalChatGenerator.\_\_init\_\_ + +```python +def __init__(model: str = "HuggingFaceH4/zephyr-7b-beta", + task: Optional[Literal["text-generation", + "text2text-generation"]] = None, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + chat_template: Optional[str] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None, + stop_words: Optional[list[str]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None, + tool_parsing_function: Optional[Callable[ + [str], Optional[list[ToolCall]]]] = None, + async_executor: Optional[ThreadPoolExecutor] = None) -> None +``` + +Initializes the HuggingFaceLocalChatGenerator component. + +**Arguments**: + +- `model`: The Hugging Face text generation model name or path, +for example, `mistralai/Mistral-7B-Instruct-v0.2` or `TheBloke/OpenHermes-2.5-Mistral-7B-16k-AWQ`. +The model must be a chat model supporting the ChatML messaging +format. +If the model is specified in `huggingface_pipeline_kwargs`, this parameter is ignored. +- `task`: The task for the Hugging Face pipeline. Possible options: +- `text-generation`: Supported by decoder models, like GPT. +- `text2text-generation`: Supported by encoder-decoder models, like T5. +If the task is specified in `huggingface_pipeline_kwargs`, this parameter is ignored. +If not specified, the component calls the Hugging Face API to infer the task from the model name. +- `device`: The device for loading the model. If `None`, automatically selects the default device. +If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter. +- `token`: The token to use as HTTP bearer authorization for remote files. +If the token is specified in `huggingface_pipeline_kwargs`, this parameter is ignored. +- `chat_template`: Specifies an optional Jinja template for formatting chat +messages. Most high-quality chat models have their own templates, but for models without this +feature or if you prefer a custom template, use this parameter. +- `generation_kwargs`: A dictionary with keyword arguments to customize text generation. +Some examples: `max_length`, `max_new_tokens`, `temperature`, `top_k`, `top_p`. +See Hugging Face's documentation for more information: +- - [customize-text-generation](https://huggingface.co/docs/transformers/main/en/generation_strategies#customize-text-generation) +- - [GenerationConfig](https://huggingface.co/docs/transformers/main/en/main_classes/text_generation#transformers.GenerationConfig) +The only `generation_kwargs` set by default is `max_new_tokens`, which is set to 512 tokens. +- `huggingface_pipeline_kwargs`: Dictionary with keyword arguments to initialize the +Hugging Face pipeline for text generation. +These keyword arguments provide fine-grained control over the Hugging Face pipeline. +In case of duplication, these kwargs override `model`, `task`, `device`, and `token` init parameters. +For kwargs, see [Hugging Face documentation](https://huggingface.co/docs/transformers/en/main_classes/pipelines#transformers.pipeline.task). +In this dictionary, you can also include `model_kwargs` to specify the kwargs for [model initialization](https://huggingface.co/docs/transformers/en/main_classes/model#transformers.PreTrainedModel.from_pretrained) +- `stop_words`: A list of stop words. If the model generates a stop word, the generation stops. +If you provide this parameter, don't specify the `stopping_criteria` in `generation_kwargs`. +For some chat models, the output includes both the new text and the original prompt. +In these cases, make sure your prompt has no stop words. +- `streaming_callback`: An optional callable for handling streaming responses. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +- `tool_parsing_function`: A callable that takes a string and returns a list of ToolCall objects or None. +If None, the default_tool_parser will be used which extracts tool calls using a predefined pattern. +- `async_executor`: Optional ThreadPoolExecutor to use for async calls. If not provided, a single-threaded executor will be +initialized and used + + + +#### HuggingFaceLocalChatGenerator.\_\_del\_\_ + +```python +def __del__() -> None +``` + +Cleanup when the instance is being destroyed. + + + +#### HuggingFaceLocalChatGenerator.shutdown + +```python +def shutdown() -> None +``` + +Explicitly shutdown the executor if we own it. + + + +#### HuggingFaceLocalChatGenerator.warm\_up + +```python +def warm_up() -> None +``` + +Initializes the component and warms up tools if provided. + + + +#### HuggingFaceLocalChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HuggingFaceLocalChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceLocalChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### HuggingFaceLocalChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + generation_kwargs: Optional[dict[str, Any]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) -> dict[str, list[ChatMessage]] +``` + +Invoke text generation inference based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage objects representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. +- `streaming_callback`: An optional callable for handling streaming responses. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### HuggingFaceLocalChatGenerator.create\_message + +```python +def create_message(text: str, + index: int, + tokenizer: Union["PreTrainedTokenizer", + "PreTrainedTokenizerFast"], + prompt: str, + generation_kwargs: dict[str, Any], + parse_tool_calls: bool = False) -> ChatMessage +``` + +Create a ChatMessage instance from the provided text, populated with metadata. + +**Arguments**: + +- `text`: The generated text. +- `index`: The index of the generated text. +- `tokenizer`: The tokenizer used for generation. +- `prompt`: The prompt used for generation. +- `generation_kwargs`: The generation parameters. +- `parse_tool_calls`: Whether to attempt parsing tool calls from the text. + +**Returns**: + +A ChatMessage instance. + + + +#### HuggingFaceLocalChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async( + messages: list[ChatMessage], + generation_kwargs: Optional[dict[str, Any]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) -> dict[str, list[ChatMessage]] +``` + +Asynchronously invokes text generation inference based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters +and return values but can be used with `await` in an async code. + +**Arguments**: + +- `messages`: A list of ChatMessage objects representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. +- `streaming_callback`: An optional callable for handling streaming responses. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module chat/hugging\_face\_api + + + +### HuggingFaceAPIChatGenerator + +Completes chats using Hugging Face APIs. + +HuggingFaceAPIChatGenerator uses the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) +format for input and output. Use it to generate text with Hugging Face APIs: +- [Serverless Inference API (Inference Providers)](https://huggingface.co/docs/inference-providers) +- [Paid Inference Endpoints](https://huggingface.co/inference-endpoints) +- [Self-hosted Text Generation Inference](https://github.com/huggingface/text-generation-inference) + +### Usage examples + +#### With the serverless inference API (Inference Providers) - free tier available + +```python +from haystack.components.generators.chat import HuggingFaceAPIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret +from haystack.utils.hf import HFGenerationAPIType + +messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"), + ChatMessage.from_user("What's Natural Language Processing?")] + +# the api_type can be expressed using the HFGenerationAPIType enum or as a string +api_type = HFGenerationAPIType.SERVERLESS_INFERENCE_API +api_type = "serverless_inference_api" # this is equivalent to the above + +generator = HuggingFaceAPIChatGenerator(api_type=api_type, + api_params={"model": "Qwen/Qwen2.5-7B-Instruct", + "provider": "together"}, + token=Secret.from_token("")) + +result = generator.run(messages) +print(result) +``` + +#### With the serverless inference API (Inference Providers) and text+image input + +```python +from haystack.components.generators.chat import HuggingFaceAPIChatGenerator +from haystack.dataclasses import ChatMessage, ImageContent +from haystack.utils import Secret +from haystack.utils.hf import HFGenerationAPIType + +# Create an image from file path, URL, or base64 +image = ImageContent.from_file_path("path/to/your/image.jpg") + +# Create a multimodal message with both text and image +messages = [ChatMessage.from_user(content_parts=["Describe this image in detail", image])] + +generator = HuggingFaceAPIChatGenerator( + api_type=HFGenerationAPIType.SERVERLESS_INFERENCE_API, + api_params={ + "model": "Qwen/Qwen2.5-VL-7B-Instruct", # Vision Language Model + "provider": "hyperbolic" + }, + token=Secret.from_token("") +) + +result = generator.run(messages) +print(result) +``` + +#### With paid inference endpoints + +```python +from haystack.components.generators.chat import HuggingFaceAPIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret + +messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"), + ChatMessage.from_user("What's Natural Language Processing?")] + +generator = HuggingFaceAPIChatGenerator(api_type="inference_endpoints", + api_params={"url": ""}, + token=Secret.from_token("")) + +result = generator.run(messages) +print(result) + +#### With self-hosted text generation inference + +```python +from haystack.components.generators.chat import HuggingFaceAPIChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant"), + ChatMessage.from_user("What's Natural Language Processing?")] + +generator = HuggingFaceAPIChatGenerator(api_type="text_generation_inference", + api_params={"url": "http://localhost:8080"}) + +result = generator.run(messages) +print(result) +``` + + + +#### HuggingFaceAPIChatGenerator.\_\_init\_\_ + +```python +def __init__(api_type: Union[HFGenerationAPIType, str], + api_params: dict[str, str], + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + generation_kwargs: Optional[dict[str, Any]] = None, + stop_words: Optional[list[str]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) +``` + +Initialize the HuggingFaceAPIChatGenerator instance. + +**Arguments**: + +- `api_type`: The type of Hugging Face API to use. Available types: +- `text_generation_inference`: See [TGI](https://github.com/huggingface/text-generation-inference). +- `inference_endpoints`: See [Inference Endpoints](https://huggingface.co/inference-endpoints). +- `serverless_inference_api`: See +[Serverless Inference API - Inference Providers](https://huggingface.co/docs/inference-providers). +- `api_params`: A dictionary with the following keys: +- `model`: Hugging Face model ID. Required when `api_type` is `SERVERLESS_INFERENCE_API`. +- `provider`: Provider name. Recommended when `api_type` is `SERVERLESS_INFERENCE_API`. +- `url`: URL of the inference endpoint. Required when `api_type` is `INFERENCE_ENDPOINTS` or +`TEXT_GENERATION_INFERENCE`. +- Other parameters specific to the chosen API type, such as `timeout`, `headers`, etc. +- `token`: The Hugging Face token to use as HTTP bearer authorization. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). +- `generation_kwargs`: A dictionary with keyword arguments to customize text generation. +Some examples: `max_tokens`, `temperature`, `top_p`. +For details, see [Hugging Face chat_completion documentation](https://huggingface.co/docs/huggingface_hub/package_reference/inference_client#huggingface_hub.InferenceClient.chat_completion). +- `stop_words`: An optional list of strings representing the stop words. +- `streaming_callback`: An optional callable for handling streaming responses. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +The chosen model should support tool/function calling, according to the model card. +Support for tools in the Hugging Face API and TGI is not yet fully refined and you may experience +unexpected behavior. + + + +#### HuggingFaceAPIChatGenerator.warm\_up + +```python +def warm_up() +``` + +Warm up the Hugging Face API chat generator. + +This will warm up the tools registered in the chat generator. +This method is idempotent and will only warm up the tools once. + + + +#### HuggingFaceAPIChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +A dictionary containing the serialized component. + + + +#### HuggingFaceAPIChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceAPIChatGenerator" +``` + +Deserialize this component from a dictionary. + + + +#### HuggingFaceAPIChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +Invoke the text generation inference based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage objects representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. +- `tools`: A list of tools or a Toolset for which the model can prepare calls. If set, it will override +the `tools` parameter set during component initialization. This parameter can accept either a +list of `Tool` objects or a `Toolset` instance. +- `streaming_callback`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback` +parameter set during component initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated responses as ChatMessage objects. + + + +#### HuggingFaceAPIChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +Asynchronously invokes the text generation inference based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters +and return values but can be used with `await` in an async code. + +**Arguments**: + +- `messages`: A list of ChatMessage objects representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. +- `tools`: A list of tools or a Toolset for which the model can prepare calls. If set, it will override the `tools` +parameter set during component initialization. This parameter can accept either a list of `Tool` objects +or a `Toolset` instance. +- `streaming_callback`: An optional callable for handling streaming responses. If set, it will override the `streaming_callback` +parameter set during component initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated responses as ChatMessage objects. + + + +## Module chat/openai + + + +### OpenAIChatGenerator + +Completes chats using OpenAI's large language models (LLMs). + +It works with the gpt-4 and o-series models and supports streaming responses +from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) +format in input and output. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.ChatCompletion.create` will work here too. + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). + +### Usage example + +```python +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = OpenAIChatGenerator() +response = client.run(messages) +print(response) +``` +Output: +``` +{'replies': + [ChatMessage(_role=, _content= + [TextContent(text="Natural Language Processing (NLP) is a branch of artificial intelligence + that focuses on enabling computers to understand, interpret, and generate human language in + a way that is meaningful and useful.")], + _name=None, + _meta={'model': 'gpt-4o-mini', 'index': 0, 'finish_reason': 'stop', + 'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}}) + ] +} +``` + + + +#### OpenAIChatGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "gpt-4o-mini", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + tools: Optional[ToolsType] = None, + tools_strict: bool = False, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an instance of OpenAIChatGenerator. Unless specified otherwise in `model`, uses OpenAI's gpt-4o-mini + +Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' +environment variables to override the `timeout` and `max_retries` parameters respectively +in the OpenAI client. + +**Arguments**: + +- `api_key`: The OpenAI API key. +You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter +during initialization. +- `model`: The name of the model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `api_base_url`: An optional base URL. +- `organization`: Your organization ID, defaults to `None`. See +[production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `generation_kwargs`: Other parameters to use for the model. These parameters are sent directly to +the OpenAI endpoint. See OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat) for +more details. +Some of the supported parameters: +- `max_completion_tokens`: An upper bound for the number of tokens that can be generated for a completion, + including visible output tokens and reasoning tokens. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2, + it will generate two completions for each of the three prompts, ending up with 6 completions in total. +- `stop`: One or more sequences after which the LLM should stop generating tokens. +- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean + the model will be less likely to repeat the same token in the text. +- `frequency_penalty`: What penalty to apply if a token has already been generated in the text. + Bigger values mean the model will be less likely to repeat the same token in the text. +- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the + values are the bias to add to that token. +- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + Notes: + - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o. + Older models only support basic version of structured outputs through `{"type": "json_object"}`. + For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode). + - For structured outputs with streaming, + the `response_format` must be a JSON schema and not a Pydantic model. +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### OpenAIChatGenerator.warm\_up + +```python +def warm_up() +``` + +Warm up the OpenAI chat generator. + +This will warm up the tools registered in the chat generator. +This method is idempotent and will only warm up the tools once. + + + +#### OpenAIChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### OpenAIChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### OpenAIChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes chat completion based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### OpenAIChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes chat completion based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module chat/openai\_responses + + + +### OpenAIResponsesChatGenerator + +Completes chats using OpenAI's Responses API. + +It works with the gpt-4 and o-series models and supports streaming responses +from OpenAI API. It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) +format in input and output. + +You can customize how the text is generated by passing parameters to the +OpenAI API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`openai.Responses.create` will work here too. + +For details on OpenAI API parameters, see +[OpenAI documentation](https://platform.openai.com/docs/api-reference/responses). + +### Usage example + +```python +from haystack.components.generators.chat import OpenAIResponsesChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = OpenAIResponsesChatGenerator(generation_kwargs={"reasoning": {"effort": "low", "summary": "auto"}}) +response = client.run(messages) +print(response) +``` + + + +#### OpenAIResponsesChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("OPENAI_API_KEY"), + model: str = "gpt-5-mini", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = None, + organization: Optional[str] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + tools: Optional[Union[ToolsType, list[dict]]] = None, + tools_strict: bool = False, + http_client_kwargs: Optional[dict[str, Any]] = None) +``` + +Creates an instance of OpenAIResponsesChatGenerator. Uses OpenAI's gpt-5-mini by default. + +Before initializing the component, you can set the 'OPENAI_TIMEOUT' and 'OPENAI_MAX_RETRIES' +environment variables to override the `timeout` and `max_retries` parameters respectively +in the OpenAI client. + +**Arguments**: + +- `api_key`: The OpenAI API key. +You can set it with an environment variable `OPENAI_API_KEY`, or pass with this parameter +during initialization. +- `model`: The name of the model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `api_base_url`: An optional base URL. +- `organization`: Your organization ID, defaults to `None`. See +[production best practices](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). +- `generation_kwargs`: Other parameters to use for the model. These parameters are sent +directly to the OpenAI endpoint. +See OpenAI [documentation](https://platform.openai.com/docs/api-reference/responses) for + more details. + Some of the supported parameters: + - `temperature`: What sampling temperature to use. Higher values like 0.8 will make the output more random, + while lower values like 0.2 will make it more focused and deterministic. + - `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. For example, 0.1 means only the tokens + comprising the top 10% probability mass are considered. + - `previous_response_id`: The ID of the previous response. + Use this to create multi-turn conversations. + - `text_format`: A Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + - `text`: A JSON schema that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + Notes: + - Both JSON Schema and Pydantic models are supported for latest models starting from GPT-4o. + - If both are provided, `text_format` takes precedence and json schema passed to `text` is ignored. + - Currently, this component doesn't support streaming for structured outputs. + - Older models only support basic version of structured outputs through `{"type": "json_object"}`. + For detailed information on JSON mode, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs#json-mode). + - `reasoning`: A dictionary of parameters for reasoning. For example: + - `summary`: The summary of the reasoning. + - `effort`: The level of effort to put into the reasoning. Can be `low`, `medium` or `high`. + - `generate_summary`: Whether to generate a summary of the reasoning. + Note: OpenAI does not return the reasoning tokens, but we can view summary if its enabled. + For details, see the [OpenAI Reasoning documentation](https://platform.openai.com/docs/guides/reasoning). +- `timeout`: Timeout for OpenAI client calls. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `tools`: The tools that the model can use to prepare calls. This parameter can accept either a +mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of +OpenAI/MCP tool definitions. +Note: You cannot pass OpenAI/MCP tools and Haystack tools together. +For details on tool support, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools). +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `False`, the model may not exactly +follow the schema provided in the `parameters` field of the tool definition. In Response API, tool calls +are strict by default. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### OpenAIResponsesChatGenerator.warm\_up + +```python +def warm_up() +``` + +Warm up the OpenAI responses chat generator. + +This will warm up the tools registered in the chat generator. +This method is idempotent and will only warm up the tools once. + + + +#### OpenAIResponsesChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### OpenAIResponsesChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIResponsesChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### OpenAIResponsesChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + *, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[Union[ToolsType, list[dict]]] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes response generation based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create). +- `tools`: The tools that the model can use to prepare calls. If set, it will override the +`tools` parameter set during component initialization. This parameter can accept either a +mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of +OpenAI/MCP tool definitions. +Note: You cannot pass OpenAI/MCP tools and Haystack tools together. +For details on tool support, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create#responses-create-tools). +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `False`, the model may not exactly +follow the schema provided in the `parameters` field of the tool definition. In Response API, tool calls +are strict by default. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### OpenAIResponsesChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + *, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + tools: Optional[Union[ToolsType, list[dict]]] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes response generation based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/responses/create). +- `tools`: A list of tools or a Toolset for which the model can prepare calls. If set, it will override the +`tools` parameter set during component initialization. This parameter can accept either a list of +mixed list of Haystack `Tool` objects and Haystack `Toolset`. Or you can pass a dictionary of +OpenAI/MCP tool definitions. +Note: You cannot pass OpenAI/MCP tools and Haystack tools together. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module chat/fallback + + + +### FallbackChatGenerator + +A chat generator wrapper that tries multiple chat generators sequentially. + +It forwards all parameters transparently to the underlying chat generators and returns the first successful result. +Calls chat generators sequentially until one succeeds. Falls back on any exception raised by a generator. +If all chat generators fail, it raises a RuntimeError with details. + +Timeout enforcement is fully delegated to the underlying chat generators. The fallback mechanism will only +work correctly if the underlying chat generators implement proper timeout handling and raise exceptions +when timeouts occur. For predictable latency guarantees, ensure your chat generators: +- Support a `timeout` parameter in their initialization +- Implement timeout as total wall-clock time (shared deadline for both streaming and non-streaming) +- Raise timeout exceptions (e.g., TimeoutError, asyncio.TimeoutError, httpx.TimeoutException) when exceeded + +Note: Most well-implemented chat generators (OpenAI, Anthropic, Cohere, etc.) support timeout parameters +with consistent semantics. For HTTP-based LLM providers, a single timeout value (e.g., `timeout=30`) +typically applies to all connection phases: connection setup, read, write, and pool. For streaming +responses, read timeout is the maximum gap between chunks. For non-streaming, it's the time limit for +receiving the complete response. + +Failover is automatically triggered when a generator raises any exception, including: +- Timeout errors (if the generator implements and raises them) +- Rate limit errors (429) +- Authentication errors (401) +- Context length errors (400) +- Server errors (500+) +- Any other exception + + + +#### FallbackChatGenerator.\_\_init\_\_ + +```python +def __init__(chat_generators: list[ChatGenerator]) +``` + +Creates an instance of FallbackChatGenerator. + +**Arguments**: + +- `chat_generators`: A non-empty list of chat generator components to try in order. + + + +#### FallbackChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component, including nested chat generators when they support serialization. + + + +#### FallbackChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> FallbackChatGenerator +``` + +Rebuild the component from a serialized representation, restoring nested chat generators. + + + +#### FallbackChatGenerator.warm\_up + +```python +def warm_up() -> None +``` + +Warm up all underlying chat generators. + +This method calls warm_up() on each underlying generator that supports it. + + + +#### FallbackChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage], meta=dict[str, Any]) +def run( + messages: list[ChatMessage], + generation_kwargs: Union[dict[str, Any], None] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Union[StreamingCallbackT, + None] = None) -> dict[str, Any] +``` + +Execute chat generators sequentially until one succeeds. + +**Arguments**: + +- `messages`: The conversation history as a list of ChatMessage instances. +- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities. +- `streaming_callback`: Optional callable for handling streaming responses. + +**Raises**: + +- `RuntimeError`: If all chat generators fail. + +**Returns**: + +A dictionary with: +- "replies": Generated ChatMessage instances from the first successful generator. +- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class, + total_attempts, failed_chat_generators, plus any metadata from the successful generator. + + + +#### FallbackChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage], meta=dict[str, Any]) +async def run_async( + messages: list[ChatMessage], + generation_kwargs: Union[dict[str, Any], None] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Union[StreamingCallbackT, + None] = None) -> dict[str, Any] +``` + +Asynchronously execute chat generators sequentially until one succeeds. + +**Arguments**: + +- `messages`: The conversation history as a list of ChatMessage instances. +- `generation_kwargs`: Optional parameters for the chat generator (e.g., temperature, max_tokens). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for function calling capabilities. +- `streaming_callback`: Optional callable for handling streaming responses. + +**Raises**: + +- `RuntimeError`: If all chat generators fail. + +**Returns**: + +A dictionary with: +- "replies": Generated ChatMessage instances from the first successful generator. +- "meta": Execution metadata including successful_chat_generator_index, successful_chat_generator_class, + total_attempts, failed_chat_generators, plus any metadata from the successful generator. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/image_converters_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/image_converters_api.md new file mode 100644 index 0000000000..639d94e9d1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/image_converters_api.md @@ -0,0 +1,375 @@ +--- +title: "Image Converters" +id: image-converters-api +description: "Various converters to transform image data from one format to another." +slug: "/image-converters-api" +--- + + + +## Module document\_to\_image + + + +### DocumentToImageContent + +Converts documents sourced from PDF and image files into ImageContents. + +This component processes a list of documents and extracts visual content from supported file formats, converting +them into ImageContents that can be used for multimodal AI tasks. It handles both direct image files and PDF +documents by extracting specific pages as images. + +Documents are expected to have metadata containing: +- The `file_path_meta_field` key with a valid file path that exists when combined with `root_path` +- A supported image format (MIME type must be one of the supported image types) +- For PDF files, a `page_number` key specifying which page to extract + +### Usage example + ```python + from haystack import Document + from haystack.components.converters.image.document_to_image import DocumentToImageContent + + converter = DocumentToImageContent( + file_path_meta_field="file_path", + root_path="/data/files", + detail="high", + size=(800, 600) + ) + + documents = [ + Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}), + Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1}) + ] + + result = converter.run(documents) + image_contents = result["image_contents"] + # [ImageContent( + # base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'} + # ), + # ImageContent( + # base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', + # meta={'page_number': 1, 'file_path': 'doc.pdf'} + # )] + ``` + + + +#### DocumentToImageContent.\_\_init\_\_ + +```python +def __init__(*, + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, int]] = None) +``` + +Initialize the DocumentToImageContent component. + +**Arguments**: + +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `detail`: Optional detail level of the image (only supported by OpenAI). Can be "auto", "high", or "low". +This will be passed to the created ImageContent objects. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. + + + +#### DocumentToImageContent.run + +```python +@component.output_types(image_contents=list[Optional[ImageContent]]) +def run(documents: list[Document]) -> dict[str, list[Optional[ImageContent]]] +``` + +Convert documents with image or PDF sources into ImageContent objects. + +This method processes the input documents, extracting images from supported file formats and converting them +into ImageContent objects. + +**Arguments**: + +- `documents`: A list of documents to process. Each document should have metadata containing at minimum +a 'file_path_meta_field' key. PDF documents additionally require a 'page_number' key to specify which +page to convert. + +**Raises**: + +- `ValueError`: If any document is missing the required metadata keys, has an invalid file path, or has an unsupported +MIME type. The error message will specify which document and what information is missing or incorrect. + +**Returns**: + +Dictionary containing one key: +- "image_contents": ImageContents created from the processed documents. These contain base64-encoded image +data and metadata. The order corresponds to order of input documents. + + + +## Module file\_to\_document + + + +### ImageFileToDocument + +Converts image file references into empty Document objects with associated metadata. + +This component is useful in pipelines where image file paths need to be wrapped in `Document` objects to be +processed by downstream components such as the `SentenceTransformersImageDocumentEmbedder`. + +It does **not** extract any content from the image files, instead it creates `Document` objects with `None` as +their content and attaches metadata such as file path and any user-provided values. + +### Usage example +```python +from haystack.components.converters.image import ImageFileToDocument + +converter = ImageFileToDocument() + +sources = ["image.jpg", "another_image.png"] + +result = converter.run(sources=sources) +documents = result["documents"] + +print(documents) + +# [Document(id=..., meta: {'file_path': 'image.jpg'}), +# Document(id=..., meta: {'file_path': 'another_image.png'})] +``` + + + +#### ImageFileToDocument.\_\_init\_\_ + +```python +def __init__(*, store_full_path: bool = False) +``` + +Initialize the ImageFileToDocument component. + +**Arguments**: + +- `store_full_path`: If True, the full path of the file is stored in the metadata of the document. +If False, only the file name is stored. + + + +#### ImageFileToDocument.run + +```python +@component.output_types(documents=list[Document]) +def run( + *, + sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None +) -> dict[str, list[Document]] +``` + +Convert image files into empty Document objects with metadata. + +This method accepts image file references (as file paths or ByteStreams) and creates `Document` objects +without content. These documents are enriched with metadata derived from the input source and optional +user-provided metadata. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects to convert. +- `meta`: Optional metadata to attach to the documents. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced documents. +If it's a list, its length must match the number of sources, as they are zipped together. +For ByteStream objects, their `meta` is added to the output documents. + +**Returns**: + +A dictionary containing: +- `documents`: A list of `Document` objects with empty content and associated metadata. + + + +## Module file\_to\_image + + + +### ImageFileToImageContent + +Converts image files to ImageContent objects. + +### Usage example +```python +from haystack.components.converters.image import ImageFileToImageContent + +converter = ImageFileToImageContent() + +sources = ["image.jpg", "another_image.png"] + +image_contents = converter.run(sources=sources)["image_contents"] +print(image_contents) + +# [ImageContent(base64_image='...', +# mime_type='image/jpeg', +# detail=None, +# meta={'file_path': 'image.jpg'}), +# ...] +``` + + + +#### ImageFileToImageContent.\_\_init\_\_ + +```python +def __init__(*, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, int]] = None) +``` + +Create the ImageFileToImageContent component. + +**Arguments**: + +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +This will be passed to the created ImageContent objects. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. + + + +#### ImageFileToImageContent.run + +```python +@component.output_types(image_contents=list[ImageContent]) +def run(sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None, + *, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, + int]] = None) -> dict[str, list[ImageContent]] +``` + +Converts files to ImageContent objects. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects to convert. +- `meta`: Optional metadata to attach to the ImageContent objects. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects. +If it's a list, its length must match the number of sources as they're zipped together. +For ByteStream objects, their `meta` is added to the output ImageContent objects. +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +This will be passed to the created ImageContent objects. +If not provided, the detail level will be the one set in the constructor. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +If not provided, the size value will be the one set in the constructor. + +**Returns**: + +A dictionary with the following keys: +- `image_contents`: A list of ImageContent objects. + + + +## Module pdf\_to\_image + + + +### PDFToImageContent + +Converts PDF files to ImageContent objects. + +### Usage example +```python +from haystack.components.converters.image import PDFToImageContent + +converter = PDFToImageContent() + +sources = ["file.pdf", "another_file.pdf"] + +image_contents = converter.run(sources=sources)["image_contents"] +print(image_contents) + +# [ImageContent(base64_image='...', +# mime_type='application/pdf', +# detail=None, +# meta={'file_path': 'file.pdf', 'page_number': 1}), +# ...] +``` + + + +#### PDFToImageContent.\_\_init\_\_ + +```python +def __init__(*, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, int]] = None, + page_range: Optional[list[Union[str, int]]] = None) +``` + +Create the PDFToImageContent component. + +**Arguments**: + +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +This will be passed to the created ImageContent objects. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `page_range`: List of page numbers and/or page ranges to convert to images. Page numbers start at 1. +If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages) +will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third +pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12'] +will convert pages 1, 2, 3, 5, 8, 10, 11, 12. + + + +#### PDFToImageContent.run + +```python +@component.output_types(image_contents=list[ImageContent]) +def run( + sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None, + *, + detail: Optional[Literal["auto", "high", "low"]] = None, + size: Optional[tuple[int, int]] = None, + page_range: Optional[list[Union[str, int]]] = None +) -> dict[str, list[ImageContent]] +``` + +Converts files to ImageContent objects. + +**Arguments**: + +- `sources`: List of file paths or ByteStream objects to convert. +- `meta`: Optional metadata to attach to the ImageContent objects. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced ImageContent objects. +If it's a list, its length must match the number of sources as they're zipped together. +For ByteStream objects, their `meta` is added to the output ImageContent objects. +- `detail`: Optional detail level of the image (only supported by OpenAI). One of "auto", "high", or "low". +This will be passed to the created ImageContent objects. +If not provided, the detail level will be the one set in the constructor. +- `size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +If not provided, the size value will be the one set in the constructor. +- `page_range`: List of page numbers and/or page ranges to convert to images. Page numbers start at 1. +If None, all pages in the PDF will be converted. Pages outside the valid range (1 to number of pages) +will be skipped with a warning. For example, page_range=[1, 3] will convert only the first and third +pages of the document. It also accepts printable range strings, e.g.: ['1-3', '5', '8', '10-12'] +will convert pages 1, 2, 3, 5, 8, 10, 11, 12. +If not provided, the page_range value will be the one set in the constructor. + +**Returns**: + +A dictionary with the following keys: +- `image_contents`: A list of ImageContent objects. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/joiners_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/joiners_api.md new file mode 100644 index 0000000000..f34b8b12f4 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/joiners_api.md @@ -0,0 +1,625 @@ +--- +title: "Joiners" +id: joiners-api +description: "Components that join list of different objects" +slug: "/joiners-api" +--- + + + +## Module answer\_joiner + + + +### JoinMode + +Enum for AnswerJoiner join modes. + + + +#### JoinMode.from\_str + +```python +@staticmethod +def from_str(string: str) -> "JoinMode" +``` + +Convert a string to a JoinMode enum. + + + +### AnswerJoiner + +Merges multiple lists of `Answer` objects into a single list. + +Use this component to combine answers from different Generators into a single list. +Currently, the component supports only one join mode: `CONCATENATE`. +This mode concatenates multiple lists of answers into a single list. + +### Usage example + +In this example, AnswerJoiner merges answers from two different Generators: + +```python +from haystack.components.builders import AnswerBuilder +from haystack.components.joiners import AnswerJoiner + +from haystack.core.pipeline import Pipeline + +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + + +query = "What's Natural Language Processing?" +messages = [ChatMessage.from_system("You are a helpful, respectful and honest assistant. Be super concise."), + ChatMessage.from_user(query)] + +pipe = Pipeline() +pipe.add_component("gpt-4o", OpenAIChatGenerator(model="gpt-4o")) +pipe.add_component("gpt-4o-mini", OpenAIChatGenerator(model="gpt-4o-mini")) +pipe.add_component("aba", AnswerBuilder()) +pipe.add_component("abb", AnswerBuilder()) +pipe.add_component("joiner", AnswerJoiner()) + +pipe.connect("gpt-4o.replies", "aba") +pipe.connect("gpt-4o-mini.replies", "abb") +pipe.connect("aba.answers", "joiner") +pipe.connect("abb.answers", "joiner") + +results = pipe.run(data={"gpt-4o": {"messages": messages}, + "gpt-4o-mini": {"messages": messages}, + "aba": {"query": query}, + "abb": {"query": query}}) +``` + + + +#### AnswerJoiner.\_\_init\_\_ + +```python +def __init__(join_mode: Union[str, JoinMode] = JoinMode.CONCATENATE, + top_k: Optional[int] = None, + sort_by_score: bool = False) +``` + +Creates an AnswerJoiner component. + +**Arguments**: + +- `join_mode`: Specifies the join mode to use. Available modes: +- `concatenate`: Concatenates multiple lists of Answers into a single list. +- `top_k`: The maximum number of Answers to return. +- `sort_by_score`: If `True`, sorts the documents by score in descending order. +If a document has no score, it is handled as if its score is -infinity. + + + +#### AnswerJoiner.run + +```python +@component.output_types(answers=list[AnswerType]) +def run(answers: Variadic[list[AnswerType]], top_k: Optional[int] = None) +``` + +Joins multiple lists of Answers into a single list depending on the `join_mode` parameter. + +**Arguments**: + +- `answers`: Nested list of Answers to be merged. +- `top_k`: The maximum number of Answers to return. Overrides the instance's `top_k` if provided. + +**Returns**: + +A dictionary with the following keys: +- `answers`: Merged list of Answers + + + +#### AnswerJoiner.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AnswerJoiner.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AnswerJoiner" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module branch + + + +### BranchJoiner + +A component that merges multiple input branches of a pipeline into a single output stream. + +`BranchJoiner` receives multiple inputs of the same data type and forwards the first received value +to its output. This is useful for scenarios where multiple branches need to converge before proceeding. + +### Common Use Cases: +- **Loop Handling:** `BranchJoiner` helps close loops in pipelines. For example, if a pipeline component validates + or modifies incoming data and produces an error-handling branch, `BranchJoiner` can merge both branches and send + (or resend in the case of a loop) the data to the component that evaluates errors. See "Usage example" below. + +- **Decision-Based Merging:** `BranchJoiner` reconciles branches coming from Router components (such as + `ConditionalRouter`, `TextLanguageRouter`). Suppose a `TextLanguageRouter` directs user queries to different + Retrievers based on the detected language. Each Retriever processes its assigned query and passes the results + to `BranchJoiner`, which consolidates them into a single output before passing them to the next component, such + as a `PromptBuilder`. + +### Example Usage: +```python +import json + +from haystack import Pipeline +from haystack.components.converters import OutputAdapter +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.joiners import BranchJoiner +from haystack.components.validators import JsonSchemaValidator +from haystack.dataclasses import ChatMessage + +# Define a schema for validation +person_schema = { + "type": "object", + "properties": { + "first_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"}, + "last_name": {"type": "string", "pattern": "^[A-Z][a-z]+$"}, + "nationality": {"type": "string", "enum": ["Italian", "Portuguese", "American"]}, + }, + "required": ["first_name", "last_name", "nationality"] +} + +# Initialize a pipeline +pipe = Pipeline() + +# Add components to the pipeline +pipe.add_component('joiner', BranchJoiner(list[ChatMessage])) +pipe.add_component('generator', OpenAIChatGenerator(model="gpt-4o-mini")) +pipe.add_component('validator', JsonSchemaValidator(json_schema=person_schema)) +pipe.add_component('adapter', OutputAdapter("{{chat_message}}", list[ChatMessage], unsafe=True)) + +# And connect them +pipe.connect("adapter", "joiner") +pipe.connect("joiner", "generator") +pipe.connect("generator.replies", "validator.messages") +pipe.connect("validator.validation_error", "joiner") + +result = pipe.run( + data={ + "generator": {"generation_kwargs": {"response_format": {"type": "json_object"}}}, + "adapter": {"chat_message": [ChatMessage.from_user("Create json from Peter Parker")]}} +) + +print(json.loads(result["validator"]["validated"][0].text)) + + +>> {'first_name': 'Peter', 'last_name': 'Parker', 'nationality': 'American', 'name': 'Spider-Man', 'occupation': +>> 'Superhero', 'age': 23, 'location': 'New York City'} +``` + +Note that `BranchJoiner` can manage only one data type at a time. In this case, `BranchJoiner` is created for +passing `list[ChatMessage]`. This determines the type of data that `BranchJoiner` will receive from the upstream +connected components and also the type of data that `BranchJoiner` will send through its output. + +In the code example, `BranchJoiner` receives a looped back `list[ChatMessage]` from the `JsonSchemaValidator` and +sends it down to the `OpenAIChatGenerator` for re-generation. We can have multiple loopback connections in the +pipeline. In this instance, the downstream component is only one (the `OpenAIChatGenerator`), but the pipeline could +have more than one downstream component. + + + +#### BranchJoiner.\_\_init\_\_ + +```python +def __init__(type_: type) +``` + +Creates a `BranchJoiner` component. + +**Arguments**: + +- `type_`: The expected data type of inputs and outputs. + + + +#### BranchJoiner.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component into a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### BranchJoiner.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "BranchJoiner" +``` + +Deserializes a `BranchJoiner` instance from a dictionary. + +**Arguments**: + +- `data`: The dictionary containing serialized component data. + +**Returns**: + +A deserialized `BranchJoiner` instance. + + + +#### BranchJoiner.run + +```python +def run(**kwargs) -> dict[str, Any] +``` + +Executes the `BranchJoiner`, selecting the first available input value and passing it downstream. + +**Arguments**: + +- `**kwargs`: The input data. Must be of the type declared by `type_` during initialization. + +**Returns**: + +A dictionary with a single key `value`, containing the first input received. + + + +## Module document\_joiner + + + +### JoinMode + +Enum for join mode. + + + +#### JoinMode.from\_str + +```python +@staticmethod +def from_str(string: str) -> "JoinMode" +``` + +Convert a string to a JoinMode enum. + + + +### DocumentJoiner + +Joins multiple lists of documents into a single list. + +It supports different join modes: +- concatenate: Keeps the highest-scored document in case of duplicates. +- merge: Calculates a weighted sum of scores for duplicates and merges them. +- reciprocal_rank_fusion: Merges and assigns scores based on reciprocal rank fusion. +- distribution_based_rank_fusion: Merges and assigns scores based on scores distribution in each Retriever. + +### Usage example: + +```python +from haystack import Pipeline, Document +from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder +from haystack.components.joiners import DocumentJoiner +from haystack.components.retrievers import InMemoryBM25Retriever +from haystack.components.retrievers import InMemoryEmbeddingRetriever +from haystack.document_stores.in_memory import InMemoryDocumentStore + +document_store = InMemoryDocumentStore() +docs = [Document(content="Paris"), Document(content="Berlin"), Document(content="London")] +embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") +embedder.warm_up() +docs_embeddings = embedder.run(docs) +document_store.write_documents(docs_embeddings['documents']) + +p = Pipeline() +p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="bm25_retriever") +p.add_component( + instance=SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2"), + name="text_embedder", + ) +p.add_component(instance=InMemoryEmbeddingRetriever(document_store=document_store), name="embedding_retriever") +p.add_component(instance=DocumentJoiner(), name="joiner") +p.connect("bm25_retriever", "joiner") +p.connect("embedding_retriever", "joiner") +p.connect("text_embedder", "embedding_retriever") +query = "What is the capital of France?" +p.run(data={"query": query, "text": query, "top_k": 1}) +``` + + + +#### DocumentJoiner.\_\_init\_\_ + +```python +def __init__(join_mode: Union[str, JoinMode] = JoinMode.CONCATENATE, + weights: Optional[list[float]] = None, + top_k: Optional[int] = None, + sort_by_score: bool = True) +``` + +Creates a DocumentJoiner component. + +**Arguments**: + +- `join_mode`: Specifies the join mode to use. Available modes: +- `concatenate`: Keeps the highest-scored document in case of duplicates. +- `merge`: Calculates a weighted sum of scores for duplicates and merges them. +- `reciprocal_rank_fusion`: Merges and assigns scores based on reciprocal rank fusion. +- `distribution_based_rank_fusion`: Merges and assigns scores based on scores +distribution in each Retriever. +- `weights`: Assign importance to each list of documents to influence how they're joined. +This parameter is ignored for +`concatenate` or `distribution_based_rank_fusion` join modes. +Weight for each list of documents must match the number of inputs. +- `top_k`: The maximum number of documents to return. +- `sort_by_score`: If `True`, sorts the documents by score in descending order. +If a document has no score, it is handled as if its score is -infinity. + + + +#### DocumentJoiner.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: Variadic[list[Document]], top_k: Optional[int] = None) +``` + +Joins multiple lists of Documents into a single list depending on the `join_mode` parameter. + +**Arguments**: + +- `documents`: List of list of documents to be merged. +- `top_k`: The maximum number of documents to return. Overrides the instance's `top_k` if provided. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Merged list of Documents + + + +#### DocumentJoiner.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### DocumentJoiner.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DocumentJoiner" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +## Module list\_joiner + + + +### ListJoiner + +A component that joins multiple lists into a single flat list. + +The ListJoiner receives multiple lists of the same type and concatenates them into a single flat list. +The output order respects the pipeline's execution sequence, with earlier inputs being added first. + +Usage example: +```python +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack import Pipeline +from haystack.components.joiners import ListJoiner + + +user_message = [ChatMessage.from_user("Give a brief answer the following question: {{query}}")] + +feedback_prompt = """ + You are given a question and an answer. + Your task is to provide a score and a brief feedback on the answer. + Question: {{query}} + Answer: {{response}} + """ +feedback_message = [ChatMessage.from_system(feedback_prompt)] + +prompt_builder = ChatPromptBuilder(template=user_message) +feedback_prompt_builder = ChatPromptBuilder(template=feedback_message) +llm = OpenAIChatGenerator(model="gpt-4o-mini") +feedback_llm = OpenAIChatGenerator(model="gpt-4o-mini") + +pipe = Pipeline() +pipe.add_component("prompt_builder", prompt_builder) +pipe.add_component("llm", llm) +pipe.add_component("feedback_prompt_builder", feedback_prompt_builder) +pipe.add_component("feedback_llm", feedback_llm) +pipe.add_component("list_joiner", ListJoiner(list[ChatMessage])) + +pipe.connect("prompt_builder.prompt", "llm.messages") +pipe.connect("prompt_builder.prompt", "list_joiner") +pipe.connect("llm.replies", "list_joiner") +pipe.connect("llm.replies", "feedback_prompt_builder.response") +pipe.connect("feedback_prompt_builder.prompt", "feedback_llm.messages") +pipe.connect("feedback_llm.replies", "list_joiner") + +query = "What is nuclear physics?" +ans = pipe.run(data={"prompt_builder": {"template_variables":{"query": query}}, + "feedback_prompt_builder": {"template_variables":{"query": query}}}) + +print(ans["list_joiner"]["values"]) +``` + + + +#### ListJoiner.\_\_init\_\_ + +```python +def __init__(list_type_: Optional[type] = None) +``` + +Creates a ListJoiner component. + +**Arguments**: + +- `list_type_`: The expected type of the lists this component will join (e.g., list[ChatMessage]). +If specified, all input lists must conform to this type. If None, the component defaults to handling +lists of any type including mixed types. + + + +#### ListJoiner.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ListJoiner.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ListJoiner" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ListJoiner.run + +```python +def run(values: Variadic[list[Any]]) -> dict[str, list[Any]] +``` + +Joins multiple lists into a single flat list. + +**Arguments**: + +- `values`: The list to be joined. + +**Returns**: + +Dictionary with 'values' key containing the joined list. + + + +## Module string\_joiner + + + +### StringJoiner + +Component to join strings from different components to a list of strings. + +### Usage example + +```python +from haystack.components.joiners import StringJoiner +from haystack.components.builders import PromptBuilder +from haystack.core.pipeline import Pipeline + +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +string_1 = "What's Natural Language Processing?" +string_2 = "What is life?" + +pipeline = Pipeline() +pipeline.add_component("prompt_builder_1", PromptBuilder("Builder 1: {{query}}")) +pipeline.add_component("prompt_builder_2", PromptBuilder("Builder 2: {{query}}")) +pipeline.add_component("string_joiner", StringJoiner()) + +pipeline.connect("prompt_builder_1.prompt", "string_joiner.strings") +pipeline.connect("prompt_builder_2.prompt", "string_joiner.strings") + +print(pipeline.run(data={"prompt_builder_1": {"query": string_1}, "prompt_builder_2": {"query": string_2}})) + +>> {"string_joiner": {"strings": ["Builder 1: What's Natural Language Processing?", "Builder 2: What is life?"]}} +``` + + + +#### StringJoiner.run + +```python +@component.output_types(strings=list[str]) +def run(strings: Variadic[str]) +``` + +Joins strings into a list of strings + +**Arguments**: + +- `strings`: strings from different components + +**Returns**: + +A dictionary with the following keys: +- `strings`: Merged list of strings + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/pipeline_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/pipeline_api.md new file mode 100644 index 0000000000..47164bad01 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/pipeline_api.md @@ -0,0 +1,1528 @@ +--- +title: "Pipeline" +id: pipeline-api +description: "Arranges components and integrations in flow." +slug: "/pipeline-api" +--- + + + +## Module async\_pipeline + + + +### AsyncPipeline + +Asynchronous version of the Pipeline orchestration engine. + +Manages components in a pipeline allowing for concurrent processing when the pipeline's execution graph permits. +This enables efficient processing of components by minimizing idle time and maximizing resource utilization. + + + +#### AsyncPipeline.run\_async\_generator + +```python +async def run_async_generator( + data: dict[str, Any], + include_outputs_from: Optional[set[str]] = None, + concurrency_limit: int = 4) -> AsyncIterator[dict[str, Any]] +``` + +Executes the pipeline step by step asynchronously, yielding partial outputs when any component finishes. + +Usage: +```python +from haystack import Document +from haystack.components.builders import ChatPromptBuilder +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.builders.prompt_builder import PromptBuilder +from haystack import AsyncPipeline +import asyncio + +# Write documents to InMemoryDocumentStore +document_store = InMemoryDocumentStore() +document_store.write_documents([ + Document(content="My name is Jean and I live in Paris."), + Document(content="My name is Mark and I live in Berlin."), + Document(content="My name is Giorgio and I live in Rome.") +]) + +prompt_template = [ + ChatMessage.from_user( + ''' + Given these documents, answer the question. + Documents: + {% for doc in documents %} + {{ doc.content }} + {% endfor %} + Question: {{question}} + Answer: + ''') +] + +# Create and connect pipeline components +retriever = InMemoryBM25Retriever(document_store=document_store) +prompt_builder = ChatPromptBuilder(template=prompt_template) +llm = OpenAIChatGenerator() + +rag_pipeline = AsyncPipeline() +rag_pipeline.add_component("retriever", retriever) +rag_pipeline.add_component("prompt_builder", prompt_builder) +rag_pipeline.add_component("llm", llm) +rag_pipeline.connect("retriever", "prompt_builder.documents") +rag_pipeline.connect("prompt_builder", "llm") + +# Prepare input data +question = "Who lives in Paris?" +data = { + "retriever": {"query": question}, + "prompt_builder": {"question": question}, +} + + +# Process results as they become available +async def process_results(): + async for partial_output in rag_pipeline.run_async_generator( + data=data, + include_outputs_from={"retriever", "llm"} + ): + # Each partial_output contains the results from a completed component + if "retriever" in partial_output: + print("Retrieved documents:", len(partial_output["retriever"]["documents"])) + if "llm" in partial_output: + print("Generated answer:", partial_output["llm"]["replies"][0]) + + +asyncio.run(process_results()) +``` + +**Arguments**: + +- `data`: Initial input data to the pipeline. +- `concurrency_limit`: The maximum number of components that are allowed to run concurrently. +- `include_outputs_from`: Set of component names whose individual outputs are to be +included in the pipeline's output. For components that are +invoked multiple times (in a loop), only the last-produced +output is included. + +**Raises**: + +- `ValueError`: If invalid inputs are provided to the pipeline. +- `PipelineMaxComponentRuns`: If a component exceeds the maximum number of allowed executions within the pipeline. +- `PipelineRuntimeError`: If the Pipeline contains cycles with unsupported connections that would cause +it to get stuck and fail running. +Or if a Component fails or returns output in an unsupported type. + +**Returns**: + +An async iterator containing partial (and final) outputs. + + + +#### AsyncPipeline.run\_async + +```python +async def run_async(data: dict[str, Any], + include_outputs_from: Optional[set[str]] = None, + concurrency_limit: int = 4) -> dict[str, Any] +``` + +Provides an asynchronous interface to run the pipeline with provided input data. + +This method allows the pipeline to be integrated into an asynchronous workflow, enabling non-blocking +execution of pipeline components. + +Usage: +```python +import asyncio + +from haystack import Document +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.core.pipeline import AsyncPipeline +from haystack.dataclasses import ChatMessage +from haystack.document_stores.in_memory import InMemoryDocumentStore + +# Write documents to InMemoryDocumentStore +document_store = InMemoryDocumentStore() +document_store.write_documents([ + Document(content="My name is Jean and I live in Paris."), + Document(content="My name is Mark and I live in Berlin."), + Document(content="My name is Giorgio and I live in Rome.") +]) + +prompt_template = [ + ChatMessage.from_user( + ''' + Given these documents, answer the question. + Documents: + {% for doc in documents %} + {{ doc.content }} + {% endfor %} + Question: {{question}} + Answer: + ''') +] + +retriever = InMemoryBM25Retriever(document_store=document_store) +prompt_builder = ChatPromptBuilder(template=prompt_template) +llm = OpenAIChatGenerator() + +rag_pipeline = AsyncPipeline() +rag_pipeline.add_component("retriever", retriever) +rag_pipeline.add_component("prompt_builder", prompt_builder) +rag_pipeline.add_component("llm", llm) +rag_pipeline.connect("retriever", "prompt_builder.documents") +rag_pipeline.connect("prompt_builder", "llm") + +# Ask a question +question = "Who lives in Paris?" + +async def run_inner(data, include_outputs_from): + return await rag_pipeline.run_async(data=data, include_outputs_from=include_outputs_from) + +data = { + "retriever": {"query": question}, + "prompt_builder": {"question": question}, +} + +results = asyncio.run(run_inner(data, include_outputs_from={"retriever", "llm"})) + +print(results["llm"]["replies"]) +# [ChatMessage(_role=, _content=[TextContent(text='Jean lives in Paris.')], +# _name=None, _meta={'model': 'gpt-4o-mini-2024-07-18', 'index': 0, 'finish_reason': 'stop', 'usage': +# {'completion_tokens': 6, 'prompt_tokens': 69, 'total_tokens': 75, +# 'completion_tokens_details': CompletionTokensDetails(accepted_prediction_tokens=0, +# audio_tokens=0, reasoning_tokens=0, rejected_prediction_tokens=0), 'prompt_tokens_details': +# PromptTokensDetails(audio_tokens=0, cached_tokens=0)}})] +``` + +**Arguments**: + +- `data`: A dictionary of inputs for the pipeline's components. Each key is a component name +and its value is a dictionary of that component's input parameters: +``` +data = { + "comp1": {"input1": 1, "input2": 2}, +} +``` +For convenience, this format is also supported when input names are unique: +``` +data = { + "input1": 1, "input2": 2, +} +``` +- `include_outputs_from`: Set of component names whose individual outputs are to be +included in the pipeline's output. For components that are +invoked multiple times (in a loop), only the last-produced +output is included. +- `concurrency_limit`: The maximum number of components that should be allowed to run concurrently. + +**Raises**: + +- `ValueError`: If invalid inputs are provided to the pipeline. +- `PipelineRuntimeError`: If the Pipeline contains cycles with unsupported connections that would cause +it to get stuck and fail running. +Or if a Component fails or returns output in an unsupported type. +- `PipelineMaxComponentRuns`: If a Component reaches the maximum number of times it can be run in this Pipeline. + +**Returns**: + +A dictionary where each entry corresponds to a component name +and its output. If `include_outputs_from` is `None`, this dictionary +will only contain the outputs of leaf components, i.e., components +without outgoing connections. + + + +#### AsyncPipeline.run + +```python +def run(data: dict[str, Any], + include_outputs_from: Optional[set[str]] = None, + concurrency_limit: int = 4) -> dict[str, Any] +``` + +Provides a synchronous interface to run the pipeline with given input data. + +Internally, the pipeline components are executed asynchronously, but the method itself +will block until the entire pipeline execution is complete. + +In case you need asynchronous methods, consider using `run_async` or `run_async_generator`. + +Usage: +```python +from haystack import Document +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.core.pipeline import AsyncPipeline +from haystack.dataclasses import ChatMessage +from haystack.document_stores.in_memory import InMemoryDocumentStore + +# Write documents to InMemoryDocumentStore +document_store = InMemoryDocumentStore() +document_store.write_documents([ + Document(content="My name is Jean and I live in Paris."), + Document(content="My name is Mark and I live in Berlin."), + Document(content="My name is Giorgio and I live in Rome.") +]) + +prompt_template = [ + ChatMessage.from_user( + ''' + Given these documents, answer the question. + Documents: + {% for doc in documents %} + {{ doc.content }} + {% endfor %} + Question: {{question}} + Answer: + ''') +] + + +retriever = InMemoryBM25Retriever(document_store=document_store) +prompt_builder = ChatPromptBuilder(template=prompt_template) +llm = OpenAIChatGenerator() + +rag_pipeline = AsyncPipeline() +rag_pipeline.add_component("retriever", retriever) +rag_pipeline.add_component("prompt_builder", prompt_builder) +rag_pipeline.add_component("llm", llm) +rag_pipeline.connect("retriever", "prompt_builder.documents") +rag_pipeline.connect("prompt_builder", "llm") + +# Ask a question +question = "Who lives in Paris?" + +data = { + "retriever": {"query": question}, + "prompt_builder": {"question": question}, +} + +results = rag_pipeline.run(data) + +print(results["llm"]["replies"]) +# [ChatMessage(_role=, _content=[TextContent(text='Jean lives in Paris.')], +# _name=None, _meta={'model': 'gpt-4o-mini-2024-07-18', 'index': 0, 'finish_reason': 'stop', 'usage': +# {'completion_tokens': 6, 'prompt_tokens': 69, 'total_tokens': 75, 'completion_tokens_details': +# CompletionTokensDetails(accepted_prediction_tokens=0, audio_tokens=0, reasoning_tokens=0, +# rejected_prediction_tokens=0), 'prompt_tokens_details': PromptTokensDetails(audio_tokens=0, +# cached_tokens=0)}})] +``` + +**Arguments**: + +- `data`: A dictionary of inputs for the pipeline's components. Each key is a component name +and its value is a dictionary of that component's input parameters: +``` +data = { + "comp1": {"input1": 1, "input2": 2}, +} +``` +For convenience, this format is also supported when input names are unique: +``` +data = { + "input1": 1, "input2": 2, +} +``` +- `include_outputs_from`: Set of component names whose individual outputs are to be +included in the pipeline's output. For components that are +invoked multiple times (in a loop), only the last-produced +output is included. +- `concurrency_limit`: The maximum number of components that should be allowed to run concurrently. + +**Raises**: + +- `ValueError`: If invalid inputs are provided to the pipeline. +- `PipelineRuntimeError`: If the Pipeline contains cycles with unsupported connections that would cause +it to get stuck and fail running. +Or if a Component fails or returns output in an unsupported type. +- `PipelineMaxComponentRuns`: If a Component reaches the maximum number of times it can be run in this Pipeline. +- `RuntimeError`: If called from within an async context. Use `run_async` instead. + +**Returns**: + +A dictionary where each entry corresponds to a component name +and its output. If `include_outputs_from` is `None`, this dictionary +will only contain the outputs of leaf components, i.e., components +without outgoing connections. + + + +#### AsyncPipeline.\_\_init\_\_ + +```python +def __init__(metadata: Optional[dict[str, Any]] = None, + max_runs_per_component: int = 100, + connection_type_validation: bool = True) +``` + +Creates the Pipeline. + +**Arguments**: + +- `metadata`: Arbitrary dictionary to store metadata about this `Pipeline`. Make sure all the values contained in +this dictionary can be serialized and deserialized if you wish to save this `Pipeline` to file. +- `max_runs_per_component`: How many times the `Pipeline` can run the same Component. +If this limit is reached a `PipelineMaxComponentRuns` exception is raised. +If not set defaults to 100 runs per Component. +- `connection_type_validation`: Whether the pipeline will validate the types of the connections. +Defaults to True. + + + +#### AsyncPipeline.\_\_eq\_\_ + +```python +def __eq__(other: object) -> bool +``` + +Pipeline equality is defined by their type and the equality of their serialized form. + +Pipelines of the same type share every metadata, node and edge, but they're not required to use +the same node instances: this allows pipeline saved and then loaded back to be equal to themselves. + + + +#### AsyncPipeline.\_\_repr\_\_ + +```python +def __repr__() -> str +``` + +Returns a text representation of the Pipeline. + + + +#### AsyncPipeline.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the pipeline to a dictionary. + +This is meant to be an intermediate representation but it can be also used to save a pipeline to file. + +**Returns**: + +Dictionary with serialized data. + + + +#### AsyncPipeline.from\_dict + +```python +@classmethod +def from_dict(cls: type[T], + data: dict[str, Any], + callbacks: Optional[DeserializationCallbacks] = None, + **kwargs: Any) -> T +``` + +Deserializes the pipeline from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. +- `callbacks`: Callbacks to invoke during deserialization. +- `kwargs`: `components`: a dictionary of `{name: instance}` to reuse instances of components instead of creating new +ones. + +**Returns**: + +Deserialized component. + + + +#### AsyncPipeline.dumps + +```python +def dumps(marshaller: Marshaller = DEFAULT_MARSHALLER) -> str +``` + +Returns the string representation of this pipeline according to the format dictated by the `Marshaller` in use. + +**Arguments**: + +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. + +**Returns**: + +A string representing the pipeline. + + + +#### AsyncPipeline.dump + +```python +def dump(fp: TextIO, marshaller: Marshaller = DEFAULT_MARSHALLER) -> None +``` + +Writes the string representation of this pipeline to the file-like object passed in the `fp` argument. + +**Arguments**: + +- `fp`: A file-like object ready to be written to. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. + + + +#### AsyncPipeline.loads + +```python +@classmethod +def loads(cls: type[T], + data: Union[str, bytes, bytearray], + marshaller: Marshaller = DEFAULT_MARSHALLER, + callbacks: Optional[DeserializationCallbacks] = None) -> T +``` + +Creates a `Pipeline` object from the string representation passed in the `data` argument. + +**Arguments**: + +- `data`: The string representation of the pipeline, can be `str`, `bytes` or `bytearray`. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. +- `callbacks`: Callbacks to invoke during deserialization. + +**Raises**: + +- `DeserializationError`: If an error occurs during deserialization. + +**Returns**: + +A `Pipeline` object. + + + +#### AsyncPipeline.load + +```python +@classmethod +def load(cls: type[T], + fp: TextIO, + marshaller: Marshaller = DEFAULT_MARSHALLER, + callbacks: Optional[DeserializationCallbacks] = None) -> T +``` + +Creates a `Pipeline` object a string representation. + +The string representation is read from the file-like object passed in the `fp` argument. + +**Arguments**: + +- `fp`: A file-like object ready to be read from. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. +- `callbacks`: Callbacks to invoke during deserialization. + +**Raises**: + +- `DeserializationError`: If an error occurs during deserialization. + +**Returns**: + +A `Pipeline` object. + + + +#### AsyncPipeline.add\_component + +```python +def add_component(name: str, instance: Component) -> None +``` + +Add the given component to the pipeline. + +Components are not connected to anything by default: use `Pipeline.connect()` to connect components together. +Component names must be unique, but component instances can be reused if needed. + +**Arguments**: + +- `name`: The name of the component to add. +- `instance`: The component instance to add. + +**Raises**: + +- `ValueError`: If a component with the same name already exists. +- `PipelineValidationError`: If the given instance is not a component. + + + +#### AsyncPipeline.remove\_component + +```python +def remove_component(name: str) -> Component +``` + +Remove and returns component from the pipeline. + +Remove an existing component from the pipeline by providing its name. +All edges that connect to the component will also be deleted. + +**Arguments**: + +- `name`: The name of the component to remove. + +**Raises**: + +- `ValueError`: If there is no component with that name already in the Pipeline. + +**Returns**: + +The removed Component instance. + + + +#### AsyncPipeline.connect + +```python +def connect(sender: str, receiver: str) -> "PipelineBase" +``` + +Connects two components together. + +All components to connect must exist in the pipeline. +If connecting to a component that has several output connections, specify the inputs and output names as +'component_name.connections_name'. + +**Arguments**: + +- `sender`: The component that delivers the value. This can be either just a component name or can be +in the format `component_name.connection_name` if the component has multiple outputs. +- `receiver`: The component that receives the value. This can be either just a component name or can be +in the format `component_name.connection_name` if the component has multiple inputs. + +**Raises**: + +- `PipelineConnectError`: If the two components cannot be connected (for example if one of the components is +not present in the pipeline, or the connections don't match by type, and so on). + +**Returns**: + +The Pipeline instance. + + + +#### AsyncPipeline.get\_component + +```python +def get_component(name: str) -> Component +``` + +Get the component with the specified name from the pipeline. + +**Arguments**: + +- `name`: The name of the component. + +**Raises**: + +- `ValueError`: If a component with that name is not present in the pipeline. + +**Returns**: + +The instance of that component. + + + +#### AsyncPipeline.get\_component\_name + +```python +def get_component_name(instance: Component) -> str +``` + +Returns the name of the Component instance if it has been added to this Pipeline or an empty string otherwise. + +**Arguments**: + +- `instance`: The Component instance to look for. + +**Returns**: + +The name of the Component instance. + + + +#### AsyncPipeline.inputs + +```python +def inputs( + include_components_with_connected_inputs: bool = False +) -> dict[str, dict[str, Any]] +``` + +Returns a dictionary containing the inputs of a pipeline. + +Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes +the input sockets of that component, including their types and whether they are optional. + +**Arguments**: + +- `include_components_with_connected_inputs`: If `False`, only components that have disconnected input edges are +included in the output. + +**Returns**: + +A dictionary where each key is a pipeline component name and each value is a dictionary of +inputs sockets of that component. + + + +#### AsyncPipeline.outputs + +```python +def outputs( + include_components_with_connected_outputs: bool = False +) -> dict[str, dict[str, Any]] +``` + +Returns a dictionary containing the outputs of a pipeline. + +Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes +the output sockets of that component. + +**Arguments**: + +- `include_components_with_connected_outputs`: If `False`, only components that have disconnected output edges are +included in the output. + +**Returns**: + +A dictionary where each key is a pipeline component name and each value is a dictionary of +output sockets of that component. + + + +#### AsyncPipeline.show + +```python +def show(*, + server_url: str = "https://mermaid.ink", + params: Optional[dict] = None, + timeout: int = 30, + super_component_expansion: bool = False) -> None +``` + +Display an image representing this `Pipeline` in a Jupyter notebook. + +This function generates a diagram of the `Pipeline` using a Mermaid server and displays it directly in +the notebook. + +**Arguments**: + +- `server_url`: The base URL of the Mermaid server used for rendering (default: 'https://mermaid.ink'). +See https://github.com/jihchi/mermaid.ink and https://github.com/mermaid-js/mermaid-live-editor for more +info on how to set up your own Mermaid server. +- `params`: Dictionary of customization parameters to modify the output. Refer to Mermaid documentation for more details +Supported keys: +- format: Output format ('img', 'svg', or 'pdf'). Default: 'img'. +- type: Image type for /img endpoint ('jpeg', 'png', 'webp'). Default: 'png'. +- theme: Mermaid theme ('default', 'neutral', 'dark', 'forest'). Default: 'neutral'. +- bgColor: Background color in hexadecimal (e.g., 'FFFFFF') or named format (e.g., '!white'). +- width: Width of the output image (integer). +- height: Height of the output image (integer). +- scale: Scaling factor (1–3). Only applicable if 'width' or 'height' is specified. +- fit: Whether to fit the diagram size to the page (PDF only, boolean). +- paper: Paper size for PDFs (e.g., 'a4', 'a3'). Ignored if 'fit' is true. +- landscape: Landscape orientation for PDFs (boolean). Ignored if 'fit' is true. +- `timeout`: Timeout in seconds for the request to the Mermaid server. +- `super_component_expansion`: If set to True and the pipeline contains SuperComponents the diagram will show the internal structure of +super-components as if they were components part of the pipeline instead of a "black-box". +Otherwise, only the super-component itself will be displayed. + +**Raises**: + +- `PipelineDrawingError`: If the function is called outside of a Jupyter notebook or if there is an issue with rendering. + + + +#### AsyncPipeline.draw + +```python +def draw(*, + path: Path, + server_url: str = "https://mermaid.ink", + params: Optional[dict] = None, + timeout: int = 30, + super_component_expansion: bool = False) -> None +``` + +Save an image representing this `Pipeline` to the specified file path. + +This function generates a diagram of the `Pipeline` using the Mermaid server and saves it to the provided path. + +**Arguments**: + +- `path`: The file path where the generated image will be saved. +- `server_url`: The base URL of the Mermaid server used for rendering (default: 'https://mermaid.ink'). +See https://github.com/jihchi/mermaid.ink and https://github.com/mermaid-js/mermaid-live-editor for more +info on how to set up your own Mermaid server. +- `params`: Dictionary of customization parameters to modify the output. Refer to Mermaid documentation for more details +Supported keys: +- format: Output format ('img', 'svg', or 'pdf'). Default: 'img'. +- type: Image type for /img endpoint ('jpeg', 'png', 'webp'). Default: 'png'. +- theme: Mermaid theme ('default', 'neutral', 'dark', 'forest'). Default: 'neutral'. +- bgColor: Background color in hexadecimal (e.g., 'FFFFFF') or named format (e.g., '!white'). +- width: Width of the output image (integer). +- height: Height of the output image (integer). +- scale: Scaling factor (1–3). Only applicable if 'width' or 'height' is specified. +- fit: Whether to fit the diagram size to the page (PDF only, boolean). +- paper: Paper size for PDFs (e.g., 'a4', 'a3'). Ignored if 'fit' is true. +- landscape: Landscape orientation for PDFs (boolean). Ignored if 'fit' is true. +- `timeout`: Timeout in seconds for the request to the Mermaid server. +- `super_component_expansion`: If set to True and the pipeline contains SuperComponents the diagram will show the internal structure of +super-components as if they were components part of the pipeline instead of a "black-box". +Otherwise, only the super-component itself will be displayed. + +**Raises**: + +- `PipelineDrawingError`: If there is an issue with rendering or saving the image. + + + +#### AsyncPipeline.walk + +```python +def walk() -> Iterator[tuple[str, Component]] +``` + +Visits each component in the pipeline exactly once and yields its name and instance. + +No guarantees are provided on the visiting order. + +**Returns**: + +An iterator of tuples of component name and component instance. + + + +#### AsyncPipeline.warm\_up + +```python +def warm_up() -> None +``` + +Make sure all nodes are warm. + +It's the node's responsibility to make sure this method can be called at every `Pipeline.run()` +without re-initializing everything. + + + +#### AsyncPipeline.validate\_input + +```python +def validate_input(data: dict[str, Any]) -> None +``` + +Validates pipeline input data. + +Validates that data: +* Each Component name actually exists in the Pipeline +* Each Component is not missing any input +* Each Component has only one input per input socket, if not variadic +* Each Component doesn't receive inputs that are already sent by another Component + +**Arguments**: + +- `data`: A dictionary of inputs for the pipeline's components. Each key is a component name. + +**Raises**: + +- `ValueError`: If inputs are invalid according to the above. + + + +#### AsyncPipeline.from\_template + +```python +@classmethod +def from_template( + cls, + predefined_pipeline: PredefinedPipeline, + template_params: Optional[dict[str, Any]] = None) -> "PipelineBase" +``` + +Create a Pipeline from a predefined template. See `PredefinedPipeline` for available options. + +**Arguments**: + +- `predefined_pipeline`: The predefined pipeline to use. +- `template_params`: An optional dictionary of parameters to use when rendering the pipeline template. + +**Returns**: + +An instance of `Pipeline`. + + + +#### AsyncPipeline.validate\_pipeline + +```python +@staticmethod +def validate_pipeline(priority_queue: FIFOPriorityQueue) -> None +``` + +Validate the pipeline to check if it is blocked or has no valid entry point. + +**Arguments**: + +- `priority_queue`: Priority queue of component names. + +**Raises**: + +- `PipelineRuntimeError`: If the pipeline is blocked or has no valid entry point. + + + +## Module pipeline + + + +### Pipeline + +Synchronous version of the orchestration engine. + +Orchestrates component execution according to the execution graph, one after the other. + + + +#### Pipeline.run + +```python +def run(data: dict[str, Any], + include_outputs_from: Optional[set[str]] = None, + *, + break_point: Optional[Union[Breakpoint, AgentBreakpoint]] = None, + pipeline_snapshot: Optional[PipelineSnapshot] = None + ) -> dict[str, Any] +``` + +Runs the Pipeline with given input data. + +Usage: +```python +from haystack import Pipeline, Document +from haystack.utils import Secret +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.components.generators import OpenAIGenerator +from haystack.components.builders.answer_builder import AnswerBuilder +from haystack.components.builders.prompt_builder import PromptBuilder + +# Write documents to InMemoryDocumentStore +document_store = InMemoryDocumentStore() +document_store.write_documents([ + Document(content="My name is Jean and I live in Paris."), + Document(content="My name is Mark and I live in Berlin."), + Document(content="My name is Giorgio and I live in Rome.") +]) + +prompt_template = """ +Given these documents, answer the question. +Documents: +{% for doc in documents %} + {{ doc.content }} +{% endfor %} +Question: {{question}} +Answer: +""" + +retriever = InMemoryBM25Retriever(document_store=document_store) +prompt_builder = PromptBuilder(template=prompt_template) +llm = OpenAIGenerator(api_key=Secret.from_token(api_key)) + +rag_pipeline = Pipeline() +rag_pipeline.add_component("retriever", retriever) +rag_pipeline.add_component("prompt_builder", prompt_builder) +rag_pipeline.add_component("llm", llm) +rag_pipeline.connect("retriever", "prompt_builder.documents") +rag_pipeline.connect("prompt_builder", "llm") + +# Ask a question +question = "Who lives in Paris?" +results = rag_pipeline.run( + { + "retriever": {"query": question}, + "prompt_builder": {"question": question}, + } +) + +print(results["llm"]["replies"]) +# Jean lives in Paris +``` + +**Arguments**: + +- `data`: A dictionary of inputs for the pipeline's components. Each key is a component name +and its value is a dictionary of that component's input parameters: +``` +data = { + "comp1": {"input1": 1, "input2": 2}, +} +``` +For convenience, this format is also supported when input names are unique: +``` +data = { + "input1": 1, "input2": 2, +} +``` +- `include_outputs_from`: Set of component names whose individual outputs are to be +included in the pipeline's output. For components that are +invoked multiple times (in a loop), only the last-produced +output is included. +- `break_point`: A set of breakpoints that can be used to debug the pipeline execution. +- `pipeline_snapshot`: A dictionary containing a snapshot of a previously saved pipeline execution. + +**Raises**: + +- `ValueError`: If invalid inputs are provided to the pipeline. +- `PipelineRuntimeError`: If the Pipeline contains cycles with unsupported connections that would cause +it to get stuck and fail running. +Or if a Component fails or returns output in an unsupported type. +- `PipelineMaxComponentRuns`: If a Component reaches the maximum number of times it can be run in this Pipeline. +- `PipelineBreakpointException`: When a pipeline_breakpoint is triggered. Contains the component name, state, and partial results. + +**Returns**: + +A dictionary where each entry corresponds to a component name +and its output. If `include_outputs_from` is `None`, this dictionary +will only contain the outputs of leaf components, i.e., components +without outgoing connections. + + + +#### Pipeline.\_\_init\_\_ + +```python +def __init__(metadata: Optional[dict[str, Any]] = None, + max_runs_per_component: int = 100, + connection_type_validation: bool = True) +``` + +Creates the Pipeline. + +**Arguments**: + +- `metadata`: Arbitrary dictionary to store metadata about this `Pipeline`. Make sure all the values contained in +this dictionary can be serialized and deserialized if you wish to save this `Pipeline` to file. +- `max_runs_per_component`: How many times the `Pipeline` can run the same Component. +If this limit is reached a `PipelineMaxComponentRuns` exception is raised. +If not set defaults to 100 runs per Component. +- `connection_type_validation`: Whether the pipeline will validate the types of the connections. +Defaults to True. + + + +#### Pipeline.\_\_eq\_\_ + +```python +def __eq__(other: object) -> bool +``` + +Pipeline equality is defined by their type and the equality of their serialized form. + +Pipelines of the same type share every metadata, node and edge, but they're not required to use +the same node instances: this allows pipeline saved and then loaded back to be equal to themselves. + + + +#### Pipeline.\_\_repr\_\_ + +```python +def __repr__() -> str +``` + +Returns a text representation of the Pipeline. + + + +#### Pipeline.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the pipeline to a dictionary. + +This is meant to be an intermediate representation but it can be also used to save a pipeline to file. + +**Returns**: + +Dictionary with serialized data. + + + +#### Pipeline.from\_dict + +```python +@classmethod +def from_dict(cls: type[T], + data: dict[str, Any], + callbacks: Optional[DeserializationCallbacks] = None, + **kwargs: Any) -> T +``` + +Deserializes the pipeline from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. +- `callbacks`: Callbacks to invoke during deserialization. +- `kwargs`: `components`: a dictionary of `{name: instance}` to reuse instances of components instead of creating new +ones. + +**Returns**: + +Deserialized component. + + + +#### Pipeline.dumps + +```python +def dumps(marshaller: Marshaller = DEFAULT_MARSHALLER) -> str +``` + +Returns the string representation of this pipeline according to the format dictated by the `Marshaller` in use. + +**Arguments**: + +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. + +**Returns**: + +A string representing the pipeline. + + + +#### Pipeline.dump + +```python +def dump(fp: TextIO, marshaller: Marshaller = DEFAULT_MARSHALLER) -> None +``` + +Writes the string representation of this pipeline to the file-like object passed in the `fp` argument. + +**Arguments**: + +- `fp`: A file-like object ready to be written to. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. + + + +#### Pipeline.loads + +```python +@classmethod +def loads(cls: type[T], + data: Union[str, bytes, bytearray], + marshaller: Marshaller = DEFAULT_MARSHALLER, + callbacks: Optional[DeserializationCallbacks] = None) -> T +``` + +Creates a `Pipeline` object from the string representation passed in the `data` argument. + +**Arguments**: + +- `data`: The string representation of the pipeline, can be `str`, `bytes` or `bytearray`. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. +- `callbacks`: Callbacks to invoke during deserialization. + +**Raises**: + +- `DeserializationError`: If an error occurs during deserialization. + +**Returns**: + +A `Pipeline` object. + + + +#### Pipeline.load + +```python +@classmethod +def load(cls: type[T], + fp: TextIO, + marshaller: Marshaller = DEFAULT_MARSHALLER, + callbacks: Optional[DeserializationCallbacks] = None) -> T +``` + +Creates a `Pipeline` object a string representation. + +The string representation is read from the file-like object passed in the `fp` argument. + +**Arguments**: + +- `fp`: A file-like object ready to be read from. +- `marshaller`: The Marshaller used to create the string representation. Defaults to `YamlMarshaller`. +- `callbacks`: Callbacks to invoke during deserialization. + +**Raises**: + +- `DeserializationError`: If an error occurs during deserialization. + +**Returns**: + +A `Pipeline` object. + + + +#### Pipeline.add\_component + +```python +def add_component(name: str, instance: Component) -> None +``` + +Add the given component to the pipeline. + +Components are not connected to anything by default: use `Pipeline.connect()` to connect components together. +Component names must be unique, but component instances can be reused if needed. + +**Arguments**: + +- `name`: The name of the component to add. +- `instance`: The component instance to add. + +**Raises**: + +- `ValueError`: If a component with the same name already exists. +- `PipelineValidationError`: If the given instance is not a component. + + + +#### Pipeline.remove\_component + +```python +def remove_component(name: str) -> Component +``` + +Remove and returns component from the pipeline. + +Remove an existing component from the pipeline by providing its name. +All edges that connect to the component will also be deleted. + +**Arguments**: + +- `name`: The name of the component to remove. + +**Raises**: + +- `ValueError`: If there is no component with that name already in the Pipeline. + +**Returns**: + +The removed Component instance. + + + +#### Pipeline.connect + +```python +def connect(sender: str, receiver: str) -> "PipelineBase" +``` + +Connects two components together. + +All components to connect must exist in the pipeline. +If connecting to a component that has several output connections, specify the inputs and output names as +'component_name.connections_name'. + +**Arguments**: + +- `sender`: The component that delivers the value. This can be either just a component name or can be +in the format `component_name.connection_name` if the component has multiple outputs. +- `receiver`: The component that receives the value. This can be either just a component name or can be +in the format `component_name.connection_name` if the component has multiple inputs. + +**Raises**: + +- `PipelineConnectError`: If the two components cannot be connected (for example if one of the components is +not present in the pipeline, or the connections don't match by type, and so on). + +**Returns**: + +The Pipeline instance. + + + +#### Pipeline.get\_component + +```python +def get_component(name: str) -> Component +``` + +Get the component with the specified name from the pipeline. + +**Arguments**: + +- `name`: The name of the component. + +**Raises**: + +- `ValueError`: If a component with that name is not present in the pipeline. + +**Returns**: + +The instance of that component. + + + +#### Pipeline.get\_component\_name + +```python +def get_component_name(instance: Component) -> str +``` + +Returns the name of the Component instance if it has been added to this Pipeline or an empty string otherwise. + +**Arguments**: + +- `instance`: The Component instance to look for. + +**Returns**: + +The name of the Component instance. + + + +#### Pipeline.inputs + +```python +def inputs( + include_components_with_connected_inputs: bool = False +) -> dict[str, dict[str, Any]] +``` + +Returns a dictionary containing the inputs of a pipeline. + +Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes +the input sockets of that component, including their types and whether they are optional. + +**Arguments**: + +- `include_components_with_connected_inputs`: If `False`, only components that have disconnected input edges are +included in the output. + +**Returns**: + +A dictionary where each key is a pipeline component name and each value is a dictionary of +inputs sockets of that component. + + + +#### Pipeline.outputs + +```python +def outputs( + include_components_with_connected_outputs: bool = False +) -> dict[str, dict[str, Any]] +``` + +Returns a dictionary containing the outputs of a pipeline. + +Each key in the dictionary corresponds to a component name, and its value is another dictionary that describes +the output sockets of that component. + +**Arguments**: + +- `include_components_with_connected_outputs`: If `False`, only components that have disconnected output edges are +included in the output. + +**Returns**: + +A dictionary where each key is a pipeline component name and each value is a dictionary of +output sockets of that component. + + + +#### Pipeline.show + +```python +def show(*, + server_url: str = "https://mermaid.ink", + params: Optional[dict] = None, + timeout: int = 30, + super_component_expansion: bool = False) -> None +``` + +Display an image representing this `Pipeline` in a Jupyter notebook. + +This function generates a diagram of the `Pipeline` using a Mermaid server and displays it directly in +the notebook. + +**Arguments**: + +- `server_url`: The base URL of the Mermaid server used for rendering (default: 'https://mermaid.ink'). +See https://github.com/jihchi/mermaid.ink and https://github.com/mermaid-js/mermaid-live-editor for more +info on how to set up your own Mermaid server. +- `params`: Dictionary of customization parameters to modify the output. Refer to Mermaid documentation for more details +Supported keys: +- format: Output format ('img', 'svg', or 'pdf'). Default: 'img'. +- type: Image type for /img endpoint ('jpeg', 'png', 'webp'). Default: 'png'. +- theme: Mermaid theme ('default', 'neutral', 'dark', 'forest'). Default: 'neutral'. +- bgColor: Background color in hexadecimal (e.g., 'FFFFFF') or named format (e.g., '!white'). +- width: Width of the output image (integer). +- height: Height of the output image (integer). +- scale: Scaling factor (1–3). Only applicable if 'width' or 'height' is specified. +- fit: Whether to fit the diagram size to the page (PDF only, boolean). +- paper: Paper size for PDFs (e.g., 'a4', 'a3'). Ignored if 'fit' is true. +- landscape: Landscape orientation for PDFs (boolean). Ignored if 'fit' is true. +- `timeout`: Timeout in seconds for the request to the Mermaid server. +- `super_component_expansion`: If set to True and the pipeline contains SuperComponents the diagram will show the internal structure of +super-components as if they were components part of the pipeline instead of a "black-box". +Otherwise, only the super-component itself will be displayed. + +**Raises**: + +- `PipelineDrawingError`: If the function is called outside of a Jupyter notebook or if there is an issue with rendering. + + + +#### Pipeline.draw + +```python +def draw(*, + path: Path, + server_url: str = "https://mermaid.ink", + params: Optional[dict] = None, + timeout: int = 30, + super_component_expansion: bool = False) -> None +``` + +Save an image representing this `Pipeline` to the specified file path. + +This function generates a diagram of the `Pipeline` using the Mermaid server and saves it to the provided path. + +**Arguments**: + +- `path`: The file path where the generated image will be saved. +- `server_url`: The base URL of the Mermaid server used for rendering (default: 'https://mermaid.ink'). +See https://github.com/jihchi/mermaid.ink and https://github.com/mermaid-js/mermaid-live-editor for more +info on how to set up your own Mermaid server. +- `params`: Dictionary of customization parameters to modify the output. Refer to Mermaid documentation for more details +Supported keys: +- format: Output format ('img', 'svg', or 'pdf'). Default: 'img'. +- type: Image type for /img endpoint ('jpeg', 'png', 'webp'). Default: 'png'. +- theme: Mermaid theme ('default', 'neutral', 'dark', 'forest'). Default: 'neutral'. +- bgColor: Background color in hexadecimal (e.g., 'FFFFFF') or named format (e.g., '!white'). +- width: Width of the output image (integer). +- height: Height of the output image (integer). +- scale: Scaling factor (1–3). Only applicable if 'width' or 'height' is specified. +- fit: Whether to fit the diagram size to the page (PDF only, boolean). +- paper: Paper size for PDFs (e.g., 'a4', 'a3'). Ignored if 'fit' is true. +- landscape: Landscape orientation for PDFs (boolean). Ignored if 'fit' is true. +- `timeout`: Timeout in seconds for the request to the Mermaid server. +- `super_component_expansion`: If set to True and the pipeline contains SuperComponents the diagram will show the internal structure of +super-components as if they were components part of the pipeline instead of a "black-box". +Otherwise, only the super-component itself will be displayed. + +**Raises**: + +- `PipelineDrawingError`: If there is an issue with rendering or saving the image. + + + +#### Pipeline.walk + +```python +def walk() -> Iterator[tuple[str, Component]] +``` + +Visits each component in the pipeline exactly once and yields its name and instance. + +No guarantees are provided on the visiting order. + +**Returns**: + +An iterator of tuples of component name and component instance. + + + +#### Pipeline.warm\_up + +```python +def warm_up() -> None +``` + +Make sure all nodes are warm. + +It's the node's responsibility to make sure this method can be called at every `Pipeline.run()` +without re-initializing everything. + + + +#### Pipeline.validate\_input + +```python +def validate_input(data: dict[str, Any]) -> None +``` + +Validates pipeline input data. + +Validates that data: +* Each Component name actually exists in the Pipeline +* Each Component is not missing any input +* Each Component has only one input per input socket, if not variadic +* Each Component doesn't receive inputs that are already sent by another Component + +**Arguments**: + +- `data`: A dictionary of inputs for the pipeline's components. Each key is a component name. + +**Raises**: + +- `ValueError`: If inputs are invalid according to the above. + + + +#### Pipeline.from\_template + +```python +@classmethod +def from_template( + cls, + predefined_pipeline: PredefinedPipeline, + template_params: Optional[dict[str, Any]] = None) -> "PipelineBase" +``` + +Create a Pipeline from a predefined template. See `PredefinedPipeline` for available options. + +**Arguments**: + +- `predefined_pipeline`: The predefined pipeline to use. +- `template_params`: An optional dictionary of parameters to use when rendering the pipeline template. + +**Returns**: + +An instance of `Pipeline`. + + + +#### Pipeline.validate\_pipeline + +```python +@staticmethod +def validate_pipeline(priority_queue: FIFOPriorityQueue) -> None +``` + +Validate the pipeline to check if it is blocked or has no valid entry point. + +**Arguments**: + +- `priority_queue`: Priority queue of component names. + +**Raises**: + +- `PipelineRuntimeError`: If the pipeline is blocked or has no valid entry point. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/preprocessors_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/preprocessors_api.md new file mode 100644 index 0000000000..2979ec5f83 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/preprocessors_api.md @@ -0,0 +1,801 @@ +--- +title: "PreProcessors" +id: preprocessors-api +description: "Preprocess your Documents and texts. Clean, split, and more." +slug: "/preprocessors-api" +--- + + + +## Module csv\_document\_cleaner + + + +### CSVDocumentCleaner + +A component for cleaning CSV documents by removing empty rows and columns. + +This component processes CSV content stored in Documents, allowing +for the optional ignoring of a specified number of rows and columns before performing +the cleaning operation. Additionally, it provides options to keep document IDs and +control whether empty rows and columns should be removed. + + + +#### CSVDocumentCleaner.\_\_init\_\_ + +```python +def __init__(*, + ignore_rows: int = 0, + ignore_columns: int = 0, + remove_empty_rows: bool = True, + remove_empty_columns: bool = True, + keep_id: bool = False) -> None +``` + +Initializes the CSVDocumentCleaner component. + +**Arguments**: + +- `ignore_rows`: Number of rows to ignore from the top of the CSV table before processing. +- `ignore_columns`: Number of columns to ignore from the left of the CSV table before processing. +- `remove_empty_rows`: Whether to remove rows that are entirely empty. +- `remove_empty_columns`: Whether to remove columns that are entirely empty. +- `keep_id`: Whether to retain the original document ID in the output document. +Rows and columns ignored using these parameters are preserved in the final output, meaning +they are not considered when removing empty rows and columns. + + + +#### CSVDocumentCleaner.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Cleans CSV documents by removing empty rows and columns while preserving specified ignored rows and columns. + +**Arguments**: + +- `documents`: List of Documents containing CSV-formatted content. + +**Returns**: + +A dictionary with a list of cleaned Documents under the key "documents". +Processing steps: +1. Reads each document's content as a CSV table. +2. Retains the specified number of `ignore_rows` from the top and `ignore_columns` from the left. +3. Drops any rows and columns that are entirely empty (if enabled by `remove_empty_rows` and + `remove_empty_columns`). +4. Reattaches the ignored rows and columns to maintain their original positions. +5. Returns the cleaned CSV content as a new `Document` object, with an option to retain the original + document ID. + + + +## Module csv\_document\_splitter + + + +### CSVDocumentSplitter + +A component for splitting CSV documents into sub-tables based on split arguments. + +The splitter supports two modes of operation: +- identify consecutive empty rows or columns that exceed a given threshold +and uses them as delimiters to segment the document into smaller tables. +- split each row into a separate sub-table, represented as a Document. + + + +#### CSVDocumentSplitter.\_\_init\_\_ + +```python +def __init__(row_split_threshold: Optional[int] = 2, + column_split_threshold: Optional[int] = 2, + read_csv_kwargs: Optional[dict[str, Any]] = None, + split_mode: SplitMode = "threshold") -> None +``` + +Initializes the CSVDocumentSplitter component. + +**Arguments**: + +- `row_split_threshold`: The minimum number of consecutive empty rows required to trigger a split. +- `column_split_threshold`: The minimum number of consecutive empty columns required to trigger a split. +- `read_csv_kwargs`: Additional keyword arguments to pass to `pandas.read_csv`. +By default, the component with options: +- `header=None` +- `skip_blank_lines=False` to preserve blank lines +- `dtype=object` to prevent type inference (e.g., converting numbers to floats). +See https://pandas.pydata.org/docs/reference/api/pandas.read_csv.html for more information. +- `split_mode`: If `threshold`, the component will split the document based on the number of +consecutive empty rows or columns that exceed the `row_split_threshold` or `column_split_threshold`. +If `row-wise`, the component will split each row into a separate sub-table. + + + +#### CSVDocumentSplitter.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Processes and splits a list of CSV documents into multiple sub-tables. + +**Splitting Process:** +1. Applies a row-based split if `row_split_threshold` is provided. +2. Applies a column-based split if `column_split_threshold` is provided. +3. If both thresholds are specified, performs a recursive split by rows first, then columns, ensuring + further fragmentation of any sub-tables that still contain empty sections. +4. Sorts the resulting sub-tables based on their original positions within the document. + +**Arguments**: + +- `documents`: A list of Documents containing CSV-formatted content. +Each document is assumed to contain one or more tables separated by empty rows or columns. + +**Returns**: + +A dictionary with a key `"documents"`, mapping to a list of new `Document` objects, +each representing an extracted sub-table from the original CSV. + The metadata of each document includes: + - A field `source_id` to track the original document. + - A field `row_idx_start` to indicate the starting row index of the sub-table in the original table. + - A field `col_idx_start` to indicate the starting column index of the sub-table in the original table. + - A field `split_id` to indicate the order of the split in the original document. + - All other metadata copied from the original document. + +- If a document cannot be processed, it is returned unchanged. +- The `meta` field from the original document is preserved in the split documents. + + + +## Module document\_cleaner + + + +### DocumentCleaner + +Cleans the text in the documents. + +It removes extra whitespaces, +empty lines, specified substrings, regexes, +page headers and footers (in this order). + +### Usage example: + +```python +from haystack import Document +from haystack.components.preprocessors import DocumentCleaner + +doc = Document(content="This is a document to clean\n\n\nsubstring to remove") + +cleaner = DocumentCleaner(remove_substrings = ["substring to remove"]) +result = cleaner.run(documents=[doc]) + +assert result["documents"][0].content == "This is a document to clean " +``` + + + +#### DocumentCleaner.\_\_init\_\_ + +```python +def __init__(remove_empty_lines: bool = True, + remove_extra_whitespaces: bool = True, + remove_repeated_substrings: bool = False, + keep_id: bool = False, + remove_substrings: Optional[list[str]] = None, + remove_regex: Optional[str] = None, + unicode_normalization: Optional[Literal["NFC", "NFKC", "NFD", + "NFKD"]] = None, + ascii_only: bool = False) +``` + +Initialize DocumentCleaner. + +**Arguments**: + +- `remove_empty_lines`: If `True`, removes empty lines. +- `remove_extra_whitespaces`: If `True`, removes extra whitespaces. +- `remove_repeated_substrings`: If `True`, removes repeated substrings (headers and footers) from pages. +Pages must be separated by a form feed character "\f", +which is supported by `TextFileToDocument` and `AzureOCRDocumentConverter`. +- `remove_substrings`: List of substrings to remove from the text. +- `remove_regex`: Regex to match and replace substrings by "". +- `keep_id`: If `True`, keeps the IDs of the original documents. +- `unicode_normalization`: Unicode normalization form to apply to the text. +Note: This will run before any other steps. +- `ascii_only`: Whether to convert the text to ASCII only. +Will remove accents from characters and replace them with ASCII characters. +Other non-ASCII characters will be removed. +Note: This will run before any pattern matching or removal. + + + +#### DocumentCleaner.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Cleans up the documents. + +**Arguments**: + +- `documents`: List of Documents to clean. + +**Raises**: + +- `TypeError`: if documents is not a list of Documents. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of cleaned Documents. + + + +## Module document\_preprocessor + + + +### DocumentPreprocessor + +A SuperComponent that first splits and then cleans documents. + +This component consists of a DocumentSplitter followed by a DocumentCleaner in a single pipeline. +It takes a list of documents as input and returns a processed list of documents. + +Usage example: +```python +from haystack import Document +from haystack.components.preprocessors import DocumentPreprocessor + +doc = Document(content="I love pizza!") +preprocessor = DocumentPreprocessor() +result = preprocessor.run(documents=[doc]) +print(result["documents"]) +``` + + + +#### DocumentPreprocessor.\_\_init\_\_ + +```python +def __init__(*, + split_by: Literal["function", "page", "passage", "period", "word", + "line", "sentence"] = "word", + split_length: int = 250, + split_overlap: int = 0, + split_threshold: int = 0, + splitting_function: Optional[Callable[[str], list[str]]] = None, + respect_sentence_boundary: bool = False, + language: Language = "en", + use_split_rules: bool = True, + extend_abbreviations: bool = True, + remove_empty_lines: bool = True, + remove_extra_whitespaces: bool = True, + remove_repeated_substrings: bool = False, + keep_id: bool = False, + remove_substrings: Optional[list[str]] = None, + remove_regex: Optional[str] = None, + unicode_normalization: Optional[Literal["NFC", "NFKC", "NFD", + "NFKD"]] = None, + ascii_only: bool = False) -> None +``` + +Initialize a DocumentPreProcessor that first splits and then cleans documents. + +**Splitter Parameters**: + +**Arguments**: + +- `split_by`: The unit of splitting: "function", "page", "passage", "period", "word", "line", or "sentence". +- `split_length`: The maximum number of units (words, lines, pages, and so on) in each split. +- `split_overlap`: The number of overlapping units between consecutive splits. +- `split_threshold`: The minimum number of units per split. If a split is smaller than this, it's merged +with the previous split. +- `splitting_function`: A custom function for splitting if `split_by="function"`. +- `respect_sentence_boundary`: If `True`, splits by words but tries not to break inside a sentence. +- `language`: Language used by the sentence tokenizer if `split_by="sentence"` or +`respect_sentence_boundary=True`. +- `use_split_rules`: Whether to apply additional splitting heuristics for the sentence splitter. +- `extend_abbreviations`: Whether to extend the sentence splitter with curated abbreviations for certain +languages. + +**Cleaner Parameters**: +- `remove_empty_lines`: If `True`, removes empty lines. +- `remove_extra_whitespaces`: If `True`, removes extra whitespaces. +- `remove_repeated_substrings`: If `True`, removes repeated substrings like headers/footers across pages. +- `keep_id`: If `True`, keeps the original document IDs. +- `remove_substrings`: A list of strings to remove from the document content. +- `remove_regex`: A regex pattern whose matches will be removed from the document content. +- `unicode_normalization`: Unicode normalization form to apply to the text, for example `"NFC"`. +- `ascii_only`: If `True`, converts text to ASCII only. + + + +#### DocumentPreprocessor.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize SuperComponent to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### DocumentPreprocessor.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DocumentPreprocessor" +``` + +Deserializes the SuperComponent from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized SuperComponent. + + + +## Module document\_splitter + + + +### DocumentSplitter + +Splits long documents into smaller chunks. + +This is a common preprocessing step during indexing. It helps Embedders create meaningful semantic representations +and prevents exceeding language model context limits. + +The DocumentSplitter is compatible with the following DocumentStores: +- [Astra](https://docs.haystack.deepset.ai/docs/astradocumentstore) +- [Chroma](https://docs.haystack.deepset.ai/docs/chromadocumentstore) limited support, overlapping information is + not stored +- [Elasticsearch](https://docs.haystack.deepset.ai/docs/elasticsearch-document-store) +- [OpenSearch](https://docs.haystack.deepset.ai/docs/opensearch-document-store) +- [Pgvector](https://docs.haystack.deepset.ai/docs/pgvectordocumentstore) +- [Pinecone](https://docs.haystack.deepset.ai/docs/pinecone-document-store) limited support, overlapping + information is not stored +- [Qdrant](https://docs.haystack.deepset.ai/docs/qdrant-document-store) +- [Weaviate](https://docs.haystack.deepset.ai/docs/weaviatedocumentstore) + +### Usage example + +```python +from haystack import Document +from haystack.components.preprocessors import DocumentSplitter + +doc = Document(content="Moonlight shimmered softly, wolves howled nearby, night enveloped everything.") + +splitter = DocumentSplitter(split_by="word", split_length=3, split_overlap=0) +result = splitter.run(documents=[doc]) +``` + + + +#### DocumentSplitter.\_\_init\_\_ + +```python +def __init__(split_by: Literal["function", "page", "passage", "period", "word", + "line", "sentence"] = "word", + split_length: int = 200, + split_overlap: int = 0, + split_threshold: int = 0, + splitting_function: Optional[Callable[[str], list[str]]] = None, + respect_sentence_boundary: bool = False, + language: Language = "en", + use_split_rules: bool = True, + extend_abbreviations: bool = True, + *, + skip_empty_documents: bool = True) +``` + +Initialize DocumentSplitter. + +**Arguments**: + +- `split_by`: The unit for splitting your documents. Choose from: +- `word` for splitting by spaces (" ") +- `period` for splitting by periods (".") +- `page` for splitting by form feed ("\f") +- `passage` for splitting by double line breaks ("\n\n") +- `line` for splitting each line ("\n") +- `sentence` for splitting by NLTK sentence tokenizer +- `split_length`: The maximum number of units in each split. +- `split_overlap`: The number of overlapping units for each split. +- `split_threshold`: The minimum number of units per split. If a split has fewer units +than the threshold, it's attached to the previous split. +- `splitting_function`: Necessary when `split_by` is set to "function". +This is a function which must accept a single `str` as input and return a `list` of `str` as output, +representing the chunks after splitting. +- `respect_sentence_boundary`: Choose whether to respect sentence boundaries when splitting by "word". +If True, uses NLTK to detect sentence boundaries, ensuring splits occur only between sentences. +- `language`: Choose the language for the NLTK tokenizer. The default is English ("en"). +- `use_split_rules`: Choose whether to use additional split rules when splitting by `sentence`. +- `extend_abbreviations`: Choose whether to extend NLTK's PunktTokenizer abbreviations with a list +of curated abbreviations, if available. This is currently supported for English ("en") and German ("de"). +- `skip_empty_documents`: Choose whether to skip documents with empty content. Default is True. +Set to False when downstream components in the Pipeline (like LLMDocumentContentExtractor) can extract text +from non-textual documents. + + + +#### DocumentSplitter.warm\_up + +```python +def warm_up() +``` + +Warm up the DocumentSplitter by loading the sentence tokenizer. + + + +#### DocumentSplitter.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Split documents into smaller parts. + +Splits documents by the unit expressed in `split_by`, with a length of `split_length` +and an overlap of `split_overlap`. + +**Arguments**: + +- `documents`: The documents to split. + +**Raises**: + +- `TypeError`: if the input is not a list of Documents. +- `ValueError`: if the content of a document is None. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of documents with the split texts. Each document includes: +- A metadata field `source_id` to track the original document. +- A metadata field `page_number` to track the original page number. +- All other metadata copied from the original document. + + + +#### DocumentSplitter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + + + +#### DocumentSplitter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DocumentSplitter" +``` + +Deserializes the component from a dictionary. + + + +## Module hierarchical\_document\_splitter + + + +### HierarchicalDocumentSplitter + +Splits a documents into different block sizes building a hierarchical tree structure of blocks of different sizes. + +The root node of the tree is the original document, the leaf nodes are the smallest blocks. The blocks in between +are connected such that the smaller blocks are children of the parent-larger blocks. + +## Usage example +```python +from haystack import Document +from haystack.components.preprocessors import HierarchicalDocumentSplitter + +doc = Document(content="This is a simple test document") +splitter = HierarchicalDocumentSplitter(block_sizes={3, 2}, split_overlap=0, split_by="word") +splitter.run([doc]) +>> {'documents': [Document(id=3f7..., content: 'This is a simple test document', meta: {'block_size': 0, 'parent_id': None, 'children_ids': ['5ff..', '8dc..'], 'level': 0}), +>> Document(id=5ff.., content: 'This is a ', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['f19..', '52c..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}), +>> Document(id=8dc.., content: 'simple test document', meta: {'block_size': 3, 'parent_id': '3f7..', 'children_ids': ['39d..', 'e23..'], 'level': 1, 'source_id': '3f7..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 10}), +>> Document(id=f19.., content: 'This is ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}), +>> Document(id=52c.., content: 'a ', meta: {'block_size': 2, 'parent_id': '5ff..', 'children_ids': [], 'level': 2, 'source_id': '5ff..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 8}), +>> Document(id=39d.., content: 'simple test ', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 0, 'split_idx_start': 0}), +>> Document(id=e23.., content: 'document', meta: {'block_size': 2, 'parent_id': '8dc..', 'children_ids': [], 'level': 2, 'source_id': '8dc..', 'page_number': 1, 'split_id': 1, 'split_idx_start': 12})]} +``` + + + +#### HierarchicalDocumentSplitter.\_\_init\_\_ + +```python +def __init__(block_sizes: set[int], + split_overlap: int = 0, + split_by: Literal["word", "sentence", "page", + "passage"] = "word") +``` + +Initialize HierarchicalDocumentSplitter. + +**Arguments**: + +- `block_sizes`: Set of block sizes to split the document into. The blocks are split in descending order. +- `split_overlap`: The number of overlapping units for each split. +- `split_by`: The unit for splitting your documents. + + + +#### HierarchicalDocumentSplitter.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Builds a hierarchical document structure for each document in a list of documents. + +**Arguments**: + +- `documents`: List of Documents to split into hierarchical blocks. + +**Returns**: + +List of HierarchicalDocument + + + +#### HierarchicalDocumentSplitter.build\_hierarchy\_from\_doc + +```python +def build_hierarchy_from_doc(document: Document) -> list[Document] +``` + +Build a hierarchical tree document structure from a single document. + +Given a document, this function splits the document into hierarchical blocks of different sizes represented +as HierarchicalDocument objects. + +**Arguments**: + +- `document`: Document to split into hierarchical blocks. + +**Returns**: + +List of HierarchicalDocument + + + +#### HierarchicalDocumentSplitter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Returns a dictionary representation of the component. + +**Returns**: + +Serialized dictionary representation of the component. + + + +#### HierarchicalDocumentSplitter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HierarchicalDocumentSplitter" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize and create the component. + +**Returns**: + +The deserialized component. + + + +## Module recursive\_splitter + + + +### RecursiveDocumentSplitter + +Recursively chunk text into smaller chunks. + +This component is used to split text into smaller chunks, it does so by recursively applying a list of separators +to the text. + +The separators are applied in the order they are provided, typically this is a list of separators that are +applied in a specific order, being the last separator the most specific one. + +Each separator is applied to the text, it then checks each of the resulting chunks, it keeps the chunks that +are within the split_length, for the ones that are larger than the split_length, it applies the next separator in the +list to the remaining text. + +This is done until all chunks are smaller than the split_length parameter. + +**Example**: + + +```python +from haystack import Document +from haystack.components.preprocessors import RecursiveDocumentSplitter + +chunker = RecursiveDocumentSplitter(split_length=260, split_overlap=0, separators=["\n\n", "\n", ".", " "]) +text = ('''Artificial intelligence (AI) - Introduction + +AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems. +AI technology is widely used throughout industry, government, and science. Some high-profile applications include advanced web search engines; recommendation systems; interacting via human speech; autonomous vehicles; generative and creative tools; and superhuman play and analysis in strategy games.''') +chunker.warm_up() +doc = Document(content=text) +doc_chunks = chunker.run([doc]) +print(doc_chunks["documents"]) +>[ +>Document(id=..., content: 'Artificial intelligence (AI) - Introduction\n\n', meta: {'original_id': '...', 'split_id': 0, 'split_idx_start': 0, '_split_overlap': []}) +>Document(id=..., content: 'AI, in its broadest sense, is intelligence exhibited by machines, particularly computer systems.\n', meta: {'original_id': '...', 'split_id': 1, 'split_idx_start': 45, '_split_overlap': []}) +>Document(id=..., content: 'AI technology is widely used throughout industry, government, and science.', meta: {'original_id': '...', 'split_id': 2, 'split_idx_start': 142, '_split_overlap': []}) +>Document(id=..., content: ' Some high-profile applications include advanced web search engines; recommendation systems; interac...', meta: {'original_id': '...', 'split_id': 3, 'split_idx_start': 216, '_split_overlap': []}) +>] +``` + + + +#### RecursiveDocumentSplitter.\_\_init\_\_ + +```python +def __init__(*, + split_length: int = 200, + split_overlap: int = 0, + split_unit: Literal["word", "char", "token"] = "word", + separators: Optional[list[str]] = None, + sentence_splitter_params: Optional[dict[str, Any]] = None) +``` + +Initializes a RecursiveDocumentSplitter. + +**Arguments**: + +- `split_length`: The maximum length of each chunk by default in words, but can be in characters or tokens. +See the `split_units` parameter. +- `split_overlap`: The number of characters to overlap between consecutive chunks. +- `split_unit`: The unit of the split_length parameter. It can be either "word", "char", or "token". +If "token" is selected, the text will be split into tokens using the tiktoken tokenizer (o200k_base). +- `separators`: An optional list of separator strings to use for splitting the text. The string +separators will be treated as regular expressions unless the separator is "sentence", in that case the +text will be split into sentences using a custom sentence tokenizer based on NLTK. +See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter. +If no separators are provided, the default separators ["\n\n", "sentence", "\n", " "] are used. +- `sentence_splitter_params`: Optional parameters to pass to the sentence tokenizer. +See: haystack.components.preprocessors.sentence_tokenizer.SentenceSplitter for more information. + +**Raises**: + +- `ValueError`: If the overlap is greater than or equal to the chunk size or if the overlap is negative, or +if any separator is not a string. + + + +#### RecursiveDocumentSplitter.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the sentence tokenizer and tiktoken tokenizer if needed. + + + +#### RecursiveDocumentSplitter.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Split a list of documents into documents with smaller chunks of text. + +**Arguments**: + +- `documents`: List of Documents to split. + +**Raises**: + +- `RuntimeError`: If the component wasn't warmed up but requires it for sentence splitting or tokenization. + +**Returns**: + +A dictionary containing a key "documents" with a List of Documents with smaller chunks of text corresponding +to the input documents. + + + +## Module text\_cleaner + + + +### TextCleaner + +Cleans text strings. + +It can remove substrings matching a list of regular expressions, convert text to lowercase, +remove punctuation, and remove numbers. +Use it to clean up text data before evaluation. + +### Usage example + +```python +from haystack.components.preprocessors import TextCleaner + +text_to_clean = "1Moonlight shimmered softly, 300 Wolves howled nearby, Night enveloped everything." + +cleaner = TextCleaner(convert_to_lowercase=True, remove_punctuation=False, remove_numbers=True) +result = cleaner.run(texts=[text_to_clean]) +``` + + + +#### TextCleaner.\_\_init\_\_ + +```python +def __init__(remove_regexps: Optional[list[str]] = None, + convert_to_lowercase: bool = False, + remove_punctuation: bool = False, + remove_numbers: bool = False) +``` + +Initializes the TextCleaner component. + +**Arguments**: + +- `remove_regexps`: A list of regex patterns to remove matching substrings from the text. +- `convert_to_lowercase`: If `True`, converts all characters to lowercase. +- `remove_punctuation`: If `True`, removes punctuation from the text. +- `remove_numbers`: If `True`, removes numerical digits from the text. + + + +#### TextCleaner.run + +```python +@component.output_types(texts=list[str]) +def run(texts: list[str]) -> dict[str, Any] +``` + +Cleans up the given list of strings. + +**Arguments**: + +- `texts`: List of strings to clean. + +**Returns**: + +A dictionary with the following key: +- `texts`: the cleaned list of strings. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/rankers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/rankers_api.md new file mode 100644 index 0000000000..a31e64d762 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/rankers_api.md @@ -0,0 +1,1087 @@ +--- +title: "Rankers" +id: rankers-api +description: "Reorders a set of Documents based on their relevance to the query." +slug: "/rankers-api" +--- + + + +## Module hugging\_face\_tei + + + +### TruncationDirection + +Defines the direction to truncate text when input length exceeds the model's limit. + +**Attributes**: + +- `LEFT` - Truncate text from the left side (start of text). +- `RIGHT` - Truncate text from the right side (end of text). + + + +### HuggingFaceTEIRanker + +Ranks documents based on their semantic similarity to the query. + +It can be used with a Text Embeddings Inference (TEI) API endpoint: +- [Self-hosted Text Embeddings Inference](https://github.com/huggingface/text-embeddings-inference) +- [Hugging Face Inference Endpoints](https://huggingface.co/inference-endpoints) + +Usage example: +```python +from haystack import Document +from haystack.components.rankers import HuggingFaceTEIRanker +from haystack.utils import Secret + +reranker = HuggingFaceTEIRanker( + url="http://localhost:8080", + top_k=5, + timeout=30, + token=Secret.from_token("my_api_token") +) + +docs = [Document(content="The capital of France is Paris"), Document(content="The capital of Germany is Berlin")] + +result = reranker.run(query="What is the capital of France?", documents=docs) + +ranked_docs = result["documents"] +print(ranked_docs) +>> {'documents': [Document(id=..., content: 'the capital of France is Paris', score: 0.9979767), +>> Document(id=..., content: 'the capital of Germany is Berlin', score: 0.13982213)]} +``` + + + +#### HuggingFaceTEIRanker.\_\_init\_\_ + +```python +def __init__( + *, + url: str, + top_k: int = 10, + raw_scores: bool = False, + timeout: Optional[int] = 30, + max_retries: int = 3, + retry_status_codes: Optional[list[int]] = None, + token: Optional[Secret] = Secret.from_env_var(["HF_API_TOKEN", "HF_TOKEN"], + strict=False) +) -> None +``` + +Initializes the TEI reranker component. + +**Arguments**: + +- `url`: Base URL of the TEI reranking service (for example, "https://api.example.com"). +- `top_k`: Maximum number of top documents to return. +- `raw_scores`: If True, include raw relevance scores in the API payload. +- `timeout`: Request timeout in seconds. +- `max_retries`: Maximum number of retry attempts for failed requests. +- `retry_status_codes`: List of HTTP status codes that will trigger a retry. +When None, HTTP 408, 418, 429 and 503 will be retried (default: None). +- `token`: The Hugging Face token to use as HTTP bearer authorization. Not always required +depending on your TEI server configuration. +Check your HF token in your [account settings](https://huggingface.co/settings/tokens). + + + +#### HuggingFaceTEIRanker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### HuggingFaceTEIRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "HuggingFaceTEIRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### HuggingFaceTEIRanker.run + +```python +@component.output_types(documents=list[Document]) +def run( + query: str, + documents: list[Document], + top_k: Optional[int] = None, + truncation_direction: Optional[TruncationDirection] = None +) -> dict[str, list[Document]] +``` + +Reranks the provided documents by relevance to the query using the TEI API. + +**Arguments**: + +- `query`: The user query string to guide reranking. +- `documents`: List of `Document` objects to rerank. +- `top_k`: Optional override for the maximum number of documents to return. +- `truncation_direction`: If set, enables text truncation in the specified direction. + +**Raises**: + +- `requests.exceptions.RequestException`: - If the API request fails. +- `RuntimeError`: - If the API returns an error response. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of reranked documents. + + + +#### HuggingFaceTEIRanker.run\_async + +```python +@component.output_types(documents=list[Document]) +async def run_async( + query: str, + documents: list[Document], + top_k: Optional[int] = None, + truncation_direction: Optional[TruncationDirection] = None +) -> dict[str, list[Document]] +``` + +Asynchronously reranks the provided documents by relevance to the query using the TEI API. + +**Arguments**: + +- `query`: The user query string to guide reranking. +- `documents`: List of `Document` objects to rerank. +- `top_k`: Optional override for the maximum number of documents to return. +- `truncation_direction`: If set, enables text truncation in the specified direction. + +**Raises**: + +- `httpx.RequestError`: - If the API request fails. +- `RuntimeError`: - If the API returns an error response. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of reranked documents. + + + +## Module lost\_in\_the\_middle + + + +### LostInTheMiddleRanker + +A LostInTheMiddle Ranker. + +Ranks documents based on the 'lost in the middle' order so that the most relevant documents are either at the +beginning or end, while the least relevant are in the middle. + +LostInTheMiddleRanker assumes that some prior component in the pipeline has already ranked documents by relevance +and requires no query as input but only documents. It is typically used as the last component before building a +prompt for an LLM to prepare the input context for the LLM. + +Lost in the Middle ranking lays out document contents into LLM context so that the most relevant contents are at +the beginning or end of the input context, while the least relevant is in the middle of the context. See the +paper ["Lost in the Middle: How Language Models Use Long Contexts"](https://arxiv.org/abs/2307.03172) for more +details. + +Usage example: +```python +from haystack.components.rankers import LostInTheMiddleRanker +from haystack import Document + +ranker = LostInTheMiddleRanker() +docs = [Document(content="Paris"), Document(content="Berlin"), Document(content="Madrid")] +result = ranker.run(documents=docs) +for doc in result["documents"]: + print(doc.content) +``` + + + +#### LostInTheMiddleRanker.\_\_init\_\_ + +```python +def __init__(word_count_threshold: Optional[int] = None, + top_k: Optional[int] = None) +``` + +Initialize the LostInTheMiddleRanker. + +If 'word_count_threshold' is specified, this ranker includes all documents up until the point where adding +another document would exceed the 'word_count_threshold'. The last document that causes the threshold to +be breached will be included in the resulting list of documents, but all subsequent documents will be +discarded. + +**Arguments**: + +- `word_count_threshold`: The maximum total number of words across all documents selected by the ranker. +- `top_k`: The maximum number of documents to return. + + + +#### LostInTheMiddleRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document], + top_k: Optional[int] = None, + word_count_threshold: Optional[int] = None + ) -> dict[str, list[Document]] +``` + +Reranks documents based on the "lost in the middle" order. + +**Arguments**: + +- `documents`: List of Documents to reorder. +- `top_k`: The maximum number of documents to return. +- `word_count_threshold`: The maximum total number of words across all documents selected by the ranker. + +**Raises**: + +- `ValueError`: If any of the documents is not textual. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Reranked list of Documents + + + +## Module meta\_field + + + +### MetaFieldRanker + +Ranks Documents based on the value of their specific meta field. + +The ranking can be performed in descending order or ascending order. + +Usage example: + +```python +from haystack import Document +from haystack.components.rankers import MetaFieldRanker + +ranker = MetaFieldRanker(meta_field="rating") +docs = [ + Document(content="Paris", meta={"rating": 1.3}), + Document(content="Berlin", meta={"rating": 0.7}), + Document(content="Barcelona", meta={"rating": 2.1}), +] + +output = ranker.run(documents=docs) +docs = output["documents"] +assert docs[0].content == "Barcelona" +``` + + + +#### MetaFieldRanker.\_\_init\_\_ + +```python +def __init__(meta_field: str, + weight: float = 1.0, + top_k: Optional[int] = None, + ranking_mode: Literal["reciprocal_rank_fusion", + "linear_score"] = "reciprocal_rank_fusion", + sort_order: Literal["ascending", "descending"] = "descending", + missing_meta: Literal["drop", "top", "bottom"] = "bottom", + meta_value_type: Optional[Literal["float", "int", + "date"]] = None) +``` + +Creates an instance of MetaFieldRanker. + +**Arguments**: + +- `meta_field`: The name of the meta field to rank by. +- `weight`: In range [0,1]. +0 disables ranking by a meta field. +0.5 ranking from previous component and based on meta field have the same weight. +1 ranking by a meta field only. +- `top_k`: The maximum number of Documents to return per query. +If not provided, the Ranker returns all documents it receives in the new ranking order. +- `ranking_mode`: The mode used to combine the Retriever's and Ranker's scores. +Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'. +Use the 'linear_score' mode only with Retrievers or Rankers that return a score in range [0,1]. +- `sort_order`: Whether to sort the meta field by ascending or descending order. +Possible values are `descending` (default) and `ascending`. +- `missing_meta`: What to do with documents that are missing the sorting metadata field. +Possible values are: +- 'drop' will drop the documents entirely. +- 'top' will place the documents at the top of the metadata-sorted list + (regardless of 'ascending' or 'descending'). +- 'bottom' will place the documents at the bottom of metadata-sorted list + (regardless of 'ascending' or 'descending'). +- `meta_value_type`: Parse the meta value into the data type specified before sorting. +This will only work if all meta values stored under `meta_field` in the provided documents are strings. +For example, if we specified `meta_value_type="date"` then for the meta value `"date": "2015-02-01"` +we would parse the string into a datetime object and then sort the documents by date. +The available options are: +- 'float' will parse the meta values into floats. +- 'int' will parse the meta values into integers. +- 'date' will parse the meta values into datetime objects. +- 'None' (default) will do no parsing. + + + +#### MetaFieldRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document], + top_k: Optional[int] = None, + weight: Optional[float] = None, + ranking_mode: Optional[Literal["reciprocal_rank_fusion", + "linear_score"]] = None, + sort_order: Optional[Literal["ascending", "descending"]] = None, + missing_meta: Optional[Literal["drop", "top", "bottom"]] = None, + meta_value_type: Optional[Literal["float", "int", "date"]] = None) +``` + +Ranks a list of Documents based on the selected meta field by: + +1. Sorting the Documents by the meta field in descending or ascending order. +2. Merging the rankings from the previous component and based on the meta field according to ranking mode and +weight. +3. Returning the top-k documents. + +**Arguments**: + +- `documents`: Documents to be ranked. +- `top_k`: The maximum number of Documents to return per query. +If not provided, the top_k provided at initialization time is used. +- `weight`: In range [0,1]. +0 disables ranking by a meta field. +0.5 ranking from previous component and based on meta field have the same weight. +1 ranking by a meta field only. +If not provided, the weight provided at initialization time is used. +- `ranking_mode`: (optional) The mode used to combine the Retriever's and Ranker's scores. +Possible values are 'reciprocal_rank_fusion' (default) and 'linear_score'. +Use the 'score' mode only with Retrievers or Rankers that return a score in range [0,1]. +If not provided, the ranking_mode provided at initialization time is used. +- `sort_order`: Whether to sort the meta field by ascending or descending order. +Possible values are `descending` (default) and `ascending`. +If not provided, the sort_order provided at initialization time is used. +- `missing_meta`: What to do with documents that are missing the sorting metadata field. +Possible values are: +- 'drop' will drop the documents entirely. +- 'top' will place the documents at the top of the metadata-sorted list + (regardless of 'ascending' or 'descending'). +- 'bottom' will place the documents at the bottom of metadata-sorted list + (regardless of 'ascending' or 'descending'). +If not provided, the missing_meta provided at initialization time is used. +- `meta_value_type`: Parse the meta value into the data type specified before sorting. +This will only work if all meta values stored under `meta_field` in the provided documents are strings. +For example, if we specified `meta_value_type="date"` then for the meta value `"date": "2015-02-01"` +we would parse the string into a datetime object and then sort the documents by date. +The available options are: +-'float' will parse the meta values into floats. +-'int' will parse the meta values into integers. +-'date' will parse the meta values into datetime objects. +-'None' (default) will do no parsing. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. +If `weight` is not in range [0,1]. +If `ranking_mode` is not 'reciprocal_rank_fusion' or 'linear_score'. +If `sort_order` is not 'ascending' or 'descending'. +If `meta_value_type` is not 'float', 'int', 'date' or `None`. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents sorted by the specified meta field. + + + +## Module meta\_field\_grouping\_ranker + + + +### MetaFieldGroupingRanker + +Reorders the documents by grouping them based on metadata keys. + +The MetaFieldGroupingRanker can group documents by a primary metadata key `group_by`, and subgroup them with an optional +secondary key, `subgroup_by`. +Within each group or subgroup, it can also sort documents by a metadata key `sort_docs_by`. + +The output is a flat list of documents ordered by `group_by` and `subgroup_by` values. +Any documents without a group are placed at the end of the list. + +The proper organization of documents helps improve the efficiency and performance of subsequent processing by an LLM. + +### Usage example + +```python +from haystack.components.rankers import MetaFieldGroupingRanker +from haystack.dataclasses import Document + + +docs = [ + Document(content="Javascript is a popular programming language", meta={"group": "42", "split_id": 7, "subgroup": "subB"}), + Document(content="Python is a popular programming language",meta={"group": "42", "split_id": 4, "subgroup": "subB"}), + Document(content="A chromosome is a package of DNA", meta={"group": "314", "split_id": 2, "subgroup": "subC"}), + Document(content="An octopus has three hearts", meta={"group": "11", "split_id": 2, "subgroup": "subD"}), + Document(content="Java is a popular programming language", meta={"group": "42", "split_id": 3, "subgroup": "subB"}) +] + +ranker = MetaFieldGroupingRanker(group_by="group",subgroup_by="subgroup", sort_docs_by="split_id") +result = ranker.run(documents=docs) +print(result["documents"]) + +# [ +# Document(id=d665bbc83e52c08c3d8275bccf4f22bf2bfee21c6e77d78794627637355b8ebc, +# content: 'Java is a popular programming language', meta: {'group': '42', 'split_id': 3, 'subgroup': 'subB'}), +# Document(id=a20b326f07382b3cbf2ce156092f7c93e8788df5d48f2986957dce2adb5fe3c2, +# content: 'Python is a popular programming language', meta: {'group': '42', 'split_id': 4, 'subgroup': 'subB'}), +# Document(id=ce12919795d22f6ca214d0f161cf870993889dcb146f3bb1b3e1ffdc95be960f, +# content: 'Javascript is a popular programming language', meta: {'group': '42', 'split_id': 7, 'subgroup': 'subB'}), +# Document(id=d9fc857046c904e5cf790b3969b971b1bbdb1b3037d50a20728fdbf82991aa94, +# content: 'A chromosome is a package of DNA', meta: {'group': '314', 'split_id': 2, 'subgroup': 'subC'}), +# Document(id=6d3b7bdc13d09aa01216471eb5fb0bfdc53c5f2f3e98ad125ff6b85d3106c9a3, +# content: 'An octopus has three hearts', meta: {'group': '11', 'split_id': 2, 'subgroup': 'subD'}) +# ] +``` + + + +#### MetaFieldGroupingRanker.\_\_init\_\_ + +```python +def __init__(group_by: str, + subgroup_by: Optional[str] = None, + sort_docs_by: Optional[str] = None) +``` + +Creates an instance of MetaFieldGroupingRanker. + +**Arguments**: + +- `group_by`: The metadata key to aggregate the documents by. +- `subgroup_by`: The metadata key to aggregate the documents within a group that was created by the +`group_by` key. +- `sort_docs_by`: Determines which metadata key is used to sort the documents. If not provided, the +documents within the groups or subgroups are not sorted and are kept in the same order as +they were inserted in the subgroups. + + + +#### MetaFieldGroupingRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, Any] +``` + +Groups the provided list of documents based on the `group_by` parameter and optionally the `subgroup_by`. + +The output is a list of documents reordered based on how they were grouped. + +**Arguments**: + +- `documents`: The list of documents to group. + +**Returns**: + +A dictionary with the following keys: +- documents: The list of documents ordered by the `group_by` and `subgroup_by` metadata values. + + + +## Module sentence\_transformers\_diversity + + + +### DiversityRankingStrategy + +The strategy to use for diversity ranking. + + + +#### DiversityRankingStrategy.\_\_str\_\_ + +```python +def __str__() -> str +``` + +Convert a Strategy enum to a string. + + + +#### DiversityRankingStrategy.from\_str + +```python +@staticmethod +def from_str(string: str) -> "DiversityRankingStrategy" +``` + +Convert a string to a Strategy enum. + + + +### DiversityRankingSimilarity + +The similarity metric to use for comparing embeddings. + + + +#### DiversityRankingSimilarity.\_\_str\_\_ + +```python +def __str__() -> str +``` + +Convert a Similarity enum to a string. + + + +#### DiversityRankingSimilarity.from\_str + +```python +@staticmethod +def from_str(string: str) -> "DiversityRankingSimilarity" +``` + +Convert a string to a Similarity enum. + + + +### SentenceTransformersDiversityRanker + +A Diversity Ranker based on Sentence Transformers. + +Applies a document ranking algorithm based on one of the two strategies: + +1. Greedy Diversity Order: + + Implements a document ranking algorithm that orders documents in a way that maximizes the overall diversity + of the documents based on their similarity to the query. + + It uses a pre-trained Sentence Transformers model to embed the query and + the documents. + +2. Maximum Margin Relevance: + + Implements a document ranking algorithm that orders documents based on their Maximum Margin Relevance (MMR) + scores. + + MMR scores are calculated for each document based on their relevance to the query and diversity from already + selected documents. The algorithm iteratively selects documents based on their MMR scores, balancing between + relevance to the query and diversity from already selected documents. The 'lambda_threshold' controls the + trade-off between relevance and diversity. + +### Usage example +```python +from haystack import Document +from haystack.components.rankers import SentenceTransformersDiversityRanker + +ranker = SentenceTransformersDiversityRanker(model="sentence-transformers/all-MiniLM-L6-v2", similarity="cosine", strategy="greedy_diversity_order") +ranker.warm_up() + +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "What is the capital of germany?" +output = ranker.run(query=query, documents=docs) +docs = output["documents"] +``` + + + +#### SentenceTransformersDiversityRanker.\_\_init\_\_ + +```python +def __init__( + model: str = "sentence-transformers/all-MiniLM-L6-v2", + top_k: int = 10, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + similarity: Union[str, DiversityRankingSimilarity] = "cosine", + query_prefix: str = "", + query_suffix: str = "", + document_prefix: str = "", + document_suffix: str = "", + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + strategy: Union[str, + DiversityRankingStrategy] = "greedy_diversity_order", + lambda_threshold: float = 0.5, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch") +``` + +Initialize a SentenceTransformersDiversityRanker. + +**Arguments**: + +- `model`: Local path or name of the model in Hugging Face's model hub, +such as `'sentence-transformers/all-MiniLM-L6-v2'`. +- `top_k`: The maximum number of Documents to return per query. +- `device`: The device on which the model is loaded. If `None`, the default device is automatically +selected. +- `token`: The API token used to download private models from Hugging Face. +- `similarity`: Similarity metric for comparing embeddings. Can be set to "dot_product" (default) or +"cosine". +- `query_prefix`: A string to add to the beginning of the query text before ranking. +Can be used to prepend the text with an instruction, as required by some embedding models, +such as E5 and BGE. +- `query_suffix`: A string to add to the end of the query text before ranking. +- `document_prefix`: A string to add to the beginning of each Document text before ranking. +Can be used to prepend the text with an instruction, as required by some embedding models, +such as E5 and BGE. +- `document_suffix`: A string to add to the end of each Document text before ranking. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document content. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document content. +- `strategy`: The strategy to use for diversity ranking. Can be either "greedy_diversity_order" or +"maximum_margin_relevance". +- `lambda_threshold`: The trade-off parameter between relevance and diversity. Only used when strategy is +"maximum_margin_relevance". +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. + + + +#### SentenceTransformersDiversityRanker.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### SentenceTransformersDiversityRanker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersDiversityRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, + Any]) -> "SentenceTransformersDiversityRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### SentenceTransformersDiversityRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(query: str, + documents: list[Document], + top_k: Optional[int] = None, + lambda_threshold: Optional[float] = None) -> dict[str, list[Document]] +``` + +Rank the documents based on their diversity. + +**Arguments**: + +- `query`: The search query. +- `documents`: List of Document objects to be ranker. +- `top_k`: Optional. An integer to override the top_k set during initialization. +- `lambda_threshold`: Override the trade-off parameter between relevance and diversity. Only used when +strategy is "maximum_margin_relevance". + +**Raises**: + +- `ValueError`: If the top_k value is less than or equal to 0. +- `RuntimeError`: If the component has not been warmed up. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of Document objects that have been selected based on the diversity ranking. + + + +## Module sentence\_transformers\_similarity + + + +### SentenceTransformersSimilarityRanker + +Ranks documents based on their semantic similarity to the query. + +It uses a pre-trained cross-encoder model from Hugging Face to embed the query and the documents. + +### Usage example + +```python +from haystack import Document +from haystack.components.rankers import SentenceTransformersSimilarityRanker + +ranker = SentenceTransformersSimilarityRanker() +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "City in Germany" +ranker.warm_up() +result = ranker.run(query=query, documents=docs) +docs = result["documents"] +print(docs[0].content) +``` + + + +#### SentenceTransformersSimilarityRanker.\_\_init\_\_ + +```python +def __init__(*, + model: Union[str, Path] = "cross-encoder/ms-marco-MiniLM-L-6-v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + top_k: int = 10, + query_prefix: str = "", + document_prefix: str = "", + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + scale_score: bool = True, + score_threshold: Optional[float] = None, + trust_remote_code: bool = False, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + config_kwargs: Optional[dict[str, Any]] = None, + backend: Literal["torch", "onnx", "openvino"] = "torch", + batch_size: int = 16) +``` + +Creates an instance of SentenceTransformersSimilarityRanker. + +**Arguments**: + +- `model`: The ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model. +- `device`: The device on which the model is loaded. If `None`, the default device is automatically selected. +- `token`: The API token to download private models from Hugging Face. +- `top_k`: The maximum number of documents to return per query. +- `query_prefix`: A string to add at the beginning of the query text before ranking. +Use it to prepend the text with an instruction, as required by reranking models like `bge`. +- `document_prefix`: A string to add at the beginning of each document before ranking. You can use it to prepend the document +with an instruction, as required by embedding models like `bge`. +- `meta_fields_to_embed`: List of metadata fields to embed with the document. +- `embedding_separator`: Separator to concatenate metadata fields to the document. +- `scale_score`: If `True`, scales the raw logit predictions using a Sigmoid activation function. +If `False`, disables scaling of the raw logit predictions. +- `score_threshold`: Use it to return documents with a score above this threshold only. +- `trust_remote_code`: If `False`, allows only Hugging Face verified model architectures. +If `True`, allows custom models and scripts. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `config_kwargs`: Additional keyword arguments for `AutoConfig.from_pretrained` when loading the model configuration. +- `backend`: The backend to use for the Sentence Transformers model. Choose from "torch", "onnx", or "openvino". +Refer to the [Sentence Transformers documentation](https://sbert.net/docs/sentence_transformer/usage/efficiency.html) +for more information on acceleration and quantization options. +- `batch_size`: The batch size to use for inference. The higher the batch size, the more memory is required. +If you run into memory issues, reduce the batch size. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + + + +#### SentenceTransformersSimilarityRanker.warm\_up + +```python +def warm_up() -> None +``` + +Initializes the component. + + + +#### SentenceTransformersSimilarityRanker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceTransformersSimilarityRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, + Any]) -> "SentenceTransformersSimilarityRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SentenceTransformersSimilarityRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(*, + query: str, + documents: list[Document], + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + score_threshold: Optional[float] = None) -> dict[str, list[Document]] +``` + +Returns a list of documents ranked by their similarity to the given query. + +**Arguments**: + +- `query`: The input query to compare the documents to. +- `documents`: A list of documents to be ranked. +- `top_k`: The maximum number of documents to return. +- `scale_score`: If `True`, scales the raw logit predictions using a Sigmoid activation function. +If `False`, disables scaling of the raw logit predictions. +If set, overrides the value set at initialization. +- `score_threshold`: Use it to return documents only with a score above this threshold. +If set, overrides the value set at initialization. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. +- `RuntimeError`: If the model is not loaded because `warm_up()` was not called before. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents closest to the query, sorted from most similar to least similar. + + + +## Module transformers\_similarity + + + +### TransformersSimilarityRanker + +Ranks documents based on their semantic similarity to the query. + +It uses a pre-trained cross-encoder model from Hugging Face to embed the query and the documents. + +**Notes**: + + This component is considered legacy and will no longer receive updates. It may be deprecated in a future release, + with removal following after a deprecation period. + Consider using SentenceTransformersSimilarityRanker instead, which provides the same functionality along with + additional features. + + ### Usage example + +```python +from haystack import Document +from haystack.components.rankers import TransformersSimilarityRanker + +ranker = TransformersSimilarityRanker() +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "City in Germany" +ranker.warm_up() +result = ranker.run(query=query, documents=docs) +docs = result["documents"] +print(docs[0].content) +``` + + + +#### TransformersSimilarityRanker.\_\_init\_\_ + +```python +def __init__(model: Union[str, Path] = "cross-encoder/ms-marco-MiniLM-L-6-v2", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + top_k: int = 10, + query_prefix: str = "", + document_prefix: str = "", + meta_fields_to_embed: Optional[list[str]] = None, + embedding_separator: str = "\n", + scale_score: bool = True, + calibration_factor: Optional[float] = 1.0, + score_threshold: Optional[float] = None, + model_kwargs: Optional[dict[str, Any]] = None, + tokenizer_kwargs: Optional[dict[str, Any]] = None, + batch_size: int = 16) +``` + +Creates an instance of TransformersSimilarityRanker. + +**Arguments**: + +- `model`: The ranking model. Pass a local path or the Hugging Face model name of a cross-encoder model. +- `device`: The device on which the model is loaded. If `None`, overrides the default device. +- `token`: The API token to download private models from Hugging Face. +- `top_k`: The maximum number of documents to return per query. +- `query_prefix`: A string to add at the beginning of the query text before ranking. +Use it to prepend the text with an instruction, as required by reranking models like `bge`. +- `document_prefix`: A string to add at the beginning of each document before ranking. You can use it to prepend the document +with an instruction, as required by embedding models like `bge`. +- `meta_fields_to_embed`: List of metadata fields to embed with the document. +- `embedding_separator`: Separator to concatenate metadata fields to the document. +- `scale_score`: If `True`, scales the raw logit predictions using a Sigmoid activation function. +If `False`, disables scaling of the raw logit predictions. +- `calibration_factor`: Use this factor to calibrate probabilities with `sigmoid(logits * calibration_factor)`. +Used only if `scale_score` is `True`. +- `score_threshold`: Use it to return documents with a score above this threshold only. +- `model_kwargs`: Additional keyword arguments for `AutoModelForSequenceClassification.from_pretrained` +when loading the model. Refer to specific model documentation for available kwargs. +- `tokenizer_kwargs`: Additional keyword arguments for `AutoTokenizer.from_pretrained` when loading the tokenizer. +Refer to specific model documentation for available kwargs. +- `batch_size`: The batch size to use for inference. The higher the batch size, the more memory is required. +If you run into memory issues, reduce the batch size. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. +If `scale_score` is True and `calibration_factor` is not provided. + + + +#### TransformersSimilarityRanker.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### TransformersSimilarityRanker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### TransformersSimilarityRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "TransformersSimilarityRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### TransformersSimilarityRanker.run + +```python +@component.output_types(documents=list[Document]) +def run(query: str, + documents: list[Document], + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + calibration_factor: Optional[float] = None, + score_threshold: Optional[float] = None) +``` + +Returns a list of documents ranked by their similarity to the given query. + +**Arguments**: + +- `query`: The input query to compare the documents to. +- `documents`: A list of documents to be ranked. +- `top_k`: The maximum number of documents to return. +- `scale_score`: If `True`, scales the raw logit predictions using a Sigmoid activation function. +If `False`, disables scaling of the raw logit predictions. +- `calibration_factor`: Use this factor to calibrate probabilities with `sigmoid(logits * calibration_factor)`. +Used only if `scale_score` is `True`. +- `score_threshold`: Use it to return documents only with a score above this threshold. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. +If `scale_score` is True and `calibration_factor` is not provided. +- `RuntimeError`: If the model is not loaded because `warm_up()` was not called before. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents closest to the query, sorted from most similar to least similar. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/readers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/readers_api.md new file mode 100644 index 0000000000..f0b95c014e --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/readers_api.md @@ -0,0 +1,210 @@ +--- +title: "Readers" +id: readers-api +description: "Takes a query and a set of Documents as input and returns ExtractedAnswers by selecting a text span within the Documents." +slug: "/readers-api" +--- + + + +## Module extractive + + + +### ExtractiveReader + +Locates and extracts answers to a given query from Documents. + +The ExtractiveReader component performs extractive question answering. +It assigns a score to every possible answer span independently of other answer spans. +This fixes a common issue of other implementations which make comparisons across documents harder by normalizing +each document's answers independently. + +Example usage: +```python +from haystack import Document +from haystack.components.readers import ExtractiveReader + +docs = [ + Document(content="Python is a popular programming language"), + Document(content="python ist eine beliebte Programmiersprache"), +] + +reader = ExtractiveReader() +reader.warm_up() + +question = "What is a popular programming language?" +result = reader.run(query=question, documents=docs) +assert "Python" in result["answers"][0].data +``` + + + +#### ExtractiveReader.\_\_init\_\_ + +```python +def __init__(model: Union[Path, str] = "deepset/roberta-base-squad2-distilled", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + top_k: int = 20, + score_threshold: Optional[float] = None, + max_seq_length: int = 384, + stride: int = 128, + max_batch_size: Optional[int] = None, + answers_per_seq: Optional[int] = None, + no_answer: bool = True, + calibration_factor: float = 0.1, + overlap_threshold: Optional[float] = 0.01, + model_kwargs: Optional[dict[str, Any]] = None) -> None +``` + +Creates an instance of ExtractiveReader. + +**Arguments**: + +- `model`: A Hugging Face transformers question answering model. +Can either be a path to a folder containing the model files or an identifier for the Hugging Face hub. +- `device`: The device on which the model is loaded. If `None`, the default device is automatically selected. +- `token`: The API token used to download private models from Hugging Face. +- `top_k`: Number of answers to return per query. It is required even if score_threshold is set. +An additional answer with no text is returned if no_answer is set to True (default). +- `score_threshold`: Returns only answers with the probability score above this threshold. +- `max_seq_length`: Maximum number of tokens. If a sequence exceeds it, the sequence is split. +- `stride`: Number of tokens that overlap when sequence is split because it exceeds max_seq_length. +- `max_batch_size`: Maximum number of samples that are fed through the model at the same time. +- `answers_per_seq`: Number of answer candidates to consider per sequence. +This is relevant when a Document was split into multiple sequences because of max_seq_length. +- `no_answer`: Whether to return an additional `no answer` with an empty text and a score representing the +probability that the other top_k answers are incorrect. +- `calibration_factor`: Factor used for calibrating probabilities. +- `overlap_threshold`: If set this will remove duplicate answers if they have an overlap larger than the +supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove +one of these answers since the second answer has a 100% (1.0) overlap with the first answer. +However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so +both of these answers could be kept if this variable is set to 0.24 or lower. +If None is provided then all answers are kept. +- `model_kwargs`: Additional keyword arguments passed to `AutoModelForQuestionAnswering.from_pretrained` +when loading the model specified in `model`. For details on what kwargs you can pass, +see the model's documentation. + + + +#### ExtractiveReader.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ExtractiveReader.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ExtractiveReader" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ExtractiveReader.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### ExtractiveReader.deduplicate\_by\_overlap + +```python +def deduplicate_by_overlap( + answers: list[ExtractedAnswer], + overlap_threshold: Optional[float]) -> list[ExtractedAnswer] +``` + +De-duplicates overlapping Extractive Answers. + +De-duplicates overlapping Extractive Answers from the same document based on how much the spans of the +answers overlap. + +**Arguments**: + +- `answers`: List of answers to be deduplicated. +- `overlap_threshold`: If set this will remove duplicate answers if they have an overlap larger than the +supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove +one of these answers since the second answer has a 100% (1.0) overlap with the first answer. +However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so +both of these answers could be kept if this variable is set to 0.24 or lower. +If None is provided then all answers are kept. + +**Returns**: + +List of deduplicated answers. + + + +#### ExtractiveReader.run + +```python +@component.output_types(answers=list[ExtractedAnswer]) +def run(query: str, + documents: list[Document], + top_k: Optional[int] = None, + score_threshold: Optional[float] = None, + max_seq_length: Optional[int] = None, + stride: Optional[int] = None, + max_batch_size: Optional[int] = None, + answers_per_seq: Optional[int] = None, + no_answer: Optional[bool] = None, + overlap_threshold: Optional[float] = None) +``` + +Locates and extracts answers from the given Documents using the given query. + +**Arguments**: + +- `query`: Query string. +- `documents`: List of Documents in which you want to search for an answer to the query. +- `top_k`: The maximum number of answers to return. +An additional answer is returned if no_answer is set to True (default). +- `score_threshold`: Returns only answers with the score above this threshold. +- `max_seq_length`: Maximum number of tokens. If a sequence exceeds it, the sequence is split. +- `stride`: Number of tokens that overlap when sequence is split because it exceeds max_seq_length. +- `max_batch_size`: Maximum number of samples that are fed through the model at the same time. +- `answers_per_seq`: Number of answer candidates to consider per sequence. +This is relevant when a Document was split into multiple sequences because of max_seq_length. +- `no_answer`: Whether to return no answer scores. +- `overlap_threshold`: If set this will remove duplicate answers if they have an overlap larger than the +supplied threshold. For example, for the answers "in the river in Maine" and "the river" we would remove +one of these answers since the second answer has a 100% (1.0) overlap with the first answer. +However, for the answers "the river in" and "in Maine" there is only a max overlap percentage of 25% so +both of these answers could be kept if this variable is set to 0.24 or lower. +If None is provided then all answers are kept. + +**Raises**: + +- `RuntimeError`: If the component was not warmed up by calling 'warm_up()' before. + +**Returns**: + +List of answers sorted by (desc.) answer score. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/retrievers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/retrievers_api.md new file mode 100644 index 0000000000..f8c68fd846 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/retrievers_api.md @@ -0,0 +1,781 @@ +--- +title: "Retrievers" +id: retrievers-api +description: "Sweeps through a Document Store and returns a set of candidate Documents that are relevant to the query." +slug: "/retrievers-api" +--- + + + +## Module auto\_merging\_retriever + + + +### AutoMergingRetriever + +A retriever which returns parent documents of the matched leaf nodes documents, based on a threshold setting. + +The AutoMergingRetriever assumes you have a hierarchical tree structure of documents, where the leaf nodes +are indexed in a document store. See the HierarchicalDocumentSplitter for more information on how to create +such a structure. During retrieval, if the number of matched leaf documents below the same parent is +higher than a defined threshold, the retriever will return the parent document instead of the individual leaf +documents. + +The rational is, given that a paragraph is split into multiple chunks represented as leaf documents, and if for +a given query, multiple chunks are matched, the whole paragraph might be more informative than the individual +chunks alone. + +Currently the AutoMergingRetriever can only be used by the following DocumentStores: +- [AstraDB](https://haystack.deepset.ai/integrations/astradb) +- [ElasticSearch](https://haystack.deepset.ai/docs/latest/documentstore/elasticsearch) +- [OpenSearch](https://haystack.deepset.ai/docs/latest/documentstore/opensearch) +- [PGVector](https://haystack.deepset.ai/docs/latest/documentstore/pgvector) +- [Qdrant](https://haystack.deepset.ai/docs/latest/documentstore/qdrant) + +```python +from haystack import Document +from haystack.components.preprocessors import HierarchicalDocumentSplitter +from haystack.components.retrievers.auto_merging_retriever import AutoMergingRetriever +from haystack.document_stores.in_memory import InMemoryDocumentStore + +# create a hierarchical document structure with 3 levels, where the parent document has 3 children +text = "The sun rose early in the morning. It cast a warm glow over the trees. Birds began to sing." +original_document = Document(content=text) +builder = HierarchicalDocumentSplitter(block_sizes=[10, 3], split_overlap=0, split_by="word") +docs = builder.run([original_document])["documents"] + +# store level-1 parent documents and initialize the retriever +doc_store_parents = InMemoryDocumentStore() +for doc in docs["documents"]: + if doc.meta["children_ids"] and doc.meta["level"] == 1: + doc_store_parents.write_documents([doc]) +retriever = AutoMergingRetriever(doc_store_parents, threshold=0.5) + +# assume we retrieved 2 leaf docs from the same parent, the parent document should be returned, +# since it has 3 children and the threshold=0.5, and we retrieved 2 children (2/3 > 0.66(6)) +leaf_docs = [doc for doc in docs["documents"] if not doc.meta["children_ids"]] +docs = retriever.run(leaf_docs[4:6]) +>> {'documents': [Document(id=538..), +>> content: 'warm glow over the trees. Birds began to sing.', +>> meta: {'block_size': 10, 'parent_id': '835..', 'children_ids': ['c17...', '3ff...', '352...'], 'level': 1, 'source_id': '835...', +>> 'page_number': 1, 'split_id': 1, 'split_idx_start': 45})]} +``` + + + +#### AutoMergingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: DocumentStore, threshold: float = 0.5) +``` + +Initialize the AutoMergingRetriever. + +**Arguments**: + +- `document_store`: DocumentStore from which to retrieve the parent documents +- `threshold`: Threshold to decide whether the parent instead of the individual documents is returned + + + +#### AutoMergingRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AutoMergingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "AutoMergingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +An instance of the component. + + + +#### AutoMergingRetriever.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) +``` + +Run the AutoMergingRetriever. + +Recursively groups documents by their parents and merges them if they meet the threshold, +continuing up the hierarchy until no more merges are possible. + +**Arguments**: + +- `documents`: List of leaf documents that were matched by a retriever + +**Returns**: + +List of documents (could be a mix of different hierarchy levels) + + + +## Module in\_memory/bm25\_retriever + + + +### InMemoryBM25Retriever + +Retrieves documents that are most similar to the query using keyword-based algorithm. + +Use this retriever with the InMemoryDocumentStore. + +### Usage example + +```python +from haystack import Document +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.document_stores.in_memory import InMemoryDocumentStore + +docs = [ + Document(content="Python is a popular programming language"), + Document(content="python ist eine beliebte Programmiersprache"), +] + +doc_store = InMemoryDocumentStore() +doc_store.write_documents(docs) +retriever = InMemoryBM25Retriever(doc_store) + +result = retriever.run(query="Programmiersprache") + +print(result["documents"]) +``` + + + +#### InMemoryBM25Retriever.\_\_init\_\_ + +```python +def __init__(document_store: InMemoryDocumentStore, + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False, + filter_policy: FilterPolicy = FilterPolicy.REPLACE) +``` + +Create the InMemoryBM25Retriever component. + +**Arguments**: + +- `document_store`: An instance of InMemoryDocumentStore where the retriever should search for relevant documents. +- `filters`: A dictionary with filters to narrow down the retriever's search space in the document store. +- `top_k`: The maximum number of documents to retrieve. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. +- `filter_policy`: The filter policy to apply during retrieval. +Filter policy determines how filters are applied when retrieving documents. You can choose: +- `REPLACE` (default): Overrides the initialization filters with the filters specified at runtime. +Use this policy to dynamically change filtering for specific queries. +- `MERGE`: Combines runtime filters with initialization filters to narrow down the search. + +**Raises**: + +- `ValueError`: If the specified `top_k` is not > 0. + + + +#### InMemoryBM25Retriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### InMemoryBM25Retriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "InMemoryBM25Retriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### InMemoryBM25Retriever.run + +```python +@component.output_types(documents=list[Document]) +def run(query: str, + filters: Optional[dict[str, Any]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None) +``` + +Run the InMemoryBM25Retriever on the given input data. + +**Arguments**: + +- `query`: The query string for the Retriever. +- `filters`: A dictionary with filters to narrow down the search space when retrieving documents. +- `top_k`: The maximum number of documents to return. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. + +**Raises**: + +- `ValueError`: If the specified DocumentStore is not found or is not a InMemoryDocumentStore instance. + +**Returns**: + +The retrieved documents. + + + +#### InMemoryBM25Retriever.run\_async + +```python +@component.output_types(documents=list[Document]) +async def run_async(query: str, + filters: Optional[dict[str, Any]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None) +``` + +Run the InMemoryBM25Retriever on the given input data. + +**Arguments**: + +- `query`: The query string for the Retriever. +- `filters`: A dictionary with filters to narrow down the search space when retrieving documents. +- `top_k`: The maximum number of documents to return. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. + +**Raises**: + +- `ValueError`: If the specified DocumentStore is not found or is not a InMemoryDocumentStore instance. + +**Returns**: + +The retrieved documents. + + + +## Module in\_memory/embedding\_retriever + + + +### InMemoryEmbeddingRetriever + +Retrieves documents that are most semantically similar to the query. + +Use this retriever with the InMemoryDocumentStore. + +When using this retriever, make sure it has query and document embeddings available. +In indexing pipelines, use a DocumentEmbedder to embed documents. +In query pipelines, use a TextEmbedder to embed queries and send them to the retriever. + +### Usage example +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersDocumentEmbedder, SentenceTransformersTextEmbedder +from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever +from haystack.document_stores.in_memory import InMemoryDocumentStore + +docs = [ + Document(content="Python is a popular programming language"), + Document(content="python ist eine beliebte Programmiersprache"), +] +doc_embedder = SentenceTransformersDocumentEmbedder() +doc_embedder.warm_up() +docs_with_embeddings = doc_embedder.run(docs)["documents"] + +doc_store = InMemoryDocumentStore() +doc_store.write_documents(docs_with_embeddings) +retriever = InMemoryEmbeddingRetriever(doc_store) + +query="Programmiersprache" +text_embedder = SentenceTransformersTextEmbedder() +text_embedder.warm_up() +query_embedding = text_embedder.run(query)["embedding"] + +result = retriever.run(query_embedding=query_embedding) + +print(result["documents"]) +``` + + + +#### InMemoryEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: InMemoryDocumentStore, + filters: Optional[dict[str, Any]] = None, + top_k: int = 10, + scale_score: bool = False, + return_embedding: bool = False, + filter_policy: FilterPolicy = FilterPolicy.REPLACE) +``` + +Create the InMemoryEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of InMemoryDocumentStore where the retriever should search for relevant documents. +- `filters`: A dictionary with filters to narrow down the retriever's search space in the document store. +- `top_k`: The maximum number of documents to retrieve. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. +- `return_embedding`: When `True`, returns the embedding of the retrieved documents. +When `False`, returns just the documents, without their embeddings. +- `filter_policy`: The filter policy to apply during retrieval. +Filter policy determines how filters are applied when retrieving documents. You can choose: +- `REPLACE` (default): Overrides the initialization filters with the filters specified at runtime. +Use this policy to dynamically change filtering for specific queries. +- `MERGE`: Combines runtime filters with initialization filters to narrow down the search. + +**Raises**: + +- `ValueError`: If the specified top_k is not > 0. + + + +#### InMemoryEmbeddingRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### InMemoryEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "InMemoryEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### InMemoryEmbeddingRetriever.run + +```python +@component.output_types(documents=list[Document]) +def run(query_embedding: list[float], + filters: Optional[dict[str, Any]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None) +``` + +Run the InMemoryEmbeddingRetriever on the given input data. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space when retrieving documents. +- `top_k`: The maximum number of documents to return. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. +- `return_embedding`: When `True`, returns the embedding of the retrieved documents. +When `False`, returns just the documents, without their embeddings. + +**Raises**: + +- `ValueError`: If the specified DocumentStore is not found or is not an InMemoryDocumentStore instance. + +**Returns**: + +The retrieved documents. + + + +#### InMemoryEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=list[Document]) +async def run_async(query_embedding: list[float], + filters: Optional[dict[str, Any]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None) +``` + +Run the InMemoryEmbeddingRetriever on the given input data. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space when retrieving documents. +- `top_k`: The maximum number of documents to return. +- `scale_score`: When `True`, scales the score of retrieved documents to a range of 0 to 1, where 1 means extremely relevant. +When `False`, uses raw similarity scores. +- `return_embedding`: When `True`, returns the embedding of the retrieved documents. +When `False`, returns just the documents, without their embeddings. + +**Raises**: + +- `ValueError`: If the specified DocumentStore is not found or is not an InMemoryDocumentStore instance. + +**Returns**: + +The retrieved documents. + + + +## Module filter\_retriever + + + +### FilterRetriever + +Retrieves documents that match the provided filters. + +### Usage example + +```python +from haystack import Document +from haystack.components.retrievers import FilterRetriever +from haystack.document_stores.in_memory import InMemoryDocumentStore + +docs = [ + Document(content="Python is a popular programming language", meta={"lang": "en"}), + Document(content="python ist eine beliebte Programmiersprache", meta={"lang": "de"}), +] + +doc_store = InMemoryDocumentStore() +doc_store.write_documents(docs) +retriever = FilterRetriever(doc_store, filters={"field": "lang", "operator": "==", "value": "en"}) + +# if passed in the run method, filters override those provided at initialization +result = retriever.run(filters={"field": "lang", "operator": "==", "value": "de"}) + +print(result["documents"]) +``` + + + +#### FilterRetriever.\_\_init\_\_ + +```python +def __init__(document_store: DocumentStore, + filters: Optional[dict[str, Any]] = None) +``` + +Create the FilterRetriever component. + +**Arguments**: + +- `document_store`: An instance of a Document Store to use with the Retriever. +- `filters`: A dictionary with filters to narrow down the search space. + + + +#### FilterRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FilterRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "FilterRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### FilterRetriever.run + +```python +@component.output_types(documents=list[Document]) +def run(filters: Optional[dict[str, Any]] = None) +``` + +Run the FilterRetriever on the given input data. + +**Arguments**: + +- `filters`: A dictionary with filters to narrow down the search space. +If not specified, the FilterRetriever uses the values provided at initialization. + +**Returns**: + +A list of retrieved documents. + + + +## Module sentence\_window\_retriever + + + +### SentenceWindowRetriever + +Retrieves neighboring documents from a DocumentStore to provide context for query results. + +This component is intended to be used after a Retriever (e.g., BM25Retriever, EmbeddingRetriever). +It enhances retrieved results by fetching adjacent document chunks to give +additional context for the user. + +The documents must include metadata indicating their origin and position: +- `source_id` is used to group sentence chunks belonging to the same original document. +- `split_id` represents the position/order of the chunk within the document. + +The number of adjacent documents to include on each side of the retrieved document can be configured using the +`window_size` parameter. You can also specify which metadata fields to use for source and split ID +via `source_id_meta_field` and `split_id_meta_field`. + +The SentenceWindowRetriever is compatible with the following DocumentStores: +- [Astra](https://docs.haystack.deepset.ai/docs/astradocumentstore) +- [Elasticsearch](https://docs.haystack.deepset.ai/docs/elasticsearch-document-store) +- [OpenSearch](https://docs.haystack.deepset.ai/docs/opensearch-document-store) +- [Pgvector](https://docs.haystack.deepset.ai/docs/pgvectordocumentstore) +- [Pinecone](https://docs.haystack.deepset.ai/docs/pinecone-document-store) +- [Qdrant](https://docs.haystack.deepset.ai/docs/qdrant-document-store) + +### Usage example + +```python +from haystack import Document, Pipeline +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever +from haystack.components.retrievers import SentenceWindowRetriever +from haystack.components.preprocessors import DocumentSplitter +from haystack.document_stores.in_memory import InMemoryDocumentStore + +splitter = DocumentSplitter(split_length=10, split_overlap=5, split_by="word") +text = ( + "This is a text with some words. There is a second sentence. And there is also a third sentence. " + "It also contains a fourth sentence. And a fifth sentence. And a sixth sentence. And a seventh sentence" +) +doc = Document(content=text) +docs = splitter.run([doc]) +doc_store = InMemoryDocumentStore() +doc_store.write_documents(docs["documents"]) + + +rag = Pipeline() +rag.add_component("bm25_retriever", InMemoryBM25Retriever(doc_store, top_k=1)) +rag.add_component("sentence_window_retriever", SentenceWindowRetriever(document_store=doc_store, window_size=2)) +rag.connect("bm25_retriever", "sentence_window_retriever") + +rag.run({'bm25_retriever': {"query":"third"}}) + +>> {'sentence_window_retriever': {'context_windows': ['some words. There is a second sentence. +>> And there is also a third sentence. It also contains a fourth sentence. And a fifth sentence. And a sixth +>> sentence. And a'], 'context_documents': [[Document(id=..., content: 'some words. There is a second sentence. +>> And there is ', meta: {'source_id': '...', 'page_number': 1, 'split_id': 1, 'split_idx_start': 20, +>> '_split_overlap': [{'doc_id': '...', 'range': (20, 43)}, {'doc_id': '...', 'range': (0, 30)}]}), +>> Document(id=..., content: 'second sentence. And there is also a third sentence. It ', +>> meta: {'source_id': '74ea87deb38012873cf8c07e...f19d01a26a098447113e1d7b83efd30c02987114', 'page_number': 1, +>> 'split_id': 2, 'split_idx_start': 43, '_split_overlap': [{'doc_id': '...', 'range': (23, 53)}, {'doc_id': '...', +>> 'range': (0, 26)}]}), Document(id=..., content: 'also a third sentence. It also contains a fourth sentence. ', +>> meta: {'source_id': '...', 'page_number': 1, 'split_id': 3, 'split_idx_start': 73, '_split_overlap': +>> [{'doc_id': '...', 'range': (30, 56)}, {'doc_id': '...', 'range': (0, 33)}]}), Document(id=..., content: +>> 'also contains a fourth sentence. And a fifth sentence. And ', meta: {'source_id': '...', 'page_number': 1, +>> 'split_id': 4, 'split_idx_start': 99, '_split_overlap': [{'doc_id': '...', 'range': (26, 59)}, +>> {'doc_id': '...', 'range': (0, 26)}]}), Document(id=..., content: 'And a fifth sentence. And a sixth sentence. +>> And a ', meta: {'source_id': '...', 'page_number': 1, 'split_id': 5, 'split_idx_start': 132, +>> '_split_overlap': [{'doc_id': '...', 'range': (33, 59)}, {'doc_id': '...', 'range': (0, 24)}]})]]}}}} +``` + + + +#### SentenceWindowRetriever.\_\_init\_\_ + +```python +def __init__(document_store: DocumentStore, + window_size: int = 3, + *, + source_id_meta_field: Union[str, list[str]] = "source_id", + split_id_meta_field: str = "split_id", + raise_on_missing_meta_fields: bool = True) +``` + +Creates a new SentenceWindowRetriever component. + +**Arguments**: + +- `document_store`: The Document Store to retrieve the surrounding documents from. +- `window_size`: The number of documents to retrieve before and after the relevant one. +For example, `window_size: 2` fetches 2 preceding and 2 following documents. +- `source_id_meta_field`: The metadata field that contains the source ID of the document. +This can be a single field or a list of fields. If multiple fields are provided, the retriever will +consider the document as part of the same source if all the fields match. +- `split_id_meta_field`: The metadata field that contains the split ID of the document. +- `raise_on_missing_meta_fields`: If True, raises an error if the documents do not contain the required +metadata fields. If False, it will skip retrieving the context for documents that are missing +the required metadata fields, but will still include the original document in the results. + + + +#### SentenceWindowRetriever.merge\_documents\_text + +```python +@staticmethod +def merge_documents_text(documents: list[Document]) -> str +``` + +Merge a list of document text into a single string. + +This functions concatenates the textual content of a list of documents into a single string, eliminating any +overlapping content. + +**Arguments**: + +- `documents`: List of Documents to merge. + + + +#### SentenceWindowRetriever.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SentenceWindowRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "SentenceWindowRetriever" +``` + +Deserializes the component from a dictionary. + +**Returns**: + +Deserialized component. + + + +#### SentenceWindowRetriever.run + +```python +@component.output_types(context_windows=list[str], + context_documents=list[Document]) +def run(retrieved_documents: list[Document], + window_size: Optional[int] = None) +``` + +Based on the `source_id` and on the `doc.meta['split_id']` get surrounding documents from the document store. + +Implements the logic behind the sentence-window technique, retrieving the surrounding documents of a given +document from the document store. + +**Arguments**: + +- `retrieved_documents`: List of retrieved documents from the previous retriever. +- `window_size`: The number of documents to retrieve before and after the relevant one. This will overwrite +the `window_size` parameter set in the constructor. + +**Returns**: + +A dictionary with the following keys: +- `context_windows`: A list of strings, where each string represents the concatenated text from the + context window of the corresponding document in `retrieved_documents`. +- `context_documents`: A list `Document` objects, containing the retrieved documents plus the context + document surrounding them. The documents are sorted by the `split_idx_start` + meta field. + + + +#### SentenceWindowRetriever.run\_async + +```python +@component.output_types(context_windows=list[str], + context_documents=list[Document]) +async def run_async(retrieved_documents: list[Document], + window_size: Optional[int] = None) +``` + +Based on the `source_id` and on the `doc.meta['split_id']` get surrounding documents from the document store. + +Implements the logic behind the sentence-window technique, retrieving the surrounding documents of a given +document from the document store. + +**Arguments**: + +- `retrieved_documents`: List of retrieved documents from the previous retriever. +- `window_size`: The number of documents to retrieve before and after the relevant one. This will overwrite +the `window_size` parameter set in the constructor. + +**Returns**: + +A dictionary with the following keys: +- `context_windows`: A list of strings, where each string represents the concatenated text from the + context window of the corresponding document in `retrieved_documents`. +- `context_documents`: A list `Document` objects, containing the retrieved documents plus the context + document surrounding them. The documents are sorted by the `split_idx_start` + meta field. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/routers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/routers_api.md new file mode 100644 index 0000000000..bb27347855 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/routers_api.md @@ -0,0 +1,1241 @@ +--- +title: "Routers" +id: routers-api +description: "Routers is a group of components that route queries or Documents to other components that can handle them best." +slug: "/routers-api" +--- + + + +## Module conditional\_router + + + +### NoRouteSelectedException + +Exception raised when no route is selected in ConditionalRouter. + + + +### RouteConditionException + +Exception raised when there is an error parsing or evaluating the condition expression in ConditionalRouter. + + + +### ConditionalRouter + +Routes data based on specific conditions. + +You define these conditions in a list of dictionaries called `routes`. +Each dictionary in this list represents a single route. Each route has these four elements: +- `condition`: A Jinja2 string expression that determines if the route is selected. +- `output`: A Jinja2 expression defining the route's output value. +- `output_type`: The type of the output data (for example, `str`, `list[int]`). +- `output_name`: The name you want to use to publish `output`. This name is used to connect +the router to other components in the pipeline. + +### Usage example + +```python +from haystack.components.routers import ConditionalRouter + +routes = [ + { + "condition": "{{streams|length > 2}}", + "output": "{{streams}}", + "output_name": "enough_streams", + "output_type": list[int], + }, + { + "condition": "{{streams|length <= 2}}", + "output": "{{streams}}", + "output_name": "insufficient_streams", + "output_type": list[int], + }, +] +router = ConditionalRouter(routes) +# When 'streams' has more than 2 items, 'enough_streams' output will activate, emitting the list [1, 2, 3] +kwargs = {"streams": [1, 2, 3], "query": "Haystack"} +result = router.run(**kwargs) +assert result == {"enough_streams": [1, 2, 3]} +``` + +In this example, we configure two routes. The first route sends the 'streams' value to 'enough_streams' if the +stream count exceeds two. The second route directs 'streams' to 'insufficient_streams' if there +are two or fewer streams. + +In the pipeline setup, the Router connects to other components using the output names. For example, +'enough_streams' might connect to a component that processes streams, while +'insufficient_streams' might connect to a component that fetches more streams. + + +Here is a pipeline that uses `ConditionalRouter` and routes the fetched `ByteStreams` to +different components depending on the number of streams fetched: + +```python +from haystack import Pipeline +from haystack.dataclasses import ByteStream +from haystack.components.routers import ConditionalRouter + +routes = [ + { + "condition": "{{streams|length > 2}}", + "output": "{{streams}}", + "output_name": "enough_streams", + "output_type": list[ByteStream], + }, + { + "condition": "{{streams|length <= 2}}", + "output": "{{streams}}", + "output_name": "insufficient_streams", + "output_type": list[ByteStream], + }, +] + +pipe = Pipeline() +pipe.add_component("router", router) +... +pipe.connect("router.enough_streams", "some_component_a.streams") +pipe.connect("router.insufficient_streams", "some_component_b.streams_or_some_other_input") +... +``` + + + +#### ConditionalRouter.\_\_init\_\_ + +```python +def __init__(routes: list[Route], + custom_filters: Optional[dict[str, Callable]] = None, + unsafe: bool = False, + validate_output_type: bool = False, + optional_variables: Optional[list[str]] = None) +``` + +Initializes the `ConditionalRouter` with a list of routes detailing the conditions for routing. + +**Arguments**: + +- `routes`: A list of dictionaries, each defining a route. +Each route has these four elements: +- `condition`: A Jinja2 string expression that determines if the route is selected. +- `output`: A Jinja2 expression defining the route's output value. +- `output_type`: The type of the output data (for example, `str`, `list[int]`). +- `output_name`: The name you want to use to publish `output`. This name is used to connect +the router to other components in the pipeline. +- `custom_filters`: A dictionary of custom Jinja2 filters used in the condition expressions. +For example, passing `{"my_filter": my_filter_fcn}` where: +- `my_filter` is the name of the custom filter. +- `my_filter_fcn` is a callable that takes `my_var:str` and returns `my_var[:3]`. + `{{ my_var|my_filter }}` can then be used inside a route condition expression: + `"condition": "{{ my_var|my_filter == 'foo' }}"`. +- `unsafe`: Enable execution of arbitrary code in the Jinja template. +This should only be used if you trust the source of the template as it can be lead to remote code execution. +- `validate_output_type`: Enable validation of routes' output. +If a route output doesn't match the declared type a ValueError is raised running. +- `optional_variables`: A list of variable names that are optional in your route conditions and outputs. +If these variables are not provided at runtime, they will be set to `None`. +This allows you to write routes that can handle missing inputs gracefully without raising errors. + +Example usage with a default fallback route in a Pipeline: +```python +from haystack import Pipeline +from haystack.components.routers import ConditionalRouter + +routes = [ + { + "condition": '{{ path == "rag" }}', + "output": "{{ question }}", + "output_name": "rag_route", + "output_type": str + }, + { + "condition": "{{ True }}", # fallback route + "output": "{{ question }}", + "output_name": "default_route", + "output_type": str + } +] + +router = ConditionalRouter(routes, optional_variables=["path"]) +pipe = Pipeline() +pipe.add_component("router", router) + +# When 'path' is provided in the pipeline: +result = pipe.run(data={"router": {"question": "What?", "path": "rag"}}) +assert result["router"] == {"rag_route": "What?"} + +# When 'path' is not provided, fallback route is taken: +result = pipe.run(data={"router": {"question": "What?"}}) +assert result["router"] == {"default_route": "What?"} +``` + +This pattern is particularly useful when: +- You want to provide default/fallback behavior when certain inputs are missing +- Some variables are only needed for specific routing conditions +- You're building flexible pipelines where not all inputs are guaranteed to be present + + + +#### ConditionalRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ConditionalRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ConditionalRouter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### ConditionalRouter.run + +```python +def run(**kwargs) +``` + +Executes the routing logic. + +Executes the routing logic by evaluating the specified boolean condition expressions for each route in the +order they are listed. The method directs the flow of data to the output specified in the first route whose +`condition` is True. + +**Arguments**: + +- `kwargs`: All variables used in the `condition` expressed in the routes. When the component is used in a +pipeline, these variables are passed from the previous component's output. + +**Raises**: + +- `NoRouteSelectedException`: If no `condition' in the routes is `True`. +- `RouteConditionException`: If there is an error parsing or evaluating the `condition` expression in the routes. +- `ValueError`: If type validation is enabled and route type doesn't match actual value type. + +**Returns**: + +A dictionary where the key is the `output_name` of the selected route and the value is the `output` +of the selected route. + + + +## Module document\_length\_router + + + +### DocumentLengthRouter + +Categorizes documents based on the length of the `content` field and routes them to the appropriate output. + +A common use case for DocumentLengthRouter is handling documents obtained from PDFs that contain non-text +content, such as scanned pages or images. This component can detect empty or low-content documents and route them to +components that perform OCR, generate captions, or compute image embeddings. + +### Usage example + +```python +from haystack.components.routers import DocumentLengthRouter +from haystack.dataclasses import Document + +docs = [ + Document(content="Short"), + Document(content="Long document "*20), +] + +router = DocumentLengthRouter(threshold=10) + +result = router.run(documents=docs) +print(result) + +# { +# "short_documents": [Document(content="Short", ...)], +# "long_documents": [Document(content="Long document ...", ...)], +# } +``` + + + +#### DocumentLengthRouter.\_\_init\_\_ + +```python +def __init__(*, threshold: int = 10) -> None +``` + +Initialize the DocumentLengthRouter component. + +**Arguments**: + +- `threshold`: The threshold for the number of characters in the document `content` field. Documents where `content` is +None or whose character count is less than or equal to the threshold will be routed to the `short_documents` +output. Otherwise, they will be routed to the `long_documents` output. +To route only documents with None content to `short_documents`, set the threshold to a negative number. + + + +#### DocumentLengthRouter.run + +```python +@component.output_types(short_documents=list[Document], + long_documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Categorize input documents into groups based on the length of the `content` field. + +**Arguments**: + +- `documents`: A list of documents to be categorized. + +**Returns**: + +A dictionary with the following keys: +- `short_documents`: A list of documents where `content` is None or the length of `content` is less than or + equal to the threshold. +- `long_documents`: A list of documents where the length of `content` is greater than the threshold. + + + +## Module document\_type\_router + + + +### DocumentTypeRouter + +Routes documents by their MIME types. + +DocumentTypeRouter is used to dynamically route documents within a pipeline based on their MIME types. +It supports exact MIME type matches and regex patterns. + +MIME types can be extracted directly from document metadata or inferred from file paths using standard or +user-supplied MIME type mappings. + +### Usage example + +```python +from haystack.components.routers import DocumentTypeRouter +from haystack.dataclasses import Document + +docs = [ + Document(content="Example text", meta={"file_path": "example.txt"}), + Document(content="Another document", meta={"mime_type": "application/pdf"}), + Document(content="Unknown type") +] + +router = DocumentTypeRouter( + mime_type_meta_field="mime_type", + file_path_meta_field="file_path", + mime_types=["text/plain", "application/pdf"] +) + +result = router.run(documents=docs) +print(result) +``` + +Expected output: +```python +{ + "text/plain": [Document(...)], + "application/pdf": [Document(...)], + "unclassified": [Document(...)] +} +``` + + + +#### DocumentTypeRouter.\_\_init\_\_ + +```python +def __init__(*, + mime_types: list[str], + mime_type_meta_field: Optional[str] = None, + file_path_meta_field: Optional[str] = None, + additional_mimetypes: Optional[dict[str, str]] = None) -> None +``` + +Initialize the DocumentTypeRouter component. + +**Arguments**: + +- `mime_types`: A list of MIME types or regex patterns to classify the input documents. +(for example: `["text/plain", "audio/x-wav", "image/jpeg"]`). +- `mime_type_meta_field`: Optional name of the metadata field that holds the MIME type. +- `file_path_meta_field`: Optional name of the metadata field that holds the file path. Used to infer the MIME type if +`mime_type_meta_field` is not provided or missing in a document. +- `additional_mimetypes`: Optional dictionary mapping MIME types to file extensions to enhance or override the standard +`mimetypes` module. Useful when working with uncommon or custom file types. +For example: `{"application/vnd.custom-type": ".custom"}`. + +**Raises**: + +- `ValueError`: If `mime_types` is empty or if both `mime_type_meta_field` and `file_path_meta_field` are +not provided. + + + +#### DocumentTypeRouter.run + +```python +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Categorize input documents into groups based on their MIME type. + +MIME types can either be directly available in document metadata or derived from file paths using the +standard Python `mimetypes` module and custom mappings. + +**Arguments**: + +- `documents`: A list of documents to be categorized. + +**Returns**: + +A dictionary where the keys are MIME types (or `"unclassified"`) and the values are lists of documents. + + + +## Module file\_type\_router + + + +### FileTypeRouter + +Categorizes files or byte streams by their MIME types, helping in context-based routing. + +FileTypeRouter supports both exact MIME type matching and regex patterns. + +For file paths, MIME types come from extensions, while byte streams use metadata. +You can use regex patterns in the `mime_types` parameter to set broad categories +(such as 'audio/*' or 'text/*') or specific types. +MIME types without regex patterns are treated as exact matches. + +### Usage example + +```python +from haystack.components.routers import FileTypeRouter +from pathlib import Path + +# For exact MIME type matching +router = FileTypeRouter(mime_types=["text/plain", "application/pdf"]) + +# For flexible matching using regex, to handle all audio types +router_with_regex = FileTypeRouter(mime_types=[r"audio/.*", r"text/plain"]) + +sources = [Path("file.txt"), Path("document.pdf"), Path("song.mp3")] +print(router.run(sources=sources)) +print(router_with_regex.run(sources=sources)) + +# Expected output: +# {'text/plain': [ +# PosixPath('file.txt')], 'application/pdf': [PosixPath('document.pdf')], 'unclassified': [PosixPath('song.mp3') +# ]} +# {'audio/.*': [ +# PosixPath('song.mp3')], 'text/plain': [PosixPath('file.txt')], 'unclassified': [PosixPath('document.pdf') +# ]} +``` + + + +#### FileTypeRouter.\_\_init\_\_ + +```python +def __init__(mime_types: list[str], + additional_mimetypes: Optional[dict[str, str]] = None, + raise_on_failure: bool = False) +``` + +Initialize the FileTypeRouter component. + +**Arguments**: + +- `mime_types`: A list of MIME types or regex patterns to classify the input files or byte streams. +(for example: `["text/plain", "audio/x-wav", "image/jpeg"]`). +- `additional_mimetypes`: A dictionary containing the MIME type to add to the mimetypes package to prevent unsupported or non-native +packages from being unclassified. +(for example: `{"application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx"}`). +- `raise_on_failure`: If True, raises FileNotFoundError when a file path doesn't exist. +If False (default), only emits a warning when a file path doesn't exist. + + + +#### FileTypeRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FileTypeRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "FileTypeRouter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### FileTypeRouter.run + +```python +def run( + sources: list[Union[str, Path, ByteStream]], + meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None +) -> dict[str, list[Union[ByteStream, Path]]] +``` + +Categorize files or byte streams according to their MIME types. + +**Arguments**: + +- `sources`: A list of file paths or byte streams to categorize. +- `meta`: Optional metadata to attach to the sources. +When provided, the sources are internally converted to ByteStream objects and the metadata is added. +This value can be a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all ByteStream objects. +If it's a list, its length must match the number of sources, as they are zipped together. + +**Returns**: + +A dictionary where the keys are MIME types and the values are lists of data sources. +Two extra keys may be returned: `"unclassified"` when a source's MIME type doesn't match any pattern +and `"failed"` when a source cannot be processed (for example, a file path that doesn't exist). + + + +## Module llm\_messages\_router + + + +### LLMMessagesRouter + +Routes Chat Messages to different connections using a generative Language Model to perform classification. + + This component can be used with general-purpose LLMs and with specialized LLMs for moderation like Llama Guard. + + ### Usage example + ```python + from haystack.components.generators.chat import HuggingFaceAPIChatGenerator + from haystack.components.routers.llm_messages_router import LLMMessagesRouter + from haystack.dataclasses import ChatMessage + + # initialize a Chat Generator with a generative model for moderation + chat_generator = HuggingFaceAPIChatGenerator( + api_type="serverless_inference_api", + api_params={"model": "meta-llama/Llama-Guard-4-12B", "provider": "groq"}, + ) + + router = LLMMessagesRouter(chat_generator=chat_generator, + output_names=["unsafe", "safe"], + output_patterns=["unsafe", "safe"]) + + + print(router.run([ChatMessage.from_user("How to rob a bank?")])) + + # { + # 'chat_generator_text': 'unsafe +S2', + # 'unsafe': [ + # ChatMessage( + # _role=, + # _content=[TextContent(text='How to rob a bank?')], + # _name=None, + # _meta={} + # ) + # ] + # } + ``` + + + +#### LLMMessagesRouter.\_\_init\_\_ + +```python +def __init__(chat_generator: ChatGenerator, + output_names: list[str], + output_patterns: list[str], + system_prompt: Optional[str] = None) +``` + +Initialize the LLMMessagesRouter component. + +**Arguments**: + +- `chat_generator`: A ChatGenerator instance which represents the LLM. +- `output_names`: A list of output connection names. These can be used to connect the router to other +components. +- `output_patterns`: A list of regular expressions to be matched against the output of the LLM. Each pattern +corresponds to an output name. Patterns are evaluated in order. +When using moderation models, refer to the model card to understand the expected outputs. +- `system_prompt`: An optional system prompt to customize the behavior of the LLM. +For moderation models, refer to the model card for supported customization options. + +**Raises**: + +- `ValueError`: If output_names and output_patterns are not non-empty lists of the same length. + + + +#### LLMMessagesRouter.warm\_up + +```python +def warm_up() +``` + +Warm up the underlying LLM. + + + +#### LLMMessagesRouter.run + +```python +def run(messages: list[ChatMessage] + ) -> dict[str, Union[str, list[ChatMessage]]] +``` + +Classify the messages based on LLM output and route them to the appropriate output connection. + +**Arguments**: + +- `messages`: A list of ChatMessages to be routed. Only user and assistant messages are supported. + +**Raises**: + +- `ValueError`: If messages is an empty list or contains messages with unsupported roles. + +**Returns**: + +A dictionary with the following keys: +- "chat_generator_text": The text output of the LLM, useful for debugging. +- "output_names": Each contains the list of messages that matched the corresponding pattern. +- "unmatched": The messages that did not match any of the output patterns. + + + +#### LLMMessagesRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### LLMMessagesRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "LLMMessagesRouter" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +## Module metadata\_router + + + +### MetadataRouter + +Routes documents or byte streams to different connections based on their metadata fields. + +Specify the routing rules in the `init` method. +If a document or byte stream does not match any of the rules, it's routed to a connection named "unmatched". + + +### Usage examples + +**Routing Documents by metadata:** +```python +from haystack import Document +from haystack.components.routers import MetadataRouter + +docs = [Document(content="Paris is the capital of France.", meta={"language": "en"}), + Document(content="Berlin ist die Haupststadt von Deutschland.", meta={"language": "de"})] + +router = MetadataRouter(rules={"en": {"field": "meta.language", "operator": "==", "value": "en"}}) + +print(router.run(documents=docs)) +# {'en': [Document(id=..., content: 'Paris is the capital of France.', meta: {'language': 'en'})], +# 'unmatched': [Document(id=..., content: 'Berlin ist die Haupststadt von Deutschland.', meta: {'language': 'de'})]} +``` + +**Routing ByteStreams by metadata:** +```python +from haystack.dataclasses import ByteStream +from haystack.components.routers import MetadataRouter + +streams = [ + ByteStream.from_string("Hello world", meta={"language": "en"}), + ByteStream.from_string("Bonjour le monde", meta={"language": "fr"}) +] + +router = MetadataRouter( + rules={"english": {"field": "meta.language", "operator": "==", "value": "en"}}, + output_type=list[ByteStream] +) + +result = router.run(documents=streams) +# {'english': [ByteStream(...)], 'unmatched': [ByteStream(...)]} +``` + + + +#### MetadataRouter.\_\_init\_\_ + +```python +def __init__(rules: dict[str, dict], + output_type: type = list[Document]) -> None +``` + +Initializes the MetadataRouter component. + +**Arguments**: + +- `rules`: A dictionary defining how to route documents or byte streams to output connections based on their +metadata. Keys are output connection names, and values are dictionaries of +[filtering expressions](https://docs.haystack.deepset.ai/docs/metadata-filtering) in Haystack. +For example: +```python +{ +"edge_1": { + "operator": "AND", + "conditions": [ + {"field": "meta.created_at", "operator": ">=", "value": "2023-01-01"}, + {"field": "meta.created_at", "operator": "<", "value": "2023-04-01"}, + ], +}, +"edge_2": { + "operator": "AND", + "conditions": [ + {"field": "meta.created_at", "operator": ">=", "value": "2023-04-01"}, + {"field": "meta.created_at", "operator": "<", "value": "2023-07-01"}, + ], +}, +"edge_3": { + "operator": "AND", + "conditions": [ + {"field": "meta.created_at", "operator": ">=", "value": "2023-07-01"}, + {"field": "meta.created_at", "operator": "<", "value": "2023-10-01"}, + ], +}, +"edge_4": { + "operator": "AND", + "conditions": [ + {"field": "meta.created_at", "operator": ">=", "value": "2023-10-01"}, + {"field": "meta.created_at", "operator": "<", "value": "2024-01-01"}, + ], +}, +} +``` +:param output_type: The type of the output produced. Lists of Documents or ByteStreams can be specified. + + + +#### MetadataRouter.run + +```python +def run(documents: Union[list[Document], list[ByteStream]]) +``` + +Routes documents or byte streams to different connections based on their metadata fields. + +If a document or byte stream does not match any of the rules, it's routed to a connection named "unmatched". + +**Arguments**: + +- `documents`: A list of `Document` or `ByteStream` objects to be routed based on their metadata. + +**Returns**: + +A dictionary where the keys are the names of the output connections (including `"unmatched"`) +and the values are lists of `Document` or `ByteStream` objects that matched the corresponding rules. + + + +#### MetadataRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### MetadataRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "MetadataRouter" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +## Module text\_language\_router + + + +### TextLanguageRouter + +Routes text strings to different output connections based on their language. + +Provide a list of languages during initialization. If the document's text doesn't match any of the +specified languages, the metadata value is set to "unmatched". +For routing documents based on their language, use the DocumentLanguageClassifier component, +followed by the MetaDataRouter. + +### Usage example + +```python +from haystack import Pipeline, Document +from haystack.components.routers import TextLanguageRouter +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.components.retrievers.in_memory import InMemoryBM25Retriever + +document_store = InMemoryDocumentStore() +document_store.write_documents([Document(content="Elvis Presley was an American singer and actor.")]) + +p = Pipeline() +p.add_component(instance=TextLanguageRouter(languages=["en"]), name="text_language_router") +p.add_component(instance=InMemoryBM25Retriever(document_store=document_store), name="retriever") +p.connect("text_language_router.en", "retriever.query") + +result = p.run({"text_language_router": {"text": "Who was Elvis Presley?"}}) +assert result["retriever"]["documents"][0].content == "Elvis Presley was an American singer and actor." + +result = p.run({"text_language_router": {"text": "ένα ελληνικό κείμενο"}}) +assert result["text_language_router"]["unmatched"] == "ένα ελληνικό κείμενο" +``` + + + +#### TextLanguageRouter.\_\_init\_\_ + +```python +def __init__(languages: Optional[list[str]] = None) +``` + +Initialize the TextLanguageRouter component. + +**Arguments**: + +- `languages`: A list of ISO language codes. +See the supported languages in [`langdetect` documentation](https://github.com/Mimino666/langdetect#languages). +If not specified, defaults to ["en"]. + + + +#### TextLanguageRouter.run + +```python +def run(text: str) -> dict[str, str] +``` + +Routes the text strings to different output connections based on their language. + +If the document's text doesn't match any of the specified languages, the metadata value is set to "unmatched". + +**Arguments**: + +- `text`: A text string to route. + +**Raises**: + +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary in which the key is the language (or `"unmatched"`), +and the value is the text. + + + +## Module transformers\_text\_router + + + +### TransformersTextRouter + +Routes the text strings to different connections based on a category label. + +The labels are specific to each model and can be found it its description on Hugging Face. + +### Usage example + +```python +from haystack.core.pipeline import Pipeline +from haystack.components.routers import TransformersTextRouter +from haystack.components.builders import PromptBuilder +from haystack.components.generators import HuggingFaceLocalGenerator + +p = Pipeline() +p.add_component( + instance=TransformersTextRouter(model="papluca/xlm-roberta-base-language-detection"), + name="text_router" +) +p.add_component( + instance=PromptBuilder(template="Answer the question: {{query}}\nAnswer:"), + name="english_prompt_builder" +) +p.add_component( + instance=PromptBuilder(template="Beantworte die Frage: {{query}}\nAntwort:"), + name="german_prompt_builder" +) + +p.add_component( + instance=HuggingFaceLocalGenerator(model="DiscoResearch/Llama3-DiscoLeo-Instruct-8B-v0.1"), + name="german_llm" +) +p.add_component( + instance=HuggingFaceLocalGenerator(model="microsoft/Phi-3-mini-4k-instruct"), + name="english_llm" +) + +p.connect("text_router.en", "english_prompt_builder.query") +p.connect("text_router.de", "german_prompt_builder.query") +p.connect("english_prompt_builder.prompt", "english_llm.prompt") +p.connect("german_prompt_builder.prompt", "german_llm.prompt") + +# English Example +print(p.run({"text_router": {"text": "What is the capital of Germany?"}})) + +# German Example +print(p.run({"text_router": {"text": "Was ist die Hauptstadt von Deutschland?"}})) +``` + + + +#### TransformersTextRouter.\_\_init\_\_ + +```python +def __init__(model: str, + labels: Optional[list[str]] = None, + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None) +``` + +Initializes the TransformersTextRouter component. + +**Arguments**: + +- `model`: The name or path of a Hugging Face model for text classification. +- `labels`: The list of labels. If not provided, the component fetches the labels +from the model configuration file hosted on the Hugging Face Hub using +`transformers.AutoConfig.from_pretrained`. +- `device`: The device for loading the model. If `None`, automatically selects the default device. +If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter. +- `token`: The API token used to download private models from Hugging Face. +If `True`, uses either `HF_API_TOKEN` or `HF_TOKEN` environment variables. +To generate these tokens, run `transformers-cli login`. +- `huggingface_pipeline_kwargs`: A dictionary of keyword arguments for initializing the Hugging Face +text classification pipeline. + + + +#### TransformersTextRouter.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### TransformersTextRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### TransformersTextRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "TransformersTextRouter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### TransformersTextRouter.run + +```python +def run(text: str) -> dict[str, str] +``` + +Routes the text strings to different connections based on a category label. + +**Arguments**: + +- `text`: A string of text to route. + +**Raises**: + +- `TypeError`: If the input is not a str. +- `RuntimeError`: If the pipeline has not been loaded because warm_up() was not called before. + +**Returns**: + +A dictionary with the label as key and the text as value. + + + +## Module zero\_shot\_text\_router + + + +### TransformersZeroShotTextRouter + +Routes the text strings to different connections based on a category label. + +Specify the set of labels for categorization when initializing the component. + +### Usage example + +```python +from haystack import Document +from haystack.document_stores.in_memory import InMemoryDocumentStore +from haystack.core.pipeline import Pipeline +from haystack.components.routers import TransformersZeroShotTextRouter +from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder +from haystack.components.retrievers import InMemoryEmbeddingRetriever + +document_store = InMemoryDocumentStore() +doc_embedder = SentenceTransformersDocumentEmbedder(model="intfloat/e5-base-v2") +doc_embedder.warm_up() +docs = [ + Document( + content="Germany, officially the Federal Republic of Germany, is a country in the western region of " + "Central Europe. The nation's capital and most populous city is Berlin and its main financial centre " + "is Frankfurt; the largest urban area is the Ruhr." + ), + Document( + content="France, officially the French Republic, is a country located primarily in Western Europe. " + "France is a unitary semi-presidential republic with its capital in Paris, the country's largest city " + "and main cultural and commercial centre; other major urban areas include Marseille, Lyon, Toulouse, " + "Lille, Bordeaux, Strasbourg, Nantes and Nice." + ) +] +docs_with_embeddings = doc_embedder.run(docs) +document_store.write_documents(docs_with_embeddings["documents"]) + +p = Pipeline() +p.add_component(instance=TransformersZeroShotTextRouter(labels=["passage", "query"]), name="text_router") +p.add_component( + instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="passage: "), + name="passage_embedder" +) +p.add_component( + instance=SentenceTransformersTextEmbedder(model="intfloat/e5-base-v2", prefix="query: "), + name="query_embedder" +) +p.add_component( + instance=InMemoryEmbeddingRetriever(document_store=document_store), + name="query_retriever" +) +p.add_component( + instance=InMemoryEmbeddingRetriever(document_store=document_store), + name="passage_retriever" +) + +p.connect("text_router.passage", "passage_embedder.text") +p.connect("passage_embedder.embedding", "passage_retriever.query_embedding") +p.connect("text_router.query", "query_embedder.text") +p.connect("query_embedder.embedding", "query_retriever.query_embedding") + +# Query Example +p.run({"text_router": {"text": "What is the capital of Germany?"}}) + +# Passage Example +p.run({ + "text_router":{ + "text": "The United Kingdom of Great Britain and Northern Ireland, commonly known as the " "United Kingdom (UK) or Britain, is a country in Northwestern Europe, off the north-western coast of " "the continental mainland." + } +}) +``` + + + +#### TransformersZeroShotTextRouter.\_\_init\_\_ + +```python +def __init__(labels: list[str], + multi_label: bool = False, + model: str = "MoritzLaurer/deberta-v3-base-zeroshot-v1.1-all-33", + device: Optional[ComponentDevice] = None, + token: Optional[Secret] = Secret.from_env_var( + ["HF_API_TOKEN", "HF_TOKEN"], strict=False), + huggingface_pipeline_kwargs: Optional[dict[str, Any]] = None) +``` + +Initializes the TransformersZeroShotTextRouter component. + +**Arguments**: + +- `labels`: The set of labels to use for classification. Can be a single label, +a string of comma-separated labels, or a list of labels. +- `multi_label`: Indicates if multiple labels can be true. +If `False`, label scores are normalized so their sum equals 1 for each sequence. +If `True`, the labels are considered independent and probabilities are normalized for each candidate by +doing a softmax of the entailment score vs. the contradiction score. +- `model`: The name or path of a Hugging Face model for zero-shot text classification. +- `device`: The device for loading the model. If `None`, automatically selects the default device. +If a device or device map is specified in `huggingface_pipeline_kwargs`, it overrides this parameter. +- `token`: The API token used to download private models from Hugging Face. +If `True`, uses either `HF_API_TOKEN` or `HF_TOKEN` environment variables. +To generate these tokens, run `transformers-cli login`. +- `huggingface_pipeline_kwargs`: A dictionary of keyword arguments for initializing the Hugging Face +zero shot text classification. + + + +#### TransformersZeroShotTextRouter.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### TransformersZeroShotTextRouter.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### TransformersZeroShotTextRouter.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "TransformersZeroShotTextRouter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### TransformersZeroShotTextRouter.run + +```python +def run(text: str) -> dict[str, str] +``` + +Routes the text strings to different connections based on a category label. + +**Arguments**: + +- `text`: A string of text to route. + +**Raises**: + +- `TypeError`: If the input is not a str. +- `RuntimeError`: If the pipeline has not been loaded because warm_up() was not called before. + +**Returns**: + +A dictionary with the label as key and the text as value. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/samplers_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/samplers_api.md new file mode 100644 index 0000000000..cea74187e7 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/samplers_api.md @@ -0,0 +1,88 @@ +--- +title: "Samplers" +id: samplers-api +description: "Filters documents based on their similarity scores using top-p sampling." +slug: "/samplers-api" +--- + + + +## Module top\_p + + + +### TopPSampler + +Implements top-p (nucleus) sampling for document filtering based on cumulative probability scores. + +This component provides functionality to filter a list of documents by selecting those whose scores fall +within the top 'p' percent of the cumulative distribution. It is useful for focusing on high-probability +documents while filtering out less relevant ones based on their assigned scores. + +Usage example: + +```python +from haystack import Document +from haystack.components.samplers import TopPSampler + +sampler = TopPSampler(top_p=0.95, score_field="similarity_score") +docs = [ + Document(content="Berlin", meta={"similarity_score": -10.6}), + Document(content="Belgrade", meta={"similarity_score": -8.9}), + Document(content="Sarajevo", meta={"similarity_score": -4.6}), +] +output = sampler.run(documents=docs) +docs = output["documents"] +assert len(docs) == 1 +assert docs[0].content == "Sarajevo" +``` + + + +#### TopPSampler.\_\_init\_\_ + +```python +def __init__(top_p: float = 1.0, + score_field: Optional[str] = None, + min_top_k: Optional[int] = None) +``` + +Creates an instance of TopPSampler. + +**Arguments**: + +- `top_p`: Float between 0 and 1 representing the cumulative probability threshold for document selection. +A value of 1.0 indicates no filtering (all documents are retained). +- `score_field`: Name of the field in each document's metadata that contains the score. If None, the default +document score field is used. +- `min_top_k`: If specified, the minimum number of documents to return. If the top_p selects +fewer documents, additional ones with the next highest scores are added to the selection. + + + +#### TopPSampler.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document], top_p: Optional[float] = None) +``` + +Filters documents using top-p sampling based on their scores. + +If the specified top_p results in no documents being selected (especially in cases of a low top_p value), the +method returns the document with the highest score. + +**Arguments**: + +- `documents`: List of Document objects to be filtered. +- `top_p`: If specified, a float to override the cumulative probability threshold set during initialization. + +**Raises**: + +- `ValueError`: If the top_p value is not within the range [0, 1]. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of Document objects that have been selected based on the top-p sampling. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tool_components_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tool_components_api.md new file mode 100644 index 0000000000..0b0a7e173c --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tool_components_api.md @@ -0,0 +1,324 @@ +--- +title: "Tool Components" +id: tool-components-api +description: "Components related to Tool Calling." +slug: "/tool-components-api" +--- + + + +## Module tool\_invoker + + + +### ToolInvokerError + +Base exception class for ToolInvoker errors. + + + +### ToolNotFoundException + +Exception raised when a tool is not found in the list of available tools. + + + +### StringConversionError + +Exception raised when the conversion of a tool result to a string fails. + + + +### ToolOutputMergeError + +Exception raised when merging tool outputs into state fails. + + + +#### ToolOutputMergeError.from\_exception + +```python +@classmethod +def from_exception(cls, tool_name: str, + error: Exception) -> "ToolOutputMergeError" +``` + +Create a ToolOutputMergeError from an exception. + + + +### ToolInvoker + +Invokes tools based on prepared tool calls and returns the results as a list of ChatMessage objects. + +Also handles reading/writing from a shared `State`. +At initialization, the ToolInvoker component is provided with a list of available tools. +At runtime, the component processes a list of ChatMessage object containing tool calls +and invokes the corresponding tools. +The results of the tool invocations are returned as a list of ChatMessage objects with tool role. + +Usage example: +```python +from haystack.dataclasses import ChatMessage, ToolCall +from haystack.tools import Tool +from haystack.components.tools import ToolInvoker + +# Tool definition +def dummy_weather_function(city: str): + return f"The weather in {city} is 20 degrees." + +parameters = {"type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"]} + +tool = Tool(name="weather_tool", + description="A tool to get the weather", + function=dummy_weather_function, + parameters=parameters) + +# Usually, the ChatMessage with tool_calls is generated by a Language Model +# Here, we create it manually for demonstration purposes +tool_call = ToolCall( + tool_name="weather_tool", + arguments={"city": "Berlin"} +) +message = ChatMessage.from_assistant(tool_calls=[tool_call]) + +# ToolInvoker initialization and run +invoker = ToolInvoker(tools=[tool]) +result = invoker.run(messages=[message]) + +print(result) +``` + +``` +>> { +>> 'tool_messages': [ +>> ChatMessage( +>> _role=, +>> _content=[ +>> ToolCallResult( +>> result='"The weather in Berlin is 20 degrees."', +>> origin=ToolCall( +>> tool_name='weather_tool', +>> arguments={'city': 'Berlin'}, +>> id=None +>> ) +>> ) +>> ], +>> _meta={} +>> ) +>> ] +>> } +``` + +Usage example with a Toolset: +```python +from haystack.dataclasses import ChatMessage, ToolCall +from haystack.tools import Tool, Toolset +from haystack.components.tools import ToolInvoker + +# Tool definition +def dummy_weather_function(city: str): + return f"The weather in {city} is 20 degrees." + +parameters = {"type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"]} + +tool = Tool(name="weather_tool", + description="A tool to get the weather", + function=dummy_weather_function, + parameters=parameters) + +# Create a Toolset +toolset = Toolset([tool]) + +# Usually, the ChatMessage with tool_calls is generated by a Language Model +# Here, we create it manually for demonstration purposes +tool_call = ToolCall( + tool_name="weather_tool", + arguments={"city": "Berlin"} +) +message = ChatMessage.from_assistant(tool_calls=[tool_call]) + +# ToolInvoker initialization and run with Toolset +invoker = ToolInvoker(tools=toolset) +result = invoker.run(messages=[message]) + +print(result) + + + +#### ToolInvoker.\_\_init\_\_ + +```python +def __init__(tools: ToolsType, + raise_on_failure: bool = True, + convert_result_to_json_string: bool = False, + streaming_callback: Optional[StreamingCallbackT] = None, + *, + enable_streaming_callback_passthrough: bool = False, + max_workers: int = 4) +``` + +Initialize the ToolInvoker component. + +**Arguments**: + +- `tools`: A list of Tool and/or Toolset objects, or a Toolset instance that can resolve tools. +- `raise_on_failure`: If True, the component will raise an exception in case of errors +(tool not found, tool invocation errors, tool result conversion errors). +If False, the component will return a ChatMessage object with `error=True` +and a description of the error in `result`. +- `convert_result_to_json_string`: If True, the tool invocation result will be converted to a string using `json.dumps`. +If False, the tool invocation result will be converted to a string using `str`. +- `streaming_callback`: A callback function that will be called to emit tool results. +Note that the result is only emitted once it becomes available — it is not +streamed incrementally in real time. +- `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. +This allows tools to stream their results back to the client. +Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. +If False, the `streaming_callback` will not be passed to the tool invocation. +- `max_workers`: The maximum number of workers to use in the thread pool executor. +This also decides the maximum number of concurrent tool invocations. + +**Raises**: + +- `ValueError`: If no tools are provided or if duplicate tool names are found. + + + +#### ToolInvoker.warm\_up + +```python +def warm_up() +``` + +Warm up the tool invoker. + +This will warm up the tools registered in the tool invoker. +This method is idempotent and will only warm up the tools once. + + + +#### ToolInvoker.run + +```python +@component.output_types(tool_messages=list[ChatMessage], state=State) +def run(messages: list[ChatMessage], + state: Optional[State] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + *, + enable_streaming_callback_passthrough: Optional[bool] = None, + tools: Optional[ToolsType] = None) -> dict[str, Any] +``` + +Processes ChatMessage objects containing tool calls and invokes the corresponding tools, if available. + +**Arguments**: + +- `messages`: A list of ChatMessage objects. +- `state`: The runtime state that should be used by the tools. +- `streaming_callback`: A callback function that will be called to emit tool results. +Note that the result is only emitted once it becomes available — it is not +streamed incrementally in real time. +- `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. +This allows tools to stream their results back to the client. +Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. +If False, the `streaming_callback` will not be passed to the tool invocation. +If None, the value from the constructor will be used. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. + +**Raises**: + +- `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True. +- `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True. +- `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True. +- `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True. + +**Returns**: + +A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. +Each ChatMessage objects wraps the result of a tool invocation. + + + +#### ToolInvoker.run\_async + +```python +@component.output_types(tool_messages=list[ChatMessage], state=State) +async def run_async( + messages: list[ChatMessage], + state: Optional[State] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + *, + enable_streaming_callback_passthrough: Optional[bool] = None, + tools: Optional[ToolsType] = None) -> dict[str, Any] +``` + +Asynchronously processes ChatMessage objects containing tool calls. + +Multiple tool calls are performed concurrently. + +**Arguments**: + +- `messages`: A list of ChatMessage objects. +- `state`: The runtime state that should be used by the tools. +- `streaming_callback`: An asynchronous callback function that will be called to emit tool results. +Note that the result is only emitted once it becomes available — it is not +streamed incrementally in real time. +- `enable_streaming_callback_passthrough`: If True, the `streaming_callback` will be passed to the tool invocation if the tool supports it. +This allows tools to stream their results back to the client. +Note that this requires the tool to have a `streaming_callback` parameter in its `invoke` method signature. +If False, the `streaming_callback` will not be passed to the tool invocation. +If None, the value from the constructor will be used. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. + +**Raises**: + +- `ToolNotFoundException`: If the tool is not found in the list of available tools and `raise_on_failure` is True. +- `ToolInvocationError`: If the tool invocation fails and `raise_on_failure` is True. +- `StringConversionError`: If the conversion of the tool result to a string fails and `raise_on_failure` is True. +- `ToolOutputMergeError`: If merging tool outputs into state fails and `raise_on_failure` is True. + +**Returns**: + +A dictionary with the key `tool_messages` containing a list of ChatMessage objects with tool role. +Each ChatMessage objects wraps the result of a tool invocation. + + + +#### ToolInvoker.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ToolInvoker.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ToolInvoker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tools_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tools_api.md new file mode 100644 index 0000000000..86ce13d124 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/tools_api.md @@ -0,0 +1,933 @@ +--- +title: "Tools" +id: tools-api +description: "Unified abstractions to represent tools across the framework." +slug: "/tools-api" +--- + + + +## Module tool + + + +### Tool + +Data class representing a Tool that Language Models can prepare a call for. + +Accurate definitions of the textual attributes such as `name` and `description` +are important for the Language Model to correctly prepare the call. + +For resource-intensive operations like establishing connections to remote services or +loading models, override the `warm_up()` method. This method is called before the Tool +is used and should be idempotent, as it may be called multiple times during +pipeline/agent setup. + +**Arguments**: + +- `name`: Name of the Tool. +- `description`: Description of the Tool. +- `parameters`: A JSON schema defining the parameters expected by the Tool. +- `function`: The function that will be invoked when the Tool is called. +- `outputs_to_string`: Optional dictionary defining how a tool outputs should be converted into a string. +If the source is provided only the specified output key is sent to the handler. +If the source is omitted the whole tool result is sent to the handler. +Example: +```python +{ + "source": "docs", "handler": format_documents +} +``` +- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names. +Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter. +- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers. +If the source is provided only the specified output key is sent to the handler. +Example: +```python +{ + "documents": {"source": "docs", "handler": custom_handler} +} +``` +If the source is omitted the whole tool result is sent to the handler. +Example: +```python +{ + "documents": {"handler": custom_handler} +} +``` + + + +#### Tool.tool\_spec + +```python +@property +def tool_spec() -> dict[str, Any] +``` + +Return the Tool specification to be used by the Language Model. + + + +#### Tool.warm\_up + +```python +def warm_up() -> None +``` + +Prepare the Tool for use. + +Override this method to establish connections to remote services, load models, +or perform other resource-intensive initialization. This method should be idempotent, +as it may be called multiple times. + + + +#### Tool.invoke + +```python +def invoke(**kwargs: Any) -> Any +``` + +Invoke the Tool with the provided keyword arguments. + + + +#### Tool.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the Tool to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### Tool.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Tool" +``` + +Deserializes the Tool from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized Tool. + + + +## Module from\_function + + + +#### create\_tool\_from\_function + +```python +def create_tool_from_function( + function: Callable, + name: Optional[str] = None, + description: Optional[str] = None, + inputs_from_state: Optional[dict[str, str]] = None, + outputs_to_state: Optional[dict[str, dict[str, + Any]]] = None) -> "Tool" +``` + +Create a Tool instance from a function. + +Allows customizing the Tool name and description. +For simpler use cases, consider using the `@tool` decorator. + +### Usage example + +```python +from typing import Annotated, Literal +from haystack.tools import create_tool_from_function + +def get_weather( + city: Annotated[str, "the city for which to get the weather"] = "Munich", + unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"): + '''A simple function to get the current weather for a location.''' + return f"Weather report for {city}: 20 {unit}, sunny" + +tool = create_tool_from_function(get_weather) + +print(tool) +>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.', +>>> parameters={ +>>> 'type': 'object', +>>> 'properties': { +>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'}, +>>> 'unit': { +>>> 'type': 'string', +>>> 'enum': ['Celsius', 'Fahrenheit'], +>>> 'description': 'the unit for the temperature', +>>> 'default': 'Celsius', +>>> }, +>>> } +>>> }, +>>> function=) +``` + +**Arguments**: + +- `function`: The function to be converted into a Tool. +The function must include type hints for all parameters. +The function is expected to have basic python input types (str, int, float, bool, list, dict, tuple). +Other input types may work but are not guaranteed. +If a parameter is annotated using `typing.Annotated`, its metadata will be used as parameter description. +- `name`: The name of the Tool. If not provided, the name of the function will be used. +- `description`: The description of the Tool. If not provided, the docstring of the function will be used. +To intentionally leave the description empty, pass an empty string. +- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names. +Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter. +- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling. +Example: +```python +{ + "documents": {"source": "docs", "handler": custom_handler}, + "message": {"source": "summary", "handler": format_summary} +} +``` + +**Raises**: + +- `ValueError`: If any parameter of the function lacks a type hint. +- `SchemaGenerationError`: If there is an error generating the JSON schema for the Tool. + +**Returns**: + +The Tool created from the function. + + + +#### tool + +```python +def tool( + function: Optional[Callable] = None, + *, + name: Optional[str] = None, + description: Optional[str] = None, + inputs_from_state: Optional[dict[str, str]] = None, + outputs_to_state: Optional[dict[str, dict[str, Any]]] = None +) -> Union[Tool, Callable[[Callable], Tool]] +``` + +Decorator to convert a function into a Tool. + +Can be used with or without parameters: +@tool # without parameters +def my_function(): ... + +@tool(name="custom_name") # with parameters +def my_function(): ... + +### Usage example +```python +from typing import Annotated, Literal +from haystack.tools import tool + +@tool +def get_weather( + city: Annotated[str, "the city for which to get the weather"] = "Munich", + unit: Annotated[Literal["Celsius", "Fahrenheit"], "the unit for the temperature"] = "Celsius"): + '''A simple function to get the current weather for a location.''' + return f"Weather report for {city}: 20 {unit}, sunny" + +print(get_weather) +>>> Tool(name='get_weather', description='A simple function to get the current weather for a location.', +>>> parameters={ +>>> 'type': 'object', +>>> 'properties': { +>>> 'city': {'type': 'string', 'description': 'the city for which to get the weather', 'default': 'Munich'}, +>>> 'unit': { +>>> 'type': 'string', +>>> 'enum': ['Celsius', 'Fahrenheit'], +>>> 'description': 'the unit for the temperature', +>>> 'default': 'Celsius', +>>> }, +>>> } +>>> }, +>>> function=) +``` + +**Arguments**: + +- `function`: The function to decorate (when used without parameters) +- `name`: Optional custom name for the tool +- `description`: Optional custom description +- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names +- `outputs_to_state`: Optional dictionary defining how tool outputs map to state and message handling + +**Returns**: + +Either a Tool instance or a decorator function that will create one + + + +## Module component\_tool + + + +### ComponentTool + +A Tool that wraps Haystack components, allowing them to be used as tools by LLMs. + +ComponentTool automatically generates LLM-compatible tool schemas from component input sockets, +which are derived from the component's `run` method signature and type hints. + + +Key features: +- Automatic LLM tool calling schema generation from component input sockets +- Type conversion and validation for component inputs +- Support for types: +- Dataclasses +- Lists of dataclasses +- Basic types (str, int, float, bool, dict) +- Lists of basic types +- Automatic name generation from component class name +- Description extraction from component docstrings + +To use ComponentTool, you first need a Haystack component - either an existing one or a new one you create. +You can create a ComponentTool from the component by passing the component to the ComponentTool constructor. +Below is an example of creating a ComponentTool from an existing SerperDevWebSearch component. + +## Usage Example: + +```python +from haystack import component, Pipeline +from haystack.tools import ComponentTool +from haystack.components.websearch import SerperDevWebSearch +from haystack.utils import Secret +from haystack.components.tools.tool_invoker import ToolInvoker +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +# Create a SerperDev search component +search = SerperDevWebSearch(api_key=Secret.from_env_var("SERPERDEV_API_KEY"), top_k=3) + +# Create a tool from the component +tool = ComponentTool( + component=search, + name="web_search", # Optional: defaults to "serper_dev_web_search" + description="Search the web for current information on any topic" # Optional: defaults to component docstring +) + +# Create pipeline with OpenAIChatGenerator and ToolInvoker +pipeline = Pipeline() +pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=[tool])) +pipeline.add_component("tool_invoker", ToolInvoker(tools=[tool])) + +# Connect components +pipeline.connect("llm.replies", "tool_invoker.messages") + +message = ChatMessage.from_user("Use the web search tool to find information about Nikola Tesla") + +# Run pipeline +result = pipeline.run({"llm": {"messages": [message]}}) + +print(result) +``` + + + +#### ComponentTool.\_\_init\_\_ + +```python +def __init__( + component: Component, + name: Optional[str] = None, + description: Optional[str] = None, + parameters: Optional[dict[str, Any]] = None, + *, + outputs_to_string: Optional[dict[str, Union[str, Callable[[Any], + str]]]] = None, + inputs_from_state: Optional[dict[str, str]] = None, + outputs_to_state: Optional[dict[str, dict[str, Union[str, + Callable]]]] = None +) -> None +``` + +Create a Tool instance from a Haystack component. + +**Arguments**: + +- `component`: The Haystack component to wrap as a tool. +- `name`: Optional name for the tool (defaults to snake_case of component class name). +- `description`: Optional description (defaults to component's docstring). +- `parameters`: A JSON schema defining the parameters expected by the Tool. +Will fall back to the parameters defined in the component's run method signature if not provided. +- `outputs_to_string`: Optional dictionary defining how a tool outputs should be converted into a string. +If the source is provided only the specified output key is sent to the handler. +If the source is omitted the whole tool result is sent to the handler. +Example: +```python +{ + "source": "docs", "handler": format_documents +} +``` +- `inputs_from_state`: Optional dictionary mapping state keys to tool parameter names. +Example: `{"repository": "repo"}` maps state's "repository" to tool's "repo" parameter. +- `outputs_to_state`: Optional dictionary defining how tool outputs map to keys within state as well as optional handlers. +If the source is provided only the specified output key is sent to the handler. +Example: +```python +{ + "documents": {"source": "docs", "handler": custom_handler} +} +``` +If the source is omitted the whole tool result is sent to the handler. +Example: +```python +{ + "documents": {"handler": custom_handler} +} +``` + +**Raises**: + +- `ValueError`: If the component is invalid or schema generation fails. + + + +#### ComponentTool.warm\_up + +```python +def warm_up() +``` + +Prepare the ComponentTool for use. + + + +#### ComponentTool.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the ComponentTool to a dictionary. + + + +#### ComponentTool.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "ComponentTool" +``` + +Deserializes the ComponentTool from a dictionary. + + + +#### ComponentTool.tool\_spec + +```python +@property +def tool_spec() -> dict[str, Any] +``` + +Return the Tool specification to be used by the Language Model. + + + +#### ComponentTool.invoke + +```python +def invoke(**kwargs: Any) -> Any +``` + +Invoke the Tool with the provided keyword arguments. + + + +## Module toolset + + + +### Toolset + +A collection of related Tools that can be used and managed as a cohesive unit. + +Toolset serves two main purposes: + +1. Group related tools together: +Toolset allows you to organize related tools into a single collection, making it easier +to manage and use them as a unit in Haystack pipelines. + +**Example**: + + ```python + from haystack.tools import Tool, Toolset + from haystack.components.tools import ToolInvoker + + # Define math functions + def add_numbers(a: int, b: int) -> int: + return a + b + + def subtract_numbers(a: int, b: int) -> int: + return a - b + + # Create tools with proper schemas + add_tool = Tool( + name="add", + description="Add two numbers", + parameters={ + "type": "object", + "properties": { + "a": {"type": "integer"}, + "b": {"type": "integer"} + }, + "required": ["a", "b"] + }, + function=add_numbers + ) + + subtract_tool = Tool( + name="subtract", + description="Subtract b from a", + parameters={ + "type": "object", + "properties": { + "a": {"type": "integer"}, + "b": {"type": "integer"} + }, + "required": ["a", "b"] + }, + function=subtract_numbers + ) + + # Create a toolset with the math tools + math_toolset = Toolset([add_tool, subtract_tool]) + + # Use the toolset with a ToolInvoker or ChatGenerator component + invoker = ToolInvoker(tools=math_toolset) + ``` + + 2. Base class for dynamic tool loading: + By subclassing Toolset, you can create implementations that dynamically load tools + from external sources like OpenAPI URLs, MCP servers, or other resources. + + +**Example**: + + ```python + from haystack.core.serialization import generate_qualified_class_name + from haystack.tools import Tool, Toolset + from haystack.components.tools import ToolInvoker + + class CalculatorToolset(Toolset): + '''A toolset for calculator operations.''' + + def __init__(self): + tools = self._create_tools() + super().__init__(tools) + + def _create_tools(self): + # These Tool instances are obviously defined statically and for illustration purposes only. + # In a real-world scenario, you would dynamically load tools from an external source here. + tools = [] + add_tool = Tool( + name="add", + description="Add two numbers", + parameters={ + "type": "object", + "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}}, + "required": ["a", "b"], + }, + function=lambda a, b: a + b, + ) + + multiply_tool = Tool( + name="multiply", + description="Multiply two numbers", + parameters={ + "type": "object", + "properties": {"a": {"type": "integer"}, "b": {"type": "integer"}}, + "required": ["a", "b"], + }, + function=lambda a, b: a * b, + ) + + tools.append(add_tool) + tools.append(multiply_tool) + + return tools + + def to_dict(self): + return { + "type": generate_qualified_class_name(type(self)), + "data": {}, # no data to serialize as we define the tools dynamically + } + + @classmethod + def from_dict(cls, data): + return cls() # Recreate the tools dynamically during deserialization + + # Create the dynamic toolset and use it with ToolInvoker + calculator_toolset = CalculatorToolset() + invoker = ToolInvoker(tools=calculator_toolset) + ``` + + Toolset implements the collection interface (__iter__, __contains__, __len__, __getitem__), + making it behave like a list of Tools. This makes it compatible with components that expect + iterable tools, such as ToolInvoker or Haystack chat generators. + + When implementing a custom Toolset subclass for dynamic tool loading: + - Perform the dynamic loading in the __init__ method + - Override to_dict() and from_dict() methods if your tools are defined dynamically + - Serialize endpoint descriptors rather than tool instances if your tools + are loaded from external sources + + + +#### Toolset.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Validate and set up the toolset after initialization. + +This handles the case when tools are provided during initialization. + + + +#### Toolset.\_\_iter\_\_ + +```python +def __iter__() -> Iterator[Tool] +``` + +Return an iterator over the Tools in this Toolset. + +This allows the Toolset to be used wherever a list of Tools is expected. + +**Returns**: + +An iterator yielding Tool instances + + + +#### Toolset.\_\_contains\_\_ + +```python +def __contains__(item: Any) -> bool +``` + +Check if a tool is in this Toolset. + +Supports checking by: +- Tool instance: tool in toolset +- Tool name: "tool_name" in toolset + +**Arguments**: + +- `item`: Tool instance or tool name string + +**Returns**: + +True if contained, False otherwise + + + +#### Toolset.warm\_up + +```python +def warm_up() -> None +``` + +Prepare the Toolset for use. + +By default, this method iterates through and warms up all tools in the Toolset. +Subclasses can override this method to customize initialization behavior, such as: + +- Setting up shared resources (database connections, HTTP sessions) instead of + warming individual tools +- Implementing custom initialization logic for dynamically loaded tools +- Controlling when and how tools are initialized + +For example, a Toolset that manages tools from an external service (like MCPToolset) +might override this to initialize a shared connection rather than warming up +individual tools: + +```python +class MCPToolset(Toolset): + def warm_up(self) -> None: + # Only warm up the shared MCP connection, not individual tools + self.mcp_connection = establish_connection(self.server_url) +``` + +This method should be idempotent, as it may be called multiple times. + + + +#### Toolset.add + +```python +def add(tool: Union[Tool, "Toolset"]) -> None +``` + +Add a new Tool or merge another Toolset. + +**Arguments**: + +- `tool`: A Tool instance or another Toolset to add + +**Raises**: + +- `ValueError`: If adding the tool would result in duplicate tool names +- `TypeError`: If the provided object is not a Tool or Toolset + + + +#### Toolset.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the Toolset to a dictionary. + +**Returns**: + +A dictionary representation of the Toolset +Note for subclass implementers: +The default implementation is ideal for scenarios where Tool resolution is static. However, if your subclass +of Toolset dynamically resolves Tool instances from external sources—such as an MCP server, OpenAPI URL, or +a local OpenAPI specification—you should consider serializing the endpoint descriptor instead of the Tool +instances themselves. This strategy preserves the dynamic nature of your Toolset and minimizes the overhead +associated with serializing potentially large collections of Tool objects. Moreover, by serializing the +descriptor, you ensure that the deserialization process can accurately reconstruct the Tool instances, even +if they have been modified or removed since the last serialization. Failing to serialize the descriptor may +lead to issues where outdated or incorrect Tool configurations are loaded, potentially causing errors or +unexpected behavior. + + + +#### Toolset.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Toolset" +``` + +Deserialize a Toolset from a dictionary. + +**Arguments**: + +- `data`: Dictionary representation of the Toolset + +**Returns**: + +A new Toolset instance + + + +#### Toolset.\_\_add\_\_ + +```python +def __add__(other: Union[Tool, "Toolset", list[Tool]]) -> "Toolset" +``` + +Concatenate this Toolset with another Tool, Toolset, or list of Tools. + +**Arguments**: + +- `other`: Another Tool, Toolset, or list of Tools to concatenate + +**Raises**: + +- `TypeError`: If the other parameter is not a Tool, Toolset, or list of Tools +- `ValueError`: If the combination would result in duplicate tool names + +**Returns**: + +A new Toolset containing all tools + + + +#### Toolset.\_\_len\_\_ + +```python +def __len__() -> int +``` + +Return the number of Tools in this Toolset. + +**Returns**: + +Number of Tools + + + +#### Toolset.\_\_getitem\_\_ + +```python +def __getitem__(index) +``` + +Get a Tool by index. + +**Arguments**: + +- `index`: Index of the Tool to get + +**Returns**: + +The Tool at the specified index + + + +### \_ToolsetWrapper + +A wrapper that holds multiple toolsets and provides a unified interface. + +This is used internally when combining different types of toolsets to preserve +their individual configurations while still being usable with ToolInvoker. + + + +#### \_ToolsetWrapper.\_\_iter\_\_ + +```python +def __iter__() +``` + +Iterate over all tools from all toolsets. + + + +#### \_ToolsetWrapper.\_\_contains\_\_ + +```python +def __contains__(item) +``` + +Check if a tool is in any of the toolsets. + + + +#### \_ToolsetWrapper.warm\_up + +```python +def warm_up() +``` + +Warm up all toolsets. + + + +#### \_ToolsetWrapper.\_\_len\_\_ + +```python +def __len__() +``` + +Return total number of tools across all toolsets. + + + +#### \_ToolsetWrapper.\_\_getitem\_\_ + +```python +def __getitem__(index) +``` + +Get a tool by index across all toolsets. + + + +#### \_ToolsetWrapper.\_\_add\_\_ + +```python +def __add__(other) +``` + +Add another toolset or tool to this wrapper. + + + +#### \_ToolsetWrapper.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Validate and set up the toolset after initialization. + +This handles the case when tools are provided during initialization. + + + +#### \_ToolsetWrapper.add + +```python +def add(tool: Union[Tool, "Toolset"]) -> None +``` + +Add a new Tool or merge another Toolset. + +**Arguments**: + +- `tool`: A Tool instance or another Toolset to add + +**Raises**: + +- `ValueError`: If adding the tool would result in duplicate tool names +- `TypeError`: If the provided object is not a Tool or Toolset + + + +#### \_ToolsetWrapper.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the Toolset to a dictionary. + +**Returns**: + +A dictionary representation of the Toolset +Note for subclass implementers: +The default implementation is ideal for scenarios where Tool resolution is static. However, if your subclass +of Toolset dynamically resolves Tool instances from external sources—such as an MCP server, OpenAPI URL, or +a local OpenAPI specification—you should consider serializing the endpoint descriptor instead of the Tool +instances themselves. This strategy preserves the dynamic nature of your Toolset and minimizes the overhead +associated with serializing potentially large collections of Tool objects. Moreover, by serializing the +descriptor, you ensure that the deserialization process can accurately reconstruct the Tool instances, even +if they have been modified or removed since the last serialization. Failing to serialize the descriptor may +lead to issues where outdated or incorrect Tool configurations are loaded, potentially causing errors or +unexpected behavior. + + + +#### \_ToolsetWrapper.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Toolset" +``` + +Deserialize a Toolset from a dictionary. + +**Arguments**: + +- `data`: Dictionary representation of the Toolset + +**Returns**: + +A new Toolset instance + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/utils_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/utils_api.md new file mode 100644 index 0000000000..91752efc9b --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/utils_api.md @@ -0,0 +1,1298 @@ +--- +title: "Utils" +id: utils-api +description: "Utility functions and classes used across the library." +slug: "/utils-api" +--- + + + +## Module azure + + + +#### default\_azure\_ad\_token\_provider + +```python +def default_azure_ad_token_provider() -> str +``` + +Get a Azure AD token using the DefaultAzureCredential and the "https://cognitiveservices.azure.com/.default" scope. + + + +## Module jupyter + + + +#### is\_in\_jupyter + +```python +def is_in_jupyter() -> bool +``` + +Returns `True` if in Jupyter or Google Colab, `False` otherwise. + + + +## Module url\_validation + + + +#### is\_valid\_http\_url + +```python +def is_valid_http_url(url: str) -> bool +``` + +Check if a URL is a valid HTTP/HTTPS URL. + + + +## Module auth + + + +### SecretType + + + +#### SecretType.from\_str + +```python +@staticmethod +def from_str(string: str) -> "SecretType" +``` + +Convert a string to a SecretType. + +**Arguments**: + +- `string`: The string to convert. + + + +### Secret + +Encapsulates a secret used for authentication. + +Usage example: +```python +from haystack.components.generators import OpenAIGenerator +from haystack.utils import Secret + +generator = OpenAIGenerator(api_key=Secret.from_token("")) +``` + + + +#### Secret.from\_token + +```python +@staticmethod +def from_token(token: str) -> "Secret" +``` + +Create a token-based secret. Cannot be serialized. + +**Arguments**: + +- `token`: The token to use for authentication. + + + +#### Secret.from\_env\_var + +```python +@staticmethod +def from_env_var(env_vars: Union[str, list[str]], + *, + strict: bool = True) -> "Secret" +``` + +Create an environment variable-based secret. Accepts one or more environment variables. + +Upon resolution, it returns a string token from the first environment variable that is set. + +**Arguments**: + +- `env_vars`: A single environment variable or an ordered list of +candidate environment variables. +- `strict`: Whether to raise an exception if none of the environment +variables are set. + + + +#### Secret.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert the secret to a JSON-serializable dictionary. + +Some secrets may not be serializable. + +**Returns**: + +The serialized policy. + + + +#### Secret.from\_dict + +```python +@staticmethod +def from_dict(dict: dict[str, Any]) -> "Secret" +``` + +Create a secret from a JSON-serializable dictionary. + +**Arguments**: + +- `dict`: The dictionary with the serialized data. + +**Returns**: + +The deserialized secret. + + + +#### Secret.resolve\_value + +```python +@abstractmethod +def resolve_value() -> Optional[Any] +``` + +Resolve the secret to an atomic value. The semantics of the value is secret-dependent. + +**Returns**: + +The value of the secret, if any. + + + +#### Secret.type + +```python +@property +@abstractmethod +def type() -> SecretType +``` + +The type of the secret. + + + +#### deserialize\_secrets\_inplace + +```python +def deserialize_secrets_inplace(data: dict[str, Any], + keys: Iterable[str], + *, + recursive: bool = False) -> None +``` + +Deserialize secrets in a dictionary inplace. + +**Arguments**: + +- `data`: The dictionary with the serialized data. +- `keys`: The keys of the secrets to deserialize. +- `recursive`: Whether to recursively deserialize nested dictionaries. + + + +## Module callable\_serialization + + + +#### serialize\_callable + +```python +def serialize_callable(callable_handle: Callable) -> str +``` + +Serializes a callable to its full path. + +**Arguments**: + +- `callable_handle`: The callable to serialize + +**Returns**: + +The full path of the callable + + + +#### deserialize\_callable + +```python +def deserialize_callable(callable_handle: str) -> Callable +``` + +Deserializes a callable given its full import path as a string. + +**Arguments**: + +- `callable_handle`: The full path of the callable_handle + +**Raises**: + +- `DeserializationError`: If the callable cannot be found + +**Returns**: + +The callable + + + +## Module asynchronous + + + +#### is\_callable\_async\_compatible + +```python +def is_callable_async_compatible(func: Callable) -> bool +``` + +Returns if the given callable is usable inside a component's `run_async` method. + +**Arguments**: + +- `callable`: The callable to check. + +**Returns**: + +True if the callable is compatible, False otherwise. + + + +## Module requests\_utils + + + +#### request\_with\_retry + +```python +def request_with_retry(attempts: int = 3, + status_codes_to_retry: Optional[list[int]] = None, + **kwargs: Any) -> requests.Response +``` + +Executes an HTTP request with a configurable exponential backoff retry on failures. + +Usage example: +```python +from haystack.utils import request_with_retry + +# Sending an HTTP request with default retry configs +res = request_with_retry(method="GET", url="https://example.com") + +# Sending an HTTP request with custom number of attempts +res = request_with_retry(method="GET", url="https://example.com", attempts=10) + +# Sending an HTTP request with custom HTTP codes to retry +res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503]) + +# Sending an HTTP request with custom timeout in seconds +res = request_with_retry(method="GET", url="https://example.com", timeout=5) + +# Sending an HTTP request with custom authorization handling +class CustomAuth(requests.auth.AuthBase): + def __call__(self, r): + r.headers["authorization"] = "Basic " + return r + +res = request_with_retry(method="GET", url="https://example.com", auth=CustomAuth()) + +# All of the above combined +res = request_with_retry( + method="GET", + url="https://example.com", + auth=CustomAuth(), + attempts=10, + status_codes_to_retry=[408, 503], + timeout=5 +) + +# Sending a POST request +res = request_with_retry(method="POST", url="https://example.com", data={"key": "value"}, attempts=10) + +# Retry all 5xx status codes +res = request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=list(range(500, 600))) +``` + +**Arguments**: + +- `attempts`: Maximum number of attempts to retry the request. +- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry. +When param is `None`, HTTP 408, 418, 429 and 503 will be retried. +- `kwargs`: Optional arguments that `request` accepts. + +**Returns**: + +The `Response` object. + + + +#### async\_request\_with\_retry + +```python +async def async_request_with_retry(attempts: int = 3, + status_codes_to_retry: Optional[ + list[int]] = None, + **kwargs: Any) -> httpx.Response +``` + +Executes an asynchronous HTTP request with a configurable exponential backoff retry on failures. + +Usage example: +```python +import asyncio +from haystack.utils import async_request_with_retry + +# Sending an async HTTP request with default retry configs +async def example(): + res = await async_request_with_retry(method="GET", url="https://example.com") + return res + +# Sending an async HTTP request with custom number of attempts +async def example_with_attempts(): + res = await async_request_with_retry(method="GET", url="https://example.com", attempts=10) + return res + +# Sending an async HTTP request with custom HTTP codes to retry +async def example_with_status_codes(): + res = await async_request_with_retry(method="GET", url="https://example.com", status_codes_to_retry=[408, 503]) + return res + +# Sending an async HTTP request with custom timeout in seconds +async def example_with_timeout(): + res = await async_request_with_retry(method="GET", url="https://example.com", timeout=5) + return res + +# Sending an async HTTP request with custom headers +async def example_with_headers(): + headers = {"Authorization": "Bearer "} + res = await async_request_with_retry(method="GET", url="https://example.com", headers=headers) + return res + +# All of the above combined +async def example_combined(): + headers = {"Authorization": "Bearer "} + res = await async_request_with_retry( + method="GET", + url="https://example.com", + headers=headers, + attempts=10, + status_codes_to_retry=[408, 503], + timeout=5 + ) + return res + +# Sending an async POST request +async def example_post(): + res = await async_request_with_retry( + method="POST", + url="https://example.com", + json={"key": "value"}, + attempts=10 + ) + return res + +# Retry all 5xx status codes +async def example_5xx(): + res = await async_request_with_retry( + method="GET", + url="https://example.com", + status_codes_to_retry=list(range(500, 600)) + ) + return res +``` + +**Arguments**: + +- `attempts`: Maximum number of attempts to retry the request. +- `status_codes_to_retry`: List of HTTP status codes that will trigger a retry. +When param is `None`, HTTP 408, 418, 429 and 503 will be retried. +- `kwargs`: Optional arguments that `httpx.AsyncClient.request` accepts. + +**Returns**: + +The `httpx.Response` object. + + + +## Module filters + + + +#### raise\_on\_invalid\_filter\_syntax + +```python +def raise_on_invalid_filter_syntax( + filters: Optional[dict[str, Any]] = None) -> None +``` + +Raise an error if the filter syntax is invalid. + + + +#### document\_matches\_filter + +```python +def document_matches_filter(filters: dict[str, Any], + document: Union[Document, ByteStream]) -> bool +``` + +Return whether `filters` match the Document or the ByteStream. + +For a detailed specification of the filters, refer to the +`DocumentStore.filter_documents()` protocol documentation. + + + +## Module misc + + + +#### expand\_page\_range + +```python +def expand_page_range(page_range: list[Union[str, int]]) -> list[int] +``` + +Takes a list of page numbers and ranges and expands them into a list of page numbers. + +For example, given a page_range=['1-3', '5', '8', '10-12'] the function will return [1, 2, 3, 5, 8, 10, 11, 12] + +**Arguments**: + +- `page_range`: List of page numbers and ranges + +**Returns**: + +An expanded list of page integers + + + +#### expit + +```python +def expit( + x: Union[float, ndarray[Any, Any]]) -> Union[float, ndarray[Any, Any]] +``` + +Compute logistic sigmoid function. Maps input values to a range between 0 and 1 + +**Arguments**: + +- `x`: input value. Can be a scalar or a numpy array. + + + +## Module device + + + +### DeviceType + +Represents device types supported by Haystack. + +This also includes devices that are not directly used by models - for example, the disk device is exclusively used +in device maps for frameworks that support offloading model weights to disk. + + + +#### DeviceType.from\_str + +```python +@staticmethod +def from_str(string: str) -> "DeviceType" +``` + +Create a device type from a string. + +**Arguments**: + +- `string`: The string to convert. + +**Returns**: + +The device type. + + + +### Device + +A generic representation of a device. + +**Arguments**: + +- `type`: The device type. +- `id`: The optional device id. + + + +#### Device.\_\_init\_\_ + +```python +def __init__(type: DeviceType, id: Optional[int] = None) +``` + +Create a generic device. + +**Arguments**: + +- `type`: The device type. +- `id`: The device id. + + + +#### Device.cpu + +```python +@staticmethod +def cpu() -> "Device" +``` + +Create a generic CPU device. + +**Returns**: + +The CPU device. + + + +#### Device.gpu + +```python +@staticmethod +def gpu(id: int = 0) -> "Device" +``` + +Create a generic GPU device. + +**Arguments**: + +- `id`: The GPU id. + +**Returns**: + +The GPU device. + + + +#### Device.disk + +```python +@staticmethod +def disk() -> "Device" +``` + +Create a generic disk device. + +**Returns**: + +The disk device. + + + +#### Device.mps + +```python +@staticmethod +def mps() -> "Device" +``` + +Create a generic Apple Metal Performance Shader device. + +**Returns**: + +The MPS device. + + + +#### Device.xpu + +```python +@staticmethod +def xpu() -> "Device" +``` + +Create a generic Intel GPU Optimization device. + +**Returns**: + +The XPU device. + + + +#### Device.from\_str + +```python +@staticmethod +def from_str(string: str) -> "Device" +``` + +Create a generic device from a string. + +**Returns**: + +The device. + + + +### DeviceMap + +A generic mapping from strings to devices. + +The semantics of the strings are dependent on target framework. Primarily used to deploy HuggingFace models to +multiple devices. + +**Arguments**: + +- `mapping`: Dictionary mapping strings to devices. + + + +#### DeviceMap.to\_dict + +```python +def to_dict() -> dict[str, str] +``` + +Serialize the mapping to a JSON-serializable dictionary. + +**Returns**: + +The serialized mapping. + + + +#### DeviceMap.first\_device + +```python +@property +def first_device() -> Optional[Device] +``` + +Return the first device in the mapping, if any. + +**Returns**: + +The first device. + + + +#### DeviceMap.from\_dict + +```python +@staticmethod +def from_dict(dict: dict[str, str]) -> "DeviceMap" +``` + +Create a generic device map from a JSON-serialized dictionary. + +**Arguments**: + +- `dict`: The serialized mapping. + +**Returns**: + +The generic device map. + + + +#### DeviceMap.from\_hf + +```python +@staticmethod +def from_hf( + hf_device_map: dict[str, Union[int, str, + "torch.device"]]) -> "DeviceMap" +``` + +Create a generic device map from a HuggingFace device map. + +**Arguments**: + +- `hf_device_map`: The HuggingFace device map. + +**Returns**: + +The deserialized device map. + + + +### ComponentDevice + +A representation of a device for a component. + +This can be either a single device or a device map. + + + +#### ComponentDevice.from\_str + +```python +@classmethod +def from_str(cls, device_str: str) -> "ComponentDevice" +``` + +Create a component device representation from a device string. + +The device string can only represent a single device. + +**Arguments**: + +- `device_str`: The device string. + +**Returns**: + +The component device representation. + + + +#### ComponentDevice.from\_single + +```python +@classmethod +def from_single(cls, device: Device) -> "ComponentDevice" +``` + +Create a component device representation from a single device. + +Disks cannot be used as single devices. + +**Arguments**: + +- `device`: The device. + +**Returns**: + +The component device representation. + + + +#### ComponentDevice.from\_multiple + +```python +@classmethod +def from_multiple(cls, device_map: DeviceMap) -> "ComponentDevice" +``` + +Create a component device representation from a device map. + +**Arguments**: + +- `device_map`: The device map. + +**Returns**: + +The component device representation. + + + +#### ComponentDevice.to\_torch + +```python +def to_torch() -> "torch.device" +``` + +Convert the component device representation to PyTorch format. + +Device maps are not supported. + +**Returns**: + +The PyTorch device representation. + + + +#### ComponentDevice.to\_torch\_str + +```python +def to_torch_str() -> str +``` + +Convert the component device representation to PyTorch string format. + +Device maps are not supported. + +**Returns**: + +The PyTorch device string representation. + + + +#### ComponentDevice.to\_spacy + +```python +def to_spacy() -> int +``` + +Convert the component device representation to spaCy format. + +Device maps are not supported. + +**Returns**: + +The spaCy device representation. + + + +#### ComponentDevice.to\_hf + +```python +def to_hf() -> Union[Union[int, str], dict[str, Union[int, str]]] +``` + +Convert the component device representation to HuggingFace format. + +**Returns**: + +The HuggingFace device representation. + + + +#### ComponentDevice.update\_hf\_kwargs + +```python +def update_hf_kwargs(hf_kwargs: dict[str, Any], *, + overwrite: bool) -> dict[str, Any] +``` + +Convert the component device representation to HuggingFace format. + +Add them as canonical keyword arguments to the keyword arguments dictionary. + +**Arguments**: + +- `hf_kwargs`: The HuggingFace keyword arguments dictionary. +- `overwrite`: Whether to overwrite existing device arguments. + +**Returns**: + +The HuggingFace keyword arguments dictionary. + + + +#### ComponentDevice.has\_multiple\_devices + +```python +@property +def has_multiple_devices() -> bool +``` + +Whether this component device representation contains multiple devices. + + + +#### ComponentDevice.first\_device + +```python +@property +def first_device() -> Optional["ComponentDevice"] +``` + +Return either the single device or the first device in the device map, if any. + +**Returns**: + +The first device. + + + +#### ComponentDevice.resolve\_device + +```python +@staticmethod +def resolve_device( + device: Optional["ComponentDevice"] = None) -> "ComponentDevice" +``` + +Select a device for a component. If a device is specified, it's used. Otherwise, the default device is used. + +**Arguments**: + +- `device`: The provided device, if any. + +**Returns**: + +The resolved device. + + + +#### ComponentDevice.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Convert the component device representation to a JSON-serializable dictionary. + +**Returns**: + +The dictionary representation. + + + +#### ComponentDevice.from\_dict + +```python +@classmethod +def from_dict(cls, dict: dict[str, Any]) -> "ComponentDevice" +``` + +Create a component device representation from a JSON-serialized dictionary. + +**Arguments**: + +- `dict`: The serialized representation. + +**Returns**: + +The deserialized component device. + + + +## Module http\_client + + + +#### init\_http\_client + +```python +def init_http_client( + http_client_kwargs: Optional[dict[str, Any]] = None, + async_client: bool = False +) -> Union[httpx.Client, httpx.AsyncClient, None] +``` + +Initialize an httpx client based on the http_client_kwargs. + +**Arguments**: + +- `http_client_kwargs`: The kwargs to pass to the httpx client. +- `async_client`: Whether to initialize an async client. + +**Returns**: + +A httpx client or an async httpx client. + + + +## Module type\_serialization + + + +#### serialize\_type + +```python +def serialize_type(target: Any) -> str +``` + +Serializes a type or an instance to its string representation, including the module name. + +This function handles types, instances of types, and special typing objects. +It assumes that non-typing objects will have a '__name__' attribute. + +**Arguments**: + +- `target`: The object to serialize, can be an instance or a type. + +**Returns**: + +The string representation of the type. + + + +#### deserialize\_type + +```python +def deserialize_type(type_str: str) -> Any +``` + +Deserializes a type given its full import path as a string, including nested generic types. + +This function will dynamically import the module if it's not already imported +and then retrieve the type object from it. It also handles nested generic types like +`list[dict[int, str]]`. + +**Arguments**: + +- `type_str`: The string representation of the type's full import path. + +**Raises**: + +- `DeserializationError`: If the type cannot be deserialized due to missing module or type. + +**Returns**: + +The deserialized type object. + + + +#### thread\_safe\_import + +```python +def thread_safe_import(module_name: str) -> ModuleType +``` + +Import a module in a thread-safe manner. + +Importing modules in a multi-threaded environment can lead to race conditions. +This function ensures that the module is imported in a thread-safe manner without having impact +on the performance of the import for single-threaded environments. + +**Arguments**: + +- `module_name`: the module to import + + + +## Module jinja2\_chat\_extension + + + +### ChatMessageExtension + +A Jinja2 extension for creating structured chat messages with mixed content types. + +This extension provides a custom `{% message %}` tag that allows creating chat messages +with different attributes (role, name, meta) and mixed content types (text, images, etc.). + +Inspired by [Banks](https://github.com/masci/banks). + +**Example**: + +``` +{% message role="system" %} +You are a helpful assistant. You like to talk with {{user_name}}. +{% endmessage %} + +{% message role="user" %} +Hello! I am {{user_name}}. Please describe the images. +{% for image in images %} +{{ image | templatize_part }} +{% endfor %} +{% endmessage %} +``` + + ### How it works + 1. The `{% message %}` tag is used to define a chat message. + 2. The message can contain text and other structured content parts. + 3. To include a structured content part in the message, the `| templatize_part` filter is used. + The filter serializes the content part into a JSON string and wraps it in a `` tag. + 4. The `_build_chat_message_json` method of the extension parses the message content parts, + converts them into a ChatMessage object and serializes it to a JSON string. + 5. The obtained JSON string is usable in the ChatPromptBuilder component, where templates are rendered to actual + ChatMessage objects. + + + +#### ChatMessageExtension.parse + +```python +def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]] +``` + +Parse the message tag and its attributes in the Jinja2 template. + +This method handles the parsing of role (mandatory), name (optional), meta (optional) and message body content. + +**Arguments**: + +- `parser`: The Jinja2 parser instance + +**Raises**: + +- `TemplateSyntaxError`: If an invalid role is provided + +**Returns**: + +A CallBlock node containing the parsed message configuration + + + +#### templatize\_part + +```python +def templatize_part(value: ChatMessageContentT) -> str +``` + +Jinja filter to convert an ChatMessageContentT object into JSON string wrapped in special XML content tags. + +**Arguments**: + +- `value`: The ChatMessageContentT object to convert + +**Raises**: + +- `ValueError`: If the value is not an instance of ChatMessageContentT + +**Returns**: + +A JSON string wrapped in special XML content tags + + + +## Module jinja2\_extensions + + + +### Jinja2TimeExtension + + + +#### Jinja2TimeExtension.\_\_init\_\_ + +```python +def __init__(environment: Environment) +``` + +Initializes the JinjaTimeExtension object. + +**Arguments**: + +- `environment`: The Jinja2 environment to initialize the extension with. +It provides the context where the extension will operate. + + + +#### Jinja2TimeExtension.parse + +```python +def parse(parser: Any) -> Union[nodes.Node, list[nodes.Node]] +``` + +Parse the template expression to determine how to handle the datetime formatting. + +**Arguments**: + +- `parser`: The parser object that processes the template expressions and manages the syntax tree. +It's used to interpret the template's structure. + + + +## Module deserialization + + + +#### deserialize\_document\_store\_in\_init\_params\_inplace + +```python +def deserialize_document_store_in_init_params_inplace( + data: dict[str, Any], key: str = "document_store") -> None +``` + +Deserializes a generic document store from the init_parameters of a serialized component in place. + +**Arguments**: + +- `data`: The dictionary to deserialize from. +- `key`: The key in the `data["init_parameters"]` dictionary where the document store is specified. + +**Raises**: + +- `DeserializationError`: If the document store is not properly specified in the serialization data or its type cannot be imported. + +**Returns**: + +The dictionary, with the document store deserialized. + + + +#### deserialize\_chatgenerator\_inplace + +```python +def deserialize_chatgenerator_inplace(data: dict[str, Any], + key: str = "chat_generator") -> None +``` + +Deserialize a ChatGenerator in a dictionary inplace. + +**Arguments**: + +- `data`: The dictionary with the serialized data. +- `key`: The key in the dictionary where the ChatGenerator is stored. + +**Raises**: + +- `DeserializationError`: If the key is missing in the serialized data, the value is not a dictionary, +the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method. + + + +#### deserialize\_component\_inplace + +```python +def deserialize_component_inplace(data: dict[str, Any], + key: str = "chat_generator") -> None +``` + +Deserialize a Component in a dictionary inplace. + +**Arguments**: + +- `data`: The dictionary with the serialized data. +- `key`: The key in the dictionary where the Component is stored. Default is "chat_generator". + +**Raises**: + +- `DeserializationError`: If the key is missing in the serialized data, the value is not a dictionary, +the type key is missing, the class cannot be imported, or the class lacks a 'from_dict' method. + + + +## Module base\_serialization + + + +#### serialize\_class\_instance + +```python +def serialize_class_instance(obj: Any) -> dict[str, Any] +``` + +Serializes an object that has a `to_dict` method into a dictionary. + +**Arguments**: + +- `obj`: The object to be serialized. + +**Raises**: + +- `SerializationError`: If the object does not have a `to_dict` method. + +**Returns**: + +A dictionary representation of the object. + + + +#### deserialize\_class\_instance + +```python +def deserialize_class_instance(data: dict[str, Any]) -> Any +``` + +Deserializes an object from a dictionary representation generated by `auto_serialize_class_instance`. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Raises**: + +- `DeserializationError`: If the serialization data is malformed, the class type cannot be imported, or the +class does not have a `from_dict` method. + +**Returns**: + +The deserialized object. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/validators_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/validators_api.md new file mode 100644 index 0000000000..a52f0f1f4d --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/validators_api.md @@ -0,0 +1,145 @@ +--- +title: "Validators" +id: validators-api +description: "Validators validate LLM outputs" +slug: "/validators-api" +--- + + + +## Module json\_schema + + + +#### is\_valid\_json + +```python +def is_valid_json(s: str) -> bool +``` + +Check if the provided string is a valid JSON. + +**Arguments**: + +- `s`: The string to be checked. + +**Returns**: + +`True` if the string is a valid JSON; otherwise, `False`. + + + +### JsonSchemaValidator + +Validates JSON content of `ChatMessage` against a specified [JSON Schema](https://json-schema.org/). + +If JSON content of a message conforms to the provided schema, the message is passed along the "validated" output. +If the JSON content does not conform to the schema, the message is passed along the "validation_error" output. +In the latter case, the error message is constructed using the provided `error_template` or a default template. +These error ChatMessages can be used by LLMs in Haystack 2.x recovery loops. + +Usage example: + +```python +from haystack import Pipeline +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.joiners import BranchJoiner +from haystack.components.validators import JsonSchemaValidator +from haystack import component +from haystack.dataclasses import ChatMessage + + +@component +class MessageProducer: + + @component.output_types(messages=list[ChatMessage]) + def run(self, messages: list[ChatMessage]) -> dict: + return {"messages": messages} + + +p = Pipeline() +p.add_component("llm", OpenAIChatGenerator(model="gpt-4-1106-preview", + generation_kwargs={"response_format": {"type": "json_object"}})) +p.add_component("schema_validator", JsonSchemaValidator()) +p.add_component("joiner_for_llm", BranchJoiner(list[ChatMessage])) +p.add_component("message_producer", MessageProducer()) + +p.connect("message_producer.messages", "joiner_for_llm") +p.connect("joiner_for_llm", "llm") +p.connect("llm.replies", "schema_validator.messages") +p.connect("schema_validator.validation_error", "joiner_for_llm") + +result = p.run(data={ + "message_producer": { + "messages":[ChatMessage.from_user("Generate JSON for person with name 'John' and age 30")]}, + "schema_validator": { + "json_schema": { + "type": "object", + "properties": {"name": {"type": "string"}, + "age": {"type": "integer"} + } + } + } +}) +print(result) +>> {'schema_validator': {'validated': [ChatMessage(_role=, +_content=[TextContent(text="\n{\n "name": "John",\n "age": 30\n}")], +_name=None, _meta={'model': 'gpt-4-1106-preview', 'index': 0, +'finish_reason': 'stop', 'usage': {'completion_tokens': 17, 'prompt_tokens': 20, 'total_tokens': 37}})]}} +``` + + + +#### JsonSchemaValidator.\_\_init\_\_ + +```python +def __init__(json_schema: Optional[dict[str, Any]] = None, + error_template: Optional[str] = None) +``` + +Initialize the JsonSchemaValidator component. + +**Arguments**: + +- `json_schema`: A dictionary representing the [JSON schema](https://json-schema.org/) against which +the messages' content is validated. +- `error_template`: A custom template string for formatting the error message in case of validation failure. + + + +#### JsonSchemaValidator.run + +```python +@component.output_types(validated=list[ChatMessage], + validation_error=list[ChatMessage]) +def run(messages: list[ChatMessage], + json_schema: Optional[dict[str, Any]] = None, + error_template: Optional[str] = None) -> dict[str, list[ChatMessage]] +``` + +Validates the last of the provided messages against the specified json schema. + +If it does, the message is passed along the "validated" output. If it does not, the message is passed along +the "validation_error" output. + +**Arguments**: + +- `messages`: A list of ChatMessage instances to be validated. The last message in this list is the one +that is validated. +- `json_schema`: A dictionary representing the [JSON schema](https://json-schema.org/) +against which the messages' content is validated. If not provided, the schema from the component init +is used. +- `error_template`: A custom template string for formatting the error message in case of validation. If not +provided, the `error_template` from the component init is used. + +**Raises**: + +- `ValueError`: If no JSON schema is provided or if the message content is not a dictionary or a list of +dictionaries. + +**Returns**: + +A dictionary with the following keys: +- "validated": A list of messages if the last message is valid. +- "validation_error": A list of messages if the last message is invalid. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/websearch_api.md b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/websearch_api.md new file mode 100644 index 0000000000..49782a8bf8 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/haystack-api/websearch_api.md @@ -0,0 +1,228 @@ +--- +title: "Websearch" +id: websearch-api +description: "Web search engine for Haystack." +slug: "/websearch-api" +--- + + + +## Module serper\_dev + + + +### SerperDevWebSearch + +Uses [Serper](https://serper.dev/) to search the web for relevant documents. + +See the [Serper Dev website](https://serper.dev/) for more details. + +Usage example: +```python +from haystack.components.websearch import SerperDevWebSearch +from haystack.utils import Secret + +websearch = SerperDevWebSearch(top_k=10, api_key=Secret.from_token("test-api-key")) +results = websearch.run(query="Who is the boyfriend of Olivia Wilde?") + +assert results["documents"] +assert results["links"] + +# Example with domain filtering - exclude subdomains +websearch_filtered = SerperDevWebSearch( + top_k=10, + allowed_domains=["example.com"], + exclude_subdomains=True, # Only results from example.com, not blog.example.com + api_key=Secret.from_token("test-api-key") +) +results_filtered = websearch_filtered.run(query="search query") +``` + + + +#### SerperDevWebSearch.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("SERPERDEV_API_KEY"), + top_k: Optional[int] = 10, + allowed_domains: Optional[list[str]] = None, + search_params: Optional[dict[str, Any]] = None, + *, + exclude_subdomains: bool = False) +``` + +Initialize the SerperDevWebSearch component. + +**Arguments**: + +- `api_key`: API key for the Serper API. +- `top_k`: Number of documents to return. +- `allowed_domains`: List of domains to limit the search to. +- `exclude_subdomains`: Whether to exclude subdomains when filtering by allowed_domains. +If True, only results from the exact domains in allowed_domains will be returned. +If False, results from subdomains will also be included. Defaults to False. +- `search_params`: Additional parameters passed to the Serper API. +For example, you can set 'num' to 20 to increase the number of search results. +See the [Serper website](https://serper.dev/) for more details. + + + +#### SerperDevWebSearch.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SerperDevWebSearch.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "SerperDevWebSearch" +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SerperDevWebSearch.run + +```python +@component.output_types(documents=list[Document], links=list[str]) +def run(query: str) -> dict[str, Union[list[Document], list[str]]] +``` + +Use [Serper](https://serper.dev/) to search the web. + +**Arguments**: + +- `query`: Search query. + +**Raises**: + +- `SerperDevError`: If an error occurs while querying the SerperDev API. +- `TimeoutError`: If the request to the SerperDev API times out. + +**Returns**: + +A dictionary with the following keys: +- "documents": List of documents returned by the search engine. +- "links": List of links returned by the search engine. + + + +## Module searchapi + + + +### SearchApiWebSearch + +Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents. + +Usage example: +```python +from haystack.components.websearch import SearchApiWebSearch +from haystack.utils import Secret + +websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_token("test-api-key")) +results = websearch.run(query="Who is the boyfriend of Olivia Wilde?") + +assert results["documents"] +assert results["links"] +``` + + + +#### SearchApiWebSearch.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"), + top_k: Optional[int] = 10, + allowed_domains: Optional[list[str]] = None, + search_params: Optional[dict[str, Any]] = None) +``` + +Initialize the SearchApiWebSearch component. + +**Arguments**: + +- `api_key`: API key for the SearchApi API +- `top_k`: Number of documents to return. +- `allowed_domains`: List of domains to limit the search to. +- `search_params`: Additional parameters passed to the SearchApi API. +For example, you can set 'num' to 100 to increase the number of search results. +See the [SearchApi website](https://www.searchapi.io/) for more details. + +The default search engine is Google, however, users can change it by setting the `engine` +parameter in the `search_params`. + + + +#### SearchApiWebSearch.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SearchApiWebSearch.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "SearchApiWebSearch" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### SearchApiWebSearch.run + +```python +@component.output_types(documents=list[Document], links=list[str]) +def run(query: str) -> dict[str, Union[list[Document], list[str]]] +``` + +Uses [SearchApi](https://www.searchapi.io/) to search the web. + +**Arguments**: + +- `query`: Search query. + +**Raises**: + +- `TimeoutError`: If the request to the SearchApi API times out. +- `SearchApiError`: If an error occurs while querying the SearchApi API. + +**Returns**: + +A dictionary with the following keys: +- "documents": List of documents returned by the search engine. +- "links": List of links returned by the search engine. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/index.mdx b/docs-website/reference_versioned_docs/version-2.20-unstable/index.mdx new file mode 100644 index 0000000000..c00b968ea5 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/index.mdx @@ -0,0 +1,21 @@ +--- +id: api-index +title: API Documentation +sidebar_position: 1 +--- + +# API Reference + +Complete technical reference for Haystack classes, functions, and modules. + +## Haystack API + +Core framework API for the `haystack-ai` package. This includes all base components, pipelines, document stores, data classes, and utilities that make up the Haystack framework. + +## Integrations API + +API reference for official Haystack integrations distributed as separate packages (for example, `-haystack`). Each integration provides components that connect Haystack to external services, models, or platforms. For more information, see the [integrations documentation](/docs/integrations). + +## Experiments API + +API reference for experimental features. These APIs are under active development and may change in future releases. For more information, see the [experimental features documentation](/docs/experimental-package). diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/aimlapi.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/aimlapi.md new file mode 100644 index 0000000000..a70195df95 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/aimlapi.md @@ -0,0 +1,209 @@ +--- +title: "AIMLAPI" +id: integrations-aimlapi +description: "AIMLAPI integration for Haystack" +slug: "/integrations-aimlapi" +--- + + + +## Module haystack\_integrations.components.generators.aimlapi.chat.chat\_generator + + + +### AIMLAPIChatGenerator + +Enables text generation using AIMLAPI generative models. +For supported models, see AIMLAPI documentation. + +Users can pass any text generation parameters valid for the AIMLAPI chat completion API +directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +Key Features and Compatibility: +- **Primary Compatibility**: Designed to work seamlessly with the AIMLAPI chat completion endpoint. +- **Streaming Support**: Supports streaming responses from the AIMLAPI chat completion endpoint. +- **Customizability**: Supports all parameters supported by the AIMLAPI chat completion endpoint. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) + +For more details on the parameters supported by the AIMLAPI API, refer to the +AIMLAPI documentation. + +Usage example: +```python +from haystack_integrations.components.generators.aimlapi import AIMLAPIChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = AIMLAPIChatGenerator(model="openai/gpt-5-chat-latest") +response = client.run(messages) +print(response) + +>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence +>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is +>>meaningful and useful.', _role=, _name=None, +>>_meta={'model': 'openai/gpt-5-chat-latest', 'index': 0, 'finish_reason': 'stop', +>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]} +``` + + + +#### AIMLAPIChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("AIMLAPI_API_KEY"), + model: str = "openai/gpt-5-chat-latest", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = "https://api.aimlapi.com/v1", + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[Union[List[Tool], Toolset]] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Dict[str, Any]] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of AIMLAPIChatGenerator. Unless specified otherwise, + +the default model is `openai/gpt-5-chat-latest`. + +**Arguments**: + +- `api_key`: The AIMLAPI API key. +- `model`: The name of the AIMLAPI chat completion model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The AIMLAPI API Base url. +For more details, see AIMLAPI documentation. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the AIMLAPI endpoint. See AIMLAPI API docs for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `tools`: A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a +list of `Tool` objects or a `Toolset` instance. +- `timeout`: The timeout for the AIMLAPI API call. +- `extra_headers`: Additional HTTP headers to include in requests to the AIMLAPI API. +- `max_retries`: Maximum number of retries to contact AIMLAPI after an internal error. +If not set, it defaults to either the `AIMLAPI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### AIMLAPIChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AIMLAPIChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AIMLAPIChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes chat completion based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### AIMLAPIChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes chat completion based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_bedrock.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_bedrock.md new file mode 100644 index 0000000000..a9383e8173 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_bedrock.md @@ -0,0 +1,1637 @@ +--- +title: "Amazon Bedrock" +id: integrations-amazon-bedrock +description: "Amazon Bedrock integration for Haystack" +slug: "/integrations-amazon-bedrock" +--- + + + +## Module haystack\_integrations.common.amazon\_bedrock.errors + + + +### AmazonBedrockError + +Any error generated by the Amazon Bedrock integration. + +This error wraps its source transparently in such a way that its attributes +can be accessed directly: for example, if the original error has a `message` attribute, +`AmazonBedrockError.message` will exist and have the expected content. + + + +### AWSConfigurationError + +Exception raised when AWS is not configured correctly + + + +### AmazonBedrockConfigurationError + +Exception raised when AmazonBedrock node is not configured correctly + + + +### AmazonBedrockInferenceError + +Exception for issues that occur in the Bedrock inference node + + + +## Module haystack\_integrations.components.embedders.amazon\_bedrock.document\_embedder + + + +### AmazonBedrockDocumentEmbedder + +A component for computing Document embeddings using Amazon Bedrock. +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +import os +from haystack.dataclasses import Document +from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentEmbedder + +os.environ["AWS_ACCESS_KEY_ID"] = "..." +os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..." +os.environ["AWS_DEFAULT_REGION"] = "..." + +embedder = AmazonBedrockDocumentEmbedder( + model="cohere.embed-english-v3", + input_type="search_document", +) + +doc = Document(content="I love Paris in the winter.", meta={"name": "doc1"}) + +result = embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.002, 0.032, 0.504, ...] +``` + + + +#### AmazonBedrockDocumentEmbedder.\_\_init\_\_ + +```python +def __init__( + model: Literal[ + "amazon.titan-embed-text-v1", + "cohere.embed-english-v3", + "cohere.embed-multilingual-v3", + "amazon.titan-embed-text-v2:0", + "amazon.titan-embed-image-v1", + ], + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + "AWS_ACCESS_KEY_ID", strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + "AWS_SECRET_ACCESS_KEY", strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + "AWS_SESSION_TOKEN", strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + "AWS_DEFAULT_REGION", strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var("AWS_PROFILE", + strict=False), + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + boto3_config: Optional[Dict[str, Any]] = None, + **kwargs: Any) -> None +``` + +Initializes the AmazonBedrockDocumentEmbedder with the provided parameters. The parameters are passed to the + +Amazon Bedrock client. + +Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded +automatically from the environment or the AWS configuration file and do not need to be provided explicitly via +the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the +constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`, + and `aws_region_name`. + +**Arguments**: + +- `model`: The embedding model to use. The model has to be specified in the format outlined in the Amazon +Bedrock [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html). +- `aws_access_key_id`: AWS access key ID. +- `aws_secret_access_key`: AWS secret access key. +- `aws_session_token`: AWS session token. +- `aws_region_name`: AWS region name. +- `aws_profile_name`: AWS profile name. +- `batch_size`: Number of Documents to encode at once. +Only Cohere models support batch inference. This parameter is ignored for Amazon Titan models. +- `progress_bar`: Whether to show a progress bar or not. Can be helpful to disable in production deployments +to keep the logs clean. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. +- `boto3_config`: The configuration for the boto3 client. +- `kwargs`: Additional parameters to pass for model inference. For example, `input_type` and `truncate` for +Cohere models. + +**Raises**: + +- `ValueError`: If the model is not supported. +- `AmazonBedrockConfigurationError`: If the AWS environment is not configured correctly. + + + +#### AmazonBedrockDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Embed the provided `Document`s using the specified model. + +**Arguments**: + +- `documents`: The `Document`s to embed. + +**Raises**: + +- `AmazonBedrockInferenceError`: If the inference fails. + +**Returns**: + +A dictionary with the following keys: +- `documents`: The `Document`s with the `embedding` field populated. + + + +#### AmazonBedrockDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AmazonBedrockDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.components.embedders.amazon\_bedrock.text\_embedder + + + +### AmazonBedrockTextEmbedder + +A component for embedding strings using Amazon Bedrock. + +Usage example: +```python +import os +from haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockTextEmbedder + +os.environ["AWS_ACCESS_KEY_ID"] = "..." +os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..." +os.environ["AWS_DEFAULT_REGION"] = "..." + +embedder = AmazonBedrockTextEmbedder( + model="cohere.embed-english-v3", + input_type="search_query", +) + +print(text_embedder.run("I love Paris in the summer.")) + +# {'embedding': [0.002, 0.032, 0.504, ...]} +``` + + + +#### AmazonBedrockTextEmbedder.\_\_init\_\_ + +```python +def __init__( + model: Literal[ + "amazon.titan-embed-text-v1", + "cohere.embed-english-v3", + "cohere.embed-multilingual-v3", + "amazon.titan-embed-text-v2:0", + "amazon.titan-embed-image-v1", + ], + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + "AWS_ACCESS_KEY_ID", strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + "AWS_SECRET_ACCESS_KEY", strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + "AWS_SESSION_TOKEN", strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + "AWS_DEFAULT_REGION", strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var("AWS_PROFILE", + strict=False), + boto3_config: Optional[Dict[str, Any]] = None, + **kwargs: Any) -> None +``` + +Initializes the AmazonBedrockTextEmbedder with the provided parameters. The parameters are passed to the + +Amazon Bedrock client. + +Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded +automatically from the environment or the AWS configuration file and do not need to be provided explicitly via +the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the +constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`, + and `aws_region_name`. + +**Arguments**: + +- `model`: The embedding model to use. The model has to be specified in the format outlined in the Amazon +Bedrock [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html). +- `aws_access_key_id`: AWS access key ID. +- `aws_secret_access_key`: AWS secret access key. +- `aws_session_token`: AWS session token. +- `aws_region_name`: AWS region name. +- `aws_profile_name`: AWS profile name. +- `boto3_config`: The configuration for the boto3 client. +- `kwargs`: Additional parameters to pass for model inference. For example, `input_type` and `truncate` for +Cohere models. + +**Raises**: + +- `ValueError`: If the model is not supported. +- `AmazonBedrockConfigurationError`: If the AWS environment is not configured correctly. + + + +#### AmazonBedrockTextEmbedder.run + +```python +@component.output_types(embedding=List[float]) +def run(text: str) -> Dict[str, List[float]] +``` + +Embeds the input text using the Amazon Bedrock model. + +**Arguments**: + +- `text`: The input text to embed. + +**Raises**: + +- `TypeError`: If the input text is not a string. +- `AmazonBedrockInferenceError`: If the model inference fails. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. + + + +#### AmazonBedrockTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AmazonBedrockTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.components.embedders.amazon\_bedrock.document\_image\_embedder + + + +### AmazonBedrockDocumentImageEmbedder + +A component for computing Document embeddings based on images using Amazon Bedrock models. + +The embedding of each Document is stored in the `embedding` field of the Document. + +### Usage example +```python +from haystack import Document +rom haystack_integrations.components.embedders.amazon_bedrock import AmazonBedrockDocumentImageEmbedder + +os.environ["AWS_ACCESS_KEY_ID"] = "..." +os.environ["AWS_SECRET_ACCESS_KEY_ID"] = "..." +os.environ["AWS_DEFAULT_REGION"] = "..." + +embedder = AmazonBedrockDocumentImageEmbedder(model="amazon.titan-embed-image-v1") + +documents = [ + Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}), + Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}), +] + +result = embedder.run(documents=documents) +documents_with_embeddings = result["documents"] +print(documents_with_embeddings) + +# [Document(id=..., +# content='A photo of a cat', +# meta={'file_path': 'cat.jpg', +# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}}, +# embedding=vector of size 512), +# ...] +``` + + + +#### AmazonBedrockDocumentImageEmbedder.\_\_init\_\_ + +```python +def __init__( + *, + model: Literal["amazon.titan-embed-image-v1", + "cohere.embed-english-v3", + "cohere.embed-multilingual-v3"], + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + "AWS_ACCESS_KEY_ID", strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + "AWS_SECRET_ACCESS_KEY", strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + "AWS_SESSION_TOKEN", strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + "AWS_DEFAULT_REGION", strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var("AWS_PROFILE", + strict=False), + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + image_size: Optional[Tuple[int, int]] = None, + progress_bar: bool = True, + boto3_config: Optional[Dict[str, Any]] = None, + **kwargs: Any) -> None +``` + +Creates a AmazonBedrockDocumentImageEmbedder component. + +**Arguments**: + +- `model`: The Bedrock model to use for calculating embeddings. Pass a valid model ID. +Supported models: +- "amazon.titan-embed-image-v1" +- "cohere.embed-english-v3" +- "cohere.embed-multilingual-v3" +- `aws_access_key_id`: AWS access key ID. +- `aws_secret_access_key`: AWS secret access key. +- `aws_session_token`: AWS session token. +- `aws_region_name`: AWS region name. +- `aws_profile_name`: AWS profile name. +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `image_size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `progress_bar`: If `True`, shows a progress bar when embedding documents. +- `boto3_config`: The configuration for the boto3 client. +- `kwargs`: Additional parameters to pass for model inference. +For example, `embeddingConfig` for Amazon Titan models and +`embedding_types` for Cohere models. + +**Raises**: + +- `ValueError`: If the model is not supported. +- `AmazonBedrockConfigurationError`: If the AWS environment is not configured correctly. + + + +#### AmazonBedrockDocumentImageEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockDocumentImageEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, + Any]) -> "AmazonBedrockDocumentImageEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AmazonBedrockDocumentImageEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Embed a list of images. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + + + +## Module haystack\_integrations.components.generators.amazon\_bedrock.generator + + + +### AmazonBedrockGenerator + +Generates text using models hosted on Amazon Bedrock. + +For example, to use the Anthropic Claude model, pass 'anthropic.claude-v2' in the `model` parameter. +Provide AWS credentials either through the local AWS profile or directly through +`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`, and `aws_region_name` parameters. + +### Usage example + +```python +from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockGenerator + +generator = AmazonBedrockGenerator( + model="anthropic.claude-v2", + max_length=99 +) + +print(generator.run("Who is the best American actor?")) +``` + +AmazonBedrockGenerator uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. +For more information on setting up an IAM identity-based policy, see [Amazon Bedrock documentation] +(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html). +If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded +automatically from the environment or the AWS configuration file. +If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`, +`aws_session_token`, and `aws_region_name` as environment variables or pass them as + [Secret](https://docs.haystack.deepset.ai/v2.0/docs/secret-management) arguments. Make sure the region you set +supports Amazon Bedrock. + + + +#### AmazonBedrockGenerator.\_\_init\_\_ + +```python +def __init__( + model: str, + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + "AWS_ACCESS_KEY_ID", strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + "AWS_SECRET_ACCESS_KEY", strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + "AWS_SESSION_TOKEN", strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + "AWS_DEFAULT_REGION", strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var("AWS_PROFILE", + strict=False), + max_length: Optional[int] = None, + truncate: Optional[bool] = None, + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None, + boto3_config: Optional[Dict[str, Any]] = None, + model_family: Optional[MODEL_FAMILIES] = None, + **kwargs: Any) -> None +``` + +Create a new `AmazonBedrockGenerator` instance. + +**Arguments**: + +- `model`: The name of the model to use. +- `aws_access_key_id`: The AWS access key ID. +- `aws_secret_access_key`: The AWS secret access key. +- `aws_session_token`: The AWS session token. +- `aws_region_name`: The AWS region name. Make sure the region you set supports Amazon Bedrock. +- `aws_profile_name`: The AWS profile name. +- `max_length`: The maximum length of the generated text. This can also be set in the `kwargs` parameter +by using the model specific parameter name. +- `truncate`: Deprecated. This parameter no longer has any effect. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `boto3_config`: The configuration for the boto3 client. +- `model_family`: The model family to use. If not provided, the model adapter is selected based on the model +name. +- `kwargs`: Additional keyword arguments to be passed to the model. +You can find the model specific arguments in AWS Bedrock's + [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html). +These arguments are specific to the model. You can find them in the model's documentation. + +**Raises**: + +- `ValueError`: If the model name is empty or None. +- `AmazonBedrockConfigurationError`: If the AWS environment is not configured correctly or the model is +not supported. + + + +#### AmazonBedrockGenerator.run + +```python +@component.output_types(replies=List[str], meta=Dict[str, Any]) +def run( + prompt: str, + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None, + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[str], Dict[str, Any]]] +``` + +Generates a list of string response to the given prompt. + +**Arguments**: + +- `prompt`: The prompt to generate a response for. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments passed to the generator. + +**Raises**: + +- `ValueError`: If the prompt is empty or None. +- `AmazonBedrockInferenceError`: If the model cannot be invoked. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated responses. +- `meta`: A dictionary containing response metadata. + + + +#### AmazonBedrockGenerator.get\_model\_adapter + +```python +@classmethod +def get_model_adapter( + cls, + model: str, + model_family: Optional[str] = None) -> Type[BedrockModelAdapter] +``` + +Gets the model adapter for the given model. + +If `model_family` is provided, the adapter for the model family is returned. +If `model_family` is not provided, the adapter is auto-detected based on the model name. + +**Arguments**: + +- `model`: The model name. +- `model_family`: The model family. + +**Raises**: + +- `AmazonBedrockConfigurationError`: If the model family is not supported or the model cannot be +auto-detected. + +**Returns**: + +The model adapter class, or None if no adapter is found. + + + +#### AmazonBedrockGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AmazonBedrockGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.components.generators.amazon\_bedrock.adapters + + + +### BedrockModelAdapter + +Base class for Amazon Bedrock model adapters. + +Each subclass of this class is designed to address the unique specificities of a particular LLM it adapts, +focusing on preparing the requests and extracting the responses from the Amazon Bedrock hosted LLMs. + +**Arguments**: + +- `model_kwargs`: Keyword arguments for the model. You can find the full list of parameters in the +Amazon Bedrock API [documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html). +- `max_length`: Maximum length of generated text. This is mapped to the correct parameter for each model. +It will be overridden by the corresponding parameter in the `model_kwargs` if it is present. + + + +#### BedrockModelAdapter.prepare\_body + +```python +@abstractmethod +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Amazon Bedrock request. + +Each subclass should implement this method to prepare the request body for the specific model. + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary containing the body for the request. + + + +#### BedrockModelAdapter.get\_responses + +```python +def get_responses(response_body: Dict[str, Any]) -> List[str] +``` + +Extracts the responses from the Amazon Bedrock response. + +**Arguments**: + +- `response_body`: The response body from the Amazon Bedrock request. + +**Returns**: + +A list of responses. + + + +#### BedrockModelAdapter.get\_stream\_responses + +```python +def get_stream_responses( + stream: EventStream, + streaming_callback: SyncStreamingCallbackT) -> List[str] +``` + +Extracts the responses from the Amazon Bedrock streaming response. + +**Arguments**: + +- `stream`: The streaming response from the Amazon Bedrock request. +- `streaming_callback`: The handler for the streaming response. + +**Returns**: + +A list of string responses. + + + +### AnthropicClaudeAdapter + +Adapter for the Anthropic Claude models. + +**Arguments**: + +- `model_kwargs`: Keyword arguments for the model. You can find the full list of parameters in the +Amazon Bedrock API documentation for the Claude model +[here](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters-claude.html). +Some example parameters are: +- use_messages_api: Whether to use the messages API, default: True +- include_thinking: Whether to include thinking output, default: True +- thinking_tag: XML tag for thinking content, default: "thinking" +- `max_length`: Maximum length of generated text + + + +#### AnthropicClaudeAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Claude model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +### MistralAdapter + +Adapter for the Mistral models. + + + +#### MistralAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Mistral model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +### CohereCommandAdapter + +Adapter for the Cohere Command model. + + + +#### CohereCommandAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Command model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +### CohereCommandRAdapter + +Adapter for the Cohere Command R models. + + + +#### CohereCommandRAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Command model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +### AI21LabsJurassic2Adapter + +Model adapter for AI21 Labs' Jurassic 2 models. + + + +#### AI21LabsJurassic2Adapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Jurassic 2 model. + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +### AmazonTitanAdapter + +Adapter for Amazon's Titan models. + + + +#### AmazonTitanAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Titan model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys +- `inputText`: The prompt to be sent to the model. +- specified inference parameters. + + + +### MetaLlamaAdapter + +Adapter for Meta's Llama2 models. + + + +#### MetaLlamaAdapter.prepare\_body + +```python +def prepare_body(prompt: str, **inference_kwargs: Any) -> Dict[str, Any] +``` + +Prepares the body for the Llama2 model + +**Arguments**: + +- `prompt`: The prompt to be sent to the model. +- `inference_kwargs`: Additional keyword arguments passed to the handler. + +**Returns**: + +A dictionary with the following keys: +- `prompt`: The prompt to be sent to the model. +- specified inference parameters. + + + +## Module haystack\_integrations.common.amazon\_bedrock.errors + + + +### AmazonBedrockError + +Any error generated by the Amazon Bedrock integration. + +This error wraps its source transparently in such a way that its attributes +can be accessed directly: for example, if the original error has a `message` attribute, +`AmazonBedrockError.message` will exist and have the expected content. + + + +### AWSConfigurationError + +Exception raised when AWS is not configured correctly + + + +### AmazonBedrockConfigurationError + +Exception raised when AmazonBedrock node is not configured correctly + + + +### AmazonBedrockInferenceError + +Exception for issues that occur in the Bedrock inference node + + + +## Module haystack\_integrations.components.generators.amazon\_bedrock.chat.chat\_generator + + + +### AmazonBedrockChatGenerator + +Completes chats using LLMs hosted on Amazon Bedrock available via the Bedrock Converse API. + +For example, to use the Anthropic Claude 3 Sonnet model, initialize this component with the +'anthropic.claude-3-5-sonnet-20240620-v1:0' model name. + +### Usage example + +```python +from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.components.generators.utils import print_streaming_chunk + +messages = [ChatMessage.from_system("\nYou are a helpful, respectful and honest assistant, answer in German only"), + ChatMessage.from_user("What's Natural Language Processing?")] + + +client = AmazonBedrockChatGenerator(model="anthropic.claude-3-5-sonnet-20240620-v1:0", + streaming_callback=print_streaming_chunk) +client.run(messages, generation_kwargs={"max_tokens": 512}) +``` + +### Multimodal example +```python +from haystack.dataclasses import ChatMessage, ImageContent +from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator + +generator = AmazonBedrockChatGenerator(model="anthropic.claude-3-5-sonnet-20240620-v1:0") + +image_content = ImageContent.from_file_path(file_path="apple.jpg") + +message = ChatMessage.from_user(content_parts=["Describe the image using 10 words at most.", image_content]) + +response = generator.run(messages=[message])["replies"][0].text + +print(response) +> The image shows a red apple. + +### Tool usage example +# AmazonBedrockChatGenerator supports Haystack's unified tool architecture, allowing tools to be used +# across different chat generators. The same tool definitions and usage patterns work consistently +# whether using Amazon Bedrock, OpenAI, Ollama, or any other supported LLM providers. + +```python +from haystack.dataclasses import ChatMessage +from haystack.tools import Tool +from haystack_integrations.components.generators.amazon_bedrock import AmazonBedrockChatGenerator + +def weather(city: str): + return f'The weather in {city} is sunny and 32°C' + +__Define tool parameters__ + +tool_parameters = { + "type": "object", + "properties": {"city": {"type": "string"}}, + "required": ["city"] +} + +__Create weather tool__ + +weather_tool = Tool( + name="weather", + description="useful to determine the weather in a given location", + parameters=tool_parameters, + function=weather +) + +__Initialize generator with tool__ + +client = AmazonBedrockChatGenerator( + model="anthropic.claude-3-5-sonnet-20240620-v1:0", + tools=[weather_tool] +) + +__Run initial query__ + +messages = [ChatMessage.from_user("What's the weather like in Paris?")] +results = client.run(messages=messages) + +__Get tool call from response__ + +tool_message = next(msg for msg in results["replies"] if msg.tool_call) +tool_call = tool_message.tool_call + +__Execute tool and send result back__ + +weather_result = weather(**tool_call.arguments) +new_messages = [ + messages[0], + tool_message, + ChatMessage.from_tool(tool_result=weather_result, origin=tool_call) +] + +__Get final response__ + +final_result = client.run(new_messages) +print(final_result["replies"][0].text) + +> Based on the information I've received, I can tell you that the weather in Paris is +> currently sunny with a temperature of 32°C (which is about 90°F). + +``` + +AmazonBedrockChatGenerator uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. +For more information on setting up an IAM identity-based policy, see [Amazon Bedrock documentation] +(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html). + +If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded +automatically from the environment or the AWS configuration file. +If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`, + and `aws_region_name` as environment variables or pass them as + [Secret](https://docs.haystack.deepset.ai/v2.0/docs/secret-management) arguments. Make sure the region you set +supports Amazon Bedrock. + + + +#### AmazonBedrockChatGenerator.\_\_init\_\_ + +```python +def __init__( + model: str, + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + ["AWS_ACCESS_KEY_ID"], strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + ["AWS_SECRET_ACCESS_KEY"], strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + ["AWS_SESSION_TOKEN"], strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + ["AWS_DEFAULT_REGION"], strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var( + ["AWS_PROFILE"], strict=False), + generation_kwargs: Optional[Dict[str, Any]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + boto3_config: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + *, + guardrail_config: Optional[Dict[str, str]] = None) -> None +``` + +Initializes the `AmazonBedrockChatGenerator` with the provided parameters. The parameters are passed to the + +Amazon Bedrock client. + +Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded +automatically from the environment or the AWS configuration file and do not need to be provided explicitly via +the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the +constructor. Aside from model, three required parameters are `aws_access_key_id`, `aws_secret_access_key`, +and `aws_region_name`. + +**Arguments**: + +- `model`: The model to use for text generation. The model must be available in Amazon Bedrock and must +be specified in the format outlined in the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids-arns.html). +- `aws_access_key_id`: AWS access key ID. +- `aws_secret_access_key`: AWS secret access key. +- `aws_session_token`: AWS session token. +- `aws_region_name`: AWS region name. Make sure the region you set supports Amazon Bedrock. +- `aws_profile_name`: AWS profile name. +- `generation_kwargs`: Keyword arguments sent to the model. These parameters are specific to a model. +You can find the model specific arguments in the AWS Bedrock API +[documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html). +- `streaming_callback`: A callback function called when a new token is received from the stream. +By default, the model is not set up for streaming. To enable streaming, set this parameter to a callback +function that handles the streaming chunks. The callback function receives a +[StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) object and switches +the streaming mode on. +- `boto3_config`: The configuration for the boto3 client. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. +- `guardrail_config`: Optional configuration for a guardrail that has been created in Amazon Bedrock. +This must be provided as a dictionary matching either +[GuardrailConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_GuardrailConfiguration.html). +or, in streaming mode (when `streaming_callback` is set), +[GuardrailStreamConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailStreamConfiguration.html). +If `trace` is set to `enabled`, the guardrail trace will be included under the `trace` key in the `meta` +attribute of the resulting `ChatMessage`. +Note: Enabling guardrails in streaming mode may introduce additional latency. +To manage this, you can adjust the `streamProcessingMode` parameter. +See the +[Guardrails Streaming documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails-streaming.html) +for more information. + +**Raises**: + +- `ValueError`: If the model name is empty or None. +- `AmazonBedrockConfigurationError`: If the AWS environment is not configured correctly or the model is +not supported. + + + +#### AmazonBedrockChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AmazonBedrockChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary with serialized data. + +**Returns**: + +Instance of `AmazonBedrockChatGenerator`. + + + +#### AmazonBedrockChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None) -> Dict[str, List[ChatMessage]] +``` + +Executes a synchronous inference call to the Amazon Bedrock model using the Converse API. + +Supports both standard and streaming responses depending on whether a streaming callback is provided. + +**Arguments**: + +- `messages`: A list of `ChatMessage` objects forming the chat history. +- `streaming_callback`: Optional callback for handling streaming outputs. +- `generation_kwargs`: Optional dictionary of generation parameters. Some common parameters are: +- `maxTokens`: Maximum number of tokens to generate. +- `stopSequences`: List of stop sequences to stop generation. +- `temperature`: Sampling temperature. +- `topP`: Nucleus sampling parameter. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. + +**Raises**: + +- `AmazonBedrockInferenceError`: If the Bedrock inference API call fails. + +**Returns**: + +A dictionary containing the model-generated replies under the `"replies"` key. + + + +#### AmazonBedrockChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async( + messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None) -> Dict[str, List[ChatMessage]] +``` + +Executes an asynchronous inference call to the Amazon Bedrock model using the Converse API. + +Designed for use cases where non-blocking or concurrent execution is desired. + +**Arguments**: + +- `messages`: A list of `ChatMessage` objects forming the chat history. +- `streaming_callback`: Optional async-compatible callback for handling streaming outputs. +- `generation_kwargs`: Optional dictionary of generation parameters. Some common parameters are: +- `maxTokens`: Maximum number of tokens to generate. +- `stopSequences`: List of stop sequences to stop generation. +- `temperature`: Sampling temperature. +- `topP`: Nucleus sampling parameter. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. + +**Raises**: + +- `AmazonBedrockInferenceError`: If the Bedrock inference API call fails. + +**Returns**: + +A dictionary containing the model-generated replies under the `"replies"` key. + + + +## Module haystack\_integrations.components.rankers.amazon\_bedrock.ranker + + + +### AmazonBedrockRanker + +Ranks Documents based on their similarity to the query using Amazon Bedrock's Cohere Rerank model. + +Documents are indexed from most to least semantically relevant to the query. + +Supported Amazon Bedrock models: +- cohere.rerank-v3-5:0 +- amazon.rerank-v1:0 + +Usage example: +```python +from haystack import Document +from haystack.utils import Secret +from haystack_integrations.components.rankers.amazon_bedrock import AmazonBedrockRanker + +ranker = AmazonBedrockRanker( + model="cohere.rerank-v3-5:0", + top_k=2, + aws_region_name=Secret.from_token("eu-central-1") +) + +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "What is the capital of germany?" +output = ranker.run(query=query, documents=docs) +docs = output["documents"] +``` + +AmazonBedrockRanker uses AWS for authentication. You can use the AWS CLI to authenticate through your IAM. +For more information on setting up an IAM identity-based policy, see [Amazon Bedrock documentation] +(https://docs.aws.amazon.com/bedrock/latest/userguide/security_iam_id-based-policy-examples.html). + +If the AWS environment is configured correctly, the AWS credentials are not required as they're loaded +automatically from the environment or the AWS configuration file. +If the AWS environment is not configured, set `aws_access_key_id`, `aws_secret_access_key`, +and `aws_region_name` as environment variables or pass them as +[Secret](https://docs.haystack.deepset.ai/v2.0/docs/secret-management) arguments. Make sure the region you set +supports Amazon Bedrock. + + + +#### AmazonBedrockRanker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AmazonBedrockRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AmazonBedrockRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### AmazonBedrockRanker.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + documents: List[Document], + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Use the Amazon Bedrock Reranker to re-rank the list of documents based on the query. + +**Arguments**: + +- `query`: Query string. +- `documents`: List of Documents. +- `top_k`: The maximum number of Documents you want the Ranker to return. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given query in descending order of similarity. + + + +## Module haystack\_integrations.components.downloaders.s3.s3\_downloader + + + +### S3Downloader + +A component for downloading files from AWS S3 Buckets to local filesystem. +Supports filtering by file extensions. + + + +#### S3Downloader.\_\_init\_\_ + +```python +def __init__( + *, + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + "AWS_ACCESS_KEY_ID", strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + "AWS_SECRET_ACCESS_KEY", strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + "AWS_SESSION_TOKEN", strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + "AWS_DEFAULT_REGION", strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var("AWS_PROFILE", + strict=False), + boto3_config: Optional[Dict[str, Any]] = None, + file_root_path: Optional[str] = None, + file_extensions: Optional[List[str]] = None, + file_name_meta_key: str = "file_name", + max_workers: int = 32, + max_cache_size: int = 100, + s3_key_generation_function: Optional[Callable[[Document], str]] = None +) -> None +``` + +Initializes the `S3Downloader` with the provided parameters. + +Note that the AWS credentials are not required if the AWS environment is configured correctly. These are loaded +automatically from the environment or the AWS configuration file and do not need to be provided explicitly via +the constructor. If the AWS environment is not configured users need to provide the AWS credentials via the +constructor. Three required parameters are `aws_access_key_id`, `aws_secret_access_key`, +and `aws_region_name`. + +**Arguments**: + +- `aws_access_key_id`: AWS access key ID. +- `aws_secret_access_key`: AWS secret access key. +- `aws_session_token`: AWS session token. +- `aws_region_name`: AWS region name. +- `aws_profile_name`: AWS profile name. +- `boto3_config`: The configuration for the boto3 client. +- `file_root_path`: The path where the file will be downloaded. +Can be set through this parameter or the `FILE_ROOT_PATH` environment variable. +If none of them is set, a `ValueError` is raised. +- `file_extensions`: The file extensions that are permitted to be downloaded. +By default, all file extensions are allowed. +- `max_workers`: The maximum number of workers to use for concurrent downloads. +- `max_cache_size`: The maximum number of files to cache. +- `file_name_meta_key`: The name of the meta key that contains the file name to download. The file name +will also be used to create local file path for download. +By default, the `Document.meta["file_name"]` is used. If you want to use a +different key in `Document.meta`, you can set it here. +- `s3_key_generation_function`: An optional function that generates the S3 key for the file to download. +If not provided, the default behavior is to use `Document.meta[file_name_meta_key]`. +The function must accept a `Document` object and return a string. +If the environment variable `S3_DOWNLOADER_PREFIX` is set, its value will be automatically +prefixed to the generated S3 key. + +**Raises**: + +- `ValueError`: If the `file_root_path` is not set through +the constructor or the `FILE_ROOT_PATH` environment variable. + + + +#### S3Downloader.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the component by initializing the settings and storage. + + + +#### S3Downloader.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Download files from AWS S3 Buckets to local filesystem. + +Return enriched `Document`s with the path of the downloaded file. + +**Arguments**: + +- `documents`: Document containing the name of the file to download in the meta field. + +**Raises**: + +- `S3Error`: If a download attempt fails or the file does not exist in the S3 bucket. +- `ValueError`: If the path where files will be downloaded is not set. + +**Returns**: + +A dictionary with: +- `documents`: The downloaded `Document`s; each has `meta['file_path']`. + + + +#### S3Downloader.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + + + +#### S3Downloader.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "S3Downloader" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.common.s3.utils + + + +### S3Storage + +This class provides a storage class for downloading files from an AWS S3 bucket. + + + +#### S3Storage.\_\_init\_\_ + +```python +def __init__(s3_bucket: str, + session: Session, + s3_prefix: Optional[str] = None, + endpoint_url: Optional[str] = None, + config: Optional[Config] = None) -> None +``` + +Initializes the S3Storage object with the provided parameters. + +**Arguments**: + +- `s3_bucket`: The name of the S3 bucket to download files from. +- `session`: The session to use for the S3 client. +- `s3_prefix`: The optional prefix of the files in the S3 bucket. +Can be used to specify folder or naming structure. +For example, if the file is in the folder "folder/subfolder/file.txt", +the s3_prefix should be "folder/subfolder/". If the file is in the root of the S3 bucket, +the s3_prefix should be None. +- `endpoint_url`: The endpoint URL of the S3 bucket to download files from. +- `config`: The configuration to use for the S3 client. + + + +#### S3Storage.download + +```python +def download(key: str, local_file_path: Path) -> None +``` + +Download a file from S3. + +**Arguments**: + +- `key`: The key of the file to download. +- `local_file_path`: The folder path to download the file to. +It will be created if it does not exist. The file will be downloaded to +the folder with the same name as the key. + +**Raises**: + +- `S3ConfigurationError`: If the S3 session client cannot be created. +- `S3StorageError`: If the file does not exist in the S3 bucket +or the file cannot be downloaded. + + + +#### S3Storage.from\_env + +```python +@classmethod +def from_env(cls, *, session: Session, config: Config) -> "S3Storage" +``` + +Create a S3Storage object from environment variables. + + + +## Module haystack\_integrations.common.s3.errors + + + +### S3Error + +Exception for issues that occur in the S3 based components + + + +### S3ConfigurationError + +Exception raised when AmazonS3 node is not configured correctly + + + +### S3StorageError + +This exception is raised when an error occurs while interacting with a S3Storage object. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_sagemaker.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_sagemaker.md new file mode 100644 index 0000000000..7b4f713b07 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/amazon_sagemaker.md @@ -0,0 +1,149 @@ +--- +title: "Amazon Sagemaker" +id: integrations-amazon-sagemaker +description: "Amazon Sagemaker integration for Haystack" +slug: "/integrations-amazon-sagemaker" +--- + + + +## Module haystack\_integrations.components.generators.amazon\_sagemaker.sagemaker + + + +### SagemakerGenerator + +Enables text generation using Amazon Sagemaker. + +SagemakerGenerator supports Large Language Models (LLMs) hosted and deployed on a SageMaker Inference Endpoint. +For guidance on how to deploy a model to SageMaker, refer to the +[SageMaker JumpStart foundation models documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/jumpstart-foundation-models-use.html). + +Usage example: +```python +# Make sure your AWS credentials are set up correctly. You can use environment variables or a shared credentials +# file. Then you can use the generator as follows: +from haystack_integrations.components.generators.amazon_sagemaker import SagemakerGenerator + +generator = SagemakerGenerator(model="jumpstart-dft-hf-llm-falcon-7b-bf16") +response = generator.run("What's Natural Language Processing? Be brief.") +print(response) +>>> {'replies': ['Natural Language Processing (NLP) is a branch of artificial intelligence that focuses on +>>> the interaction between computers and human language. It involves enabling computers to understand, interpret, +>>> and respond to natural human language in a way that is both meaningful and useful.'], 'meta': [{}]} +``` + + + +#### SagemakerGenerator.\_\_init\_\_ + +```python +def __init__( + model: str, + aws_access_key_id: Optional[Secret] = Secret.from_env_var( + ["AWS_ACCESS_KEY_ID"], strict=False), + aws_secret_access_key: Optional[Secret] = Secret. + from_env_var( # noqa: B008 + ["AWS_SECRET_ACCESS_KEY"], strict=False), + aws_session_token: Optional[Secret] = Secret.from_env_var( + ["AWS_SESSION_TOKEN"], strict=False), + aws_region_name: Optional[Secret] = Secret.from_env_var( + ["AWS_DEFAULT_REGION"], strict=False), + aws_profile_name: Optional[Secret] = Secret.from_env_var( + ["AWS_PROFILE"], strict=False), + aws_custom_attributes: Optional[Dict[str, Any]] = None, + generation_kwargs: Optional[Dict[str, Any]] = None) +``` + +Instantiates the session with SageMaker. + +**Arguments**: + +- `aws_access_key_id`: The `Secret` for AWS access key ID. +- `aws_secret_access_key`: The `Secret` for AWS secret access key. +- `aws_session_token`: The `Secret` for AWS session token. +- `aws_region_name`: The `Secret` for AWS region name. If not provided, the default region will be used. +- `aws_profile_name`: The `Secret` for AWS profile name. If not provided, the default profile will be used. +- `model`: The name for SageMaker Model Endpoint. +- `aws_custom_attributes`: Custom attributes to be passed to SageMaker, for example `{"accept_eula": True}` +in case of Llama-2 models. +- `generation_kwargs`: Additional keyword arguments for text generation. For a list of supported parameters +see your model's documentation page, for example here for HuggingFace models: +https://huggingface.co/blog/sagemaker-huggingface-llm#4-run-inference-and-chat-with-our-model + +Specifically, Llama-2 models support the following inference payload parameters: + +- `max_new_tokens`: Model generates text until the output length (excluding the input context length) + reaches `max_new_tokens`. If specified, it must be a positive integer. +- `temperature`: Controls the randomness in the output. Higher temperature results in output sequence with + low-probability words and lower temperature results in output sequence with high-probability words. + If `temperature=0`, it results in greedy decoding. If specified, it must be a positive float. +- `top_p`: In each step of text generation, sample from the smallest possible set of words with cumulative + probability `top_p`. If specified, it must be a float between 0 and 1. +- `return_full_text`: If `True`, input text will be part of the output generated text. If specified, it must + be boolean. The default value for it is `False`. + + + +#### SagemakerGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SagemakerGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "SagemakerGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SagemakerGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run( + prompt: str, + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Invoke the text generation inference based on the provided prompt and generation parameters. + +**Arguments**: + +- `prompt`: The string prompt to use for text generation. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +potentially override the parameters passed in the `__init__` method. + +**Raises**: + +- `ValueError`: If the model response type is not a list of dictionaries or a single dictionary. +- `SagemakerNotReadyError`: If the SageMaker model is not ready to accept requests. +- `SagemakerInferenceError`: If the SageMaker Inference returns an error. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of strings containing the generated responses +- `meta`: A list of dictionaries containing the metadata for each response. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/anthropic.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/anthropic.md new file mode 100644 index 0000000000..0ea96cf58f --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/anthropic.md @@ -0,0 +1,465 @@ +--- +title: "Anthropic" +id: integrations-anthropic +description: "Anthropic integration for Haystack" +slug: "/integrations-anthropic" +--- + + + +## Module haystack\_integrations.components.generators.anthropic.generator + + + +### AnthropicGenerator + +```python +@component +class AnthropicGenerator() +``` + +Enables text generation using Anthropic large language models (LLMs). It supports the Claude family of models. + +Although Anthropic natively supports a much richer messaging API, we have intentionally simplified it in this +component so that the main input/output interface is string-based. +For more complete support, consider using the AnthropicChatGenerator. + +```python +from haystack_integrations.components.generators.anthropic import AnthropicGenerator + +client = AnthropicGenerator(model="claude-sonnet-4-20250514") +response = client.run("What's Natural Language Processing? Be brief.") +print(response) +>>{'replies': ['Natural language processing (NLP) is a branch of artificial intelligence focused on enabling +>>computers to understand, interpret, and manipulate human language. The goal of NLP is to read, decipher, +>> understand, and make sense of the human languages in a manner that is valuable.'], 'meta': {'model': +>> 'claude-2.1', 'index': 0, 'finish_reason': 'end_turn', 'usage': {'input_tokens': 18, 'output_tokens': 58}}} +``` + + + +#### AnthropicGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"), + model: str = "claude-sonnet-4-20250514", + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None, + system_prompt: Optional[str] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None) +``` + +Initialize the AnthropicGenerator. + +**Arguments**: + +- `api_key`: The Anthropic API key. +- `model`: The name of the Anthropic model to use. +- `streaming_callback`: An optional callback function to handle streaming chunks. +- `system_prompt`: An optional system prompt to use for generation. +- `generation_kwargs`: Additional keyword arguments for generation. + + + +#### AnthropicGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AnthropicGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AnthropicGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AnthropicGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run( + prompt: str, + generation_kwargs: Optional[Dict[str, Any]] = None, + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None +) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Generate replies using the Anthropic API. + +**Arguments**: + +- `prompt`: The input prompt for generation. +- `generation_kwargs`: Additional keyword arguments for generation. +- `streaming_callback`: An optional callback function to handle streaming chunks. + +**Returns**: + +A dictionary containing: +- `replies`: A list of generated replies. +- `meta`: A list of metadata dictionaries for each reply. + + + +## Module haystack\_integrations.components.generators.anthropic.chat.chat\_generator + + + +### AnthropicChatGenerator + +```python +@component +class AnthropicChatGenerator() +``` + +Completes chats using Anthropic's large language models (LLMs). + +It uses [ChatMessage](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage) +format in input and output. Supports multimodal inputs including text and images. + +You can customize how the text is generated by passing parameters to the +Anthropic API. Use the `**generation_kwargs` argument when you initialize +the component or when you run it. Any parameter that works with +`anthropic.Message.create` will work here too. + +For details on Anthropic API parameters, see +[Anthropic documentation](https://docs.anthropic.com/en/api/messages). + +Usage example: +```python +from haystack_integrations.components.generators.anthropic import ( + AnthropicChatGenerator, +) +from haystack.dataclasses import ChatMessage + +generator = AnthropicChatGenerator( + model="claude-sonnet-4-20250514", + generation_kwargs={ + "max_tokens": 1000, + "temperature": 0.7, + }, +) + +messages = [ + ChatMessage.from_system( + "You are a helpful, respectful and honest assistant" + ), + ChatMessage.from_user("What's Natural Language Processing?"), +] +print(generator.run(messages=messages)) +``` + +Usage example with images: +```python +from haystack.dataclasses import ChatMessage, ImageContent + +image_content = ImageContent.from_file_path("path/to/image.jpg") +messages = [ + ChatMessage.from_user( + content_parts=["What's in this image?", image_content] + ) +] +generator = AnthropicChatGenerator() +result = generator.run(messages) +``` + + + +#### AnthropicChatGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("ANTHROPIC_API_KEY"), + model: str = "claude-sonnet-4-20250514", + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + ignore_tools_thinking_messages: bool = True, + tools: Optional[ToolsType] = None, + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None) +``` + +Creates an instance of AnthropicChatGenerator. + +**Arguments**: + +- `api_key`: The Anthropic API key +- `model`: The name of the model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Anthropic endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post) +for more details. + +Supported generation_kwargs parameters are: +- `system`: The system message to be passed to the model. +- `max_tokens`: The maximum number of tokens to generate. +- `metadata`: A dictionary of metadata to be passed to the model. +- `stop_sequences`: A list of strings that the model should stop generating at. +- `temperature`: The temperature to use for sampling. +- `top_p`: The top_p value to use for nucleus sampling. +- `top_k`: The top_k value to use for top-k sampling. +- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features). +- `thinking`: A dictionary of thinking parameters to be passed to the model. + The `budget_tokens` passed for thinking should be less than `max_tokens`. + For more details and supported models, see: [Anthropic Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) +- `ignore_tools_thinking_messages`: Anthropic's approach to tools (function calling) resolution involves a +"chain of thought" messages before returning the actual function names and parameters in a message. If +`ignore_tools_thinking_messages` is `True`, the generator will drop so-called thinking messages when tool +use is detected. See the Anthropic [tools](https://docs.anthropic.com/en/docs/tool-use#chain-of-thought-tool-use) +for more details. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset, that the model can use. +Each tool should have a unique name. +- `timeout`: Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client. +- `max_retries`: Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by +the Anthropic client. + + + +#### AnthropicChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AnthropicChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AnthropicChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### AnthropicChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None) -> Dict[str, List[ChatMessage]] +``` + +Invokes the Anthropic API with the given messages and generation kwargs. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Optional arguments to pass to the Anthropic generation endpoint. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset, that the model can use. +Each tool should have a unique name. If set, it will override the `tools` parameter set during component +initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: The responses from the model + + + +#### AnthropicChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async( + messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None) -> Dict[str, List[ChatMessage]] +``` + +Async version of the run method. Invokes the Anthropic API with the given messages and generation kwargs. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Optional arguments to pass to the Anthropic generation endpoint. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset, that the model can use. +Each tool should have a unique name. If set, it will override the `tools` parameter set during component +initialization. + +**Returns**: + +A dictionary with the following keys: +- `replies`: The responses from the model + + + +## Module haystack\_integrations.components.generators.anthropic.chat.vertex\_chat\_generator + + + +### AnthropicVertexChatGenerator + +```python +@component +class AnthropicVertexChatGenerator(AnthropicChatGenerator) +``` + +Enables text generation using state-of-the-art Claude 3 LLMs via the Anthropic Vertex AI API. +It supports models such as `Claude 3.5 Sonnet`, `Claude 3 Opus`, `Claude 3 Sonnet`, and `Claude 3 Haiku`, +accessible through the Vertex AI API endpoint. + +To use AnthropicVertexChatGenerator, you must have a GCP project with Vertex AI enabled. +Additionally, ensure that the desired Anthropic model is activated in the Vertex AI Model Garden. +Before making requests, you may need to authenticate with GCP using `gcloud auth login`. +For more details, refer to the [guide] (https://docs.anthropic.com/en/api/claude-on-vertex-ai). + +Any valid text generation parameters for the Anthropic messaging API can be passed to +the AnthropicVertex API. Users can provide these parameters directly to the component via +the `generation_kwargs` parameter in `__init__` or the `run` method. + +For more details on the parameters supported by the Anthropic API, refer to the +Anthropic Message API [documentation](https://docs.anthropic.com/en/api/messages). + +```python +from haystack_integrations.components.generators.anthropic import AnthropicVertexChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] +client = AnthropicVertexChatGenerator( + model="claude-sonnet-4@20250514", + project_id="your-project-id", region="your-region" + ) +response = client.run(messages) +print(response) + +>> {'replies': [ChatMessage(_role=, _content=[TextContent(text= +>> "Natural Language Processing (NLP) is a field of artificial intelligence that +>> focuses on enabling computers to understand, interpret, and generate human language. It involves developing +>> techniques and algorithms to analyze and process text or speech data, allowing machines to comprehend and +>> communicate in natural languages like English, Spanish, or Chinese.")], +>> _name=None, _meta={'model': 'claude-sonnet-4@20250514', 'index': 0, 'finish_reason': 'end_turn', +>> 'usage': {'input_tokens': 15, 'output_tokens': 64}})]} +``` + +For more details on supported models and their capabilities, refer to the Anthropic +[documentation](https://docs.anthropic.com/claude/docs/intro-to-claude). + + + +#### AnthropicVertexChatGenerator.\_\_init\_\_ + +```python +def __init__(region: str, + project_id: str, + model: str = "claude-sonnet-4@20250514", + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + ignore_tools_thinking_messages: bool = True, + tools: Optional[ToolsType] = None, + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None) +``` + +Creates an instance of AnthropicVertexChatGenerator. + +**Arguments**: + +- `region`: The region where the Anthropic model is deployed. Defaults to "us-central1". +- `project_id`: The GCP project ID where the Anthropic model is deployed. +- `model`: The name of the model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the AnthropicVertex endpoint. See Anthropic [documentation](https://docs.anthropic.com/claude/reference/messages_post) +for more details. + +Supported generation_kwargs parameters are: +- `system`: The system message to be passed to the model. +- `max_tokens`: The maximum number of tokens to generate. +- `metadata`: A dictionary of metadata to be passed to the model. +- `stop_sequences`: A list of strings that the model should stop generating at. +- `temperature`: The temperature to use for sampling. +- `top_p`: The top_p value to use for nucleus sampling. +- `top_k`: The top_k value to use for top-k sampling. +- `extra_headers`: A dictionary of extra headers to be passed to the model (i.e. for beta features). +- `ignore_tools_thinking_messages`: Anthropic's approach to tools (function calling) resolution involves a +"chain of thought" messages before returning the actual function names and parameters in a message. If +`ignore_tools_thinking_messages` is `True`, the generator will drop so-called thinking messages when tool +use is detected. See the Anthropic [tools](https://docs.anthropic.com/en/docs/tool-use#chain-of-thought-tool-use) +for more details. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset, that the model can use. +Each tool should have a unique name. +- `timeout`: Timeout for Anthropic client calls. If not set, it defaults to the default set by the Anthropic client. +- `max_retries`: Maximum number of retries to attempt for failed requests. If not set, it defaults to the default set by +the Anthropic client. + + + +#### AnthropicVertexChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### AnthropicVertexChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AnthropicVertexChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/astra.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/astra.md new file mode 100644 index 0000000000..b1d6aae2e6 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/astra.md @@ -0,0 +1,388 @@ +--- +title: "Astra" +id: integrations-astra +description: "Astra integration for Haystack" +slug: "/integrations-astra" +--- + + + +## Module haystack\_integrations.components.retrievers.astra.retriever + + + +### AstraEmbeddingRetriever + +A component for retrieving documents from an AstraDocumentStore. + +Usage example: +```python +from haystack_integrations.document_stores.astra import AstraDocumentStore +from haystack_integrations.components.retrievers.astra import AstraEmbeddingRetriever + +document_store = AstraDocumentStore( + api_endpoint=api_endpoint, + token=token, + collection_name=collection_name, + duplicates_policy=DuplicatePolicy.SKIP, + embedding_dim=384, +) + +retriever = AstraEmbeddingRetriever(document_store=document_store) +``` + + + +#### AstraEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: AstraDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: An instance of AstraDocumentStore. +- `filters`: a dictionary with filters to narrow down the search space. +- `top_k`: the maximum number of documents to retrieve. +- `filter_policy`: Policy to determine how filters are applied. + + + +#### AstraEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents from the AstraDocumentStore. + +**Arguments**: + +- `query_embedding`: floats representing the query embedding +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: the maximum number of documents to retrieve. + +**Returns**: + +a dictionary with the following keys: +- `documents`: A list of documents retrieved from the AstraDocumentStore. + + + +#### AstraEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AstraEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AstraEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.document\_stores.astra.document\_store + + + +### AstraDocumentStore + +An AstraDocumentStore document store for Haystack. + +Example Usage: +```python +from haystack_integrations.document_stores.astra import AstraDocumentStore + +document_store = AstraDocumentStore( + api_endpoint=api_endpoint, + token=token, + collection_name=collection_name, + duplicates_policy=DuplicatePolicy.SKIP, + embedding_dim=384, +) +``` + + + +#### AstraDocumentStore.\_\_init\_\_ + +```python +def __init__( + api_endpoint: Secret = Secret.from_env_var("ASTRA_DB_API_ENDPOINT"), + token: Secret = Secret.from_env_var("ASTRA_DB_APPLICATION_TOKEN"), + collection_name: str = "documents", + embedding_dimension: int = 768, + duplicates_policy: DuplicatePolicy = DuplicatePolicy.NONE, + similarity: str = "cosine", + namespace: Optional[str] = None) +``` + +The connection to Astra DB is established and managed through the JSON API. + +The required credentials (api endpoint and application token) can be generated +through the UI by clicking and the connect tab, and then selecting JSON API and +Generate Configuration. + +**Arguments**: + +- `api_endpoint`: the Astra DB API endpoint. +- `token`: the Astra DB application token. +- `collection_name`: the current collection in the keyspace in the current Astra DB. +- `embedding_dimension`: dimension of embedding vector. +- `duplicates_policy`: handle duplicate documents based on DuplicatePolicy parameter options. +Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`) +- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists, + it is skipped and not written. +- `DuplicatePolicy.SKIP`: if a Document with the same ID already exists, it is skipped and not written. +- `DuplicatePolicy.OVERWRITE`: if a Document with the same ID already exists, it is overwritten. +- `DuplicatePolicy.FAIL`: if a Document with the same ID already exists, an error is raised. +- `similarity`: the similarity function used to compare document vectors. + +**Raises**: + +- `ValueError`: if the API endpoint or token is not set. + + + +#### AstraDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AstraDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AstraDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AstraDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Indexes documents for later queries. + +**Arguments**: + +- `documents`: a list of Haystack Document objects. +- `policy`: handle duplicate documents based on DuplicatePolicy parameter options. +Parameter options : (`SKIP`, `OVERWRITE`, `FAIL`, `NONE`) +- `DuplicatePolicy.NONE`: Default policy, If a Document with the same ID already exists, + it is skipped and not written. +- `DuplicatePolicy.SKIP`: If a Document with the same ID already exists, + it is skipped and not written. +- `DuplicatePolicy.OVERWRITE`: If a Document with the same ID already exists, it is overwritten. +- `DuplicatePolicy.FAIL`: If a Document with the same ID already exists, an error is raised. + +**Raises**: + +- `ValueError`: if the documents are not of type Document or dict. +- `DuplicateDocumentError`: if a document with the same ID already exists and policy is set to FAIL. +- `Exception`: if the document ID is not a string or if `id` and `_id` are both present in the document. + +**Returns**: + +number of documents written. + + + +#### AstraDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Counts the number of documents in the document store. + +**Returns**: + +the number of documents in the document store. + + + +#### AstraDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns at most 1000 documents that match the filter. + +**Arguments**: + +- `filters`: filters to apply. + +**Raises**: + +- `AstraDocumentStoreFilterError`: if the filter is invalid or not supported by this class. + +**Returns**: + +matching documents. + + + +#### AstraDocumentStore.get\_documents\_by\_id + +```python +def get_documents_by_id(ids: List[str]) -> List[Document] +``` + +Gets documents by their IDs. + +**Arguments**: + +- `ids`: the IDs of the documents to retrieve. + +**Returns**: + +the matching documents. + + + +#### AstraDocumentStore.get\_document\_by\_id + +```python +def get_document_by_id(document_id: str) -> Document +``` + +Gets a document by its ID. + +**Arguments**: + +- `document_id`: the ID to filter by + +**Raises**: + +- `MissingDocumentError`: if the document is not found + +**Returns**: + +the found document + + + +#### AstraDocumentStore.search + +```python +def search(query_embedding: List[float], + top_k: int, + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Perform a search for a list of queries. + +**Arguments**: + +- `query_embedding`: a list of query embeddings. +- `top_k`: the number of results to return. +- `filters`: filters to apply during search. + +**Returns**: + +matching documents. + + + +#### AstraDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes documents from the document store. + +**Arguments**: + +- `document_ids`: IDs of the documents to delete. +- `delete_all`: if `True`, delete all documents. + +**Raises**: + +- `MissingDocumentError`: if no document was deleted but document IDs were provided. + + + +#### AstraDocumentStore.delete\_all\_documents + +```python +def delete_all_documents() -> None +``` + +Deletes all documents from the document store. + + + +## Module haystack\_integrations.document\_stores.astra.errors + + + +### AstraDocumentStoreError + +Parent class for all AstraDocumentStore errors. + + + +### AstraDocumentStoreFilterError + +Raised when an invalid filter is passed to AstraDocumentStore. + + + +### AstraDocumentStoreConfigError + +Raised when an invalid configuration is passed to AstraDocumentStore. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/azure_ai_search.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/azure_ai_search.md new file mode 100644 index 0000000000..5f3ccd5cd0 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/azure_ai_search.md @@ -0,0 +1,307 @@ +--- +title: "Azure AI Search" +id: integrations-azure_ai_search +description: "Azure AI Search integration for Haystack" +slug: "/integrations-azure_ai_search" +--- + + + +## Module haystack\_integrations.components.retrievers.azure\_ai\_search.embedding\_retriever + + + +### AzureAISearchEmbeddingRetriever + +Retrieves documents from the AzureAISearchDocumentStore using a vector similarity metric. +Must be connected to the AzureAISearchDocumentStore to run. + + + +#### AzureAISearchEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: AzureAISearchDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + **kwargs: Any) +``` + +Create the AzureAISearchEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of AzureAISearchDocumentStore to use with the Retriever. +- `filters`: Filters applied when fetching documents from the Document Store. +- `top_k`: Maximum number of documents to return. +- `filter_policy`: Policy to determine how filters are applied. +- `kwargs`: Additional keyword arguments to pass to the Azure AI's search endpoint. +Some of the supported parameters: + - `query_type`: A string indicating the type of query to perform. Possible values are + 'simple','full' and 'semantic'. + - `semantic_configuration_name`: The name of semantic configuration to be used when + processing semantic queries. +For more information on parameters, see the +[official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/). + + + +#### AzureAISearchEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AzureAISearchEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AzureAISearchEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AzureAISearchEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents from the AzureAISearchDocumentStore. + +**Arguments**: + +- `query_embedding`: A list of floats representing the query embedding. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See `__init__` method docstring for more +details. +- `top_k`: The maximum number of documents to retrieve. + +**Returns**: + +Dictionary with the following keys: +- `documents`: A list of documents retrieved from the AzureAISearchDocumentStore. + + + +## Module haystack\_integrations.document\_stores.azure\_ai\_search.document\_store + + + +### AzureAISearchDocumentStore + + + +#### AzureAISearchDocumentStore.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("AZURE_AI_SEARCH_API_KEY", + strict=False), + azure_endpoint: Secret = Secret.from_env_var( + "AZURE_AI_SEARCH_ENDPOINT", strict=True), + index_name: str = "default", + embedding_dimension: int = 768, + metadata_fields: Optional[Dict[str, Union[SearchField, + type]]] = None, + vector_search_configuration: Optional[VectorSearch] = None, + include_search_metadata: bool = False, + **index_creation_kwargs: Any) +``` + +A document store using [Azure AI Search](https://azure.microsoft.com/products/ai-services/ai-search/) + +as the backend. + +**Arguments**: + +- `azure_endpoint`: The URL endpoint of an Azure AI Search service. +- `api_key`: The API key to use for authentication. +- `index_name`: Name of index in Azure AI Search, if it doesn't exist it will be created. +- `embedding_dimension`: Dimension of the embeddings. +- `metadata_fields`: A dictionary mapping metadata field names to their corresponding field definitions. +Each field can be defined either as: +- A SearchField object to specify detailed field configuration like type, searchability, and filterability +- A Python type (`str`, `bool`, `int`, `float`, or `datetime`) to create a simple filterable field + +These fields are automatically added when creating the search index. +Example: +```python +metadata_fields={ + "Title": SearchField( + name="Title", + type="Edm.String", + searchable=True, + filterable=True + ), + "Pages": int +} +``` +- `vector_search_configuration`: Configuration option related to vector search. +Default configuration uses the HNSW algorithm with cosine similarity to handle vector searches. +- `include_search_metadata`: Whether to include Azure AI Search metadata fields +in the returned documents. When set to True, the `meta` field of the returned +documents will contain the @search.score, @search.reranker_score, @search.highlights, +@search.captions, and other fields returned by Azure AI Search. +- `index_creation_kwargs`: Optional keyword parameters to be passed to `SearchIndex` class +during index creation. Some of the supported parameters: + - `semantic_search`: Defines semantic configuration of the search index. This parameter is needed + to enable semantic search capabilities in index. + - `similarity`: The type of similarity algorithm to be used when scoring and ranking the documents + matching a search query. The similarity algorithm can only be defined at index creation time and + cannot be modified on existing indexes. + +For more information on parameters, see the [official Azure AI Search documentation](https://learn.microsoft.com/en-us/azure/search/). + + + +#### AzureAISearchDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### AzureAISearchDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "AzureAISearchDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### AzureAISearchDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the search index. + +**Returns**: + +list of retrieved documents. + + + +#### AzureAISearchDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes the provided documents to search index. + +**Arguments**: + +- `documents`: documents to write to the index. +- `policy`: Policy to determine how duplicates are handled. + +**Raises**: + +- `ValueError`: If the documents are not of type Document. +- `TypeError`: If the document ids are not strings. + +**Returns**: + +the number of documents added to index. + + + +#### AzureAISearchDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes all documents with a matching document_ids from the search index. + +**Arguments**: + +- `document_ids`: ids of the documents to be deleted. + + + +#### AzureAISearchDocumentStore.search\_documents + +```python +def search_documents(search_text: str = "*", + top_k: int = 10) -> List[Document] +``` + +Returns all documents that match the provided search_text. + +If search_text is None, returns all documents. + +**Arguments**: + +- `search_text`: the text to search for in the Document list. +- `top_k`: Maximum number of documents to return. + +**Returns**: + +A list of Documents that match the given search_text. + + + +#### AzureAISearchDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the provided filters. + +Filters should be given as a dictionary supporting filtering by metadata. For details on +filters, see the [metadata filtering documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering). + +**Arguments**: + +- `filters`: the filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/chroma.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/chroma.md new file mode 100644 index 0000000000..71c1c05d2f --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/chroma.md @@ -0,0 +1,699 @@ +--- +title: "Chroma" +id: integrations-chroma +description: "Chroma integration for Haystack" +slug: "/integrations-chroma" +--- + + + +## Module haystack\_integrations.components.retrievers.chroma.retriever + + + +### ChromaQueryTextRetriever + +A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using the `query` API. + +Example usage: +```python +from haystack import Pipeline +from haystack.components.converters import TextFileToDocument +from haystack.components.writers import DocumentWriter + +from haystack_integrations.document_stores.chroma import ChromaDocumentStore +from haystack_integrations.components.retrievers.chroma import ChromaQueryTextRetriever + +file_paths = ... + +# Chroma is used in-memory so we use the same instances in the two pipelines below +document_store = ChromaDocumentStore() + +indexing = Pipeline() +indexing.add_component("converter", TextFileToDocument()) +indexing.add_component("writer", DocumentWriter(document_store)) +indexing.connect("converter", "writer") +indexing.run({"converter": {"sources": file_paths}}) + +querying = Pipeline() +querying.add_component("retriever", ChromaQueryTextRetriever(document_store)) +results = querying.run({"retriever": {"query": "Variable declarations", "top_k": 3}}) + +for d in results["retriever"]["documents"]: + print(d.meta, d.score) +``` + + + +#### ChromaQueryTextRetriever.\_\_init\_\_ + +```python +def __init__(document_store: ChromaDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: an instance of `ChromaDocumentStore`. +- `filters`: filters to narrow down the search space. +- `top_k`: the maximum number of documents to retrieve. +- `filter_policy`: Policy to determine how filters are applied. + + + +#### ChromaQueryTextRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, Any] +``` + +Run the retriever on the given input data. + +**Arguments**: + +- `query`: The input data for the retriever. In this case, a plain-text query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to retrieve. +If not specified, the default value from the constructor is used. + +**Raises**: + +- `ValueError`: If the specified document store is not found or is not a MemoryDocumentStore instance. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of documents returned by the search engine. + + + +#### ChromaQueryTextRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, Any] +``` + +Asynchronously run the retriever on the given input data. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `query`: The input data for the retriever. In this case, a plain-text query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to retrieve. +If not specified, the default value from the constructor is used. + +**Raises**: + +- `ValueError`: If the specified document store is not found or is not a MemoryDocumentStore instance. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of documents returned by the search engine. + + + +#### ChromaQueryTextRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChromaQueryTextRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ChromaQueryTextRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +### ChromaEmbeddingRetriever + +A component for retrieving documents from a [Chroma database](https://docs.trychroma.com/) using embeddings. + + + +#### ChromaEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: ChromaDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: an instance of `ChromaDocumentStore`. +- `filters`: filters to narrow down the search space. +- `top_k`: the maximum number of documents to retrieve. +- `filter_policy`: Policy to determine how filters are applied. + + + +#### ChromaEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, Any] +``` + +Run the retriever on the given input data. + +**Arguments**: + +- `query_embedding`: the query embeddings. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: the maximum number of documents to retrieve. +If not specified, the default value from the constructor is used. + +**Returns**: + +a dictionary with the following keys: +- `documents`: List of documents returned by the search engine. + + + +#### ChromaEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, Any] +``` + +Asynchronously run the retriever on the given input data. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `query_embedding`: the query embeddings. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: the maximum number of documents to retrieve. +If not specified, the default value from the constructor is used. + +**Returns**: + +a dictionary with the following keys: +- `documents`: List of documents returned by the search engine. + + + +#### ChromaEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChromaEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ChromaEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module haystack\_integrations.document\_stores.chroma.document\_store + + + +### ChromaDocumentStore + +A document store using [Chroma](https://docs.trychroma.com/) as the backend. + +We use the `collection.get` API to implement the document store protocol, +the `collection.search` API will be used in the retriever instead. + + + +#### ChromaDocumentStore.\_\_init\_\_ + +```python +def __init__(collection_name: str = "documents", + embedding_function: str = "default", + persist_path: Optional[str] = None, + host: Optional[str] = None, + port: Optional[int] = None, + distance_function: Literal["l2", "cosine", "ip"] = "l2", + metadata: Optional[dict] = None, + **embedding_function_params: Any) +``` + +Creates a new ChromaDocumentStore instance. + +It is meant to be connected to a Chroma collection. + +Note: for the component to be part of a serializable pipeline, the __init__ +parameters must be serializable, reason why we use a registry to configure the +embedding function passing a string. + +**Arguments**: + +- `collection_name`: the name of the collection to use in the database. +- `embedding_function`: the name of the embedding function to use to embed the query +- `persist_path`: Path for local persistent storage. Cannot be used in combination with `host` and `port`. +If none of `persist_path`, `host`, and `port` is specified, the database will be `in-memory`. +- `host`: The host address for the remote Chroma HTTP client connection. Cannot be used with `persist_path`. +- `port`: The port number for the remote Chroma HTTP client connection. Cannot be used with `persist_path`. +- `distance_function`: The distance metric for the embedding space. +- `"l2"` computes the Euclidean (straight-line) distance between vectors, +where smaller scores indicate more similarity. +- `"cosine"` computes the cosine similarity between vectors, +with higher scores indicating greater similarity. +- `"ip"` stands for inner product, where higher scores indicate greater similarity between vectors. +**Note**: `distance_function` can only be set during the creation of a collection. +To change the distance metric of an existing collection, consider cloning the collection. +- `metadata`: a dictionary of chromadb collection parameters passed directly to chromadb's client +method `create_collection`. If it contains the key `"hnsw:space"`, the value will take precedence over the +`distance_function` parameter above. +- `embedding_function_params`: additional parameters to pass to the embedding function. + + + +#### ChromaDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + +**Returns**: + +how many documents are present in the document store. + + + +#### ChromaDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns how many documents are present in the document store. + +Asynchronous methods are only supported for HTTP connections. + +**Returns**: + +how many documents are present in the document store. + + + +#### ChromaDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering). + +**Arguments**: + +- `filters`: the filters to apply to the document list. + +**Returns**: + +a list of Documents that match the given filters. + + + +#### ChromaDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously returns the documents that match the filters provided. + +Asynchronous methods are only supported for HTTP connections. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering). + +**Arguments**: + +- `filters`: the filters to apply to the document list. + +**Returns**: + +a list of Documents that match the given filters. + + + +#### ChromaDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> int +``` + +Writes (or overwrites) documents into the store. + +**Arguments**: + +- `documents`: A list of documents to write into the document store. +- `policy`: Not supported at the moment. + +**Raises**: + +- `ValueError`: When input is not valid. + +**Returns**: + +The number of documents written + + + +#### ChromaDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> int +``` + +Asynchronously writes (or overwrites) documents into the store. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `documents`: A list of documents to write into the document store. +- `policy`: Not supported at the moment. + +**Raises**: + +- `ValueError`: When input is not valid. + +**Returns**: + +The number of documents written + + + +#### ChromaDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes all documents with a matching document_ids from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### ChromaDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes all documents with a matching document_ids from the document store. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### ChromaDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(*, recreate_index: bool = False) -> None +``` + +Deletes all documents in the document store. + +A fast way to clear all documents from the document store while preserving any collection settings and mappings. + +**Arguments**: + +- `recreate_index`: Whether to recreate the index after deleting all documents. + + + +#### ChromaDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async(*, recreate_index: bool = False) -> None +``` + +Asynchronously deletes all documents in the document store. + +A fast way to clear all documents from the document store while preserving any collection settings and mappings. + +**Arguments**: + +- `recreate_index`: Whether to recreate the index after deleting all documents. + + + +#### ChromaDocumentStore.search + +```python +def search(queries: List[str], + top_k: int, + filters: Optional[Dict[str, Any]] = None) -> List[List[Document]] +``` + +Search the documents in the store using the provided text queries. + +**Arguments**: + +- `queries`: the list of queries to search for. +- `top_k`: top_k documents to return for each query. +- `filters`: a dictionary of filters to apply to the search. Accepts filters in haystack format. + +**Returns**: + +matching documents for each query. + + + +#### ChromaDocumentStore.search\_async + +```python +async def search_async( + queries: List[str], + top_k: int, + filters: Optional[Dict[str, Any]] = None) -> List[List[Document]] +``` + +Asynchronously search the documents in the store using the provided text queries. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `queries`: the list of queries to search for. +- `top_k`: top_k documents to return for each query. +- `filters`: a dictionary of filters to apply to the search. Accepts filters in haystack format. + +**Returns**: + +matching documents for each query. + + + +#### ChromaDocumentStore.search\_embeddings + +```python +def search_embeddings( + query_embeddings: List[List[float]], + top_k: int, + filters: Optional[Dict[str, Any]] = None) -> List[List[Document]] +``` + +Perform vector search on the stored document, pass the embeddings of the queries instead of their text. + +**Arguments**: + +- `query_embeddings`: a list of embeddings to use as queries. +- `top_k`: the maximum number of documents to retrieve. +- `filters`: a dictionary of filters to apply to the search. Accepts filters in haystack format. + +**Returns**: + +a list of lists of documents that match the given filters. + + + +#### ChromaDocumentStore.search\_embeddings\_async + +```python +async def search_embeddings_async( + query_embeddings: List[List[float]], + top_k: int, + filters: Optional[Dict[str, Any]] = None) -> List[List[Document]] +``` + +Asynchronously perform vector search on the stored document, pass the embeddings of the queries instead of + +their text. + +Asynchronous methods are only supported for HTTP connections. + +**Arguments**: + +- `query_embeddings`: a list of embeddings to use as queries. +- `top_k`: the maximum number of documents to retrieve. +- `filters`: a dictionary of filters to apply to the search. Accepts filters in haystack format. + +**Returns**: + +a list of lists of documents that match the given filters. + + + +#### ChromaDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChromaDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ChromaDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module haystack\_integrations.document\_stores.chroma.errors + + + +### ChromaDocumentStoreError + +Parent class for all ChromaDocumentStore exceptions. + + + +### ChromaDocumentStoreFilterError + +Raised when a filter is not valid for a ChromaDocumentStore. + + + +### ChromaDocumentStoreConfigError + +Raised when a configuration is not valid for a ChromaDocumentStore. + + + +## Module haystack\_integrations.document\_stores.chroma.utils + + + +#### get\_embedding\_function + +```python +def get_embedding_function(function_name: str, + **kwargs: Any) -> EmbeddingFunction +``` + +Load an embedding function by name. + +**Arguments**: + +- `function_name`: the name of the embedding function. +- `kwargs`: additional arguments to pass to the embedding function. + +**Raises**: + +- `ChromaDocumentStoreConfigError`: if the function name is invalid. + +**Returns**: + +the loaded embedding function. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/cohere.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/cohere.md new file mode 100644 index 0000000000..5062839bef --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/cohere.md @@ -0,0 +1,987 @@ +--- +title: "Cohere" +id: integrations-cohere +description: "Cohere integration for Haystack" +slug: "/integrations-cohere" +--- + + + +## Module haystack\_integrations.components.embedders.cohere.document\_embedder + + + +### CohereDocumentEmbedder + +A component for computing Document embeddings using Cohere models. + +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.cohere import CohereDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = CohereDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [-0.453125, 1.2236328, 2.0058594, ...] +``` + + + +#### CohereDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + model: str = "embed-english-v2.0", + input_type: str = "search_document", + api_base_url: str = "https://api.cohere.com", + truncate: str = "END", + timeout: float = 120.0, + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + embedding_type: Optional[EmbeddingTypes] = None) +``` + +**Arguments**: + +- `api_key`: the Cohere API key. +- `model`: the name of the model to use. Supported Models are: +`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`, +`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`, +`"embed-multilingual-v2.0"`. This list of all supported models can be found in the +[model documentation](https://docs.cohere.com/docs/models#representation). +- `input_type`: specifies the type of input you're giving to the model. Supported values are +"search_document", "search_query", "classification" and "clustering". Not +required for older versions of the embedding models (meaning anything lower than v3), but is required for +more recent versions (meaning anything bigger than v2). +- `api_base_url`: the Cohere API Base url. +- `truncate`: truncate embeddings that are too long from start or end, ("NONE"|"START"|"END"). +Passing "START" will discard the start of the input. "END" will discard the end of the input. In both +cases, input is discarded until the remaining input is exactly the maximum input token length for the model. +If "NONE" is selected, when the input exceeds the maximum input token length an error will be returned. +- `timeout`: request timeout in seconds. +- `batch_size`: number of Documents to encode at once. +- `progress_bar`: whether to show a progress bar or not. Can be helpful to disable in production deployments +to keep the logs clean. +- `meta_fields_to_embed`: list of meta fields that should be embedded along with the Document text. +- `embedding_separator`: separator used to concatenate the meta fields to the Document text. +- `embedding_type`: the type of embeddings to return. Defaults to float embeddings. +Note that int8, uint8, binary, and ubinary are only valid for v3 models. + + + +#### CohereDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CohereDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "CohereDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### CohereDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +def run( + documents: List[Document] +) -> Dict[str, Union[List[Document], Dict[str, Any]]] +``` + +Embed a list of `Documents`. + +**Arguments**: + +- `documents`: documents to embed. + +**Raises**: + +- `TypeError`: if the input is not a list of `Documents`. + +**Returns**: + +A dictionary with the following keys: +- `documents`: documents with the `embedding` field set. +- `meta`: metadata about the embedding process. + + + +#### CohereDocumentEmbedder.run\_async + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +async def run_async( + documents: List[Document] +) -> Dict[str, Union[List[Document], Dict[str, Any]]] +``` + +Embed a list of `Documents` asynchronously. + +**Arguments**: + +- `documents`: documents to embed. + +**Raises**: + +- `TypeError`: if the input is not a list of `Documents`. + +**Returns**: + +A dictionary with the following keys: +- `documents`: documents with the `embedding` field set. +- `meta`: metadata about the embedding process. + + + +## Module haystack\_integrations.components.embedders.cohere.document\_image\_embedder + + + +### CohereDocumentImageEmbedder + +A component for computing Document embeddings based on images using Cohere models. + +The embedding of each Document is stored in the `embedding` field of the Document. + +### Usage example +```python +from haystack import Document +from haystack_integrations.components.embedders.cohere import CohereDocumentImageEmbedder + +embedder = CohereDocumentImageEmbedder(model="embed-v4.0") + +documents = [ + Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}), + Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}), +] + +result = embedder.run(documents=documents) +documents_with_embeddings = result["documents"] +print(documents_with_embeddings) + +# [Document(id=..., +# content='A photo of a cat', +# meta={'file_path': 'cat.jpg', +# 'embedding_source': {'type': 'image', 'file_path_meta_field': 'file_path'}}, +# embedding=vector of size 1536), +# ...] +``` + + + +#### CohereDocumentImageEmbedder.\_\_init\_\_ + +```python +def __init__(*, + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + image_size: Optional[Tuple[int, int]] = None, + api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + model: str = "embed-v4.0", + api_base_url: str = "https://api.cohere.com", + timeout: float = 120.0, + embedding_dimension: Optional[int] = None, + embedding_type: EmbeddingTypes = EmbeddingTypes.FLOAT, + progress_bar: bool = True) -> None +``` + +Creates a CohereDocumentImageEmbedder component. + +**Arguments**: + +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `image_size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time, which is beneficial +when working with models that have resolution constraints or when transmitting images to remote services. +- `api_key`: The Cohere API key. +- `model`: The Cohere model to use for calculating embeddings. +Read [Cohere documentation](https://docs.cohere.com/docs/models#embed) for a list of all supported models. +- `api_base_url`: The Cohere API base URL. +- `timeout`: Request timeout in seconds. +- `embedding_dimension`: The dimension of the embeddings to return. Only valid for v4 and newer models. +Read [Cohere API reference](https://docs.cohere.com/reference/embed) for a list possible values and +supported models. +- `embedding_type`: The type of embeddings to return. Defaults to float embeddings. +Specifying a type different from float is only supported for Embed v3.0 and newer models. +- `progress_bar`: Whether to show a progress bar or not. Can be helpful to disable in production deployments +to keep the logs clean. + + + +#### CohereDocumentImageEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CohereDocumentImageEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "CohereDocumentImageEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### CohereDocumentImageEmbedder.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: list[Document]) -> dict[str, list[Document]] +``` + +Embed a list of image documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + + + +#### CohereDocumentImageEmbedder.run\_async + +```python +@component.output_types(documents=list[Document]) +async def run_async(documents: list[Document]) -> dict[str, list[Document]] +``` + +Asynchronously embed a list of image documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + + + +## Module haystack\_integrations.components.embedders.cohere.text\_embedder + + + +### CohereTextEmbedder + +A component for embedding strings using Cohere models. + +Usage example: +```python +from haystack_integrations.components.embedders.cohere import CohereTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = CohereTextEmbedder() + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [-0.453125, 1.2236328, 2.0058594, ...] +# 'meta': {'api_version': {'version': '1'}, 'billed_units': {'input_tokens': 4}}} +``` + + + +#### CohereTextEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + model: str = "embed-english-v2.0", + input_type: str = "search_query", + api_base_url: str = "https://api.cohere.com", + truncate: str = "END", + timeout: float = 120.0, + embedding_type: Optional[EmbeddingTypes] = None) +``` + +**Arguments**: + +- `api_key`: the Cohere API key. +- `model`: the name of the model to use. Supported Models are: +`"embed-english-v3.0"`, `"embed-english-light-v3.0"`, `"embed-multilingual-v3.0"`, +`"embed-multilingual-light-v3.0"`, `"embed-english-v2.0"`, `"embed-english-light-v2.0"`, +`"embed-multilingual-v2.0"`. This list of all supported models can be found in the +[model documentation](https://docs.cohere.com/docs/models#representation). +- `input_type`: specifies the type of input you're giving to the model. Supported values are +"search_document", "search_query", "classification" and "clustering". Not +required for older versions of the embedding models (meaning anything lower than v3), but is required for +more recent versions (meaning anything bigger than v2). +- `api_base_url`: the Cohere API Base url. +- `truncate`: truncate embeddings that are too long from start or end, ("NONE"|"START"|"END"). +Passing "START" will discard the start of the input. "END" will discard the end of the input. In both +cases, input is discarded until the remaining input is exactly the maximum input token length for the model. +If "NONE" is selected, when the input exceeds the maximum input token length an error will be returned. +- `timeout`: request timeout in seconds. +- `embedding_type`: the type of embeddings to return. Defaults to float embeddings. +Note that int8, uint8, binary, and ubinary are only valid for v3 models. + + + +#### CohereTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CohereTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "CohereTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### CohereTextEmbedder.run + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +def run(text: str) -> Dict[str, Union[List[float], Dict[str, Any]]] +``` + +Embed text. + +**Arguments**: + +- `text`: the text to embed. + +**Raises**: + +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: the embedding of the text. +- `meta`: metadata about the request. + + + +#### CohereTextEmbedder.run\_async + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +async def run_async( + text: str) -> Dict[str, Union[List[float], Dict[str, Any]]] +``` + +Asynchronously embed text. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + + :param text: + Text to embed. + +**Raises**: + +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: the embedding of the text. +- `meta`: metadata about the request. + + + +## Module haystack\_integrations.components.embedders.cohere.utils + + + +#### get\_async\_response + +```python +async def get_async_response( + cohere_async_client: AsyncClientV2, + texts: List[str], + model_name: str, + input_type: str, + truncate: str, + embedding_type: Optional[EmbeddingTypes] = None +) -> Tuple[List[List[float]], Dict[str, Any]] +``` + +Embeds a list of texts asynchronously using the Cohere API. + +**Arguments**: + +- `cohere_async_client`: the Cohere `AsyncClient` +- `texts`: the texts to embed +- `model_name`: the name of the model to use +- `input_type`: one of "classification", "clustering", "search_document", "search_query". +The type of input text provided to embed. +- `truncate`: one of "NONE", "START", "END". How the API handles text longer than the maximum token length. +- `embedding_type`: the type of embeddings to return. Defaults to float embeddings. + +**Raises**: + +- `ValueError`: If an error occurs while querying the Cohere API. + +**Returns**: + +A tuple of the embeddings and metadata. + + + +#### get\_response + +```python +def get_response( + cohere_client: ClientV2, + texts: List[str], + model_name: str, + input_type: str, + truncate: str, + batch_size: int = 32, + progress_bar: bool = False, + embedding_type: Optional[EmbeddingTypes] = None +) -> Tuple[List[List[float]], Dict[str, Any]] +``` + +Embeds a list of texts using the Cohere API. + +**Arguments**: + +- `cohere_client`: the Cohere `Client` +- `texts`: the texts to embed +- `model_name`: the name of the model to use +- `input_type`: one of "classification", "clustering", "search_document", "search_query". +The type of input text provided to embed. +- `truncate`: one of "NONE", "START", "END". How the API handles text longer than the maximum token length. +- `batch_size`: the batch size to use +- `progress_bar`: if `True`, show a progress bar +- `embedding_type`: the type of embeddings to return. Defaults to float embeddings. + +**Raises**: + +- `ValueError`: If an error occurs while querying the Cohere API. + +**Returns**: + +A tuple of the embeddings and metadata. + + + +## Module haystack\_integrations.components.generators.cohere.generator + + + +### CohereGenerator + +Generates text using Cohere's models through Cohere's `generate` endpoint. + +NOTE: Cohere discontinued the `generate` API, so this generator is a mere wrapper +around `CohereChatGenerator` provided for backward compatibility. + +### Usage example + +```python +from haystack_integrations.components.generators.cohere import CohereGenerator + +generator = CohereGenerator(api_key="test-api-key") +generator.run(prompt="What's the capital of France?") +``` + + + +#### CohereGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + model: str = "command-r-08-2024", + streaming_callback: Optional[Callable] = None, + api_base_url: Optional[str] = None, + **kwargs: Any) +``` + +Instantiates a `CohereGenerator` component. + +**Arguments**: + +- `api_key`: Cohere API key. +- `model`: Cohere model to use for generation. +- `streaming_callback`: Callback function that is called when a new token is received from the stream. +The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `api_base_url`: Cohere base URL. +- `**kwargs`: Additional arguments passed to the model. These arguments are specific to the model. +You can check them in model's documentation. + + + +#### CohereGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run(prompt: str) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Queries the LLM with the prompts to produce replies. + +**Arguments**: + +- `prompt`: the prompt to be sent to the generative model. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of replies generated by the model. +- `meta`: Information about the request. + + + +#### CohereGenerator.run\_async + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +async def run_async( + prompt: str) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Queries the LLM asynchronously with the prompts to produce replies. + +**Arguments**: + +- `prompt`: the prompt to be sent to the generative model. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of replies generated by the model. +- `meta`: Information about the request. + + + +## Module haystack\_integrations.components.generators.cohere.chat.chat\_generator + + + +### CohereChatGenerator + +Completes chats using Cohere's models using cohere.ClientV2 `chat` endpoint. + +This component supports both text-only and multimodal (text + image) conversations +using Cohere's vision models like Command A Vision. + +Supported image formats: PNG, JPEG, WEBP, GIF (non-animated). +Maximum 20 images per request with 20MB total limit. + +You can customize how the chat response is generated by passing parameters to the +Cohere API through the `**generation_kwargs` parameter. You can do this when +initializing or running the component. Any parameter that works with + `cohere.ClientV2.chat` will work here too. +For details, see [Cohere API](https://docs.cohere.com/reference/chat). + +Below is an example of how to use the component: + +### Simple example +```python +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret +from haystack_integrations.components.generators.cohere import CohereChatGenerator + +client = CohereChatGenerator(model="command-r-08-2024", api_key=Secret.from_env_var("COHERE_API_KEY")) +messages = [ChatMessage.from_user("What's Natural Language Processing?")] +client.run(messages) + +# Output: {'replies': [ChatMessage(_role=, +# _content=[TextContent(text='Natural Language Processing (NLP) is an interdisciplinary... +``` + +### Multimodal example +```python +from haystack.dataclasses import ChatMessage, ImageContent +from haystack.utils import Secret +from haystack_integrations.components.generators.cohere import CohereChatGenerator + +# Create an image from file path or base64 +image_content = ImageContent.from_file_path("path/to/your/image.jpg") + +# Create a multimodal message with both text and image +messages = [ChatMessage.from_user(content_parts=["What's in this image?", image_content])] + +# Use a multimodal model like Command A Vision +client = CohereChatGenerator(model="command-a-vision-07-2025", api_key=Secret.from_env_var("COHERE_API_KEY")) +response = client.run(messages) +print(response) +``` + +### Advanced example + +CohereChatGenerator can be integrated into pipelines and supports Haystack's tooling +architecture, enabling tools to be invoked seamlessly across various generators. + +```python +from haystack import Pipeline +from haystack.dataclasses import ChatMessage +from haystack.components.tools import ToolInvoker +from haystack.tools import Tool +from haystack_integrations.components.generators.cohere import CohereChatGenerator + +# Create a weather tool +def weather(city: str) -> str: + return f"The weather in {city} is sunny and 32°C" + +weather_tool = Tool( + name="weather", + description="useful to determine the weather in a given location", + parameters={ + "type": "object", + "properties": { + "city": { + "type": "string", + "description": "The name of the city to get weather for, e.g. Paris, London", + } + }, + "required": ["city"], + }, + function=weather, +) + +# Create and set up the pipeline +pipeline = Pipeline() +pipeline.add_component("generator", CohereChatGenerator(model="command-r-08-2024", tools=[weather_tool])) +pipeline.add_component("tool_invoker", ToolInvoker(tools=[weather_tool])) +pipeline.connect("generator", "tool_invoker") + +# Run the pipeline with a weather query +results = pipeline.run( + data={"generator": {"messages": [ChatMessage.from_user("What's the weather like in Paris?")]}} +) + +# The tool result will be available in the pipeline output +print(results["tool_invoker"]["tool_messages"][0].tool_call_result.result) +# Output: "The weather in Paris is sunny and 32°C" +``` + + + +#### CohereChatGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + model: str = "command-r-08-2024", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + **kwargs: Any) +``` + +Initialize the CohereChatGenerator instance. + +**Arguments**: + +- `api_key`: The API key for the Cohere API. +- `model`: The name of the model to use. You can use models from the `command` family. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts [StreamingChunk](https://docs.haystack.deepset.ai/docs/data-classes#streamingchunk) +as an argument. +- `api_base_url`: The base URL of the Cohere API. +- `generation_kwargs`: Other parameters to use for the model during generation. For a list of parameters, +see [Cohere Chat endpoint](https://docs.cohere.com/reference/chat). +Some of the parameters are: +- 'messages': A list of messages between the user and the model, meant to give the model + conversational context for responding to the user's message. +- 'system_message': When specified, adds a system message at the beginning of the conversation. +- 'citation_quality': Defaults to `accurate`. Dictates the approach taken to generating citations + as part of the RAG flow by allowing the user to specify whether they want + `accurate` results or `fast` results. +- 'temperature': A non-negative float that tunes the degree of randomness in generation. Lower temperatures + mean less random generations. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset that the model can use. +Each tool should have a unique name. + + + +#### CohereChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CohereChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "CohereChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### CohereChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run( + messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Optional[StreamingCallbackT] = None +) -> Dict[str, List[ChatMessage]] +``` + +Invoke the chat endpoint based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: list of `ChatMessage` instances representing the input messages. +- `generation_kwargs`: additional keyword arguments for chat generation. These parameters will +potentially override the parameters passed in the __init__ method. +For more details on the parameters supported by the Cohere API, refer to the +Cohere [documentation](https://docs.cohere.com/reference/chat). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter set during component initialization. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. + +**Returns**: + +A dictionary with the following keys: +- `replies`: a list of `ChatMessage` instances representing the generated responses. + + + +#### CohereChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async( + messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + streaming_callback: Optional[StreamingCallbackT] = None +) -> Dict[str, List[ChatMessage]] +``` + +Asynchronously invoke the chat endpoint based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: list of `ChatMessage` instances representing the input messages. +- `generation_kwargs`: additional keyword arguments for chat generation. These parameters will +potentially override the parameters passed in the __init__ method. +For more details on the parameters supported by the Cohere API, refer to the +Cohere [documentation](https://docs.cohere.com/reference/chat). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter set during component initialization. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. + +**Returns**: + +A dictionary with the following keys: +- `replies`: a list of `ChatMessage` instances representing the generated responses. + + + +## Module haystack\_integrations.components.rankers.cohere.ranker + + + +### CohereRanker + +Ranks Documents based on their similarity to the query using [Cohere models](https://docs.cohere.com/reference/rerank-1). + +Documents are indexed from most to least semantically relevant to the query. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.rankers.cohere import CohereRanker + +ranker = CohereRanker(model="rerank-v3.5", top_k=2) + +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "What is the capital of germany?" +output = ranker.run(query=query, documents=docs) +docs = output["documents"] +``` + + + +#### CohereRanker.\_\_init\_\_ + +```python +def __init__(model: str = "rerank-v3.5", + top_k: int = 10, + api_key: Secret = Secret.from_env_var( + ["COHERE_API_KEY", "CO_API_KEY"]), + api_base_url: str = "https://api.cohere.com", + meta_fields_to_embed: Optional[List[str]] = None, + meta_data_separator: str = "\n", + max_tokens_per_doc: int = 4096) +``` + +Creates an instance of the 'CohereRanker'. + +**Arguments**: + +- `model`: Cohere model name. Check the list of supported models in the [Cohere documentation](https://docs.cohere.com/docs/models). +- `top_k`: The maximum number of documents to return. +- `api_key`: Cohere API key. +- `api_base_url`: the base URL of the Cohere API. +- `meta_fields_to_embed`: List of meta fields that should be concatenated +with the document content for reranking. +- `meta_data_separator`: Separator used to concatenate the meta fields +to the Document content. +- `max_tokens_per_doc`: The maximum number of tokens to embed for each document defaults to 4096. + + + +#### CohereRanker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### CohereRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "CohereRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### CohereRanker.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + documents: List[Document], + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Use the Cohere Reranker to re-rank the list of documents based on the query. + +**Arguments**: + +- `query`: Query string. +- `documents`: List of Documents. +- `top_k`: The maximum number of Documents you want the Ranker to return. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given query in descending order of similarity. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/deepeval.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/deepeval.md new file mode 100644 index 0000000000..1211eff805 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/deepeval.md @@ -0,0 +1,193 @@ +--- +title: "DeepEval" +id: integrations-deepeval +description: "DeepEval integration for Haystack" +slug: "/integrations-deepeval" +--- + + + +## Module haystack\_integrations.components.evaluators.deepeval.evaluator + + + +### DeepEvalEvaluator + +A component that uses the [DeepEval framework](https://docs.confident-ai.com/docs/evaluation-introduction) +to evaluate inputs against a specific metric. Supported metrics are defined by `DeepEvalMetric`. + +Usage example: +```python +from haystack_integrations.components.evaluators.deepeval import DeepEvalEvaluator, DeepEvalMetric + +evaluator = DeepEvalEvaluator( + metric=DeepEvalMetric.FAITHFULNESS, + metric_params={"model": "gpt-4"}, +) +output = evaluator.run( + questions=["Which is the most popular global sport?"], + contexts=[ + [ + "Football is undoubtedly the world's most popular sport with" + "major events like the FIFA World Cup and sports personalities" + "like Ronaldo and Messi, drawing a followership of more than 4" + "billion people." + ] + ], + responses=["Football is the most popular sport with around 4 billion" "followers worldwide"], +) +print(output["results"]) +``` + + + +#### DeepEvalEvaluator.\_\_init\_\_ + +```python +def __init__(metric: str | DeepEvalMetric, + metric_params: dict[str, Any] | None = None) +``` + +Construct a new DeepEval evaluator. + +**Arguments**: + +- `metric`: The metric to use for evaluation. +- `metric_params`: Parameters to pass to the metric's constructor. +Refer to the `RagasMetric` class for more details +on required parameters. + + + +#### DeepEvalEvaluator.run + +```python +@component.output_types(results=list[list[dict[str, Any]]]) +def run(**inputs: Any) -> dict[str, Any] +``` + +Run the DeepEval evaluator on the provided inputs. + +**Arguments**: + +- `inputs`: The inputs to evaluate. These are determined by the +metric being calculated. See `DeepEvalMetric` for more +information. + +**Returns**: + +A dictionary with a single `results` entry that contains +a nested list of metric results. Each input can have one or more +results, depending on the metric. Each result is a dictionary +containing the following keys and values: +- `name` - The name of the metric. +- `score` - The score of the metric. +- `explanation` - An optional explanation of the score. + + + +#### DeepEvalEvaluator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Raises**: + +- `DeserializationError`: If the component cannot be serialized. + +**Returns**: + +Dictionary with serialized data. + + + +#### DeepEvalEvaluator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "DeepEvalEvaluator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.components.evaluators.deepeval.metrics + + + +### DeepEvalMetric + +Metrics supported by DeepEval. + +All metrics require a `model` parameter, which specifies +the model to use for evaluation. Refer to the DeepEval +documentation for information on the supported models. + + + +#### ANSWER\_RELEVANCY + +Answer relevancy.\ +Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]` + + + +#### FAITHFULNESS + +Faithfulness.\ +Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]` + + + +#### CONTEXTUAL\_PRECISION + +Contextual precision.\ +Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\ +The ground truth is the expected response. + + + +#### CONTEXTUAL\_RECALL + +Contextual recall.\ +Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str], ground_truths: List[str]`\ +The ground truth is the expected response.\ + + + +#### CONTEXTUAL\_RELEVANCE + +Contextual relevance.\ +Inputs - `questions: List[str], contexts: List[List[str]], responses: List[str]` + + + +#### DeepEvalMetric.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "DeepEvalMetric" +``` + +Create a metric type from a string. + +**Arguments**: + +- `string`: The string to convert. + +**Returns**: + +The metric. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/elasticsearch.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/elasticsearch.md new file mode 100644 index 0000000000..24e966187f --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/elasticsearch.md @@ -0,0 +1,642 @@ +--- +title: "Elasticsearch" +id: integrations-elasticsearch +description: "Elasticsearch integration for Haystack" +slug: "/integrations-elasticsearch" +--- + + + +## Module haystack\_integrations.components.retrievers.elasticsearch.bm25\_retriever + + + +### ElasticsearchBM25Retriever + +ElasticsearchBM25Retriever retrieves documents from the ElasticsearchDocumentStore using BM25 algorithm to find the +most similar documents to a user's query. + +This retriever is only compatible with ElasticsearchDocumentStore. + +Usage example: +```python +from haystack import Document +from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore +from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchBM25Retriever + +document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200") +retriever = ElasticsearchBM25Retriever(document_store=document_store) + +# Add documents to DocumentStore +documents = [ + Document(text="My name is Carla and I live in Berlin"), + Document(text="My name is Paul and I live in New York"), + Document(text="My name is Silvano and I live in Matera"), + Document(text="My name is Usagi Tsukino and I live in Tokyo"), +] +document_store.write_documents(documents) + +result = retriever.run(query="Who lives in Berlin?") +for doc in result["documents"]: + print(doc.content) +``` + + + +#### ElasticsearchBM25Retriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: ElasticsearchDocumentStore, + filters: Optional[Dict[str, Any]] = None, + fuzziness: str = "AUTO", + top_k: int = 10, + scale_score: bool = False, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Initialize ElasticsearchBM25Retriever with an instance ElasticsearchDocumentStore. + +**Arguments**: + +- `document_store`: An instance of ElasticsearchDocumentStore. +- `filters`: Filters applied to the retrieved Documents, for more info +see `ElasticsearchDocumentStore.filter_documents`. +- `fuzziness`: Fuzziness parameter passed to Elasticsearch. See the official +[documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#fuzziness) +for more details. +- `top_k`: Maximum number of Documents to return. +- `scale_score`: If `True` scales the Document`s scores between 0 and 1. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `ElasticsearchDocumentStore`. + + + +#### ElasticsearchBM25Retriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ElasticsearchBM25Retriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ElasticsearchBM25Retriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ElasticsearchBM25Retriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents using the BM25 keyword-based algorithm. + +**Arguments**: + +- `query`: String to search in the `Document`s text. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of `Document` to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that match the query. + + + +#### ElasticsearchBM25Retriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents using the BM25 keyword-based algorithm. + +**Arguments**: + +- `query`: String to search in the `Document` text. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of `Document` to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that match the query. + + + +## Module haystack\_integrations.components.retrievers.elasticsearch.embedding\_retriever + + + +### ElasticsearchEmbeddingRetriever + +ElasticsearchEmbeddingRetriever retrieves documents from the ElasticsearchDocumentStore using vector similarity. + +Usage example: +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersTextEmbedder +from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore +from haystack_integrations.components.retrievers.elasticsearch import ElasticsearchEmbeddingRetriever + +document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200") +retriever = ElasticsearchEmbeddingRetriever(document_store=document_store) + +# Add documents to DocumentStore +documents = [ + Document(text="My name is Carla and I live in Berlin"), + Document(text="My name is Paul and I live in New York"), + Document(text="My name is Silvano and I live in Matera"), + Document(text="My name is Usagi Tsukino and I live in Tokyo"), +] +document_store.write_documents(documents) + +te = SentenceTransformersTextEmbedder() +te.warm_up() +query_embeddings = te.run("Who lives in Berlin?")["embedding"] + +result = retriever.run(query=query_embeddings) +for doc in result["documents"]: + print(doc.content) +``` + + + +#### ElasticsearchEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: ElasticsearchDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + num_candidates: Optional[int] = None, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Create the ElasticsearchEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of ElasticsearchDocumentStore. +- `filters`: Filters applied to the retrieved Documents. +Filters are applied during the approximate KNN search to ensure that top_k matching documents are returned. +- `top_k`: Maximum number of Documents to return. +- `num_candidates`: Number of approximate nearest neighbor candidates on each shard. Defaults to top_k * 10. +Increasing this value will improve search accuracy at the cost of slower search speeds. +You can read more about it in the Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/knn-search.html#tune-approximate-knn-for-speed-accuracy) +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of ElasticsearchDocumentStore. + + + +#### ElasticsearchEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ElasticsearchEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ElasticsearchEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ElasticsearchEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied when fetching documents from the Document Store. +Filters are applied during the approximate kNN search to ensure the Retriever returns + `top_k` matching documents. +The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever. +- `top_k`: Maximum number of documents to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s most similar to the given `query_embedding` + + + +#### ElasticsearchEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied when fetching documents from the Document Store. +Filters are applied during the approximate kNN search to ensure the Retriever returns + `top_k` matching documents. +The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever. +- `top_k`: Maximum number of documents to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that match the query. + + + +## Module haystack\_integrations.document\_stores.elasticsearch.document\_store + + + +### ElasticsearchDocumentStore + +An ElasticsearchDocumentStore instance that works with Elastic Cloud or your own +Elasticsearch cluster. + +Usage example (Elastic Cloud): +```python +from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore +document_store = ElasticsearchDocumentStore( + api_key_id=Secret.from_env_var("ELASTIC_API_KEY_ID", strict=False), + api_key=Secret.from_env_var("ELASTIC_API_KEY", strict=False), +) +``` + +Usage example (self-hosted Elasticsearch instance): +```python +from haystack_integrations.document_stores.elasticsearch import ElasticsearchDocumentStore +document_store = ElasticsearchDocumentStore(hosts="http://localhost:9200") +``` +In the above example we connect with security disabled just to show the basic usage. +We strongly recommend to enable security so that only authorized users can access your data. + +For more details on how to connect to Elasticsearch and configure security, +see the official Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/connecting.html) + +All extra keyword arguments will be passed to the Elasticsearch client. + + + +#### ElasticsearchDocumentStore.\_\_init\_\_ + +```python +def __init__( + *, + hosts: Optional[Hosts] = None, + custom_mapping: Optional[Dict[str, Any]] = None, + index: str = "default", + api_key: Secret = Secret.from_env_var("ELASTIC_API_KEY", strict=False), + api_key_id: Secret = Secret.from_env_var("ELASTIC_API_KEY_ID", + strict=False), + embedding_similarity_function: Literal["cosine", "dot_product", + "l2_norm", + "max_inner_product"] = "cosine", + **kwargs: Any) +``` + +Creates a new ElasticsearchDocumentStore instance. + +It will also try to create that index if it doesn't exist yet. Otherwise, it will use the existing one. + +One can also set the similarity function used to compare Documents embeddings. This is mostly useful +when using the `ElasticsearchDocumentStore` in a Pipeline with an `ElasticsearchEmbeddingRetriever`. + +For more information on connection parameters, see the official Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/client/python-api/current/connecting.html) + +For the full list of supported kwargs, see the official Elasticsearch +[reference](https://elasticsearch-py.readthedocs.io/en/stable/api.html#module-elasticsearch) + +Authentication is provided via Secret objects, which by default are loaded from environment variables. +You can either provide both `api_key_id` and `api_key`, or just `api_key` containing a base64-encoded string +of `id:secret`. Secret instances can also be loaded from a token using the `Secret.from_token()` method. + +**Arguments**: + +- `hosts`: List of hosts running the Elasticsearch client. +- `custom_mapping`: Custom mapping for the index. If not provided, a default mapping will be used. +- `index`: Name of index in Elasticsearch. +- `api_key`: A Secret object containing the API key for authenticating or base64-encoded with the +concatenated secret and id for authenticating with Elasticsearch (separated by “:”). +- `api_key_id`: A Secret object containing the API key ID for authenticating with Elasticsearch. +- `embedding_similarity_function`: The similarity function used to compare Documents embeddings. +This parameter only takes effect if the index does not yet exist and is created. +To choose the most appropriate function, look for information about your embedding model. +To understand how document scores are computed, see the Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/dense-vector.html#dense-vector-params) +- `**kwargs`: Optional arguments that `Elasticsearch` takes. + + + +#### ElasticsearchDocumentStore.client + +```python +@property +def client() -> Elasticsearch +``` + +Returns the synchronous Elasticsearch client, initializing it if necessary. + + + +#### ElasticsearchDocumentStore.async\_client + +```python +@property +def async_client() -> AsyncElasticsearch +``` + +Returns the asynchronous Elasticsearch client, initializing it if necessary. + + + +#### ElasticsearchDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### ElasticsearchDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ElasticsearchDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### ElasticsearchDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + +**Returns**: + +Number of documents in the document store. + + + +#### ElasticsearchDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns how many documents are present in the document store. + +**Returns**: + +Number of documents in the document store. + + + +#### ElasticsearchDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +The main query method for the document store. It retrieves all documents that match the filters. + +**Arguments**: + +- `filters`: A dictionary of filters to apply. For more information on the structure of the filters, +see the official Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) + +**Returns**: + +List of `Document`s that match the filters. + + + +#### ElasticsearchDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously retrieves all documents that match the filters. + +**Arguments**: + +- `filters`: A dictionary of filters to apply. For more information on the structure of the filters, +see the official Elasticsearch +[documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) + +**Returns**: + +List of `Document`s that match the filters. + + + +#### ElasticsearchDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes `Document`s to Elasticsearch. + +**Arguments**: + +- `documents`: List of Documents to write to the document store. +- `policy`: DuplicatePolicy to apply when a document with the same ID already exists in the document store. + +**Raises**: + +- `ValueError`: If `documents` is not a list of `Document`s. +- `DuplicateDocumentError`: If a document with the same ID already exists in the document store and +`policy` is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`. +- `DocumentStoreError`: If an error occurs while writing the documents to the document store. + +**Returns**: + +Number of documents written to the document store. + + + +#### ElasticsearchDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Asynchronously writes `Document`s to Elasticsearch. + +**Arguments**: + +- `documents`: List of Documents to write to the document store. +- `policy`: DuplicatePolicy to apply when a document with the same ID already exists in the document store. + +**Raises**: + +- `ValueError`: If `documents` is not a list of `Document`s. +- `DuplicateDocumentError`: If a document with the same ID already exists in the document store and +`policy` is set to `DuplicatePolicy.FAIL` or `DuplicatePolicy.NONE`. +- `DocumentStoreError`: If an error occurs while writing the documents to the document store. + +**Returns**: + +Number of documents written to the document store. + + + +#### ElasticsearchDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes all documents with a matching document_ids from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### ElasticsearchDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes all documents with a matching document_ids from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### ElasticsearchDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(recreate_index: bool = False) -> None +``` + +Deletes all documents in the document store. + +A fast way to clear all documents from the document store while preserving any index settings and mappings. + +**Arguments**: + +- `recreate_index`: If True, the index will be deleted and recreated with the original mappings and +settings. If False, all documents will be deleted using the `delete_by_query` API. + + + +#### ElasticsearchDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async(recreate_index: bool = False) -> None +``` + +Asynchronously deletes all documents in the document store. + +A fast way to clear all documents from the document store while preserving any index settings and mappings. + +**Arguments**: + +- `recreate_index`: If True, the index will be deleted and recreated with the original mappings and +settings. If False, all documents will be deleted using the `delete_by_query` API. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/fastembed.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/fastembed.md new file mode 100644 index 0000000000..306a272e6f --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/fastembed.md @@ -0,0 +1,620 @@ +--- +title: "FastEmbed" +id: fastembed-embedders +description: "FastEmbed integration for Haystack" +slug: "/fastembed-embedders" +--- + + + +## Module haystack\_integrations.components.embedders.fastembed.fastembed\_document\_embedder + + + +### FastembedDocumentEmbedder + +FastembedDocumentEmbedder computes Document embeddings using Fastembed embedding models. +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +# To use this component, install the "fastembed-haystack" package. +# pip install fastembed-haystack + +from haystack_integrations.components.embedders.fastembed import FastembedDocumentEmbedder +from haystack.dataclasses import Document + +doc_embedder = FastembedDocumentEmbedder( + model="BAAI/bge-small-en-v1.5", + batch_size=256, +) + +doc_embedder.warm_up() + +# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa) +document_list = [ + Document( + content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint " + "destruction. Radical species with oxidative activity, including reactive nitrogen species, " + "represent mediators of inflammation and cartilage damage."), + meta={ + "pubid": "25,445,628", + "long_answer": "yes", + }, + ), + Document( + content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic " + "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion " + "and actions are still poorly understood."), + meta={ + "pubid": "25,445,712", + "long_answer": "yes", + }, + ), +] + +result = doc_embedder.run(document_list) +print(f"Document Text: {result['documents'][0].content}") +print(f"Document Embedding: {result['documents'][0].embedding}") +print(f"Embedding Dimension: {len(result['documents'][0].embedding)}") +``` + + + +#### FastembedDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "BAAI/bge-small-en-v1.5", + cache_dir: Optional[str] = None, + threads: Optional[int] = None, + prefix: str = "", + suffix: str = "", + batch_size: int = 256, + progress_bar: bool = True, + parallel: Optional[int] = None, + local_files_only: bool = False, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n") +``` + +Create an FastembedDocumentEmbedder component. + +**Arguments**: + +- `model`: Local path or name of the model in Hugging Face's model hub, +such as `BAAI/bge-small-en-v1.5`. +- `cache_dir`: The path to the cache directory. +Can be set using the `FASTEMBED_CACHE_PATH` env variable. +Defaults to `fastembed_cache` in the system's temp directory. +- `threads`: The number of threads single onnxruntime session can use. Defaults to None. +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `batch_size`: Number of strings to encode at once. +- `progress_bar`: If `True`, displays progress bar during embedding. +- `parallel`: If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets. +If 0, use all available cores. +If None, don't use data-parallel processing, use default onnxruntime threading instead. +- `local_files_only`: If `True`, only use the model files in the `cache_dir`. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document content. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document content. + + + +#### FastembedDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FastembedDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### FastembedDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Embeds a list of Documents. + +**Arguments**: + +- `documents`: List of Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents with each Document's `embedding` field set to the computed embeddings. + + + +## Module haystack\_integrations.components.embedders.fastembed.fastembed\_text\_embedder + + + +### FastembedTextEmbedder + +FastembedTextEmbedder computes string embedding using fastembed embedding models. + +Usage example: +```python +from haystack_integrations.components.embedders.fastembed import FastembedTextEmbedder + +text = ("It clearly says online this will work on a Mac OS system. " + "The disk comes and it does not, only Windows. Do Not order this if you have a Mac!!") + +text_embedder = FastembedTextEmbedder( + model="BAAI/bge-small-en-v1.5" +) +text_embedder.warm_up() + +embedding = text_embedder.run(text)["embedding"] +``` + + + +#### FastembedTextEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "BAAI/bge-small-en-v1.5", + cache_dir: Optional[str] = None, + threads: Optional[int] = None, + prefix: str = "", + suffix: str = "", + progress_bar: bool = True, + parallel: Optional[int] = None, + local_files_only: bool = False) +``` + +Create a FastembedTextEmbedder component. + +**Arguments**: + +- `model`: Local path or name of the model in Fastembed's model hub, such as `BAAI/bge-small-en-v1.5` +- `cache_dir`: The path to the cache directory. +Can be set using the `FASTEMBED_CACHE_PATH` env variable. +Defaults to `fastembed_cache` in the system's temp directory. +- `threads`: The number of threads single onnxruntime session can use. Defaults to None. +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `progress_bar`: If `True`, displays progress bar during embedding. +- `parallel`: If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets. +If 0, use all available cores. +If None, don't use data-parallel processing, use default onnxruntime threading instead. +- `local_files_only`: If `True`, only use the model files in the `cache_dir`. + + + +#### FastembedTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FastembedTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### FastembedTextEmbedder.run + +```python +@component.output_types(embedding=List[float]) +def run(text: str) -> Dict[str, List[float]] +``` + +Embeds text using the Fastembed model. + +**Arguments**: + +- `text`: A string to embed. + +**Raises**: + +- `TypeError`: If the input is not a string. +- `RuntimeError`: If the embedding model has not been loaded. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: A list of floats representing the embedding of the input text. + + + +## Module haystack\_integrations.components.embedders.fastembed.fastembed\_sparse\_document\_embedder + + + +### FastembedSparseDocumentEmbedder + +FastembedSparseDocumentEmbedder computes Document embeddings using Fastembed sparse models. + +Usage example: +```python +from haystack_integrations.components.embedders.fastembed import FastembedSparseDocumentEmbedder +from haystack.dataclasses import Document + +sparse_doc_embedder = FastembedSparseDocumentEmbedder( + model="prithivida/Splade_PP_en_v1", + batch_size=32, +) + +sparse_doc_embedder.warm_up() + +# Text taken from PubMed QA Dataset (https://huggingface.co/datasets/pubmed_qa) +document_list = [ + Document( + content=("Oxidative stress generated within inflammatory joints can produce autoimmune phenomena and joint " + "destruction. Radical species with oxidative activity, including reactive nitrogen species, " + "represent mediators of inflammation and cartilage damage."), + meta={ + "pubid": "25,445,628", + "long_answer": "yes", + }, + ), + Document( + content=("Plasma levels of pancreatic polypeptide (PP) rise upon food intake. Although other pancreatic " + "islet hormones, such as insulin and glucagon, have been extensively investigated, PP secretion " + "and actions are still poorly understood."), + meta={ + "pubid": "25,445,712", + "long_answer": "yes", + }, + ), +] + +result = sparse_doc_embedder.run(document_list) +print(f"Document Text: {result['documents'][0].content}") +print(f"Document Sparse Embedding: {result['documents'][0].sparse_embedding}") +print(f"Sparse Embedding Dimension: {len(result['documents'][0].sparse_embedding)}") +``` + + + +#### FastembedSparseDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "prithivida/Splade_PP_en_v1", + cache_dir: Optional[str] = None, + threads: Optional[int] = None, + batch_size: int = 32, + progress_bar: bool = True, + parallel: Optional[int] = None, + local_files_only: bool = False, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + model_kwargs: Optional[Dict[str, Any]] = None) +``` + +Create an FastembedDocumentEmbedder component. + +**Arguments**: + +- `model`: Local path or name of the model in Hugging Face's model hub, +such as `prithivida/Splade_PP_en_v1`. +- `cache_dir`: The path to the cache directory. +Can be set using the `FASTEMBED_CACHE_PATH` env variable. +Defaults to `fastembed_cache` in the system's temp directory. +- `threads`: The number of threads single onnxruntime session can use. +- `batch_size`: Number of strings to encode at once. +- `progress_bar`: If `True`, displays progress bar during embedding. +- `parallel`: If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets. +If 0, use all available cores. +If None, don't use data-parallel processing, use default onnxruntime threading instead. +- `local_files_only`: If `True`, only use the model files in the `cache_dir`. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document content. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document content. +- `model_kwargs`: Dictionary containing model parameters such as `k`, `b`, `avg_len`, `language`. + + + +#### FastembedSparseDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FastembedSparseDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### FastembedSparseDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Embeds a list of Documents. + +**Arguments**: + +- `documents`: List of Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents with each Document's `sparse_embedding` +field set to the computed embeddings. + + + +## Module haystack\_integrations.components.embedders.fastembed.fastembed\_sparse\_text\_embedder + + + +### FastembedSparseTextEmbedder + +FastembedSparseTextEmbedder computes string embedding using fastembed sparse models. + +Usage example: +```python +from haystack_integrations.components.embedders.fastembed import FastembedSparseTextEmbedder + +text = ("It clearly says online this will work on a Mac OS system. " + "The disk comes and it does not, only Windows. Do Not order this if you have a Mac!!") + +sparse_text_embedder = FastembedSparseTextEmbedder( + model="prithivida/Splade_PP_en_v1" +) +sparse_text_embedder.warm_up() + +sparse_embedding = sparse_text_embedder.run(text)["sparse_embedding"] +``` + + + +#### FastembedSparseTextEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "prithivida/Splade_PP_en_v1", + cache_dir: Optional[str] = None, + threads: Optional[int] = None, + progress_bar: bool = True, + parallel: Optional[int] = None, + local_files_only: bool = False, + model_kwargs: Optional[Dict[str, Any]] = None) +``` + +Create a FastembedSparseTextEmbedder component. + +**Arguments**: + +- `model`: Local path or name of the model in Fastembed's model hub, such as `prithivida/Splade_PP_en_v1` +- `cache_dir`: The path to the cache directory. +Can be set using the `FASTEMBED_CACHE_PATH` env variable. +Defaults to `fastembed_cache` in the system's temp directory. +- `threads`: The number of threads single onnxruntime session can use. Defaults to None. +- `progress_bar`: If `True`, displays progress bar during embedding. +- `parallel`: If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets. +If 0, use all available cores. +If None, don't use data-parallel processing, use default onnxruntime threading instead. +- `local_files_only`: If `True`, only use the model files in the `cache_dir`. +- `model_kwargs`: Dictionary containing model parameters such as `k`, `b`, `avg_len`, `language`. + + + +#### FastembedSparseTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FastembedSparseTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### FastembedSparseTextEmbedder.run + +```python +@component.output_types(sparse_embedding=SparseEmbedding) +def run(text: str) -> Dict[str, SparseEmbedding] +``` + +Embeds text using the Fastembed model. + +**Arguments**: + +- `text`: A string to embed. + +**Raises**: + +- `TypeError`: If the input is not a string. +- `RuntimeError`: If the embedding model has not been loaded. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: A list of floats representing the embedding of the input text. + + + +## Module haystack\_integrations.components.rankers.fastembed.ranker + + + +### FastembedRanker + +Ranks Documents based on their similarity to the query using +[Fastembed models](https://qdrant.github.io/fastembed/examples/Supported_Models/). + +Documents are indexed from most to least semantically relevant to the query. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.rankers.fastembed import FastembedRanker + +ranker = FastembedRanker(model_name="Xenova/ms-marco-MiniLM-L-6-v2", top_k=2) + +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "What is the capital of germany?" +output = ranker.run(query=query, documents=docs) +print(output["documents"][0].content) + +# Berlin +``` + + + +#### FastembedRanker.\_\_init\_\_ + +```python +def __init__(model_name: str = "Xenova/ms-marco-MiniLM-L-6-v2", + top_k: int = 10, + cache_dir: Optional[str] = None, + threads: Optional[int] = None, + batch_size: int = 64, + parallel: Optional[int] = None, + local_files_only: bool = False, + meta_fields_to_embed: Optional[List[str]] = None, + meta_data_separator: str = "\n") +``` + +Creates an instance of the 'FastembedRanker'. + +**Arguments**: + +- `model_name`: Fastembed model name. Check the list of supported models in the [Fastembed documentation](https://qdrant.github.io/fastembed/examples/Supported_Models/). +- `top_k`: The maximum number of documents to return. +- `cache_dir`: The path to the cache directory. +Can be set using the `FASTEMBED_CACHE_PATH` env variable. +Defaults to `fastembed_cache` in the system's temp directory. +- `threads`: The number of threads single onnxruntime session can use. Defaults to None. +- `batch_size`: Number of strings to encode at once. +- `parallel`: If > 1, data-parallel encoding will be used, recommended for offline encoding of large datasets. +If 0, use all available cores. +If None, don't use data-parallel processing, use default onnxruntime threading instead. +- `local_files_only`: If `True`, only use the model files in the `cache_dir`. +- `meta_fields_to_embed`: List of meta fields that should be concatenated +with the document content for reranking. +- `meta_data_separator`: Separator used to concatenate the meta fields +to the Document content. + + + +#### FastembedRanker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### FastembedRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "FastembedRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### FastembedRanker.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### FastembedRanker.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + documents: List[Document], + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Returns a list of documents ranked by their similarity to the given query, using FastEmbed. + +**Arguments**: + +- `query`: The input query to compare the documents to. +- `documents`: A list of documents to be ranked. +- `top_k`: The maximum number of documents to return. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents closest to the query, sorted from most similar to least similar. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/github.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/github.md new file mode 100644 index 0000000000..3c45605ba4 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/github.md @@ -0,0 +1,687 @@ +--- +title: "GitHub" +id: integrations-github +description: "GitHub integration for Haystack" +slug: "/integrations-github" +--- + + + +## Module haystack\_integrations.components.connectors.github.file\_editor + + + +### Command + +Available commands for file operations in GitHub. + +**Attributes**: + +- `EDIT` - Edit an existing file by replacing content +- `UNDO` - Revert the last commit if made by the same user +- `CREATE` - Create a new file +- `DELETE` - Delete an existing file + + + +### GitHubFileEditor + +A Haystack component for editing files in GitHub repositories. + +Supports editing, undoing changes, deleting files, and creating new files +through the GitHub API. + +### Usage example +```python +from haystack_integrations.components.connectors.github import Command, GitHubFileEditor +from haystack.utils import Secret + +# Initialize with default repo and branch +editor = GitHubFileEditor( + github_token=Secret.from_env_var("GITHUB_TOKEN"), + repo="owner/repo", + branch="main" +) + +# Edit a file using default repo and branch +result = editor.run( + command=Command.EDIT, + payload={ + "path": "path/to/file.py", + "original": "def old_function():", + "replacement": "def new_function():", + "message": "Renamed function for clarity" + } +) + +# Edit a file in a different repo/branch +result = editor.run( + command=Command.EDIT, + repo="other-owner/other-repo", # Override default repo + branch="feature", # Override default branch + payload={ + "path": "path/to/file.py", + "original": "def old_function():", + "replacement": "def new_function():", + "message": "Renamed function for clarity" + } +) +``` + + + +#### GitHubFileEditor.\_\_init\_\_ + +```python +def __init__(*, + github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"), + repo: Optional[str] = None, + branch: str = "main", + raise_on_failure: bool = True) +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for API authentication +- `repo`: Default repository in owner/repo format +- `branch`: Default branch to work with +- `raise_on_failure`: If True, raises exceptions on API errors + +**Raises**: + +- `TypeError`: If github_token is not a Secret + + + +#### GitHubFileEditor.run + +```python +@component.output_types(result=str) +def run(command: Union[Command, str], + payload: Dict[str, Any], + repo: Optional[str] = None, + branch: Optional[str] = None) -> Dict[str, str] +``` + +Process GitHub file operations. + +**Arguments**: + +- `command`: Operation to perform ("edit", "undo", "create", "delete") +- `payload`: Dictionary containing command-specific parameters +- `repo`: Repository in owner/repo format (overrides default if provided) +- `branch`: Branch to perform operations on (overrides default if provided) + +**Raises**: + +- `ValueError`: If command is not a valid Command enum value + +**Returns**: + +Dictionary containing operation result + + + +#### GitHubFileEditor.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + + + +#### GitHubFileEditor.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubFileEditor" +``` + +Deserialize the component from a dictionary. + + + +## Module haystack\_integrations.components.connectors.github.issue\_commenter + + + +### GitHubIssueCommenter + +Posts comments to GitHub issues. + +The component takes a GitHub issue URL and comment text, then posts the comment +to the specified issue using the GitHub API. + +### Usage example +```python +from haystack_integrations.components.connectors.github import GitHubIssueCommenter +from haystack.utils import Secret + +commenter = GitHubIssueCommenter(github_token=Secret.from_env_var("GITHUB_TOKEN")) +result = commenter.run( + url="https://github.com/owner/repo/issues/123", + comment="Thanks for reporting this issue! We'll look into it." +) + +print(result["success"]) +``` + + + +#### GitHubIssueCommenter.\_\_init\_\_ + +```python +def __init__(*, + github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"), + raise_on_failure: bool = True, + retry_attempts: int = 2) +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for API authentication as a Secret +- `raise_on_failure`: If True, raises exceptions on API errors +- `retry_attempts`: Number of retry attempts for failed requests + + + +#### GitHubIssueCommenter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GitHubIssueCommenter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubIssueCommenter" +``` + +Deserialize the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GitHubIssueCommenter.run + +```python +@component.output_types(success=bool) +def run(url: str, comment: str) -> dict +``` + +Post a comment to a GitHub issue. + +**Arguments**: + +- `url`: GitHub issue URL +- `comment`: Comment text to post + +**Returns**: + +Dictionary containing success status + + + +## Module haystack\_integrations.components.connectors.github.issue\_viewer + + + +### GitHubIssueViewer + +Fetches and parses GitHub issues into Haystack documents. + +The component takes a GitHub issue URL and returns a list of documents where: +- First document contains the main issue content +- Subsequent documents contain the issue comments + +### Usage example +```python +from haystack_integrations.components.connectors.github import GitHubIssueViewer + +viewer = GitHubIssueViewer() +docs = viewer.run( + url="https://github.com/owner/repo/issues/123" +)["documents"] + +print(docs) +``` + + + +#### GitHubIssueViewer.\_\_init\_\_ + +```python +def __init__(*, + github_token: Optional[Secret] = None, + raise_on_failure: bool = True, + retry_attempts: int = 2) +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for API authentication as a Secret +- `raise_on_failure`: If True, raises exceptions on API errors +- `retry_attempts`: Number of retry attempts for failed requests + + + +#### GitHubIssueViewer.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GitHubIssueViewer.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubIssueViewer" +``` + +Deserialize the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GitHubIssueViewer.run + +```python +@component.output_types(documents=List[Document]) +def run(url: str) -> dict +``` + +Process a GitHub issue URL and return documents. + +**Arguments**: + +- `url`: GitHub issue URL + +**Returns**: + +Dictionary containing list of documents + + + +## Module haystack\_integrations.components.connectors.github.pr\_creator + + + +### GitHubPRCreator + +A Haystack component for creating pull requests from a fork back to the original repository. + +Uses the authenticated user's fork to create the PR and links it to an existing issue. + +### Usage example +```python +from haystack_integrations.components.connectors.github import GitHubPRCreator +from haystack.utils import Secret + +pr_creator = GitHubPRCreator( + github_token=Secret.from_env_var("GITHUB_TOKEN") # Token from the fork owner +) + +# Create a PR from your fork +result = pr_creator.run( + issue_url="https://github.com/owner/repo/issues/123", + title="Fix issue `123`", + body="This PR addresses issue `123`", + branch="feature-branch", # The branch in your fork with the changes + base="main" # The branch in the original repo to merge into +) +``` + + + +#### GitHubPRCreator.\_\_init\_\_ + +```python +def __init__(*, + github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"), + raise_on_failure: bool = True) +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for authentication (from the fork owner) +- `raise_on_failure`: If True, raises exceptions on API errors + + + +#### GitHubPRCreator.run + +```python +@component.output_types(result=str) +def run(issue_url: str, + title: str, + branch: str, + base: str, + body: str = "", + draft: bool = False) -> Dict[str, str] +``` + +Create a new pull request from your fork to the original repository, linked to the specified issue. + +**Arguments**: + +- `issue_url`: URL of the GitHub issue to link the PR to +- `title`: Title of the pull request +- `branch`: Name of the branch in your fork where changes are implemented +- `base`: Name of the branch in the original repo you want to merge into +- `body`: Additional content for the pull request description +- `draft`: Whether to create a draft pull request + +**Returns**: + +Dictionary containing operation result + + + +#### GitHubPRCreator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + + + +#### GitHubPRCreator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubPRCreator" +``` + +Deserialize the component from a dictionary. + + + +## Module haystack\_integrations.components.connectors.github.repo\_viewer + + + +### GitHubItem + +Represents an item (file or directory) in a GitHub repository + + + +#### type + +"file" or "dir" + + + +### GitHubRepoViewer + +Navigates and fetches content from GitHub repositories. + +For directories: +- Returns a list of Documents, one for each item +- Each Document's content is the item name +- Full path and metadata in Document.meta + +For files: +- Returns a single Document +- Document's content is the file content +- Full path and metadata in Document.meta + +For errors: +- Returns a single Document +- Document's content is the error message +- Document's meta contains type="error" + +### Usage example +```python +from haystack_integrations.components.connectors.github import GitHubRepoViewer + +viewer = GitHubRepoViewer() + +# List directory contents - returns multiple documents +result = viewer.run( + repo="owner/repository", + path="docs/", + branch="main" +) +print(result) + +# Get specific file - returns single document +result = viewer.run( + repo="owner/repository", + path="README.md", + branch="main" +) +print(result) +``` + + + +#### GitHubRepoViewer.\_\_init\_\_ + +```python +def __init__(*, + github_token: Optional[Secret] = None, + raise_on_failure: bool = True, + max_file_size: int = 1_000_000, + repo: Optional[str] = None, + branch: str = "main") +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for API authentication +- `raise_on_failure`: If True, raises exceptions on API errors +- `max_file_size`: Maximum file size in bytes to fetch (default: 1MB) +- `repo`: Repository in format "owner/repo" +- `branch`: Git reference (branch, tag, commit) to use + + + +#### GitHubRepoViewer.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GitHubRepoViewer.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubRepoViewer" +``` + +Deserialize the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GitHubRepoViewer.run + +```python +@component.output_types(documents=List[Document]) +def run(path: str, + repo: Optional[str] = None, + branch: Optional[str] = None) -> Dict[str, List[Document]] +``` + +Process a GitHub repository path and return documents. + +**Arguments**: + +- `repo`: Repository in format "owner/repo" +- `path`: Path within repository (default: root) +- `branch`: Git reference (branch, tag, commit) to use + +**Returns**: + +Dictionary containing list of documents + + + +## Module haystack\_integrations.components.connectors.github.repo\_forker + + + +### GitHubRepoForker + +Forks a GitHub repository from an issue URL. + +The component takes a GitHub issue URL, extracts the repository information, +creates or syncs a fork of that repository, and optionally creates an issue-specific branch. + +### Usage example +```python +from haystack_integrations.components.connectors.github import GitHubRepoForker +from haystack.utils import Secret + +# Using direct token with auto-sync and branch creation +forker = GitHubRepoForker( + github_token=Secret.from_env_var("GITHUB_TOKEN"), + auto_sync=True, + create_branch=True +) + +result = forker.run(url="https://github.com/owner/repo/issues/123") +print(result) +# Will create or sync fork and create branch "fix-123" +``` + + + +#### GitHubRepoForker.\_\_init\_\_ + +```python +def __init__(*, + github_token: Secret = Secret.from_env_var("GITHUB_TOKEN"), + raise_on_failure: bool = True, + wait_for_completion: bool = False, + max_wait_seconds: int = 300, + poll_interval: int = 2, + auto_sync: bool = True, + create_branch: bool = True) +``` + +Initialize the component. + +**Arguments**: + +- `github_token`: GitHub personal access token for API authentication +- `raise_on_failure`: If True, raises exceptions on API errors +- `wait_for_completion`: If True, waits until fork is fully created +- `max_wait_seconds`: Maximum time to wait for fork completion in seconds +- `poll_interval`: Time between status checks in seconds +- `auto_sync`: If True, syncs fork with original repository if it already exists +- `create_branch`: If True, creates a fix branch based on the issue number + + + +#### GitHubRepoForker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GitHubRepoForker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GitHubRepoForker" +``` + +Deserialize the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GitHubRepoForker.run + +```python +@component.output_types(repo=str, issue_branch=str) +def run(url: str) -> dict +``` + +Process a GitHub issue URL and create or sync a fork of the repository. + +**Arguments**: + +- `url`: GitHub issue URL + +**Returns**: + +Dictionary containing repository path in owner/repo format + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_ai.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_ai.md new file mode 100644 index 0000000000..3ab3b4b0c2 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_ai.md @@ -0,0 +1,345 @@ +--- +title: "Google AI" +id: integrations-google-ai +description: "Google AI integration for Haystack" +slug: "/integrations-google-ai" +--- + + + +## Module haystack\_integrations.components.generators.google\_ai.gemini + + + +### GoogleAIGeminiGenerator + +Generates text using multimodal Gemini models through Google AI Studio. + +### Usage example + +```python +from haystack.utils import Secret +from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator + +gemini = GoogleAIGeminiGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("")) +res = gemini.run(parts = ["What is the most interesting thing you know?"]) +for answer in res["replies"]: + print(answer) +``` + +#### Multimodal example + +```python +import requests +from haystack.utils import Secret +from haystack.dataclasses.byte_stream import ByteStream +from haystack_integrations.components.generators.google_ai import GoogleAIGeminiGenerator + +BASE_URL = ( + "https://raw.githubusercontent.com/deepset-ai/haystack-core-integrations" + "/main/integrations/google_ai/example_assets" +) + +URLS = [ + f"{BASE_URL}/robot1.jpg", + f"{BASE_URL}/robot2.jpg", + f"{BASE_URL}/robot3.jpg", + f"{BASE_URL}/robot4.jpg" +] +images = [ + ByteStream(data=requests.get(url).content, mime_type="image/jpeg") + for url in URLS +] + +gemini = GoogleAIGeminiGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("")) +result = gemini.run(parts = ["What can you tell me about this robots?", *images]) +for answer in result["replies"]: + print(answer) +``` + + + +#### GoogleAIGeminiGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("GOOGLE_API_KEY"), + model: str = "gemini-2.0-flash", + generation_config: Optional[Union[GenerationConfig, + Dict[str, Any]]] = None, + safety_settings: Optional[Dict[HarmCategory, + HarmBlockThreshold]] = None, + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None) +``` + +Initializes a `GoogleAIGeminiGenerator` instance. + +To get an API key, visit: https://makersuite.google.com + +**Arguments**: + +- `api_key`: Google AI Studio API key. +- `model`: Name of the model to use. For available models, see https://ai.google.dev/gemini-api/docs/models/gemini +- `generation_config`: The generation configuration to use. +This can either be a `GenerationConfig` object or a dictionary of parameters. +For available parameters, see +[the `GenerationConfig` API reference](https://ai.google.dev/api/python/google/generativeai/GenerationConfig). +- `safety_settings`: The safety settings to use. +A dictionary with `HarmCategory` as keys and `HarmBlockThreshold` as values. +For more information, see [the API reference](https://ai.google.dev/api) +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. + + + +#### GoogleAIGeminiGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GoogleAIGeminiGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GoogleAIGeminiGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GoogleAIGeminiGenerator.run + +```python +@component.output_types(replies=List[str]) +def run(parts: Variadic[Union[str, ByteStream, Part]], + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None) +``` + +Generates text based on the given input parts. + +**Arguments**: + +- `parts`: A heterogeneous list of strings, `ByteStream` or `Part` objects. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. + +**Returns**: + +A dictionary containing the following key: +- `replies`: A list of strings containing the generated responses. + + + +## Module haystack\_integrations.components.generators.google\_ai.chat.gemini + + + +### GoogleAIGeminiChatGenerator + +Completes chats using Gemini models through Google AI Studio. + +It uses the [`ChatMessage`](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage) + dataclass to interact with the model. + +### Usage example + +```python +from haystack.utils import Secret +from haystack.dataclasses.chat_message import ChatMessage +from haystack_integrations.components.generators.google_ai import GoogleAIGeminiChatGenerator + + +gemini_chat = GoogleAIGeminiChatGenerator(model="gemini-2.0-flash", api_key=Secret.from_token("")) + +messages = [ChatMessage.from_user("What is the most interesting thing you know?")] +res = gemini_chat.run(messages=messages) +for reply in res["replies"]: + print(reply.text) + +messages += res["replies"] + [ChatMessage.from_user("Tell me more about it")] +res = gemini_chat.run(messages=messages) +for reply in res["replies"]: + print(reply.text) +``` + + +#### With function calling: + +```python +from typing import Annotated +from haystack.utils import Secret +from haystack.dataclasses.chat_message import ChatMessage +from haystack.components.tools import ToolInvoker +from haystack.tools import create_tool_from_function + +from haystack_integrations.components.generators.google_ai import GoogleAIGeminiChatGenerator + +# example function to get the current weather +def get_current_weather( + location: Annotated[str, "The city for which to get the weather, e.g. 'San Francisco'"] = "Munich", + unit: Annotated[str, "The unit for the temperature, e.g. 'celsius'"] = "celsius", +) -> str: + return f"The weather in {location} is sunny. The temperature is 20 {unit}." + +tool = create_tool_from_function(get_current_weather) +tool_invoker = ToolInvoker(tools=[tool]) + +gemini_chat = GoogleAIGeminiChatGenerator( + model="gemini-2.0-flash-exp", + api_key=Secret.from_token(""), + tools=[tool], +) +user_message = [ChatMessage.from_user("What is the temperature in celsius in Berlin?")] +replies = gemini_chat.run(messages=user_message)["replies"] +print(replies[0].tool_calls) + +# actually invoke the tool +tool_messages = tool_invoker.run(messages=replies)["tool_messages"] +messages = user_message + replies + tool_messages + +# transform the tool call result into a human readable message +final_replies = gemini_chat.run(messages=messages)["replies"] +print(final_replies[0].text) +``` + + + +#### GoogleAIGeminiChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("GOOGLE_API_KEY"), + model: str = "gemini-2.0-flash", + generation_config: Optional[Union[GenerationConfig, + Dict[str, Any]]] = None, + safety_settings: Optional[Dict[HarmCategory, + HarmBlockThreshold]] = None, + tools: Optional[List[Tool]] = None, + tool_config: Optional[content_types.ToolConfigDict] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +Initializes a `GoogleAIGeminiChatGenerator` instance. + +To get an API key, visit: https://aistudio.google.com/ + +**Arguments**: + +- `api_key`: Google AI Studio API key. To get a key, +see [Google AI Studio](https://aistudio.google.com/). +- `model`: Name of the model to use. For available models, see https://ai.google.dev/gemini-api/docs/models/gemini. +- `generation_config`: The generation configuration to use. +This can either be a `GenerationConfig` object or a dictionary of parameters. +For available parameters, see +[the API reference](https://ai.google.dev/api/generate-content). +- `safety_settings`: The safety settings to use. +A dictionary with `HarmCategory` as keys and `HarmBlockThreshold` as values. +For more information, see [the API reference](https://ai.google.dev/api/generate-content) +- `tools`: A list of tools for which the model can prepare calls. +- `tool_config`: The tool config to use. See the documentation for +[ToolConfig](https://ai.google.dev/api/caching#ToolConfig). +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. + + + +#### GoogleAIGeminiChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GoogleAIGeminiChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GoogleAIGeminiChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GoogleAIGeminiChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + tools: Optional[List[Tool]] = None) +``` + +Generates text based on the provided messages. + +**Arguments**: + +- `messages`: A list of `ChatMessage` instances, representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set +during component initialization. + +**Returns**: + +A dictionary containing the following key: +- `replies`: A list containing the generated responses as `ChatMessage` instances. + + + +#### GoogleAIGeminiChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + tools: Optional[List[Tool]] = None) +``` + +Async version of the run method. Generates text based on the provided messages. + +**Arguments**: + +- `messages`: A list of `ChatMessage` instances, representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set +during component initialization. + +**Returns**: + +A dictionary containing the following key: +- `replies`: A list containing the generated responses as `ChatMessage` instances. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_genai.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_genai.md new file mode 100644 index 0000000000..e9cc647592 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_genai.md @@ -0,0 +1,641 @@ +--- +title: "Google GenAI" +id: integrations-google-genai +description: "Google GenAI integration for Haystack" +slug: "/integrations-google-genai" +--- + + + +## Module haystack\_integrations.components.generators.google\_genai.chat.chat\_generator + + + +### GoogleGenAIChatGenerator + +A component for generating chat completions using Google's Gemini models via the Google Gen AI SDK. + +Supports models like gemini-2.0-flash and other Gemini variants. For Gemini 2.5 series models, +enables thinking features via `generation_kwargs={"thinking_budget": value}`. + +### Thinking Support (Gemini 2.5 Series) +- **Reasoning transparency**: Models can show their reasoning process +- **Thought signatures**: Maintains thought context across multi-turn conversations with tools +- **Configurable thinking budgets**: Control token allocation for reasoning + +Configure thinking behavior: +- `thinking_budget: -1`: Dynamic allocation (default) +- `thinking_budget: 0`: Disable thinking (Flash/Flash-Lite only) +- `thinking_budget: N`: Set explicit token budget + +### Multi-Turn Thinking with Thought Signatures +Gemini uses **thought signatures** when tools are present - encrypted "save states" that maintain +context across turns. Include previous assistant responses in chat history for context preservation. + +### Authentication +**Gemini Developer API**: Set `GOOGLE_API_KEY` or `GEMINI_API_KEY` environment variable +**Vertex AI**: Use `api="vertex"` with Application Default Credentials or API key + +### Authentication Examples + +**1. Gemini Developer API (API Key Authentication)** +```python +from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator + +# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) +chat_generator = GoogleGenAIChatGenerator(model="gemini-2.0-flash") +``` + +**2. Vertex AI (Application Default Credentials)** +```python +from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator + +# Using Application Default Credentials (requires gcloud auth setup) +chat_generator = GoogleGenAIChatGenerator( + api="vertex", + vertex_ai_project="my-project", + vertex_ai_location="us-central1", + model="gemini-2.0-flash" +) +``` + +**3. Vertex AI (API Key Authentication)** +```python +from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator + +# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) +chat_generator = GoogleGenAIChatGenerator( + api="vertex", + model="gemini-2.0-flash" +) +``` + +### Usage example + +```python +from haystack.dataclasses.chat_message import ChatMessage +from haystack.tools import Tool, Toolset +from haystack_integrations.components.generators.google_genai import GoogleGenAIChatGenerator + +# Initialize the chat generator with thinking support +chat_generator = GoogleGenAIChatGenerator( + model="gemini-2.5-flash", + generation_kwargs={"thinking_budget": 1024} # Enable thinking with 1024 token budget +) + +# Generate a response +messages = [ChatMessage.from_user("Tell me about the future of AI")] +response = chat_generator.run(messages=messages) +print(response["replies"][0].text) + +# Access reasoning content if available +message = response["replies"][0] +if message.reasonings: + for reasoning in message.reasonings: + print("Reasoning:", reasoning.reasoning_text) + +# Tool usage example with thinking +def weather_function(city: str): + return f"The weather in {city} is sunny and 25°C" + +weather_tool = Tool( + name="weather", + description="Get weather information for a city", + parameters={"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}, + function=weather_function +) + +# Can use either List[Tool] or Toolset +chat_generator_with_tools = GoogleGenAIChatGenerator( + model="gemini-2.5-flash", + tools=[weather_tool], # or tools=Toolset([weather_tool]) + generation_kwargs={"thinking_budget": -1} # Dynamic thinking allocation +) + +messages = [ChatMessage.from_user("What's the weather in Paris?")] +response = chat_generator_with_tools.run(messages=messages) +``` + + + +#### GoogleGenAIChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var( + ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False), + api: Literal["gemini", "vertex"] = "gemini", + vertex_ai_project: Optional[str] = None, + vertex_ai_location: Optional[str] = None, + model: str = "gemini-2.0-flash", + generation_kwargs: Optional[Dict[str, Any]] = None, + safety_settings: Optional[List[Dict[str, Any]]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) +``` + +Initialize a GoogleGenAIChatGenerator instance. + +**Arguments**: + +- `api_key`: Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables. +Not needed if using Vertex AI with Application Default Credentials. +Go to https://aistudio.google.com/app/apikey for a Gemini API key. +Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key. +- `api`: Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI. +- `vertex_ai_project`: Google Cloud project ID for Vertex AI. Required when using Vertex AI with +Application Default Credentials. +- `vertex_ai_location`: Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1"). +Required when using Vertex AI with Application Default Credentials. +- `model`: Name of the model to use (e.g., "gemini-2.0-flash") +- `generation_kwargs`: Configuration for generation (temperature, max_tokens, etc.). +For Gemini 2.5 series, supports `thinking_budget` to configure thinking behavior: +- `thinking_budget`: int, controls thinking token allocation + - `-1`: Dynamic (default for most models) + - `0`: Disable thinking (Flash/Flash-Lite only) + - Positive integer: Set explicit budget +- `safety_settings`: Safety settings for content filtering +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. + + + +#### GoogleGenAIChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GoogleGenAIChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAIChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GoogleGenAIChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run(messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + safety_settings: Optional[List[Dict[str, Any]]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) -> Dict[str, Any] +``` + +Run the Google Gen AI chat generator on the given input data. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Configuration for generation. If provided, it will override +the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration. +- `safety_settings`: Safety settings for content filtering. If provided, it will override the +default settings. +- `streaming_callback`: A callback function that is called when a new token is +received from the stream. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If provided, it will override the tools set during initialization. + +**Raises**: + +- `RuntimeError`: If there is an error in the Google Gen AI chat generation. +- `ValueError`: If a ChatMessage does not contain at least one of TextContent, ToolCall, or +ToolCallResult or if the role in ChatMessage is different from User, System, Assistant. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated ChatMessage responses. + + + +#### GoogleGenAIChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async(messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + safety_settings: Optional[List[Dict[str, Any]]] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + tools: Optional[ToolsType] = None) -> Dict[str, Any] +``` + +Async version of the run method. Run the Google Gen AI chat generator on the given input data. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Configuration for generation. If provided, it will override +the default config. Supports `thinking_budget` for Gemini 2.5 series thinking configuration. +See https://ai.google.dev/gemini-api/docs/thinking for possible values. +- `safety_settings`: Safety settings for content filtering. If provided, it will override the +default settings. +- `streaming_callback`: A callback function that is called when a new token is +received from the stream. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If provided, it will override the tools set during initialization. + +**Raises**: + +- `RuntimeError`: If there is an error in the async Google Gen AI chat generation. +- `ValueError`: If a ChatMessage does not contain at least one of TextContent, ToolCall, or +ToolCallResult or if the role in ChatMessage is different from User, System, Assistant. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list containing the generated ChatMessage responses. + + + +## Module haystack\_integrations.components.embedders.google\_genai.document\_embedder + + + +### GoogleGenAIDocumentEmbedder + +Computes document embeddings using Google AI models. + +### Authentication examples + +**1. Gemini Developer API (API Key Authentication)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder + +# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) +document_embedder = GoogleGenAIDocumentEmbedder(model="text-embedding-004") + +**2. Vertex AI (Application Default Credentials)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder + +__Using Application Default Credentials (requires gcloud auth setup)__ + +document_embedder = GoogleGenAIDocumentEmbedder( + api="vertex", + vertex_ai_project="my-project", + vertex_ai_location="us-central1", + model="text-embedding-004" +) +``` + +**3. Vertex AI (API Key Authentication)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder + +__export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)__ + +document_embedder = GoogleGenAIDocumentEmbedder( + api="vertex", + model="text-embedding-004" +) +``` + +### Usage example + +```python +from haystack import Document +from haystack_integrations.components.embedders.google_genai import GoogleGenAIDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = GoogleGenAIDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +__[0.017020374536514282, -0.023255806416273117, ...]__ + +``` + + + +#### GoogleGenAIDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var( + ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False), + api: Literal["gemini", "vertex"] = "gemini", + vertex_ai_project: Optional[str] = None, + vertex_ai_location: Optional[str] = None, + model: str = "text-embedding-004", + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + config: Optional[Dict[str, Any]] = None) -> None +``` + +Creates an GoogleGenAIDocumentEmbedder component. + +**Arguments**: + +- `api_key`: Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables. +Not needed if using Vertex AI with Application Default Credentials. +Go to https://aistudio.google.com/app/apikey for a Gemini API key. +Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key. +- `api`: Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI. +- `vertex_ai_project`: Google Cloud project ID for Vertex AI. Required when using Vertex AI with +Application Default Credentials. +- `vertex_ai_location`: Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1"). +Required when using Vertex AI with Application Default Credentials. +- `model`: The name of the model to use for calculating embeddings. +The default model is `text-embedding-ada-002`. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `batch_size`: Number of documents to embed at once. +- `progress_bar`: If `True`, shows a progress bar when running. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `config`: A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`. +If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`. +For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types). + + + +#### GoogleGenAIDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GoogleGenAIDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GoogleGenAIDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +def run( + documents: List[Document] +) -> Union[Dict[str, List[Document]], Dict[str, Any]] +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +#### GoogleGenAIDocumentEmbedder.run\_async + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +async def run_async( + documents: List[Document] +) -> Union[Dict[str, List[Document]], Dict[str, Any]] +``` + +Embeds a list of documents asynchronously. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +## Module haystack\_integrations.components.embedders.google\_genai.text\_embedder + + + +### GoogleGenAITextEmbedder + +Embeds strings using Google AI models. + +You can use it to embed user query and send it to an embedding Retriever. + +### Authentication examples + +**1. Gemini Developer API (API Key Authentication)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder + +# export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY) +text_embedder = GoogleGenAITextEmbedder(model="text-embedding-004") + +**2. Vertex AI (Application Default Credentials)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder + +__Using Application Default Credentials (requires gcloud auth setup)__ + +text_embedder = GoogleGenAITextEmbedder( + api="vertex", + vertex_ai_project="my-project", + vertex_ai_location="us-central1", + model="text-embedding-004" +) +``` + +**3. Vertex AI (API Key Authentication)** +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder + +__export the environment variable (GOOGLE_API_KEY or GEMINI_API_KEY)__ + +text_embedder = GoogleGenAITextEmbedder( + api="vertex", + model="text-embedding-004" +) +``` + + +### Usage example + +```python +from haystack_integrations.components.embedders.google_genai import GoogleGenAITextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = GoogleGenAITextEmbedder() + +print(text_embedder.run(text_to_embed)) + +__{'embedding': [0.017020374536514282, -0.023255806416273117, ...],__ + +__'meta': {'model': 'text-embedding-004-v2',__ + +__ 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}__ + +``` + + + +#### GoogleGenAITextEmbedder.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var( + ["GOOGLE_API_KEY", "GEMINI_API_KEY"], strict=False), + api: Literal["gemini", "vertex"] = "gemini", + vertex_ai_project: Optional[str] = None, + vertex_ai_location: Optional[str] = None, + model: str = "text-embedding-004", + prefix: str = "", + suffix: str = "", + config: Optional[Dict[str, Any]] = None) -> None +``` + +Creates an GoogleGenAITextEmbedder component. + +**Arguments**: + +- `api_key`: Google API key, defaults to the `GOOGLE_API_KEY` and `GEMINI_API_KEY` environment variables. +Not needed if using Vertex AI with Application Default Credentials. +Go to https://aistudio.google.com/app/apikey for a Gemini API key. +Go to https://cloud.google.com/vertex-ai/generative-ai/docs/start/api-keys for a Vertex AI API key. +- `api`: Which API to use. Either "gemini" for the Gemini Developer API or "vertex" for Vertex AI. +- `vertex_ai_project`: Google Cloud project ID for Vertex AI. Required when using Vertex AI with +Application Default Credentials. +- `vertex_ai_location`: Google Cloud location for Vertex AI (e.g., "us-central1", "europe-west1"). +Required when using Vertex AI with Application Default Credentials. +- `model`: The name of the model to use for calculating embeddings. +The default model is `text-embedding-004`. +- `prefix`: A string to add at the beginning of each text to embed. +- `suffix`: A string to add at the end of each text to embed. +- `config`: A dictionary of keyword arguments to configure embedding content configuration `types.EmbedContentConfig`. +If not specified, it defaults to `{"task_type": "SEMANTIC_SIMILARITY"}`. +For more information, see the [Google AI Task types](https://ai.google.dev/gemini-api/docs/embeddings#task-types). + + + +#### GoogleGenAITextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### GoogleGenAITextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "GoogleGenAITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### GoogleGenAITextEmbedder.run + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +def run(text: str) -> Union[Dict[str, List[float]], Dict[str, Any]] +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +#### GoogleGenAITextEmbedder.run\_async + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +async def run_async( + text: str) -> Union[Dict[str, List[float]], Dict[str, Any]] +``` + +Asynchronously embed a single string. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_vertex.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_vertex.md new file mode 100644 index 0000000000..e2d0a312d9 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/google_vertex.md @@ -0,0 +1,1221 @@ +--- +title: "Google Vertex" +id: integrations-google-vertex +description: "Google Vertex integration for Haystack" +slug: "/integrations-google-vertex" +--- + + + +## Module haystack\_integrations.components.generators.google\_vertex.gemini + + + +### VertexAIGeminiGenerator + +`VertexAIGeminiGenerator` enables text generation using Google Gemini models. + +Usage example: +```python +from haystack_integrations.components.generators.google_vertex import VertexAIGeminiGenerator + + +gemini = VertexAIGeminiGenerator() +result = gemini.run(parts = ["What is the most interesting thing you know?"]) +for answer in result["replies"]: + print(answer) + +>>> 1. **The Origin of Life:** How and where did life begin? The answers to this ... +>>> 2. **The Unseen Universe:** The vast majority of the universe is ... +>>> 3. **Quantum Entanglement:** This eerie phenomenon in quantum mechanics allows ... +>>> 4. **Time Dilation:** Einstein's theory of relativity revealed that time can ... +>>> 5. **The Fermi Paradox:** Despite the vastness of the universe and the ... +>>> 6. **Biological Evolution:** The idea that life evolves over time through natural ... +>>> 7. **Neuroplasticity:** The brain's ability to adapt and change throughout life, ... +>>> 8. **The Goldilocks Zone:** The concept of the habitable zone, or the Goldilocks zone, ... +>>> 9. **String Theory:** This theoretical framework in physics aims to unify all ... +>>> 10. **Consciousness:** The nature of human consciousness and how it arises ... +``` + + + +#### VertexAIGeminiGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str = "gemini-2.0-flash", + project_id: Optional[str] = None, + location: Optional[str] = None, + generation_config: Optional[Union[GenerationConfig, + Dict[str, Any]]] = None, + safety_settings: Optional[Dict[HarmCategory, + HarmBlockThreshold]] = None, + system_instruction: Optional[Union[str, ByteStream, Part]] = None, + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None) +``` + +Multi-modal generator using Gemini model via Google Vertex AI. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +- `generation_config`: The generation config to use. +Can either be a [`GenerationConfig`](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.GenerationConfig) +object or a dictionary of parameters. +Accepted fields are: + - temperature + - top_p + - top_k + - candidate_count + - max_output_tokens + - stop_sequences +- `safety_settings`: The safety settings to use. See the documentation +for [HarmBlockThreshold](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmBlockThreshold) +and [HarmCategory](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmCategory) +for more details. +- `system_instruction`: Default system instruction to use for generating content. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. + + + +#### VertexAIGeminiGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIGeminiGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIGeminiGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAIGeminiGenerator.run + +```python +@component.output_types(replies=List[str]) +def run(parts: Variadic[Union[str, ByteStream, Part]], + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None) +``` + +Generates content using the Gemini model. + +**Arguments**: + +- `parts`: Prompt for the model. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated content. + + + +## Module haystack\_integrations.components.generators.google\_vertex.captioner + + + +### VertexAIImageCaptioner + +`VertexAIImageCaptioner` enables text generation using Google Vertex AI imagetext generative model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +Usage example: +```python +import requests + +from haystack.dataclasses.byte_stream import ByteStream +from haystack_integrations.components.generators.google_vertex import VertexAIImageCaptioner + +captioner = VertexAIImageCaptioner() + +image = ByteStream( + data=requests.get( + "https://raw.githubusercontent.com/deepset-ai/haystack-core-integrations/main/integrations/google_vertex/example_assets/robot1.jpg" + ).content +) +result = captioner.run(image=image) + +for caption in result["captions"]: + print(caption) + +>>> two gold robots are standing next to each other in the desert +``` + + + +#### VertexAIImageCaptioner.\_\_init\_\_ + +```python +def __init__(*, + model: str = "imagetext", + project_id: Optional[str] = None, + location: Optional[str] = None, + **kwargs) +``` + +Generate image captions using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +Defaults to None. +- `kwargs`: Additional keyword arguments to pass to the model. +For a list of supported arguments see the `ImageTextModel.get_captions()` documentation. + + + +#### VertexAIImageCaptioner.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIImageCaptioner.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIImageCaptioner" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAIImageCaptioner.run + +```python +@component.output_types(captions=List[str]) +def run(image: ByteStream) +``` + +Prompts the model to generate captions for the given image. + +**Arguments**: + +- `image`: The image to generate captions for. + +**Returns**: + +A dictionary with the following keys: +- `captions`: A list of captions generated by the model. + + + +## Module haystack\_integrations.components.generators.google\_vertex.code\_generator + + + +### VertexAICodeGenerator + +This component enables code generation using Google Vertex AI generative model. + +`VertexAICodeGenerator` supports `code-bison`, `code-bison-32k`, and `code-gecko`. + +Usage example: +```python + from haystack_integrations.components.generators.google_vertex import VertexAICodeGenerator + + generator = VertexAICodeGenerator() + + result = generator.run(prefix="def to_json(data):") + + for answer in result["replies"]: + print(answer) + + >>> ```python + >>> import json + >>> + >>> def to_json(data): + >>> """Converts a Python object to a JSON string. + >>> + >>> Args: + >>> data: The Python object to convert. + >>> + >>> Returns: + >>> A JSON string representing the Python object. + >>> """ + >>> + >>> return json.dumps(data) + >>> ``` +``` + + + +#### VertexAICodeGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str = "code-bison", + project_id: Optional[str] = None, + location: Optional[str] = None, + **kwargs) +``` + +Generate code using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +- `kwargs`: Additional keyword arguments to pass to the model. +For a list of supported arguments see the `TextGenerationModel.predict()` documentation. + + + +#### VertexAICodeGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAICodeGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAICodeGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAICodeGenerator.run + +```python +@component.output_types(replies=List[str]) +def run(prefix: str, suffix: Optional[str] = None) +``` + +Generate code using a Google Vertex AI model. + +**Arguments**: + +- `prefix`: Code before the current point. +- `suffix`: Code after the current point. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated code snippets. + + + +## Module haystack\_integrations.components.generators.google\_vertex.image\_generator + + + +### VertexAIImageGenerator + +This component enables image generation using Google Vertex AI generative model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +Usage example: +```python +from pathlib import Path + +from haystack_integrations.components.generators.google_vertex import VertexAIImageGenerator + +generator = VertexAIImageGenerator() +result = generator.run(prompt="Generate an image of a cute cat") +result["images"][0].to_file(Path("my_image.png")) +``` + + + +#### VertexAIImageGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str = "imagegeneration", + project_id: Optional[str] = None, + location: Optional[str] = None, + **kwargs) +``` + +Generates images using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +- `kwargs`: Additional keyword arguments to pass to the model. +For a list of supported arguments see the `ImageGenerationModel.generate_images()` documentation. + + + +#### VertexAIImageGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIImageGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIImageGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAIImageGenerator.run + +```python +@component.output_types(images=List[ByteStream]) +def run(prompt: str, negative_prompt: Optional[str] = None) +``` + +Produces images based on the given prompt. + +**Arguments**: + +- `prompt`: The prompt to generate images from. +- `negative_prompt`: A description of what you want to omit in +the generated images. + +**Returns**: + +A dictionary with the following keys: +- `images`: A list of ByteStream objects, each containing an image. + + + +## Module haystack\_integrations.components.generators.google\_vertex.question\_answering + + + +### VertexAIImageQA + +This component enables text generation (image captioning) using Google Vertex AI generative models. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +Usage example: +```python +from haystack.dataclasses.byte_stream import ByteStream +from haystack_integrations.components.generators.google_vertex import VertexAIImageQA + +qa = VertexAIImageQA() + +image = ByteStream.from_file_path("dog.jpg") + +res = qa.run(image=image, question="What color is this dog") + +print(res["replies"][0]) + +>>> white +``` + + + +#### VertexAIImageQA.\_\_init\_\_ + +```python +def __init__(*, + model: str = "imagetext", + project_id: Optional[str] = None, + location: Optional[str] = None, + **kwargs) +``` + +Answers questions about an image using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +- `kwargs`: Additional keyword arguments to pass to the model. +For a list of supported arguments see the `ImageTextModel.ask_question()` documentation. + + + +#### VertexAIImageQA.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIImageQA.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIImageQA" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAIImageQA.run + +```python +@component.output_types(replies=List[str]) +def run(image: ByteStream, question: str) +``` + +Prompts model to answer a question about an image. + +**Arguments**: + +- `image`: The image to ask the question about. +- `question`: The question to ask. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of answers to the question. + + + +## Module haystack\_integrations.components.generators.google\_vertex.text\_generator + + + +### VertexAITextGenerator + +This component enables text generation using Google Vertex AI generative models. + +`VertexAITextGenerator` supports `text-bison`, `text-unicorn` and `text-bison-32k` models. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +Usage example: +```python + from haystack_integrations.components.generators.google_vertex import VertexAITextGenerator + + generator = VertexAITextGenerator() + res = generator.run("Tell me a good interview question for a software engineer.") + + print(res["replies"][0]) + + >>> **Question:** + >>> You are given a list of integers and a target sum. + >>> Find all unique combinations of numbers in the list that add up to the target sum. + >>> + >>> **Example:** + >>> + >>> ``` + >>> Input: [1, 2, 3, 4, 5], target = 7 + >>> Output: [[1, 2, 4], [3, 4]] + >>> ``` + >>> + >>> **Follow-up:** What if the list contains duplicate numbers? +``` + + + +#### VertexAITextGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str = "text-bison", + project_id: Optional[str] = None, + location: Optional[str] = None, + **kwargs) +``` + +Generate text using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `model`: Name of the model to use. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +- `kwargs`: Additional keyword arguments to pass to the model. +For a list of supported arguments see the `TextGenerationModel.predict()` documentation. + + + +#### VertexAITextGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAITextGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAITextGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAITextGenerator.run + +```python +@component.output_types(replies=List[str], + safety_attributes=Dict[str, float], + citations=List[Dict[str, Any]]) +def run(prompt: str) +``` + +Prompts the model to generate text. + +**Arguments**: + +- `prompt`: The prompt to use for text generation. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated replies. +- `safety_attributes`: A dictionary with the [safety scores](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/responsible-ai#safety_attribute_descriptions) + of each answer. +- `citations`: A list of citations for each answer. + + + +## Module haystack\_integrations.components.generators.google\_vertex.chat.gemini + + + +### VertexAIGeminiChatGenerator + +`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +### Usage example +```python +from haystack.dataclasses import ChatMessage +from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator + +gemini_chat = VertexAIGeminiChatGenerator() + +messages = [ChatMessage.from_user("Tell me the name of a movie")] +res = gemini_chat.run(messages) + +print(res["replies"][0].text) +>>> The Shawshank Redemption + +#### With Tool calling: + +```python +from typing import Annotated +from haystack.utils import Secret +from haystack.dataclasses.chat_message import ChatMessage +from haystack.components.tools import ToolInvoker +from haystack.tools import create_tool_from_function + +from haystack_integrations.components.generators.google_vertex import VertexAIGeminiChatGenerator + +__example function to get the current weather__ + +def get_current_weather( + location: Annotated[str, "The city for which to get the weather, e.g. 'San Francisco'"] = "Munich", + unit: Annotated[str, "The unit for the temperature, e.g. 'celsius'"] = "celsius", +) -> str: + return f"The weather in {location} is sunny. The temperature is 20 {unit}." + +tool = create_tool_from_function(get_current_weather) +tool_invoker = ToolInvoker(tools=[tool]) + +gemini_chat = VertexAIGeminiChatGenerator( + model="gemini-2.0-flash-exp", + tools=[tool], +) +user_message = [ChatMessage.from_user("What is the temperature in celsius in Berlin?")] +replies = gemini_chat.run(messages=user_message)["replies"] +print(replies[0].tool_calls) + +__actually invoke the tool__ + +tool_messages = tool_invoker.run(messages=replies)["tool_messages"] +messages = user_message + replies + tool_messages + +__transform the tool call result into a human readable message__ + +final_replies = gemini_chat.run(messages=messages)["replies"] +print(final_replies[0].text) +``` + + + +#### VertexAIGeminiChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str = "gemini-1.5-flash", + project_id: Optional[str] = None, + location: Optional[str] = None, + generation_config: Optional[Union[GenerationConfig, + Dict[str, Any]]] = None, + safety_settings: Optional[Dict[HarmCategory, + HarmBlockThreshold]] = None, + tools: Optional[List[Tool]] = None, + tool_config: Optional[ToolConfig] = None, + streaming_callback: Optional[StreamingCallbackT] = None) +``` + +`VertexAIGeminiChatGenerator` enables chat completion using Google Gemini models. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `model`: Name of the model to use. For available models, see https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models. +- `project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `location`: The default location to use when making API calls, if not set uses us-central-1. +Defaults to None. +- `generation_config`: Configuration for the generation process. +See the [GenerationConfig documentation](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.GenerationConfig +for a list of supported arguments. +- `safety_settings`: Safety settings to use when generating content. See the documentation +for [HarmBlockThreshold](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmBlockThreshold) +and [HarmCategory](https://cloud.google.com/python/docs/reference/aiplatform/latest/vertexai.generative_models.HarmCategory) +for more details. +- `tools`: A list of tools for which the model can prepare calls. +- `tool_config`: The tool config to use. See the documentation for [ToolConfig] +(https://cloud.google.com/vertex-ai/generative-ai/docs/reference/python/latest/vertexai.generative_models.ToolConfig) +- `streaming_callback`: A callback function that is called when a new token is received from +the stream. The callback function accepts StreamingChunk as an argument. + + + +#### VertexAIGeminiChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIGeminiChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIGeminiChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### VertexAIGeminiChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + tools: Optional[List[Tool]] = None) +``` + +**Arguments**: + +- `messages`: A list of `ChatMessage` instances, representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set +during component initialization. + +**Returns**: + +A dictionary containing the following key: +- `replies`: A list containing the generated responses as `ChatMessage` instances. + + + +#### VertexAIGeminiChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async(messages: List[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + *, + tools: Optional[List[Tool]] = None) +``` + +Async version of the run method. Generates text based on the provided messages. + +**Arguments**: + +- `messages`: A list of `ChatMessage` instances, representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `tools`: A list of tools for which the model can prepare calls. If set, it will override the `tools` parameter set +during component initialization. + +**Returns**: + +A dictionary containing the following key: +- `replies`: A list containing the generated responses as `ChatMessage` instances. + + + +## Module haystack\_integrations.components.embedders.google\_vertex.document\_embedder + + + +### VertexAIDocumentEmbedder + +Embed text using Vertex AI Embeddings API. + +See available models in the official +[Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#syntax). + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.google_vertex import VertexAIDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = VertexAIDocumentEmbedder(model="text-embedding-005") + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) +# [-0.044606007635593414, 0.02857724390923977, -0.03549133986234665, +``` + + + +#### VertexAIDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: Literal[ + "text-embedding-004", + "text-embedding-005", + "textembedding-gecko-multilingual@001", + "text-multilingual-embedding-002", + "text-embedding-large-exp-03-07", +], + task_type: Literal[ + "RETRIEVAL_DOCUMENT", + "RETRIEVAL_QUERY", + "SEMANTIC_SIMILARITY", + "CLASSIFICATION", + "CLUSTERING", + "QUESTION_ANSWERING", + "FACT_VERIFICATION", + "CODE_RETRIEVAL_QUERY", + ] = "RETRIEVAL_DOCUMENT", + gcp_region_name: Optional[Secret] = Secret.from_env_var( + "GCP_DEFAULT_REGION", strict=False), + gcp_project_id: Optional[Secret] = Secret.from_env_var( + "GCP_PROJECT_ID", strict=False), + batch_size: int = 32, + max_tokens_total: int = 20000, + time_sleep: int = 30, + retries: int = 3, + progress_bar: bool = True, + truncate_dim: Optional[int] = None, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n") -> None +``` + +Generate Document Embedder using a Google Vertex AI model. + +Authenticates using Google Cloud Application Default Credentials (ADCs). +For more information see the official [Google documentation](https://cloud.google.com/docs/authentication/provide-credentials-adc). + +**Arguments**: + +- `model`: Name of the model to use. +- `task_type`: The type of task for which the embeddings are being generated. +For more information see the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype). +- `gcp_region_name`: The default location to use when making API calls, if not set uses us-central-1. +- `gcp_project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `batch_size`: The number of documents to process in a single batch. +- `max_tokens_total`: The maximum number of tokens to process in total. +- `time_sleep`: The time to sleep between retries in seconds. +- `retries`: The number of retries in case of failure. +- `progress_bar`: Whether to display a progress bar during processing. +- `truncate_dim`: The dimension to truncate the embeddings to, if specified. +- `meta_fields_to_embed`: A list of metadata fields to include in the embeddings. +- `embedding_separator`: The separator to use between different embeddings. + +**Raises**: + +- `ValueError`: If the provided model is not in the list of supported models. + + + +#### VertexAIDocumentEmbedder.get\_text\_embedding\_input + +```python +def get_text_embedding_input( + batch: List[Document]) -> List[TextEmbeddingInput] +``` + +Converts a batch of Document objects into a list of TextEmbeddingInput objects. + +**Arguments**: + +- `batch` _List[Document]_ - A list of Document objects to be converted. + + +**Returns**: + +- `List[TextEmbeddingInput]` - A list of TextEmbeddingInput objects created from the input documents. + + + +#### VertexAIDocumentEmbedder.embed\_batch\_by\_smaller\_batches + +```python +def embed_batch_by_smaller_batches(batch: List[str], + subbatch=1) -> List[List[float]] +``` + +Embeds a batch of text strings by dividing them into smaller sub-batches. + +**Arguments**: + +- `batch` _List[str]_ - A list of text strings to be embedded. +- `subbatch` _int, optional_ - The size of the smaller sub-batches. Defaults to 1. + +**Returns**: + +- `List[List[float]]` - A list of embeddings, where each embedding is a list of floats. + +**Raises**: + +- `Exception` - If embedding fails at the item level, an exception is raised with the error details. + + + +#### VertexAIDocumentEmbedder.embed\_batch + +```python +def embed_batch(batch: List[str]) -> List[List[float]] +``` + +Generate embeddings for a batch of text strings. + +**Arguments**: + +- `batch` _List[str]_ - A list of text strings to be embedded. + + +**Returns**: + +- `List[List[float]]` - A list of embeddings, where each embedding is a list of floats. + + + +#### VertexAIDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) +``` + +Processes all documents in batches while adhering to the API's token limit per request. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. + + + +#### VertexAIDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAIDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.components.embedders.google\_vertex.text\_embedder + + + +### VertexAITextEmbedder + +Embed text using VertexAI Text Embeddings API. + +See available models in the official +[Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#syntax). + +Usage example: +```python +from haystack_integrations.components.embedders.google_vertex import VertexAITextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = VertexAITextEmbedder(model="text-embedding-005") + +print(text_embedder.run(text_to_embed)) +# {'embedding': [-0.08127457648515701, 0.03399784862995148, -0.05116401985287666, ...] +``` + + + +#### VertexAITextEmbedder.\_\_init\_\_ + +```python +def __init__(model: Literal[ + "text-embedding-004", + "text-embedding-005", + "textembedding-gecko-multilingual@001", + "text-multilingual-embedding-002", + "text-embedding-large-exp-03-07", +], + task_type: Literal[ + "RETRIEVAL_DOCUMENT", + "RETRIEVAL_QUERY", + "SEMANTIC_SIMILARITY", + "CLASSIFICATION", + "CLUSTERING", + "QUESTION_ANSWERING", + "FACT_VERIFICATION", + "CODE_RETRIEVAL_QUERY", + ] = "RETRIEVAL_QUERY", + gcp_region_name: Optional[Secret] = Secret.from_env_var( + "GCP_DEFAULT_REGION", strict=False), + gcp_project_id: Optional[Secret] = Secret.from_env_var( + "GCP_PROJECT_ID", strict=False), + progress_bar: bool = True, + truncate_dim: Optional[int] = None) -> None +``` + +Initializes the TextEmbedder with the specified model, task type, and GCP configuration. + +**Arguments**: + +- `model`: Name of the model to use. +- `task_type`: The type of task for which the embeddings are being generated. +For more information see the official [Google documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text-embeddings-api#tasktype). +- `gcp_region_name`: The default location to use when making API calls, if not set uses us-central-1. +- `gcp_project_id`: ID of the GCP project to use. By default, it is set during Google Cloud authentication. +- `progress_bar`: Whether to display a progress bar during processing. +- `truncate_dim`: The dimension to truncate the embeddings to, if specified. + + + +#### VertexAITextEmbedder.run + +```python +@component.output_types(embedding=List[float]) +def run(text: Union[List[Document], List[str], str]) +``` + +Processes text in batches while adhering to the API's token limit per request. + +**Arguments**: + +- `text`: The text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. + + + +#### VertexAITextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### VertexAITextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "VertexAITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/hanlp.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/hanlp.md new file mode 100644 index 0000000000..4db74aa5c1 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/hanlp.md @@ -0,0 +1,158 @@ +--- +title: "HanLP" +id: integrations-hanlp +description: "HanLP integration for Haystack" +slug: "/integrations-hanlp" +--- + + + +## Module haystack\_integrations.components.preprocessors.hanlp.chinese\_document\_splitter + + + +### ChineseDocumentSplitter + +A DocumentSplitter for Chinese text. + +'coarse' represents coarse granularity Chinese word segmentation, 'fine' represents fine granularity word +segmentation, default is coarse granularity word segmentation. + +Unlike English where words are usually separated by spaces, +Chinese text is written continuously without spaces between words. +Chinese words can consist of multiple characters. +For example, the English word "America" is translated to "美国" in Chinese, +which consists of two characters but is treated as a single word. +Similarly, "Portugal" is "葡萄牙" in Chinese, three characters but one word. +Therefore, splitting by word means splitting by these multi-character tokens, +not simply by single characters or spaces. + +### Usage example +```python +doc = Document(content= + "这是第一句话，这是第二句话，这是第三句话。" + "这是第四句话，这是第五句话，这是第六句话！" + "这是第七句话，这是第八句话，这是第九句话？" +) + +splitter = ChineseDocumentSplitter( + split_by="word", split_length=10, split_overlap=3, respect_sentence_boundary=True +) +splitter.warm_up() +result = splitter.run(documents=[doc]) +print(result["documents"]) +``` + + + +#### ChineseDocumentSplitter.\_\_init\_\_ + +```python +def __init__(split_by: Literal["word", "sentence", "passage", "page", "line", + "period", "function"] = "word", + split_length: int = 1000, + split_overlap: int = 200, + split_threshold: int = 0, + respect_sentence_boundary: bool = False, + splitting_function: Optional[Callable] = None, + granularity: Literal["coarse", "fine"] = "coarse") +``` + +Initialize the ChineseDocumentSplitter component. + +**Arguments**: + +- `split_by`: The unit for splitting your documents. Choose from: +- `word` for splitting by spaces (" ") +- `period` for splitting by periods (".") +- `page` for splitting by form feed ("\f") +- `passage` for splitting by double line breaks ("\n\n") +- `line` for splitting each line ("\n") +- `sentence` for splitting by HanLP sentence tokenizer +- `split_length`: The maximum number of units in each split. +- `split_overlap`: The number of overlapping units for each split. +- `split_threshold`: The minimum number of units per split. If a split has fewer units +than the threshold, it's attached to the previous split. +- `respect_sentence_boundary`: Choose whether to respect sentence boundaries when splitting by "word". +If True, uses HanLP to detect sentence boundaries, ensuring splits occur only between sentences. +- `splitting_function`: Necessary when `split_by` is set to "function". +This is a function which must accept a single `str` as input and return a `list` of `str` as output, +representing the chunks after splitting. +- `granularity`: The granularity of Chinese word segmentation, either 'coarse' or 'fine'. + +**Raises**: + +- `ValueError`: If the granularity is not 'coarse' or 'fine'. + + + +#### ChineseDocumentSplitter.run + +```python +@component.output_types(documents=list[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Split documents into smaller chunks. + +**Arguments**: + +- `documents`: The documents to split. + +**Raises**: + +- `RuntimeError`: If the Chinese word segmentation model is not loaded. + +**Returns**: + +A dictionary containing the split documents. + + + +#### ChineseDocumentSplitter.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the component by loading the necessary models. + + + +#### ChineseDocumentSplitter.chinese\_sentence\_split + +```python +def chinese_sentence_split(text: str) -> List[Dict[str, Any]] +``` + +Split Chinese text into sentences. + +**Arguments**: + +- `text`: The text to split. + +**Returns**: + +A list of split sentences. + + + +#### ChineseDocumentSplitter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + + + +#### ChineseDocumentSplitter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "ChineseDocumentSplitter" +``` + +Deserializes the component from a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/jina.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/jina.md new file mode 100644 index 0000000000..f522fea07a --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/jina.md @@ -0,0 +1,598 @@ +--- +title: "Jina" +id: integrations-jina +description: "Jina integration for Haystack" +slug: "/integrations-jina" +--- + + + +## Module haystack\_integrations.components.embedders.jina.document\_embedder + + + +### JinaDocumentEmbedder + +A component for computing Document embeddings using Jina AI models. +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.jina import JinaDocumentEmbedder + +# Make sure that the environment variable JINA_API_KEY is set + +document_embedder = JinaDocumentEmbedder(task="retrieval.query") + +doc = Document(content="I love pizza!") + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### JinaDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("JINA_API_KEY"), + model: str = "jina-embeddings-v3", + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + task: Optional[str] = None, + dimensions: Optional[int] = None, + late_chunking: Optional[bool] = None) +``` + +Create a JinaDocumentEmbedder component. + +**Arguments**: + +- `api_key`: The Jina API key. +- `model`: The name of the Jina model to use. +Check the list of available models on [Jina documentation](https://jina.ai/embeddings/). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `batch_size`: Number of Documents to encode at once. +- `progress_bar`: Whether to show a progress bar or not. Can be helpful to disable in production deployments +to keep the logs clean. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. +- `task`: The downstream task for which the embeddings will be used. +The model will return the optimized embeddings for that task. +Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/). +- `dimensions`: Number of desired dimension. +Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL. +- `late_chunking`: A boolean to enable or disable late chunking. +Apply the late chunking technique to leverage the model's long-context capabilities for +generating contextual chunk embeddings. + +The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3. + + + +#### JinaDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JinaDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "JinaDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JinaDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +def run(documents: List[Document]) -> Dict[str, Any] +``` + +Compute the embeddings for a list of Documents. + +**Arguments**: + +- `documents`: A list of Documents to embed. + +**Raises**: + +- `TypeError`: If the input is not a list of Documents. + +**Returns**: + +A dictionary with following keys: +- `documents`: List of Documents, each with an `embedding` field containing the computed embedding. +- `meta`: A dictionary with metadata including the model name and usage statistics. + + + +## Module haystack\_integrations.components.embedders.jina.document\_image\_embedder + + + +### JinaDocumentImageEmbedder + +A component for computing Document embeddings based on images using Jina AI multimodal models. + +The embedding of each Document is stored in the `embedding` field of the Document. + +The JinaDocumentImageEmbedder supports models from the jina-clip series and jina-embeddings-v4 +which can encode images into vector representations in the same embedding space as text. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.jina import JinaDocumentImageEmbedder + +# Make sure that the environment variable JINA_API_KEY is set + +embedder = JinaDocumentImageEmbedder(model="jina-clip-v2") + +documents = [ + Document(content="A photo of a cat", meta={"file_path": "cat.jpg"}), + Document(content="A photo of a dog", meta={"file_path": "dog.jpg"}), +] + +result = embedder.run(documents=documents) +documents_with_embeddings = result["documents"] +print(documents_with_embeddings[0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### JinaDocumentImageEmbedder.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("JINA_API_KEY"), + model: str = "jina-clip-v2", + file_path_meta_field: str = "file_path", + root_path: Optional[str] = None, + embedding_dimension: Optional[int] = None, + image_size: Optional[Tuple[int, int]] = None, + batch_size: int = 5) +``` + +Create a JinaDocumentImageEmbedder component. + +**Arguments**: + +- `api_key`: The Jina API key. It can be explicitly provided or automatically read from the +environment variable `JINA_API_KEY` (recommended). +- `model`: The name of the Jina multimodal model to use. +Supported models include: +- "jina-clip-v1" +- "jina-clip-v2" (default) +- "jina-embeddings-v4" +Check the list of available models on [Jina documentation](https://jina.ai/embeddings/). +- `file_path_meta_field`: The metadata field in the Document that contains the file path to the image or PDF. +- `root_path`: The root directory path where document files are located. If provided, file paths in +document metadata will be resolved relative to this path. If None, file paths are treated as absolute paths. +- `embedding_dimension`: Number of desired dimensions for the embedding. +Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL. +Only supported by jina-embeddings-v4. +- `image_size`: If provided, resizes the image to fit within the specified dimensions (width, height) while +maintaining aspect ratio. This reduces file size, memory usage, and processing time. +- `batch_size`: Number of images to send in each API request. Defaults to 5. + + + +#### JinaDocumentImageEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JinaDocumentImageEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "JinaDocumentImageEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JinaDocumentImageEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Embed a list of image documents. + +**Arguments**: + +- `documents`: Documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embeddings. + + + +## Module haystack\_integrations.components.embedders.jina.text\_embedder + + + +### JinaTextEmbedder + +A component for embedding strings using Jina AI models. + +Usage example: +```python +from haystack_integrations.components.embedders.jina import JinaTextEmbedder + +# Make sure that the environment variable JINA_API_KEY is set + +text_embedder = JinaTextEmbedder(task="retrieval.query") + +text_to_embed = "I love pizza!" + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +# 'meta': {'model': 'jina-embeddings-v3', +# 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}} +``` + + + +#### JinaTextEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("JINA_API_KEY"), + model: str = "jina-embeddings-v3", + prefix: str = "", + suffix: str = "", + task: Optional[str] = None, + dimensions: Optional[int] = None, + late_chunking: Optional[bool] = None) +``` + +Create a JinaTextEmbedder component. + +**Arguments**: + +- `api_key`: The Jina API key. It can be explicitly provided or automatically read from the +environment variable `JINA_API_KEY` (recommended). +- `model`: The name of the Jina model to use. +Check the list of available models on [Jina documentation](https://jina.ai/embeddings/). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `task`: The downstream task for which the embeddings will be used. +The model will return the optimized embeddings for that task. +Check the list of available tasks on [Jina documentation](https://jina.ai/embeddings/). +- `dimensions`: Number of desired dimension. +Smaller dimensions are easier to store and retrieve, with minimal performance impact thanks to MRL. +- `late_chunking`: A boolean to enable or disable late chunking. +Apply the late chunking technique to leverage the model's long-context capabilities for +generating contextual chunk embeddings. + +The support of `task` and `late_chunking` parameters is only available for jina-embeddings-v3. + + + +#### JinaTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JinaTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "JinaTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JinaTextEmbedder.run + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +def run(text: str) -> Dict[str, Any] +``` + +Embed a string. + +**Arguments**: + +- `text`: The string to embed. + +**Raises**: + +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary with following keys: +- `embedding`: The embedding of the input string. +- `meta`: A dictionary with metadata including the model name and usage statistics. + + + +## Module haystack\_integrations.components.rankers.jina.ranker + + + +### JinaRanker + +Ranks Documents based on their similarity to the query using Jina AI models. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.rankers.jina import JinaRanker + +ranker = JinaRanker() +docs = [Document(content="Paris"), Document(content="Berlin")] +query = "City in Germany" +result = ranker.run(query=query, documents=docs) +docs = result["documents"] +print(docs[0].content) +``` + + + +#### JinaRanker.\_\_init\_\_ + +```python +def __init__(model: str = "jina-reranker-v1-base-en", + api_key: Secret = Secret.from_env_var("JINA_API_KEY"), + top_k: Optional[int] = None, + score_threshold: Optional[float] = None) +``` + +Creates an instance of JinaRanker. + +**Arguments**: + +- `api_key`: The Jina API key. It can be explicitly provided or automatically read from the +environment variable JINA_API_KEY (recommended). +- `model`: The name of the Jina model to use. Check the list of available models on `https://jina.ai/reranker/` +- `top_k`: The maximum number of Documents to return per query. If `None`, all documents are returned +- `score_threshold`: If provided only returns documents with a score above this threshold. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + + + +#### JinaRanker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JinaRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "JinaRanker" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JinaRanker.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + documents: List[Document], + top_k: Optional[int] = None, + score_threshold: Optional[float] = None) +``` + +Returns a list of Documents ranked by their similarity to the given query. + +**Arguments**: + +- `query`: Query string. +- `documents`: List of Documents. +- `top_k`: The maximum number of Documents you want the Ranker to return. +- `score_threshold`: If provided only returns documents with a score above this threshold. + +**Raises**: + +- `ValueError`: If `top_k` is not > 0. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given query in descending order of similarity. + + + +## Module haystack\_integrations.components.connectors.jina.reader + + + +### JinaReaderConnector + +A component that interacts with Jina AI's reader service to process queries and return documents. + +This component supports different modes of operation: `read`, `search`, and `ground`. + +Usage example: +```python +from haystack_integrations.components.connectors.jina import JinaReaderConnector + +reader = JinaReaderConnector(mode="read") +query = "https://example.com" +result = reader.run(query=query) +document = result["documents"][0] +print(document.content) + +>>> "This domain is for use in illustrative examples..." +``` + + + +#### JinaReaderConnector.\_\_init\_\_ + +```python +def __init__(mode: Union[JinaReaderMode, str], + api_key: Secret = Secret.from_env_var("JINA_API_KEY"), + json_response: bool = True) +``` + +Initialize a JinaReader instance. + +**Arguments**: + +- `mode`: The operation mode for the reader (`read`, `search` or `ground`). +- `read`: process a URL and return the textual content of the page. +- `search`: search the web and return textual content of the most relevant pages. +- `ground`: call the grounding engine to perform fact checking. +For more information on the modes, see the [Jina Reader documentation](https://jina.ai/reader/). +- `api_key`: The Jina API key. It can be explicitly provided or automatically read from the +environment variable JINA_API_KEY (recommended). +- `json_response`: Controls the response format from the Jina Reader API. +If `True`, requests a JSON response, resulting in Documents with rich structured metadata. +If `False`, requests a raw response, resulting in one Document with minimal metadata. + + + +#### JinaReaderConnector.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### JinaReaderConnector.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "JinaReaderConnector" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### JinaReaderConnector.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + headers: Optional[Dict[str, str]] = None) -> Dict[str, List[Document]] +``` + +Process the query/URL using the Jina AI reader service. + +**Arguments**: + +- `query`: The query string or URL to process. +- `headers`: Optional headers to include in the request for customization. Refer to the +[Jina Reader documentation](https://jina.ai/reader/) for more information. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of `Document` objects. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/langfuse.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/langfuse.md new file mode 100644 index 0000000000..d82bace525 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/langfuse.md @@ -0,0 +1,485 @@ +--- +title: "langfuse" +id: integrations-langfuse +description: "Langfuse integration for Haystack" +slug: "/integrations-langfuse" +--- + + + +## Module haystack\_integrations.components.connectors.langfuse.langfuse\_connector + + + +### LangfuseConnector + +LangfuseConnector connects Haystack LLM framework with [Langfuse](https://langfuse.com) in order to enable the +tracing of operations and data flow within various components of a pipeline. + +To use LangfuseConnector, add it to your pipeline without connecting it to any other components. +It will automatically trace all pipeline operations when tracing is enabled. + +**Environment Configuration:** +- `LANGFUSE_SECRET_KEY` and `LANGFUSE_PUBLIC_KEY`: Required Langfuse API credentials. +- `HAYSTACK_CONTENT_TRACING_ENABLED`: Must be set to `"true"` to enable tracing. +- `HAYSTACK_LANGFUSE_ENFORCE_FLUSH`: (Optional) If set to `"false"`, disables flushing after each component. + Be cautious: this may cause data loss on crashes unless you manually flush before shutdown. + By default, the data is flushed after each component and blocks the thread until the data is sent to Langfuse. + +If you disable flushing after each component make sure you will call langfuse.flush() explicitly before the +program exits. For example: + +```python +from haystack.tracing import tracer + +try: + # your code here +finally: + tracer.actual_tracer.flush() +``` +or in FastAPI by defining a shutdown event handler: +```python +from haystack.tracing import tracer + +# ... + +@app.on_event("shutdown") +async def shutdown_event(): + tracer.actual_tracer.flush() +``` + +Here is an example of how to use LangfuseConnector in a pipeline: + +```python +import os + +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +from haystack import Pipeline +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage +from haystack_integrations.components.connectors.langfuse import ( + LangfuseConnector, +) + +pipe = Pipeline() +pipe.add_component("tracer", LangfuseConnector("Chat example")) +pipe.add_component("prompt_builder", ChatPromptBuilder()) +pipe.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini")) + +pipe.connect("prompt_builder.prompt", "llm.messages") + +messages = [ + ChatMessage.from_system( + "Always respond in German even if some input data is in other languages." + ), + ChatMessage.from_user("Tell me about {{location}}"), +] + +response = pipe.run( + data={ + "prompt_builder": { + "template_variables": {"location": "Berlin"}, + "template": messages, + } + } +) +print(response["llm"]["replies"][0]) +print(response["tracer"]["trace_url"]) +print(response["tracer"]["trace_id"]) +``` + +For advanced use cases, you can also customize how spans are created and processed by providing a custom +SpanHandler. This allows you to add custom metrics, set warning levels, or attach additional metadata to your +Langfuse traces: + +```python +from haystack_integrations.tracing.langfuse import DefaultSpanHandler, LangfuseSpan +from typing import Optional + +class CustomSpanHandler(DefaultSpanHandler): + + def handle(self, span: LangfuseSpan, component_type: Optional[str]) -> None: + # Custom span handling logic, customize Langfuse spans however it fits you + # see DefaultSpanHandler for how we create and process spans by default + pass + +connector = LangfuseConnector(span_handler=CustomSpanHandler()) +``` + + + +#### LangfuseConnector.\_\_init\_\_ + +```python +def __init__(name: str, + public: bool = False, + public_key: Optional[Secret] = Secret.from_env_var( + "LANGFUSE_PUBLIC_KEY"), + secret_key: Optional[Secret] = Secret.from_env_var( + "LANGFUSE_SECRET_KEY"), + httpx_client: Optional[httpx.Client] = None, + span_handler: Optional[SpanHandler] = None, + *, + host: Optional[str] = None, + langfuse_client_kwargs: Optional[Dict[str, Any]] = None) -> None +``` + +Initialize the LangfuseConnector component. + +**Arguments**: + +- `name`: The name for the trace. This name will be used to identify the tracing run in the Langfuse +dashboard. +- `public`: Whether the tracing data should be public or private. If set to `True`, the tracing data will be +publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private and +only accessible to the Langfuse account owner. The default is `False`. +- `public_key`: The Langfuse public key. Defaults to reading from LANGFUSE_PUBLIC_KEY environment variable. +- `secret_key`: The Langfuse secret key. Defaults to reading from LANGFUSE_SECRET_KEY environment variable. +- `httpx_client`: Optional custom httpx.Client instance to use for Langfuse API calls. Note that when +deserializing a pipeline from YAML, any custom client is discarded and Langfuse will create its own default +client, since HTTPX clients cannot be serialized. +- `span_handler`: Optional custom handler for processing spans. If None, uses DefaultSpanHandler. +The span handler controls how spans are created and processed, allowing customization of span types + based on component types and additional processing after spans are yielded. See SpanHandler class for + details on implementing custom handlers. +host: Host of Langfuse API. Can also be set via `LANGFUSE_HOST` environment variable. + By default it is set to `https://cloud.langfuse.com`. +- `langfuse_client_kwargs`: Optional custom configuration for the Langfuse client. This is a dictionary +containing any additional configuration options for the Langfuse client. See the Langfuse documentation +for more details on available configuration options. + + + +#### LangfuseConnector.run + +```python +@component.output_types(name=str, trace_url=str, trace_id=str) +def run(invocation_context: Optional[Dict[str, Any]] = None) -> Dict[str, str] +``` + +Runs the LangfuseConnector component. + +**Arguments**: + +- `invocation_context`: A dictionary with additional context for the invocation. This parameter +is useful when users want to mark this particular invocation with additional information, e.g. +a run id from their own execution framework, user id, etc. These key-value pairs are then visible +in the Langfuse traces. + +**Returns**: + +A dictionary with the following keys: +- `name`: The name of the tracing component. +- `trace_url`: The URL to the tracing data. +- `trace_id`: The ID of the trace. + + + +#### LangfuseConnector.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### LangfuseConnector.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "LangfuseConnector" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +## Module haystack\_integrations.tracing.langfuse.tracer + + + +### LangfuseSpan + +Internal class representing a bridge between the Haystack span tracing API and Langfuse. + + + +#### LangfuseSpan.\_\_init\_\_ + +```python +def __init__(context_manager: AbstractContextManager) -> None +``` + +Initialize a LangfuseSpan instance. + +**Arguments**: + +- `context_manager`: The context manager from Langfuse created with +`langfuse.get_client().start_as_current_span` or +`langfuse.get_client().start_as_current_observation`. + + + +#### LangfuseSpan.set\_tag + +```python +def set_tag(key: str, value: Any) -> None +``` + +Set a generic tag for this span. + +**Arguments**: + +- `key`: The tag key. +- `value`: The tag value. + + + +#### LangfuseSpan.set\_content\_tag + +```python +def set_content_tag(key: str, value: Any) -> None +``` + +Set a content-specific tag for this span. + +**Arguments**: + +- `key`: The content tag key. +- `value`: The content tag value. + + + +#### LangfuseSpan.raw\_span + +```python +def raw_span() -> LangfuseClientSpan +``` + +Return the underlying span instance. + +**Returns**: + +The Langfuse span instance. + + + +#### LangfuseSpan.get\_data + +```python +def get_data() -> Dict[str, Any] +``` + +Return the data associated with the span. + +**Returns**: + +The data associated with the span. + + + +### SpanContext + +Context for creating spans in Langfuse. + +Encapsulates the information needed to create and configure a span in Langfuse tracing. +Used by SpanHandler to determine the span type (trace, generation, or default) and its configuration. + +**Arguments**: + +- `name`: The name of the span to create. For components, this is typically the component name. +- `operation_name`: The operation being traced (e.g. "haystack.pipeline.run"). Used to determine +if a new trace should be created without warning. +- `component_type`: The type of component creating the span (e.g. "OpenAIChatGenerator"). +Can be used to determine the type of span to create. +- `tags`: Additional metadata to attach to the span. Contains component input/output data +and other trace information. +- `parent_span`: The parent span if this is a child span. If None, a new trace will be created. +- `trace_name`: The name to use for the trace when creating a parent span. Defaults to "Haystack". +- `public`: Whether traces should be publicly accessible. Defaults to False. + + + +#### SpanContext.\_\_post\_init\_\_ + +```python +def __post_init__() -> None +``` + +Validate the span context attributes. + +**Raises**: + +- `ValueError`: If name, operation_name or trace_name are empty +- `TypeError`: If tags is not a dictionary + + + +### SpanHandler + +Abstract base class for customizing how Langfuse spans are created and processed. + +This class defines two key extension points: +1. create_span: Controls what type of span to create (default or generation) +2. handle: Processes the span after component execution (adding metadata, metrics, etc.) + +To implement a custom handler: +- Extend this class or DefaultSpanHandler +- Override create_span and handle methods. It is more common to override handle. +- Pass your handler to LangfuseConnector init method + + + +#### SpanHandler.init\_tracer + +```python +def init_tracer(tracer: langfuse.Langfuse) -> None +``` + +Initialize with Langfuse tracer. Called internally by LangfuseTracer. + +**Arguments**: + +- `tracer`: The Langfuse client instance to use for creating spans + + + +#### SpanHandler.create\_span + +```python +@abstractmethod +def create_span(context: SpanContext) -> LangfuseSpan +``` + +Create a span of appropriate type based on the context. + +This method determines what kind of span to create: +- A new trace if there's no parent span +- A generation span for LLM components +- A default span for other components + +**Arguments**: + +- `context`: The context containing all information needed to create the span + +**Returns**: + +A new LangfuseSpan instance configured according to the context + + + +#### SpanHandler.handle + +```python +@abstractmethod +def handle(span: LangfuseSpan, component_type: Optional[str]) -> None +``` + +Process a span after component execution by attaching metadata and metrics. + +This method is called after the component or pipeline yields its span, allowing you to: +- Extract and attach token usage statistics +- Add model information +- Record timing data (e.g., time-to-first-token) +- Set log levels for quality monitoring +- Add custom metrics and observations + +**Arguments**: + +- `span`: The span that was yielded by the component +- `component_type`: The type of component that created the span, used to determine +what metadata to extract and how to process it + + + +### DefaultSpanHandler + +DefaultSpanHandler provides the default Langfuse tracing behavior for Haystack. + + + +### LangfuseTracer + +Internal class representing a bridge between the Haystack tracer and Langfuse. + + + +#### LangfuseTracer.\_\_init\_\_ + +```python +def __init__(tracer: langfuse.Langfuse, + name: str = "Haystack", + public: bool = False, + span_handler: Optional[SpanHandler] = None) -> None +``` + +Initialize a LangfuseTracer instance. + +**Arguments**: + +- `tracer`: The Langfuse tracer instance. +- `name`: The name of the pipeline or component. This name will be used to identify the tracing run on the +Langfuse dashboard. +- `public`: Whether the tracing data should be public or private. If set to `True`, the tracing data will +be publicly accessible to anyone with the tracing URL. If set to `False`, the tracing data will be private +and only accessible to the Langfuse account owner. +- `span_handler`: Custom handler for processing spans. If None, uses DefaultSpanHandler. + + + +#### LangfuseTracer.current\_span + +```python +def current_span() -> Optional[Span] +``` + +Return the current active span. + +**Returns**: + +The current span if available, else None. + + + +#### LangfuseTracer.get\_trace\_url + +```python +def get_trace_url() -> str +``` + +Return the URL to the tracing data. + +**Returns**: + +The URL to the tracing data. + + + +#### LangfuseTracer.get\_trace\_id + +```python +def get_trace_id() -> str +``` + +Return the trace ID. + +**Returns**: + +The trace ID. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_cpp.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_cpp.md new file mode 100644 index 0000000000..5ac3b58539 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_cpp.md @@ -0,0 +1,83 @@ +--- +title: "Llama.cpp" +id: integrations-llama-cpp +description: "Llama.cpp integration for Haystack" +slug: "/integrations-llama-cpp" +--- + + + +## Module haystack\_integrations.components.generators.llama\_cpp.generator + + + +### LlamaCppGenerator + +Provides an interface to generate text using LLM via llama.cpp. + +[llama.cpp](https://github.com/ggml-org/llama.cpp) is a project written in C/C++ for efficient inference of LLMs. +It employs the quantized GGUF format, suitable for running these models on standard machines (even without GPUs). + +Usage example: +```python +from haystack_integrations.components.generators.llama_cpp import LlamaCppGenerator +generator = LlamaCppGenerator(model="zephyr-7b-beta.Q4_0.gguf", n_ctx=2048, n_batch=512) + +print(generator.run("Who is the best American actor?", generation_kwargs={"max_tokens": 128})) +# {'replies': ['John Cusack'], 'meta': [{"object": "text_completion", ...}]} +``` + + + +#### LlamaCppGenerator.\_\_init\_\_ + +```python +def __init__(model: str, + n_ctx: Optional[int] = 0, + n_batch: Optional[int] = 512, + model_kwargs: Optional[Dict[str, Any]] = None, + generation_kwargs: Optional[Dict[str, Any]] = None) +``` + +**Arguments**: + +- `model`: The path of a quantized model for text generation, for example, "zephyr-7b-beta.Q4_0.gguf". +If the model path is also specified in the `model_kwargs`, this parameter will be ignored. +- `n_ctx`: The number of tokens in the context. When set to 0, the context will be taken from the model. +- `n_batch`: Prompt processing maximum batch size. +- `model_kwargs`: Dictionary containing keyword arguments used to initialize the LLM for text generation. +These keyword arguments provide fine-grained control over the model loading. +In case of duplication, these kwargs override `model`, `n_ctx`, and `n_batch` init parameters. +For more information on the available kwargs, see +[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.__init__`). +- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation. +For more information on the available kwargs, see +[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_completion`). + + + +#### LlamaCppGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run( + prompt: str, + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Run the text generation model on the given prompt. + +**Arguments**: + +- `prompt`: the prompt to be sent to the generative model. +- `generation_kwargs`: A dictionary containing keyword arguments to customize text generation. +For more information on the available kwargs, see +[llama.cpp documentation](https://llama-cpp-python.readthedocs.io/en/latest/api-reference/`llama_cpp.Llama.create_completion`). + +**Returns**: + +A dictionary with the following keys: +- `replies`: the list of replies generated by the model. +- `meta`: metadata about the request. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_stack.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_stack.md new file mode 100644 index 0000000000..1689909d4e --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/llama_stack.md @@ -0,0 +1,137 @@ +--- +title: "Llama Stack" +id: integrations-llama-stack +description: "Llama Stack integration for Haystack" +slug: "/integrations-llama-stack" +--- + + + +## Module haystack\_integrations.components.generators.llama\_stack.chat.chat\_generator + + + +### LlamaStackChatGenerator + +Enables text generation using Llama Stack framework. +Llama Stack Server supports multiple inference providers, including Ollama, Together, +and vLLM and other cloud providers. +For a complete list of inference providers, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/providers/inference/index.html). + +Users can pass any text generation parameters valid for the OpenAI chat completion API +directly to this component using the `generation_kwargs` +parameter in `__init__` or the `generation_kwargs` parameter in `run` method. + +This component uses the `ChatMessage` format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the `ChatMessage` format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) + +Usage example: +You need to setup Llama Stack Server before running this example and have a model available. For a quick start on +how to setup server with Ollama, see [Llama Stack docs](https://llama-stack.readthedocs.io/en/latest/getting_started/index.html). + +```python +from haystack_integrations.components.generators.llama_stack import LlamaStackChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = LlamaStackChatGenerator(model="ollama/llama3.2:3b") +response = client.run(messages) +print(response) + +>>{'replies': [ChatMessage(_content=[TextContent(text='Natural Language Processing (NLP) +is a branch of artificial intelligence +>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is +>>meaningful and useful.')], _role=, _name=None, +>>_meta={'model': 'ollama/llama3.2:3b', 'index': 0, 'finish_reason': 'stop', +>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]} + + + +#### LlamaStackChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + model: str, + api_base_url: str = "http://localhost:8321/v1/openai/v1", + organization: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + timeout: Optional[int] = None, + tools: Optional[ToolsType] = None, + tools_strict: bool = False, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of LlamaStackChatGenerator. To use this chat generator, + +you need to setup Llama Stack Server with an inference provider and have a model available. + +**Arguments**: + +- `model`: The name of the model to use for chat completion. +This depends on the inference provider used for the Llama Stack Server. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The Llama Stack API base url. If not specified, the localhost is used with the default port 8321. +- `organization`: Your organization ID, defaults to `None`. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Llama Stack endpoint. See [Llama Stack API docs](https://llama-stack.readthedocs.io/) for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `timeout`: Timeout for client calls using OpenAI API. If not set, it defaults to either the +`OPENAI_TIMEOUT` environment variable, or 30 seconds. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### LlamaStackChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### LlamaStackChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "LlamaStackChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mcp.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mcp.md new file mode 100644 index 0000000000..f84906866b --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mcp.md @@ -0,0 +1,1055 @@ +--- +title: "MCP" +id: integrations-mcp +description: "MCP integration for Haystack" +slug: "/integrations-mcp" +--- + + + +## Module haystack\_integrations.tools.mcp.mcp\_tool + + + +### AsyncExecutor + +Thread-safe event loop executor for running async code from sync contexts. + + + +#### AsyncExecutor.get\_instance + +```python +@classmethod +def get_instance(cls) -> "AsyncExecutor" +``` + +Get or create the global singleton executor instance. + + + +#### AsyncExecutor.\_\_init\_\_ + +```python +def __init__() +``` + +Initialize a dedicated event loop + + + +#### AsyncExecutor.run + +```python +def run(coro: Coroutine[Any, Any, Any], timeout: float | None = None) -> Any +``` + +Run a coroutine in the event loop. + +**Arguments**: + +- `coro`: Coroutine to execute +- `timeout`: Optional timeout in seconds + +**Raises**: + +- `TimeoutError`: If execution exceeds timeout + +**Returns**: + +Result of the coroutine + + + +#### AsyncExecutor.get\_loop + +```python +def get_loop() +``` + +Get the event loop. + +**Returns**: + +The event loop + + + +#### AsyncExecutor.run\_background + +```python +def run_background( + coro_factory: Callable[[asyncio.Event], Coroutine[Any, Any, Any]], + timeout: float | None = None +) -> tuple[concurrent.futures.Future[Any], asyncio.Event] +``` + +Schedule `coro_factory` to run in the executor's event loop **without** blocking the + +caller thread. + +The factory receives an :class:`asyncio.Event` that can be used to cooperatively shut +the coroutine down. The method returns **both** the concurrent future (to observe +completion or failure) and the created *stop_event* so that callers can signal termination. + +**Arguments**: + +- `coro_factory`: A callable receiving the stop_event and returning the coroutine to execute. +- `timeout`: Optional timeout while waiting for the stop_event to be created. + +**Returns**: + +Tuple ``(future, stop_event)``. + + + +#### AsyncExecutor.shutdown + +```python +def shutdown(timeout: float = 2) -> None +``` + +Shut down the background event loop and thread. + +**Arguments**: + +- `timeout`: Timeout in seconds for shutting down the event loop + + + +### MCPError + +Base class for MCP-related errors. + + + +#### MCPError.\_\_init\_\_ + +```python +def __init__(message: str) -> None +``` + +Initialize the MCPError. + +**Arguments**: + +- `message`: Descriptive error message + + + +### MCPConnectionError + +Error connecting to MCP server. + + + +#### MCPConnectionError.\_\_init\_\_ + +```python +def __init__(message: str, + server_info: "MCPServerInfo | None" = None, + operation: str | None = None) -> None +``` + +Initialize the MCPConnectionError. + +**Arguments**: + +- `message`: Descriptive error message +- `server_info`: Server connection information that was used +- `operation`: Name of the operation that was being attempted + + + +### MCPToolNotFoundError + +Error when a tool is not found on the server. + + + +#### MCPToolNotFoundError.\_\_init\_\_ + +```python +def __init__(message: str, + tool_name: str, + available_tools: list[str] | None = None) -> None +``` + +Initialize the MCPToolNotFoundError. + +**Arguments**: + +- `message`: Descriptive error message +- `tool_name`: Name of the tool that was requested but not found +- `available_tools`: List of available tool names, if known + + + +### MCPInvocationError + +Error during tool invocation. + + + +#### MCPInvocationError.\_\_init\_\_ + +```python +def __init__(message: str, + tool_name: str, + tool_args: dict[str, Any] | None = None) -> None +``` + +Initialize the MCPInvocationError. + +**Arguments**: + +- `message`: Descriptive error message +- `tool_name`: Name of the tool that was being invoked +- `tool_args`: Arguments that were passed to the tool + + + +### MCPClient + +Abstract base class for MCP clients. + +This class defines the common interface and shared functionality for all MCP clients, +regardless of the transport mechanism used. + + + +#### MCPClient.connect + +```python +@abstractmethod +async def connect() -> list[types.Tool] +``` + +Connect to an MCP server. + +**Raises**: + +- `MCPConnectionError`: If connection to the server fails + +**Returns**: + +List of available tools on the server + + + +#### MCPClient.call\_tool + +```python +async def call_tool(tool_name: str, tool_args: dict[str, Any]) -> str +``` + +Call a tool on the connected MCP server. + +**Arguments**: + +- `tool_name`: Name of the tool to call +- `tool_args`: Arguments to pass to the tool + +**Raises**: + +- `MCPConnectionError`: If not connected to an MCP server +- `MCPInvocationError`: If the tool invocation fails + +**Returns**: + +JSON string representation of the tool invocation result + + + +#### MCPClient.aclose + +```python +async def aclose() -> None +``` + +Close the connection and clean up resources. + +This method ensures all resources are properly released, even if errors occur. + + + +### StdioClient + +MCP client that connects to servers using stdio transport. + + + +#### StdioClient.\_\_init\_\_ + +```python +def __init__(command: str, + args: list[str] | None = None, + env: dict[str, str | Secret] | None = None, + max_retries: int = 3, + base_delay: float = 1.0, + max_delay: float = 30.0) -> None +``` + +Initialize a stdio MCP client. + +**Arguments**: + +- `command`: Command to run (e.g., "python", "node") +- `args`: Arguments to pass to the command +- `env`: Environment variables for the command +- `max_retries`: Maximum number of reconnection attempts +- `base_delay`: Base delay for exponential backoff in seconds + + + +#### StdioClient.connect + +```python +async def connect() -> list[types.Tool] +``` + +Connect to an MCP server using stdio transport. + +**Raises**: + +- `MCPConnectionError`: If connection to the server fails + +**Returns**: + +List of available tools on the server + + + +### SSEClient + +MCP client that connects to servers using SSE transport. + + + +#### SSEClient.\_\_init\_\_ + +```python +def __init__(server_info: "SSEServerInfo", + max_retries: int = 3, + base_delay: float = 1.0, + max_delay: float = 30.0) -> None +``` + +Initialize an SSE MCP client using server configuration. + +**Arguments**: + +- `server_info`: Configuration object containing URL, token, timeout, etc. +- `max_retries`: Maximum number of reconnection attempts +- `base_delay`: Base delay for exponential backoff in seconds + + + +#### SSEClient.connect + +```python +async def connect() -> list[types.Tool] +``` + +Connect to an MCP server using SSE transport. + +Note: If both custom headers and token are provided, custom headers take precedence. + +**Raises**: + +- `MCPConnectionError`: If connection to the server fails + +**Returns**: + +List of available tools on the server + + + +### StreamableHttpClient + +MCP client that connects to servers using streamable HTTP transport. + + + +#### StreamableHttpClient.\_\_init\_\_ + +```python +def __init__(server_info: "StreamableHttpServerInfo", + max_retries: int = 3, + base_delay: float = 1.0, + max_delay: float = 30.0) -> None +``` + +Initialize a streamable HTTP MCP client using server configuration. + +**Arguments**: + +- `server_info`: Configuration object containing URL, token, timeout, etc. +- `max_retries`: Maximum number of reconnection attempts +- `base_delay`: Base delay for exponential backoff in seconds + + + +#### StreamableHttpClient.connect + +```python +async def connect() -> list[types.Tool] +``` + +Connect to an MCP server using streamable HTTP transport. + +Note: If both custom headers and token are provided, custom headers take precedence. + +**Raises**: + +- `MCPConnectionError`: If connection to the server fails + +**Returns**: + +List of available tools on the server + + + +### MCPServerInfo + +Abstract base class for MCP server connection parameters. + +This class defines the common interface for all MCP server connection types. + + + +#### MCPServerInfo.create\_client + +```python +@abstractmethod +def create_client() -> MCPClient +``` + +Create an appropriate MCP client for this server info. + +**Returns**: + +An instance of MCPClient configured with this server info + + + +#### MCPServerInfo.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize this server info to a dictionary. + +**Returns**: + +Dictionary representation of this server info + + + +#### MCPServerInfo.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "MCPServerInfo" +``` + +Deserialize server info from a dictionary. + +**Arguments**: + +- `data`: Dictionary containing serialized server info + +**Returns**: + +Instance of the appropriate server info class + + + +### SSEServerInfo + +Data class that encapsulates SSE MCP server connection parameters. + +For authentication tokens containing sensitive data, you can use Secret objects +for secure handling and serialization: + +```python +server_info = SSEServerInfo( + url="https://my-mcp-server.com", + token=Secret.from_env_var("API_KEY"), +) +``` + +For custom headers (e.g., non-standard authentication): + +```python +# Single custom header with Secret +server_info = SSEServerInfo( + url="https://my-mcp-server.com", + headers={"X-API-Key": Secret.from_env_var("API_KEY")}, +) + +# Multiple headers (mix of Secret and plain strings) +server_info = SSEServerInfo( + url="https://my-mcp-server.com", + headers={ + "X-API-Key": Secret.from_env_var("API_KEY"), + "X-Client-ID": "my-client-id", + }, +) +``` + +**Arguments**: + +- `url`: Full URL of the MCP server (including /sse endpoint) +- `base_url`: Base URL of the MCP server (deprecated, use url instead) +- `token`: Authentication token for the server (optional, generates "Authorization: Bearer ``" header) +- `headers`: Custom HTTP headers (optional, takes precedence over token parameter if provided) +- `timeout`: Connection timeout in seconds + + + +#### base\_url + +deprecated + + + +#### SSEServerInfo.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Validate that either url or base_url is provided. + + + +#### SSEServerInfo.create\_client + +```python +def create_client() -> MCPClient +``` + +Create an SSE MCP client. + +**Returns**: + +Configured MCPClient instance + + + +### StreamableHttpServerInfo + +Data class that encapsulates streamable HTTP MCP server connection parameters. + +For authentication tokens containing sensitive data, you can use Secret objects +for secure handling and serialization: + +```python +server_info = StreamableHttpServerInfo( + url="https://my-mcp-server.com", + token=Secret.from_env_var("API_KEY"), +) +``` + +For custom headers (e.g., non-standard authentication): + +```python +# Single custom header with Secret +server_info = StreamableHttpServerInfo( + url="https://my-mcp-server.com", + headers={"X-API-Key": Secret.from_env_var("API_KEY")}, +) + +# Multiple headers (mix of Secret and plain strings) +server_info = StreamableHttpServerInfo( + url="https://my-mcp-server.com", + headers={ + "X-API-Key": Secret.from_env_var("API_KEY"), + "X-Client-ID": "my-client-id", + }, +) +``` + +**Arguments**: + +- `url`: Full URL of the MCP server (streamable HTTP endpoint) +- `token`: Authentication token for the server (optional, generates "Authorization: Bearer ``" header) +- `headers`: Custom HTTP headers (optional, takes precedence over token parameter if provided) +- `timeout`: Connection timeout in seconds + + + +#### StreamableHttpServerInfo.\_\_post\_init\_\_ + +```python +def __post_init__() +``` + +Validate the URL. + + + +#### StreamableHttpServerInfo.create\_client + +```python +def create_client() -> MCPClient +``` + +Create a streamable HTTP MCP client. + +**Returns**: + +Configured StreamableHttpClient instance + + + +### StdioServerInfo + +Data class that encapsulates stdio MCP server connection parameters. + +**Arguments**: + +- `command`: Command to run (e.g., "python", "node") +- `args`: Arguments to pass to the command +- `env`: Environment variables for the command +For environment variables containing sensitive data, you can use Secret objects +for secure handling and serialization: + +```python +server_info = StdioServerInfo( + command="uv", + args=["run", "my-mcp-server"], + env={ + "WORKSPACE_PATH": "/path/to/workspace", # Plain string + "API_KEY": Secret.from_env_var("API_KEY"), # Secret object + } +) +``` + +Secret objects will be properly serialized and deserialized without exposing +the secret value, while plain strings will be preserved as-is. Use Secret objects +for sensitive data that needs to be handled securely. + + + +#### StdioServerInfo.create\_client + +```python +def create_client() -> MCPClient +``` + +Create a stdio MCP client. + +**Returns**: + +Configured StdioMCPClient instance + + + +### MCPTool + +A Tool that represents a single tool from an MCP server. + +This implementation uses the official MCP SDK for protocol handling while maintaining +compatibility with the Haystack tool ecosystem. + +Response handling: +- Text and image content are supported and returned as JSON strings +- The JSON contains the structured response from the MCP server +- Use json.loads() to parse the response into a dictionary + +Example using Streamable HTTP: +```python +import json +from haystack_integrations.tools.mcp import MCPTool, StreamableHttpServerInfo + +# Create tool instance +tool = MCPTool( + name="multiply", + server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp") +) + +# Use the tool and parse result +result_json = tool.invoke(a=5, b=3) +result = json.loads(result_json) +``` + +Example using SSE (deprecated): +```python +import json +from haystack.tools import MCPTool, SSEServerInfo + +# Create tool instance +tool = MCPTool( + name="add", + server_info=SSEServerInfo(url="http://localhost:8000/sse") +) + +# Use the tool and parse result +result_json = tool.invoke(a=5, b=3) +result = json.loads(result_json) +``` + +Example using stdio: +```python +import json +from haystack.tools import MCPTool, StdioServerInfo + +# Create tool instance +tool = MCPTool( + name="get_current_time", + server_info=StdioServerInfo(command="python", args=["path/to/server.py"]) +) + +# Use the tool and parse result +result_json = tool.invoke(timezone="America/New_York") +result = json.loads(result_json) +``` + + + +#### MCPTool.\_\_init\_\_ + +```python +def __init__(name: str, + server_info: MCPServerInfo, + description: str | None = None, + connection_timeout: int = 30, + invocation_timeout: int = 30, + eager_connect: bool = False) +``` + +Initialize the MCP tool. + +**Arguments**: + +- `name`: Name of the tool to use +- `server_info`: Server connection information +- `description`: Custom description (if None, server description will be used) +- `connection_timeout`: Timeout in seconds for server connection +- `invocation_timeout`: Default timeout in seconds for tool invocations +- `eager_connect`: If True, connect to server during initialization. +If False (default), defer connection until warm_up or first tool use, +whichever comes first. + +**Raises**: + +- `MCPConnectionError`: If connection to the server fails +- `MCPToolNotFoundError`: If no tools are available or the requested tool is not found +- `TimeoutError`: If connection times out + + + +#### MCPTool.ainvoke + +```python +async def ainvoke(**kwargs: Any) -> str +``` + +Asynchronous tool invocation. + +**Arguments**: + +- `kwargs`: Arguments to pass to the tool + +**Raises**: + +- `MCPInvocationError`: If the tool invocation fails +- `TimeoutError`: If the operation times out + +**Returns**: + +JSON string representation of the tool invocation result + + + +#### MCPTool.warm\_up + +```python +def warm_up() -> None +``` + +Connect and fetch the tool schema if eager_connect is turned off. + + + +#### MCPTool.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the MCPTool to a dictionary. + +The serialization preserves all information needed to recreate the tool, +including server connection parameters and timeout settings. Note that the +active connection is not maintained. + +**Returns**: + +Dictionary with serialized data in the format: +`{"type": fully_qualified_class_name, "data": {parameters}}` + + + +#### MCPTool.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "Tool" +``` + +Deserializes the MCPTool from a dictionary. + +This method reconstructs an MCPTool instance from a serialized dictionary, +including recreating the server_info object. A new connection will be established +to the MCP server during initialization. + +**Arguments**: + +- `data`: Dictionary containing serialized tool data + +**Raises**: + +- `None`: Various exceptions if connection fails + +**Returns**: + +A fully initialized MCPTool instance + + + +#### MCPTool.close + +```python +def close() +``` + +Close the tool synchronously. + + + +#### MCPTool.\_\_del\_\_ + +```python +def __del__() +``` + +Cleanup resources when the tool is garbage collected. + + + +### \_MCPClientSessionManager + +Runs an MCPClient connect/close inside the AsyncExecutor's event loop. + +Life-cycle: + 1. Create the worker to schedule a long-running coroutine in the + dedicated background loop. + 2. The coroutine calls *connect* on mcp client; when it has the tool list it fulfils + a concurrent future so the synchronous thread can continue. + 3. It then waits on an `asyncio.Event`. + 4. `stop()` sets the event from any thread. The same coroutine then calls + *close()* on mcp client and finishes without the dreaded + `Attempted to exit cancel scope in a different task than it was entered in` error + thus properly closing the client. + + + +#### \_MCPClientSessionManager.tools + +```python +def tools() -> list[types.Tool] +``` + +Return the tool list already collected during startup. + + + +#### \_MCPClientSessionManager.stop + +```python +def stop() -> None +``` + +Request the worker to shut down and block until done. + + + +## Module haystack\_integrations.tools.mcp.mcp\_toolset + + + +### MCPToolset + +A Toolset that connects to an MCP (Model Context Protocol) server and provides +access to its tools. + +MCPToolset dynamically discovers and loads all tools from any MCP-compliant server, +supporting both network-based streaming connections (Streamable HTTP, SSE) and local +process-based stdio connections. +This dual connectivity allows for integrating with both remote and local MCP servers. + +Example using MCPToolset in a Haystack Pipeline: +```python +# Prerequisites: +# 1. pip install uvx mcp-server-time # Install required MCP server and tools +# 2. export OPENAI_API_KEY="your-api-key" # Set up your OpenAI API key + +import os +from haystack import Pipeline +from haystack.components.converters import OutputAdapter +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.components.tools import ToolInvoker +from haystack.dataclasses import ChatMessage +from haystack_integrations.tools.mcp import MCPToolset, StdioServerInfo + +# Create server info for the time service (can also use SSEServerInfo for remote servers) +server_info = StdioServerInfo(command="uvx", args=["mcp-server-time", "--local-timezone=Europe/Berlin"]) + +# Create the toolset - this will automatically discover all available tools +# You can optionally specify which tools to include +mcp_toolset = MCPToolset( + server_info=server_info, + tool_names=["get_current_time"] # Only include the get_current_time tool +) + +# Create a pipeline with the toolset +pipeline = Pipeline() +pipeline.add_component("llm", OpenAIChatGenerator(model="gpt-4o-mini", tools=mcp_toolset)) +pipeline.add_component("tool_invoker", ToolInvoker(tools=mcp_toolset)) +pipeline.add_component( + "adapter", + OutputAdapter( + template="{{ initial_msg + initial_tool_messages + tool_messages }}", + output_type=list[ChatMessage], + unsafe=True, + ), +) +pipeline.add_component("response_llm", OpenAIChatGenerator(model="gpt-4o-mini")) +pipeline.connect("llm.replies", "tool_invoker.messages") +pipeline.connect("llm.replies", "adapter.initial_tool_messages") +pipeline.connect("tool_invoker.tool_messages", "adapter.tool_messages") +pipeline.connect("adapter.output", "response_llm.messages") + +# Run the pipeline with a user question +user_input = "What is the time in New York? Be brief." +user_input_msg = ChatMessage.from_user(text=user_input) + +result = pipeline.run({"llm": {"messages": [user_input_msg]}, "adapter": {"initial_msg": [user_input_msg]}}) +print(result["response_llm"]["replies"][0].text) +``` + +You can also use the toolset via Streamable HTTP to talk to remote servers: +```python +from haystack_integrations.tools.mcp import MCPToolset, StreamableHttpServerInfo + +# Create the toolset with streamable HTTP connection +toolset = MCPToolset( + server_info=StreamableHttpServerInfo(url="http://localhost:8000/mcp"), + tool_names=["multiply"] # Optional: only include specific tools +) +# Use the toolset as shown in the pipeline example above +``` + +Example using SSE (deprecated): +```python +from haystack_integrations.tools.mcp import MCPToolset, SSEServerInfo +from haystack.components.tools import ToolInvoker + +# Create the toolset with an SSE connection +sse_toolset = MCPToolset( + server_info=SSEServerInfo(url="http://some-remote-server.com:8000/sse"), + tool_names=["add", "subtract"] # Only include specific tools +) + +# Use the toolset as shown in the pipeline example above +``` + + + +#### MCPToolset.\_\_init\_\_ + +```python +def __init__(server_info: MCPServerInfo, + tool_names: list[str] | None = None, + connection_timeout: float = 30.0, + invocation_timeout: float = 30.0, + eager_connect: bool = False) +``` + +Initialize the MCP toolset. + +**Arguments**: + +- `server_info`: Connection information for the MCP server +- `tool_names`: Optional list of tool names to include. If provided, only tools with +matching names will be added to the toolset. +- `connection_timeout`: Timeout in seconds for server connection +- `invocation_timeout`: Default timeout in seconds for tool invocations +- `eager_connect`: If True, connect to server and load tools during initialization. +If False (default), defer connection to warm_up. + +**Raises**: + +- `MCPToolNotFoundError`: If any of the specified tool names are not found on the server + + + +#### MCPToolset.warm\_up + +```python +def warm_up() -> None +``` + +Connect and load tools when eager_connect is turned off. + +This method is automatically called by ``ToolInvoker.warm_up()`` and ``Pipeline.warm_up()``. +You can also call it directly before using the toolset to ensure all tool schemas +are available without performing a real invocation. + + + +#### MCPToolset.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the MCPToolset to a dictionary. + +**Returns**: + +A dictionary representation of the MCPToolset + + + +#### MCPToolset.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "MCPToolset" +``` + +Deserialize an MCPToolset from a dictionary. + +**Arguments**: + +- `data`: Dictionary representation of the MCPToolset + +**Returns**: + +A new MCPToolset instance + + + +#### MCPToolset.close + +```python +def close() +``` + +Close the underlying MCP client safely. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/meta_llama.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/meta_llama.md new file mode 100644 index 0000000000..1662babb55 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/meta_llama.md @@ -0,0 +1,111 @@ +--- +title: "Meta Llama API" +id: integrations-meta-llama +description: "Meta Llama API integration for Haystack" +slug: "/integrations-meta-llama" +--- + + + +## Module haystack\_integrations.components.generators.meta\_llama.chat.chat\_generator + + + +### MetaLlamaChatGenerator + +Enables text generation using Llama generative models. +For supported models, see [Llama API Docs](https://llama.developer.meta.com/docs/). + +Users can pass any text generation parameters valid for the Llama Chat Completion API +directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +Key Features and Compatibility: +- **Primary Compatibility**: Designed to work seamlessly with the Llama API Chat Completion endpoint. +- **Streaming Support**: Supports streaming responses from the Llama API Chat Completion endpoint. +- **Customizability**: Supports parameters supported by the Llama API Chat Completion endpoint. +- **Response Format**: Currently only supports json_schema response format. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/data-classes#chatmessage) + +For more details on the parameters supported by the Llama API, refer to the +[Llama API Docs](https://llama.developer.meta.com/docs/). + +Usage example: +```python +from haystack_integrations.components.generators.llama import LlamaChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = LlamaChatGenerator() +response = client.run(messages) +print(response) +``` + + + +#### MetaLlamaChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("LLAMA_API_KEY"), + model: str = "Llama-4-Scout-17B-16E-Instruct-FP8", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = "https://api.llama.com/compat/v1/", + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None) +``` + +Creates an instance of LlamaChatGenerator. Unless specified otherwise in the `model`, this is for Llama's + +`Llama-4-Scout-17B-16E-Instruct-FP8` model. + +**Arguments**: + +- `api_key`: The Llama API key. +- `model`: The name of the Llama chat completion model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The Llama API Base url. +For more details, see LlamaAPI [docs](https://llama.developer.meta.com/docs/features/compatibility/). +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Llama API endpoint. See [Llama API docs](https://llama.developer.meta.com/docs/features/compatibility/) +for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + For structured outputs with streaming, the `response_format` must be a JSON + schema and not a Pydantic model. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. + + + +#### MetaLlamaChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mistral.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mistral.md new file mode 100644 index 0000000000..c5f1f91320 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mistral.md @@ -0,0 +1,476 @@ +--- +title: "Mistral" +id: integrations-mistral +description: "Mistral integration for Haystack" +slug: "/integrations-mistral" +--- + + + +## Module haystack\_integrations.components.embedders.mistral.document\_embedder + + + +### MistralDocumentEmbedder + +A component for computing Document embeddings using Mistral models. +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.mistral import MistralDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = MistralDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### MistralDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"), + model: str = "mistral-embed", + api_base_url: Optional[str] = "https://api.mistral.ai/v1", + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates a MistralDocumentEmbedder component. + +**Arguments**: + +- `api_key`: The Mistral API key. +- `model`: The name of the model to use. +- `api_base_url`: The Mistral API Base url. For more details, see Mistral [docs](https://docs.mistral.ai/api/). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `batch_size`: Number of Documents to encode at once. +- `progress_bar`: Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep +the logs clean. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. +- `timeout`: Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment +variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact Mistral after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### MistralDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module haystack\_integrations.components.embedders.mistral.text\_embedder + + + +### MistralTextEmbedder + +A component for embedding strings using Mistral models. + +Usage example: + ```python +from haystack_integrations.components.embedders.mistral.text_embedder import MistralTextEmbedder + +text_to_embed = "I love pizza!" +text_embedder = MistralTextEmbedder() +print(text_embedder.run(text_to_embed)) + +__output:__ + +__{'embedding': [0.017020374536514282, -0.023255806416273117, ...],__ + +__'meta': {'model': 'mistral-embed',__ + +__ 'usage': {'prompt_tokens': 4, 'total_tokens': 4}}}__ + +``` + + + +#### MistralTextEmbedder.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"), + model: str = "mistral-embed", + api_base_url: Optional[str] = "https://api.mistral.ai/v1", + prefix: str = "", + suffix: str = "", + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an MistralTextEmbedder component. + +**Arguments**: + +- `api_key`: The Mistral API key. +- `model`: The name of the Mistral embedding model to be used. +- `api_base_url`: The Mistral API Base url. +For more details, see Mistral [docs](https://docs.mistral.ai/api/). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `timeout`: Timeout for Mistral client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment +variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact Mistral after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### MistralTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module haystack\_integrations.components.generators.mistral.chat.chat\_generator + + + +### MistralChatGenerator + +Enables text generation using Mistral AI generative models. +For supported models, see [Mistral AI docs](https://docs.mistral.ai/platform/endpoints/`operation`/listModels). + +Users can pass any text generation parameters valid for the Mistral Chat Completion API +directly to this component via the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +Key Features and Compatibility: +- **Primary Compatibility**: Designed to work seamlessly with the Mistral API Chat Completion endpoint. +- **Streaming Support**: Supports streaming responses from the Mistral API Chat Completion endpoint. +- **Customizability**: Supports all parameters supported by the Mistral API Chat Completion endpoint. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/v2.0/docs/data-classes#chatmessage) + +For more details on the parameters supported by the Mistral API, refer to the +[Mistral API Docs](https://docs.mistral.ai/api/). + +Usage example: +```python +from haystack_integrations.components.generators.mistral import MistralChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = MistralChatGenerator() +response = client.run(messages) +print(response) + +>>{'replies': [ChatMessage(_role=, _content=[TextContent(text= +>> "Natural Language Processing (NLP) is a branch of artificial intelligence +>> that focuses on enabling computers to understand, interpret, and generate human language in a way that is +>> meaningful and useful.")], _name=None, +>> _meta={'model': 'mistral-small-latest', 'index': 0, 'finish_reason': 'stop', +>> 'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]} +``` + + + +#### MistralChatGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"), + model: str = "mistral-small-latest", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = "https://api.mistral.ai/v1", + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of MistralChatGenerator. Unless specified otherwise in the `model`, this is for Mistral's + +`mistral-small-latest` model. + +**Arguments**: + +- `api_key`: The Mistral API key. +- `model`: The name of the Mistral chat completion model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The Mistral API Base url. +For more details, see Mistral [docs](https://docs.mistral.ai/api/). +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Mistral endpoint. See [Mistral API docs](https://docs.mistral.ai/api/) for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. + - `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + Notes: + - For structured outputs with streaming, + the `response_format` must be a JSON schema and not a Pydantic model. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. +- `timeout`: The timeout for the Mistral API call. If not set, it defaults to either the `OPENAI_TIMEOUT` +environment variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### MistralChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +## Module haystack\_integrations.components.converters.mistral.ocr\_document\_converter + + + +### MistralOCRDocumentConverter + +This component extracts text from documents using Mistral's OCR API, with optional structured +annotations for both individual image regions (bounding boxes) and full documents. + +Accepts document sources in various formats (str/Path for local files, ByteStream for in-memory data, +DocumentURLChunk for document URLs, ImageURLChunk for image URLs, or FileChunk for Mistral file IDs) +and retrieves the recognized text via Mistral's OCR service. Local files are automatically uploaded +to Mistral's storage. +Returns Haystack Documents (one per source) containing all pages concatenated with form feed characters (\f), +ensuring compatibility with Haystack's DocumentSplitter for accurate page-wise splitting and overlap handling. + +**How Annotations Work:** +When annotation schemas (`bbox_annotation_schema` or `document_annotation_schema`) are provided, +the OCR model first extracts text and structure from the document. Then, a Vision LLM is called +to analyze the content and generate structured annotations according to your defined schemas. +For more details, see: https://docs.mistral.ai/capabilities/document_ai/annotations/`how`-it-works + +**Usage Example:** + +**Structured Output Example:** +```python +from haystack.utils import Secret +from haystack_integrations.mistral import MistralOCRDocumentConverter +from mistralai.models import DocumentURLChunk, ImageURLChunk, FileChunk + +converter = MistralOCRDocumentConverter( + api_key=Secret.from_env_var("MISTRAL_API_KEY"), + model="mistral-ocr-2505" +) + +# Process multiple sources +sources = [ + DocumentURLChunk(document_url="https://example.com/document.pdf"), + ImageURLChunk(image_url="https://example.com/receipt.jpg"), + FileChunk(file_id="file-abc123"), +] +result = converter.run(sources=sources) + +documents = result["documents"] # List of 3 Documents +raw_responses = result["raw_mistral_response"] # List of 3 raw responses +``` +```python +from pydantic import BaseModel, Field +from haystack_integrations.mistral import MistralOCRDocumentConverter + +# Define schema for structured image annotations +class ImageAnnotation(BaseModel): + image_type: str = Field(..., description="The type of image content") + short_description: str = Field(..., description="Short natural-language description") + summary: str = Field(..., description="Detailed summary of the image content") + +# Define schema for structured document annotations +class DocumentAnnotation(BaseModel): + language: str = Field(..., description="Primary language of the document") + chapter_titles: List[str] = Field(..., description="Detected chapter or section titles") + urls: List[str] = Field(..., description="URLs found in the text") + +converter = MistralOCRDocumentConverter( + model="mistral-ocr-2505", +) + +sources = [DocumentURLChunk(document_url="https://example.com/report.pdf")] +result = converter.run( + sources=sources, + bbox_annotation_schema=ImageAnnotation, + document_annotation_schema=DocumentAnnotation, +) + +documents = result["documents"] +raw_responses = result["raw_mistral_response"] +``` + + + +#### MistralOCRDocumentConverter.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("MISTRAL_API_KEY"), + model: str = "mistral-ocr-2505", + include_image_base64: bool = False, + pages: Optional[List[int]] = None, + image_limit: Optional[int] = None, + image_min_size: Optional[int] = None, + cleanup_uploaded_files: bool = True) +``` + +Creates a MistralOCRDocumentConverter component. + +**Arguments**: + +- `api_key`: The Mistral API key. Defaults to the MISTRAL_API_KEY environment variable. +- `model`: The OCR model to use. Default is "mistral-ocr-2505". +See more: https://docs.mistral.ai/getting-started/models/models_overview/ +- `include_image_base64`: If True, includes base64 encoded images in the response. +This may significantly increase response size and processing time. +- `pages`: Specific page numbers to process (0-indexed). If None, processes all pages. +- `image_limit`: Maximum number of images to extract from the document. +- `image_min_size`: Minimum height and width (in pixels) for images to be extracted. +- `cleanup_uploaded_files`: If True, automatically deletes files uploaded to Mistral after processing. +Only affects files uploaded from local sources (str, Path, ByteStream). +Files provided as FileChunk are not deleted. Default is True. + + + +#### MistralOCRDocumentConverter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### MistralOCRDocumentConverter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "MistralOCRDocumentConverter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### MistralOCRDocumentConverter.run + +```python +@component.output_types(documents=List[Document], + raw_mistral_response=List[Dict[str, Any]]) +def run( + sources: List[Union[str, Path, ByteStream, DocumentURLChunk, FileChunk, + ImageURLChunk]], + meta: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None, + bbox_annotation_schema: Optional[Type[BaseModel]] = None, + document_annotation_schema: Optional[Type[BaseModel]] = None +) -> Dict[str, Any] +``` + +Extract text from documents using Mistral OCR. + +**Arguments**: + +- `sources`: List of document sources to process. Each source can be one of: +- str: File path to a local document +- Path: Path object to a local document +- ByteStream: Haystack ByteStream object containing document data +- DocumentURLChunk: Mistral chunk for document URLs (signed or public URLs to PDFs, etc.) +- ImageURLChunk: Mistral chunk for image URLs (signed or public URLs to images) +- FileChunk: Mistral chunk for file IDs (files previously uploaded to Mistral) +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of sources, because they will be zipped. +- `bbox_annotation_schema`: Optional Pydantic model for structured annotations per bounding box. +When provided, a Vision LLM analyzes each image region and returns structured data. +- `document_annotation_schema`: Optional Pydantic model for structured annotations for the full document. +When provided, a Vision LLM analyzes the entire document and returns structured data. +Note: Document annotation is limited to a maximum of 8 pages. Documents exceeding +this limit will not be processed for document annotation. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Haystack Documents (one per source). Each Document has the following structure: + - `content`: All pages joined with form feed (\f) separators in markdown format. + When using bbox_annotation_schema, image tags will be enriched with your defined descriptions. + - `meta`: Aggregated metadata dictionary with structure: + `{"source_page_count": int, "source_total_images": int, "source_*": any}`. + If document_annotation_schema was provided, all annotation fields are unpacked + with 'source_' prefix (e.g., source_language, source_chapter_titles, source_urls). +- `raw_mistral_response`: + List of dictionaries containing raw OCR responses from Mistral API (one per source). + Each response includes per-page details, images, annotations, and usage info. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mongodb_atlas.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mongodb_atlas.md new file mode 100644 index 0000000000..317abb2890 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/mongodb_atlas.md @@ -0,0 +1,725 @@ +--- +title: "MongoDB Atlas" +id: integrations-mongodb-atlas +description: "MongoDB Atlas integration for Haystack" +slug: "/integrations-mongodb-atlas" +--- + + + +## Module haystack\_integrations.document\_stores.mongodb\_atlas.document\_store + + + +### MongoDBAtlasDocumentStore + +A MongoDBAtlasDocumentStore implementation that uses the +[MongoDB Atlas](https://www.mongodb.com/atlas/database) service that is easy to deploy, operate, and scale. + +To connect to MongoDB Atlas, you need to provide a connection string in the format: +`"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`. + +This connection string can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button, selecting +Python as the driver, and copying the connection string. The connection string can be provided as an environment +variable `MONGO_CONNECTION_STRING` or directly as a parameter to the `MongoDBAtlasDocumentStore` constructor. + +After providing the connection string, you'll need to specify the `database_name` and `collection_name` to use. +Most likely that you'll create these via the MongoDB Atlas web UI but one can also create them via the MongoDB +Python driver. Creating databases and collections is beyond the scope of MongoDBAtlasDocumentStore. The primary +purpose of this document store is to read and write documents to an existing collection. + +Users must provide both a `vector_search_index` for vector search operations and a `full_text_search_index` +for full-text search operations. The `vector_search_index` supports a chosen metric +(e.g., cosine, dot product, or Euclidean), while the `full_text_search_index` enables efficient text-based searches. +Both indexes can be created through the Atlas web UI. + +For more details on MongoDB Atlas, see the official +MongoDB Atlas [documentation](https://www.mongodb.com/docs/atlas/getting-started/). + +Usage example: +```python +from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore + +store = MongoDBAtlasDocumentStore(database_name="your_existing_db", + collection_name="your_existing_collection", + vector_search_index="your_existing_index", + full_text_search_index="your_existing_index") +print(store.count_documents()) +``` + + + +#### MongoDBAtlasDocumentStore.\_\_init\_\_ + +```python +def __init__(*, + mongo_connection_string: Secret = Secret.from_env_var( + "MONGO_CONNECTION_STRING"), + database_name: str, + collection_name: str, + vector_search_index: str, + full_text_search_index: str, + embedding_field: str = "embedding", + content_field: str = "content") +``` + +Creates a new MongoDBAtlasDocumentStore instance. + +**Arguments**: + +- `mongo_connection_string`: MongoDB Atlas connection string in the format: +`"mongodb+srv://{mongo_atlas_username}:{mongo_atlas_password}@{mongo_atlas_host}/?{mongo_atlas_params_string}"`. +This can be obtained on the MongoDB Atlas Dashboard by clicking on the `CONNECT` button. +This value will be read automatically from the env var "MONGO_CONNECTION_STRING". +- `database_name`: Name of the database to use. +- `collection_name`: Name of the collection to use. To use this document store for embedding retrieval, +this collection needs to have a vector search index set up on the `embedding` field. +- `vector_search_index`: The name of the vector search index to use for vector search operations. +Create a vector_search_index in the Atlas web UI and specify the init params of MongoDBAtlasDocumentStore. For more details refer to MongoDB +Atlas [documentation](https://www.mongodb.com/docs/atlas/atlas-vector-search/create-index/`std`-label-avs-create-index). +- `full_text_search_index`: The name of the search index to use for full-text search operations. +Create a full_text_search_index in the Atlas web UI and specify the init params of +MongoDBAtlasDocumentStore. For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/create-index/). +- `embedding_field`: The name of the field containing document embeddings. Default is "embedding". +- `content_field`: The name of the field containing the document content. Default is "content". +This field is allows defining which field to load into the Haystack Document object as content. +It can be particularly useful when integrating with an existing collection for retrieval. We discourage +using this parameter when working with collections created by Haystack. + +**Raises**: + +- `ValueError`: If the collection name contains invalid characters. + + + +#### MongoDBAtlasDocumentStore.\_\_del\_\_ + +```python +def __del__() -> None +``` + +Destructor method to close MongoDB connections when the instance is destroyed. + + + +#### MongoDBAtlasDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### MongoDBAtlasDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "MongoDBAtlasDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### MongoDBAtlasDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + +**Returns**: + +The number of documents in the document store. + + + +#### MongoDBAtlasDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns how many documents are present in the document store. + +**Returns**: + +The number of documents in the document store. + + + +#### MongoDBAtlasDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the Haystack [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering). + +**Arguments**: + +- `filters`: The filters to apply. It returns only the documents that match the filters. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### MongoDBAtlasDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the Haystack [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering). + +**Arguments**: + +- `filters`: The filters to apply. It returns only the documents that match the filters. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### MongoDBAtlasDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes documents into the MongoDB Atlas collection. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Raises**: + +- `DuplicateDocumentError`: If a document with the same ID already exists in the document store +and the policy is set to DuplicatePolicy.FAIL (or not specified). +- `ValueError`: If the documents are not of type Document. + +**Returns**: + +The number of documents written to the document store. + + + +#### MongoDBAtlasDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes documents into the MongoDB Atlas collection. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Raises**: + +- `DuplicateDocumentError`: If a document with the same ID already exists in the document store +and the policy is set to DuplicatePolicy.FAIL (or not specified). +- `ValueError`: If the documents are not of type Document. + +**Returns**: + +The number of documents written to the document store. + + + +#### MongoDBAtlasDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes all documents with a matching document_ids from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### MongoDBAtlasDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes all documents with a matching document_ids from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### MongoDBAtlasDocumentStore.delete\_by\_filter + +```python +def delete_by_filter(filters: Dict[str, Any]) -> int +``` + +Deletes all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for deletion. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Returns**: + +The number of documents deleted. + + + +#### MongoDBAtlasDocumentStore.delete\_by\_filter\_async + +```python +async def delete_by_filter_async(filters: Dict[str, Any]) -> int +``` + +Asynchronously deletes all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for deletion. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Returns**: + +The number of documents deleted. + + + +#### MongoDBAtlasDocumentStore.update\_by\_filter + +```python +def update_by_filter(filters: Dict[str, Any], meta: Dict[str, Any]) -> int +``` + +Updates the metadata of all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for updating. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) +- `meta`: The metadata fields to update. + +**Returns**: + +The number of documents updated. + + + +#### MongoDBAtlasDocumentStore.update\_by\_filter\_async + +```python +async def update_by_filter_async(filters: Dict[str, Any], + meta: Dict[str, Any]) -> int +``` + +Asynchronously updates the metadata of all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for updating. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) +- `meta`: The metadata fields to update. + +**Returns**: + +The number of documents updated. + + + +#### MongoDBAtlasDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(*, recreate_collection: bool = False) -> None +``` + +Deletes all documents in the document store. + +**Arguments**: + +- `recreate_collection`: If True, the collection will be dropped and recreated with the original +configuration and indexes. If False, all documents will be deleted while preserving the collection. +Recreating the collection is faster for very large collections. + + + +#### MongoDBAtlasDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async(*, + recreate_collection: bool = False + ) -> None +``` + +Asynchronously deletes all documents in the document store. + +**Arguments**: + +- `recreate_collection`: If True, the collection will be dropped and recreated with the original +configuration and indexes. If False, all documents will be deleted while preserving the collection. +Recreating the collection is faster for very large collections. + + + +## Module haystack\_integrations.components.retrievers.mongodb\_atlas.embedding\_retriever + + + +### MongoDBAtlasEmbeddingRetriever + +Retrieves documents from the MongoDBAtlasDocumentStore by embedding similarity. + +The similarity is dependent on the vector_search_index used in the MongoDBAtlasDocumentStore and the chosen metric +during the creation of the index (i.e. cosine, dot product, or euclidean). See MongoDBAtlasDocumentStore for more +information. + +Usage example: +```python +import numpy as np +from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore +from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasEmbeddingRetriever + +store = MongoDBAtlasDocumentStore(database_name="haystack_integration_test", + collection_name="test_embeddings_collection", + vector_search_index="cosine_index", + full_text_search_index="full_text_index") +retriever = MongoDBAtlasEmbeddingRetriever(document_store=store) + +results = retriever.run(query_embedding=np.random.random(768).tolist()) +print(results["documents"]) +``` + +The example above retrieves the 10 most similar documents to a random query embedding from the +MongoDBAtlasDocumentStore. Note that dimensions of the query_embedding must match the dimensions of the embeddings +stored in the MongoDBAtlasDocumentStore. + + + +#### MongoDBAtlasEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: MongoDBAtlasDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Create the MongoDBAtlasDocumentStore component. + +**Arguments**: + +- `document_store`: An instance of MongoDBAtlasDocumentStore. +- `filters`: Filters applied to the retrieved Documents. Make sure that the fields used in the filters are +included in the configuration of the `vector_search_index`. The configuration must be done manually +in the Web UI of MongoDB Atlas. +- `top_k`: Maximum number of Documents to return. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `MongoDBAtlasDocumentStore`. + + + +#### MongoDBAtlasEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### MongoDBAtlasEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "MongoDBAtlasEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### MongoDBAtlasEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding similarity. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. Overrides the value specified at initialization. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given `query_embedding` + + + +#### MongoDBAtlasEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents from the MongoDBAtlasDocumentStore, based on the provided embedding + +similarity. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. Overrides the value specified at initialization. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given `query_embedding` + + + +## Module haystack\_integrations.components.retrievers.mongodb\_atlas.full\_text\_retriever + + + +### MongoDBAtlasFullTextRetriever + +Retrieves documents from the MongoDBAtlasDocumentStore by full-text search. + +The full-text search is dependent on the full_text_search_index used in the MongoDBAtlasDocumentStore. +See MongoDBAtlasDocumentStore for more information. + +Usage example: +```python +from haystack_integrations.document_stores.mongodb_atlas import MongoDBAtlasDocumentStore +from haystack_integrations.components.retrievers.mongodb_atlas import MongoDBAtlasFullTextRetriever + +store = MongoDBAtlasDocumentStore(database_name="your_existing_db", + collection_name="your_existing_collection", + vector_search_index="your_existing_index", + full_text_search_index="your_existing_index") +retriever = MongoDBAtlasFullTextRetriever(document_store=store) + +results = retriever.run(query="Lorem ipsum") +print(results["documents"]) +``` + +The example above retrieves the 10 most similar documents to the query "Lorem ipsum" from the +MongoDBAtlasDocumentStore. + + + +#### MongoDBAtlasFullTextRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: MongoDBAtlasDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: An instance of MongoDBAtlasDocumentStore. +- `filters`: Filters applied to the retrieved Documents. Make sure that the fields used in the filters are +included in the configuration of the `full_text_search_index`. The configuration must be done manually +in the Web UI of MongoDB Atlas. +- `top_k`: Maximum number of Documents to return. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of MongoDBAtlasDocumentStore. + + + +#### MongoDBAtlasFullTextRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### MongoDBAtlasFullTextRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "MongoDBAtlasFullTextRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### MongoDBAtlasFullTextRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: Union[str, List[str]], + fuzzy: Optional[Dict[str, int]] = None, + match_criteria: Optional[Literal["any", "all"]] = None, + score: Optional[Dict[str, Dict]] = None, + synonyms: Optional[str] = None, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10) -> Dict[str, List[Document]] +``` + +Retrieve documents from the MongoDBAtlasDocumentStore by full-text search. + +**Arguments**: + +- `query`: The query string or a list of query strings to search for. +If the query contains multiple terms, Atlas Search evaluates each term separately for matches. +- `fuzzy`: Enables finding strings similar to the search term(s). +Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`, +and `maxExpansions`. For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `match_criteria`: Defines how terms in the query are matched. Supported options are `"any"` and `"all"`. +For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `score`: Specifies the scoring method for matching results. Supported options include `boost`, `constant`, +and `function`. For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `synonyms`: The name of the synonym mapping definition in the index. This value cannot be an empty string. +Note, `synonyms` can not be used with `fuzzy`. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. Overrides the value specified at initialization. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given `query` + + + +#### MongoDBAtlasFullTextRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query: Union[str, List[str]], + fuzzy: Optional[Dict[str, int]] = None, + match_criteria: Optional[Literal["any", "all"]] = None, + score: Optional[Dict[str, Dict]] = None, + synonyms: Optional[str] = None, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents from the MongoDBAtlasDocumentStore by full-text search. + +**Arguments**: + +- `query`: The query string or a list of query strings to search for. +If the query contains multiple terms, Atlas Search evaluates each term separately for matches. +- `fuzzy`: Enables finding strings similar to the search term(s). +Note, `fuzzy` cannot be used with `synonyms`. Configurable options include `maxEdits`, `prefixLength`, +and `maxExpansions`. For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `match_criteria`: Defines how terms in the query are matched. Supported options are `"any"` and `"all"`. +For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `score`: Specifies the scoring method for matching results. Supported options include `boost`, `constant`, +and `function`. For more details refer to MongoDB Atlas +[documentation](https://www.mongodb.com/docs/atlas/atlas-search/text/`fields`). +- `synonyms`: The name of the synonym mapping definition in the index. This value cannot be an empty string. +Note, `synonyms` can not be used with `fuzzy`. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. Overrides the value specified at initialization. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of Documents most similar to the given `query` + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/nvidia.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/nvidia.md new file mode 100644 index 0000000000..368f2afa02 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/nvidia.md @@ -0,0 +1,670 @@ +--- +title: "Nvidia" +id: integrations-nvidia +description: "Nvidia integration for Haystack" +slug: "/integrations-nvidia" +--- + + + +## Module haystack\_integrations.components.embedders.nvidia.document\_embedder + + + +### NvidiaDocumentEmbedder + +A component for embedding documents using embedding models provided by +[NVIDIA NIMs](https://ai.nvidia.com). + +Usage example: +```python +from haystack_integrations.components.embedders.nvidia import NvidiaDocumentEmbedder + +doc = Document(content="I love pizza!") + +text_embedder = NvidiaDocumentEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1") +text_embedder.warm_up() + +result = document_embedder.run([doc]) +print(result["documents"][0].embedding) +``` + + + +#### NvidiaDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: Optional[str] = None, + api_key: Optional[Secret] = Secret.from_env_var("NVIDIA_API_KEY"), + api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL), + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + truncate: Optional[Union[EmbeddingTruncateMode, str]] = None, + timeout: Optional[float] = None) +``` + +Create a NvidiaTextEmbedder component. + +**Arguments**: + +- `model`: Embedding model to use. +If no specific model along with locally hosted API URL is provided, +the system defaults to the available model found using /models API. +- `api_key`: API key for the NVIDIA NIM. +- `api_url`: Custom API URL for the NVIDIA NIM. +Format for API URL is `http://host:port` +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `batch_size`: Number of Documents to encode at once. +Cannot be greater than 50. +- `progress_bar`: Whether to show a progress bar or not. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. +- `truncate`: Specifies how inputs longer than the maximum token length should be truncated. +If None the behavior is model-dependent, see the official documentation for more information. +- `timeout`: Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable +or set to 60 by default. + + + +#### NvidiaDocumentEmbedder.default\_model + +```python +def default_model() +``` + +Set default model in local NIM mode. + + + +#### NvidiaDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### NvidiaDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### NvidiaDocumentEmbedder.available\_models + +```python +@property +def available_models() -> List[Model] +``` + +Get a list of available models that work with NvidiaDocumentEmbedder. + + + +#### NvidiaDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "NvidiaDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### NvidiaDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +def run( + documents: List[Document] +) -> Dict[str, Union[List[Document], Dict[str, Any]]] +``` + +Embed a list of Documents. + +The embedding of each Document is stored in the `embedding` field of the Document. + +**Arguments**: + +- `documents`: A list of Documents to embed. + +**Raises**: + +- `RuntimeError`: If the component was not initialized. +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary with the following keys and values: +- `documents` - List of processed Documents with embeddings. +- `meta` - Metadata on usage statistics, etc. + + + +## Module haystack\_integrations.components.embedders.nvidia.text\_embedder + + + +### NvidiaTextEmbedder + +A component for embedding strings using embedding models provided by +[NVIDIA NIMs](https://ai.nvidia.com). + +For models that differentiate between query and document inputs, +this component embeds the input string as a query. + +Usage example: +```python +from haystack_integrations.components.embedders.nvidia import NvidiaTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = NvidiaTextEmbedder(model="nvidia/nv-embedqa-e5-v5", api_url="https://integrate.api.nvidia.com/v1") +text_embedder.warm_up() + +print(text_embedder.run(text_to_embed)) +``` + + + +#### NvidiaTextEmbedder.\_\_init\_\_ + +```python +def __init__(model: Optional[str] = None, + api_key: Optional[Secret] = Secret.from_env_var("NVIDIA_API_KEY"), + api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL), + prefix: str = "", + suffix: str = "", + truncate: Optional[Union[EmbeddingTruncateMode, str]] = None, + timeout: Optional[float] = None) +``` + +Create a NvidiaTextEmbedder component. + +**Arguments**: + +- `model`: Embedding model to use. +If no specific model along with locally hosted API URL is provided, +the system defaults to the available model found using /models API. +- `api_key`: API key for the NVIDIA NIM. +- `api_url`: Custom API URL for the NVIDIA NIM. +Format for API URL is `http://host:port` +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `truncate`: Specifies how inputs longer that the maximum token length should be truncated. +If None the behavior is model-dependent, see the official documentation for more information. +- `timeout`: Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable +or set to 60 by default. + + + +#### NvidiaTextEmbedder.default\_model + +```python +def default_model() +``` + +Set default model in local NIM mode. + + + +#### NvidiaTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### NvidiaTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### NvidiaTextEmbedder.available\_models + +```python +@property +def available_models() -> List[Model] +``` + +Get a list of available models that work with NvidiaTextEmbedder. + + + +#### NvidiaTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "NvidiaTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### NvidiaTextEmbedder.run + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +def run(text: str) -> Dict[str, Union[List[float], Dict[str, Any]]] +``` + +Embed a string. + +**Arguments**: + +- `text`: The text to embed. + +**Raises**: + +- `RuntimeError`: If the component was not initialized. +- `TypeError`: If the input is not a string. + +**Returns**: + +A dictionary with the following keys and values: +- `embedding` - Embedding of the text. +- `meta` - Metadata on usage statistics, etc. + + + +## Module haystack\_integrations.components.embedders.nvidia.truncate + + + +### EmbeddingTruncateMode + +Specifies how inputs to the NVIDIA embedding components are truncated. +If START, the input will be truncated from the start. +If END, the input will be truncated from the end. +If NONE, an error will be returned (if the input is too long). + + + +#### EmbeddingTruncateMode.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "EmbeddingTruncateMode" +``` + +Create an truncate mode from a string. + +**Arguments**: + +- `string`: String to convert. + +**Returns**: + +Truncate mode. + + + +## Module haystack\_integrations.components.generators.nvidia.generator + + + +### NvidiaGenerator + +Generates text using generative models hosted with +[NVIDIA NIM](https://ai.nvidia.com) on the [NVIDIA API Catalog](https://build.nvidia.com/explore/discover). + +### Usage example + +```python +from haystack_integrations.components.generators.nvidia import NvidiaGenerator + +generator = NvidiaGenerator( + model="meta/llama3-8b-instruct", + model_arguments={ + "temperature": 0.2, + "top_p": 0.7, + "max_tokens": 1024, + }, +) +generator.warm_up() + +result = generator.run(prompt="What is the answer?") +print(result["replies"]) +print(result["meta"]) +print(result["usage"]) +``` + +You need an NVIDIA API key for this component to work. + + + +#### NvidiaGenerator.\_\_init\_\_ + +```python +def __init__(model: Optional[str] = None, + api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL), + api_key: Optional[Secret] = Secret.from_env_var("NVIDIA_API_KEY"), + model_arguments: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None) +``` + +Create a NvidiaGenerator component. + +**Arguments**: + +- `model`: Name of the model to use for text generation. +See the [NVIDIA NIMs](https://ai.nvidia.com) +for more information on the supported models. +`Note`: If no specific model along with locally hosted API URL is provided, +the system defaults to the available model found using /models API. +Check supported models at [NVIDIA NIM](https://ai.nvidia.com). +- `api_key`: API key for the NVIDIA NIM. Set it as the `NVIDIA_API_KEY` environment +variable or pass it here. +- `api_url`: Custom API URL for the NVIDIA NIM. +- `model_arguments`: Additional arguments to pass to the model provider. These arguments are +specific to a model. +Search your model in the [NVIDIA NIM](https://ai.nvidia.com) +to find the arguments it accepts. +- `timeout`: Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable +or set to 60 by default. + + + +#### NvidiaGenerator.default\_model + +```python +def default_model() +``` + +Set default model in local NIM mode. + + + +#### NvidiaGenerator.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### NvidiaGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### NvidiaGenerator.available\_models + +```python +@property +def available_models() -> List[Model] +``` + +Get a list of available models that work with ChatNVIDIA. + + + +#### NvidiaGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "NvidiaGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### NvidiaGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run(prompt: str) -> Dict[str, Union[List[str], List[Dict[str, Any]]]] +``` + +Queries the model with the provided prompt. + +**Arguments**: + +- `prompt`: Text to be sent to the generative model. + +**Returns**: + +A dictionary with the following keys: +- `replies` - Replies generated by the model. +- `meta` - Metadata for each reply. + + + +## Module haystack\_integrations.components.rankers.nvidia.ranker + + + +### NvidiaRanker + +A component for ranking documents using ranking models provided by +[NVIDIA NIMs](https://ai.nvidia.com). + +Usage example: +```python +from haystack_integrations.components.rankers.nvidia import NvidiaRanker +from haystack import Document +from haystack.utils import Secret + +ranker = NvidiaRanker( + model="nvidia/nv-rerankqa-mistral-4b-v3", + api_key=Secret.from_env_var("NVIDIA_API_KEY"), +) +ranker.warm_up() + +query = "What is the capital of Germany?" +documents = [ + Document(content="Berlin is the capital of Germany."), + Document(content="The capital of Germany is Berlin."), + Document(content="Germany's capital is Berlin."), +] + +result = ranker.run(query, documents, top_k=2) +print(result["documents"]) +``` + + + +#### NvidiaRanker.\_\_init\_\_ + +```python +def __init__(model: Optional[str] = None, + truncate: Optional[Union[RankerTruncateMode, str]] = None, + api_url: str = os.getenv("NVIDIA_API_URL", DEFAULT_API_URL), + api_key: Optional[Secret] = Secret.from_env_var("NVIDIA_API_KEY"), + top_k: int = 5, + query_prefix: str = "", + document_prefix: str = "", + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + timeout: Optional[float] = None) +``` + +Create a NvidiaRanker component. + +**Arguments**: + +- `model`: Ranking model to use. +- `truncate`: Truncation strategy to use. Can be "NONE", "END", or RankerTruncateMode. Defaults to NIM's default. +- `api_key`: API key for the NVIDIA NIM. +- `api_url`: Custom API URL for the NVIDIA NIM. +- `top_k`: Number of documents to return. +- `query_prefix`: A string to add at the beginning of the query text before ranking. +Use it to prepend the text with an instruction, as required by reranking models like `bge`. +- `document_prefix`: A string to add at the beginning of each document before ranking. You can use it to prepend the document +with an instruction, as required by embedding models like `bge`. +- `meta_fields_to_embed`: List of metadata fields to embed with the document. +- `embedding_separator`: Separator to concatenate metadata fields to the document. +- `timeout`: Timeout for request calls, if not set it is inferred from the `NVIDIA_TIMEOUT` environment variable +or set to 60 by default. + + + +#### NvidiaRanker.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize the ranker to a dictionary. + +**Returns**: + +A dictionary containing the ranker's attributes. + + + +#### NvidiaRanker.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "NvidiaRanker" +``` + +Deserialize the ranker from a dictionary. + +**Arguments**: + +- `data`: A dictionary containing the ranker's attributes. + +**Returns**: + +The deserialized ranker. + + + +#### NvidiaRanker.warm\_up + +```python +def warm_up() +``` + +Initialize the ranker. + +**Raises**: + +- `ValueError`: If the API key is required for hosted NVIDIA NIMs. + + + +#### NvidiaRanker.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + documents: List[Document], + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Rank a list of documents based on a given query. + +**Arguments**: + +- `query`: The query to rank the documents against. +- `documents`: The list of documents to rank. +- `top_k`: The number of documents to return. + +**Raises**: + +- `RuntimeError`: If the ranker has not been loaded. +- `TypeError`: If the arguments are of the wrong type. + +**Returns**: + +A dictionary containing the ranked documents. + + + +## Module haystack\_integrations.components.rankers.nvidia.truncate + + + +### RankerTruncateMode + +Specifies how inputs to the NVIDIA ranker components are truncated. +If NONE, the input will not be truncated and an error returned instead. +If END, the input will be truncated from the end. + + + +#### RankerTruncateMode.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "RankerTruncateMode" +``` + +Create an truncate mode from a string. + +**Arguments**: + +- `string`: String to convert. + +**Returns**: + +Truncate mode. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ollama.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ollama.md new file mode 100644 index 0000000000..eefffbd938 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ollama.md @@ -0,0 +1,531 @@ +--- +title: "Ollama" +id: integrations-ollama +description: "Ollama integration for Haystack" +slug: "/integrations-ollama" +--- + + + +## Module haystack\_integrations.components.generators.ollama.generator + + + +### OllamaGenerator + +Provides an interface to generate text using an LLM running on Ollama. + +Usage example: +```python +from haystack_integrations.components.generators.ollama import OllamaGenerator + +generator = OllamaGenerator(model="zephyr", + url = "http://localhost:11434", + generation_kwargs={ + "num_predict": 100, + "temperature": 0.9, + }) + +print(generator.run("Who is the best American actor?")) +``` + + + +#### OllamaGenerator.\_\_init\_\_ + +```python +def __init__(model: str = "orca-mini", + url: str = "http://localhost:11434", + generation_kwargs: Optional[Dict[str, Any]] = None, + system_prompt: Optional[str] = None, + template: Optional[str] = None, + raw: bool = False, + timeout: int = 120, + keep_alive: Optional[Union[float, str]] = None, + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None) +``` + +**Arguments**: + +- `model`: The name of the model to use. The model should be available in the running Ollama instance. +- `url`: The URL of a running Ollama instance. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, and others. See the available arguments in +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- `system_prompt`: Optional system message (overrides what is defined in the Ollama Modelfile). +- `template`: The full prompt template (overrides what is defined in the Ollama Modelfile). +- `raw`: If True, no formatting will be applied to the prompt. You may choose to use the raw parameter +if you are specifying a full templated prompt in your API request. +- `timeout`: The number of seconds before throwing a timeout error from the Ollama API. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `keep_alive`: The option that controls how long the model will stay loaded into memory following the request. +If not set, it will use the default value from the Ollama (5 minutes). +The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. + + + +#### OllamaGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OllamaGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OllamaGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OllamaGenerator.run + +```python +@component.output_types(replies=List[str], meta=List[Dict[str, Any]]) +def run( + prompt: str, + generation_kwargs: Optional[Dict[str, Any]] = None, + *, + streaming_callback: Optional[Callable[[StreamingChunk], None]] = None +) -> Dict[str, List[Any]] +``` + +Runs an Ollama Model on the given prompt. + +**Arguments**: + +- `prompt`: The prompt to generate a response for. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, and others. See the available arguments in +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- `streaming_callback`: A callback function that is called when a new token is received from the stream. + +**Returns**: + +A dictionary with the following keys: +- `replies`: The responses from the model +- `meta`: The metadata collected during the run + + + +## Module haystack\_integrations.components.generators.ollama.chat.chat\_generator + + + +### OllamaChatGenerator + +Haystack Chat Generator for models served with Ollama (https://ollama.ai). + +Supports streaming, tool calls, reasoning, and structured outputs. + +Usage example: +```python +from haystack_integrations.components.generators.ollama.chat import OllamaChatGenerator +from haystack.dataclasses import ChatMessage + +llm = OllamaChatGenerator(model="qwen3:0.6b") +result = llm.run(messages=[ChatMessage.from_user("What is the capital of France?")]) +print(result) +``` + + + +#### OllamaChatGenerator.\_\_init\_\_ + +```python +def __init__(model: str = "qwen3:0.6b", + url: str = "http://localhost:11434", + generation_kwargs: Optional[Dict[str, Any]] = None, + timeout: int = 120, + keep_alive: Optional[Union[float, str]] = None, + streaming_callback: Optional[Callable[[StreamingChunk], + None]] = None, + tools: Optional[ToolsType] = None, + response_format: Optional[Union[None, Literal["json"], + JsonSchemaValue]] = None, + think: Union[bool, Literal["low", "medium", "high"]] = False) +``` + +:param model: + +The name of the model to use. The model must already be present (pulled) in the running Ollama instance. +:param url: + The base URL of the Ollama server (default "http://localhost:11434"). +:param generation_kwargs: + Optional arguments to pass to the Ollama generation endpoint, such as temperature, + top_p, and others. See the available arguments in + [Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +:param timeout: + The number of seconds before throwing a timeout error from the Ollama API. +:param think + If True, the model will "think" before producing a response. + Only [thinking models](https://ollama.com/search?c=thinking) support this feature. + Some models like gpt-oss support different levels of thinking: "low", "medium", "high". + The intermediate "thinking" output can be found by inspecting the `reasoning` property of the returned + `ChatMessage`. +:param keep_alive: + The option that controls how long the model will stay loaded into memory following the request. + If not set, it will use the default value from the Ollama (5 minutes). + The value can be set to: + - a duration string (such as "10m" or "24h") + - a number in seconds (such as 3600) + - any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") + - '0' which will unload the model immediately after generating a response. +:param streaming_callback: + A callback function that is called when a new token is received from the stream. + The callback function accepts StreamingChunk as an argument. +:param tools: + A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. + Each tool should have a unique name. Not all models support tools. For a list of models compatible + with tools, see the [models page](https://ollama.com/search?c=tools). +:param response_format: + The format for structured model outputs. The value can be: + - None: No specific structure or format is applied to the response. The response is returned as-is. + - "json": The response is formatted as a JSON object. + - JSON Schema: The response is formatted as a JSON object + that adheres to the specified JSON Schema. (needs Ollama ≥ 0.1.34) + + + + +#### OllamaChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OllamaChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OllamaChatGenerator" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OllamaChatGenerator.run + +```python +@component.output_types(replies=List[ChatMessage]) +def run( + messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + *, + streaming_callback: Optional[StreamingCallbackT] = None +) -> Dict[str, List[ChatMessage]] +``` + +Runs an Ollama Model on a given chat history. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Per-call overrides for Ollama inference options. +These are merged on top of the instance-level `generation_kwargs`. +Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, etc. See the +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter set during component initialization. +- `streaming_callback`: A callable to receive `StreamingChunk` objects as they +arrive. Supplying a callback (here or in the constructor) switches +the component into streaming mode. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of ChatMessages containing the model's response + + + +#### OllamaChatGenerator.run\_async + +```python +@component.output_types(replies=List[ChatMessage]) +async def run_async( + messages: List[ChatMessage], + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + *, + streaming_callback: Optional[StreamingCallbackT] = None +) -> Dict[str, List[ChatMessage]] +``` + +Async version of run. Runs an Ollama Model on a given chat history. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Per-call overrides for Ollama inference options. +These are merged on top of the instance-level `generation_kwargs`. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter set during component initialization. +- `streaming_callback`: A callable to receive `StreamingChunk` objects as they arrive. +Supplying a callback switches the component into streaming mode. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of ChatMessages containing the model's response + + + +## Module haystack\_integrations.components.embedders.ollama.document\_embedder + + + +### OllamaDocumentEmbedder + +Computes the embeddings of a list of Documents and stores the obtained vectors in the embedding field of each +Document. It uses embedding models compatible with the Ollama Library. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.ollama import OllamaDocumentEmbedder + +doc = Document(content="What do llamas say once you have thanked them? No probllama!") +document_embedder = OllamaDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) +``` + + + +#### OllamaDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "nomic-embed-text", + url: str = "http://localhost:11434", + generation_kwargs: Optional[Dict[str, Any]] = None, + timeout: int = 120, + keep_alive: Optional[Union[float, str]] = None, + prefix: str = "", + suffix: str = "", + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + batch_size: int = 32) +``` + +**Arguments**: + +- `model`: The name of the model to use. The model should be available in the running Ollama instance. +- `url`: The URL of a running Ollama instance. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, top_p, and others. +See the available arguments in +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- `timeout`: The number of seconds before throwing a timeout error from the Ollama API. +- `keep_alive`: The option that controls how long the model will stay loaded into memory following the request. +If not set, it will use the default value from the Ollama (5 minutes). +The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `progress_bar`: If `True`, shows a progress bar when running. +- `meta_fields_to_embed`: List of metadata fields to embed along with the document text. +- `embedding_separator`: Separator used to concatenate the metadata fields to the document text. +- `batch_size`: Number of documents to process at once. + + + +#### OllamaDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +def run( + documents: List[Document], + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[Document], Dict[str, Any]]] +``` + +Runs an Ollama Model to compute embeddings of the provided documents. + +**Arguments**: + +- `documents`: Documents to be converted to an embedding. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, etc. See the +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embedding information attached +- `meta`: The metadata collected during the embedding process + + + +#### OllamaDocumentEmbedder.run\_async + +```python +@component.output_types(documents=List[Document], meta=Dict[str, Any]) +async def run_async( + documents: List[Document], + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[Document], Dict[str, Any]]] +``` + +Asynchronously run an Ollama Model to compute embeddings of the provided documents. + +**Arguments**: + +- `documents`: Documents to be converted to an embedding. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, etc. See the +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns**: + +A dictionary with the following keys: +- `documents`: Documents with embedding information attached +- `meta`: The metadata collected during the embedding process + + + +## Module haystack\_integrations.components.embedders.ollama.text\_embedder + + + +### OllamaTextEmbedder + +Computes the embeddings of a list of Documents and stores the obtained vectors in the embedding field of +each Document. It uses embedding models compatible with the Ollama Library. + +Usage example: +```python +from haystack_integrations.components.embedders.ollama import OllamaTextEmbedder + +embedder = OllamaTextEmbedder() +result = embedder.run(text="What do llamas say once you have thanked them? No probllama!") +print(result['embedding']) +``` + + + +#### OllamaTextEmbedder.\_\_init\_\_ + +```python +def __init__(model: str = "nomic-embed-text", + url: str = "http://localhost:11434", + generation_kwargs: Optional[Dict[str, Any]] = None, + timeout: int = 120, + keep_alive: Optional[Union[float, str]] = None) +``` + +**Arguments**: + +- `model`: The name of the model to use. The model should be available in the running Ollama instance. +- `url`: The URL of a running Ollama instance. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, and others. See the available arguments in +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). +- `timeout`: The number of seconds before throwing a timeout error from the Ollama API. +- `keep_alive`: The option that controls how long the model will stay loaded into memory following the request. +If not set, it will use the default value from the Ollama (5 minutes). +The value can be set to: +- a duration string (such as "10m" or "24h") +- a number in seconds (such as 3600) +- any negative number which will keep the model loaded in memory (e.g. -1 or "-1m") +- '0' which will unload the model immediately after generating a response. + + + +#### OllamaTextEmbedder.run + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +def run( + text: str, + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[float], Dict[str, Any]]] +``` + +Runs an Ollama Model to compute embeddings of the provided text. + +**Arguments**: + +- `text`: Text to be converted to an embedding. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, etc. See the +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The computed embeddings +- `meta`: The metadata collected during the embedding process + + + +#### OllamaTextEmbedder.run\_async + +```python +@component.output_types(embedding=List[float], meta=Dict[str, Any]) +async def run_async( + text: str, + generation_kwargs: Optional[Dict[str, Any]] = None +) -> Dict[str, Union[List[float], Dict[str, Any]]] +``` + +Asynchronously run an Ollama Model to compute embeddings of the provided text. + +**Arguments**: + +- `text`: Text to be converted to an embedding. +- `generation_kwargs`: Optional arguments to pass to the Ollama generation endpoint, such as temperature, +top_p, etc. See the +[Ollama docs](https://github.com/jmorganca/ollama/blob/main/docs/modelfile.md#valid-parameters-and-values). + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The computed embeddings +- `meta`: The metadata collected during the embedding process diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/openrouter.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/openrouter.md new file mode 100644 index 0000000000..faaf9cd30c --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/openrouter.md @@ -0,0 +1,129 @@ +--- +title: "OpenRouter" +id: integrations-openrouter +description: "OpenRouter integration for Haystack" +slug: "/integrations-openrouter" +--- + + + +## Module haystack\_integrations.components.generators.openrouter.chat.chat\_generator + + + +### OpenRouterChatGenerator + +Enables text generation using OpenRouter generative models. +For supported models, see [OpenRouter docs](https://openrouter.ai/models). + +Users can pass any text generation parameters valid for the OpenRouter chat completion API +directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +Key Features and Compatibility: +- **Primary Compatibility**: Designed to work seamlessly with the OpenRouter chat completion endpoint. +- **Streaming Support**: Supports streaming responses from the OpenRouter chat completion endpoint. +- **Customizability**: Supports all parameters supported by the OpenRouter chat completion endpoint. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) + +For more details on the parameters supported by the OpenRouter API, refer to the +[OpenRouter API Docs](https://openrouter.ai/docs/quickstart). + +Usage example: +```python +from haystack_integrations.components.generators.openrouter import OpenRouterChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = OpenRouterChatGenerator() +response = client.run(messages) +print(response) + +>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence +>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is +>>meaningful and useful.', _role=, _name=None, +>>_meta={'model': 'openai/gpt-4o-mini', 'index': 0, 'finish_reason': 'stop', +>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]} +``` + + + +#### OpenRouterChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("OPENROUTER_API_KEY"), + model: str = "openai/gpt-4o-mini", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = "https://openrouter.ai/api/v1", + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + timeout: Optional[float] = None, + extra_headers: Optional[Dict[str, Any]] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of OpenRouterChatGenerator. Unless specified otherwise, + +the default model is `openai/gpt-4o-mini`. + +**Arguments**: + +- `api_key`: The OpenRouter API key. +- `model`: The name of the OpenRouter chat completion model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The OpenRouter API Base url. +For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart). +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the OpenRouter endpoint. See [OpenRouter API docs](https://openrouter.ai/docs/quickstart) for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `response_format`: A JSON schema or a Pydantic model that enforces the structure of the model's response. + If provided, the output will always be validated against this + format (unless the model returns a tool call). + For details, see the [OpenAI Structured Outputs documentation](https://platform.openai.com/docs/guides/structured-outputs). + Notes: + - This parameter accepts Pydantic models and JSON schemas for latest models starting from GPT-4o. + - For structured outputs with streaming, + the `response_format` must be a JSON schema and not a Pydantic model. +- `tools`: A list of tools or a Toolset for which the model can prepare calls. This parameter can accept either a +list of `Tool` objects or a `Toolset` instance. +- `timeout`: The timeout for the OpenRouter API call. +- `extra_headers`: Additional HTTP headers to include in requests to the OpenRouter API. +This can be useful for adding site URL or title for rankings on openrouter.ai +For more details, see OpenRouter [docs](https://openrouter.ai/docs/quickstart). +- `max_retries`: Maximum number of retries to contact OpenAI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### OpenRouterChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/opensearch.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/opensearch.md new file mode 100644 index 0000000000..52f8a1a52b --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/opensearch.md @@ -0,0 +1,1079 @@ +--- +title: "OpenSearch" +id: integrations-opensearch +description: "OpenSearch integration for Haystack" +slug: "/integrations-opensearch" +--- + + + +## Module haystack\_integrations.components.retrievers.opensearch.bm25\_retriever + + + +### OpenSearchBM25Retriever + +Fetches documents from OpenSearchDocumentStore using the keyword-based BM25 algorithm. + +BM25 computes a weighted word overlap between the query string and a document to determine its similarity. + + + +#### OpenSearchBM25Retriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: OpenSearchDocumentStore, + filters: Optional[Dict[str, Any]] = None, + fuzziness: Union[int, str] = "AUTO", + top_k: int = 10, + scale_score: bool = False, + all_terms_must_match: bool = False, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + custom_query: Optional[Dict[str, Any]] = None, + raise_on_failure: bool = True) +``` + +Creates the OpenSearchBM25Retriever component. + +**Arguments**: + +- `document_store`: An instance of OpenSearchDocumentStore to use with the Retriever. +- `filters`: Filters to narrow down the search for documents in the Document Store. +- `fuzziness`: Determines how approximate string matching is applied in full-text queries. +This parameter sets the number of character edits (insertions, deletions, or substitutions) +required to transform one word into another. For example, the "fuzziness" between the words +"wined" and "wind" is 1 because only one edit is needed to match them. + +Use "AUTO" (the default) for automatic adjustment based on term length, which is optimal for +most scenarios. For detailed guidance, refer to the +[OpenSearch fuzzy query documentation](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/). +- `top_k`: Maximum number of documents to return. +- `scale_score`: If `True`, scales the score of retrieved documents to a range between 0 and 1. +This is useful when comparing documents across different indexes. +- `all_terms_must_match`: If `True`, all terms in the query string must be present in the +retrieved documents. This is useful when searching for short text where even one term +can make a difference. +- `filter_policy`: Policy to determine how filters are applied. Possible options: +- `replace`: Runtime filters replace initialization filters. Use this policy to change the filtering scope +for specific queries. +- `merge`: Runtime filters are merged with initialization filters. +- `custom_query`: The query containing a mandatory `$query` and an optional `$filters` placeholder. + **An example custom_query:** + + ```python + { + "query": { + "bool": { + "should": [{"multi_match": { + "query": "$query", // mandatory query placeholder + "type": "most_fields", + "fields": ["content", "title"]}}], + "filter": "$filters" // optional filter placeholder + } + } + } + ``` + +An example `run()` method for this `custom_query`: + +```python +retriever.run( + query="Why did the revenue increase?", + filters={ + "operator": "AND", + "conditions": [ + {"field": "meta.years", "operator": "==", "value": "2019"}, + {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]}, + ], + }, +) +``` +- `raise_on_failure`: Whether to raise an exception if the API call fails. Otherwise log a warning and return an empty list. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of OpenSearchDocumentStore. + + + +#### OpenSearchBM25Retriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenSearchBM25Retriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OpenSearchBM25Retriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OpenSearchBM25Retriever.run + +```python +@component.output_types(documents=List[Document]) +def run( + query: str, + filters: Optional[Dict[str, Any]] = None, + all_terms_must_match: Optional[bool] = None, + top_k: Optional[int] = None, + fuzziness: Optional[Union[int, str]] = None, + scale_score: Optional[bool] = None, + custom_query: Optional[Dict[str, Any]] = None, + document_store: Optional[OpenSearchDocumentStore] = None +) -> Dict[str, List[Document]] +``` + +Retrieve documents using BM25 retrieval. + +**Arguments**: + +- `query`: The query string. +- `filters`: Filters applied to the retrieved documents. The way runtime filters are applied depends on +the `filter_policy` specified at Retriever's initialization. +- `all_terms_must_match`: If `True`, all terms in the query string must be present in the +retrieved documents. +- `top_k`: Maximum number of documents to return. +- `fuzziness`: Fuzziness parameter for full-text queries to apply approximate string matching. +For more information, see [OpenSearch fuzzy query](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/). +- `scale_score`: If `True`, scales the score of retrieved documents to a range between 0 and 1. +This is useful when comparing documents across different indexes. +- `custom_query`: A custom OpenSearch query. It must include a `$query` and may optionally +include a `$filters` placeholder. + + **An example custom_query:** + + ```python + { + "query": { + "bool": { + "should": [{"multi_match": { + "query": "$query", // mandatory query placeholder + "type": "most_fields", + "fields": ["content", "title"]}}], + "filter": "$filters" // optional filter placeholder + } + } + } + ``` + +**For this custom_query, a sample `run()` could be:** + +```python +retriever.run( + query="Why did the revenue increase?", + filters={ + "operator": "AND", + "conditions": [ + {"field": "meta.years", "operator": "==", "value": "2019"}, + {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]}, + ], + }, +) +``` +- `document_store`: Optionally, an instance of OpenSearchDocumentStore to use with the Retriever + +**Returns**: + +A dictionary containing the retrieved documents with the following structure: +- documents: List of retrieved Documents. + + + +#### OpenSearchBM25Retriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query: str, + filters: Optional[Dict[str, Any]] = None, + all_terms_must_match: Optional[bool] = None, + top_k: Optional[int] = None, + fuzziness: Optional[Union[int, str]] = None, + scale_score: Optional[bool] = None, + custom_query: Optional[Dict[str, Any]] = None, + document_store: Optional[OpenSearchDocumentStore] = None +) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents using BM25 retrieval. + +**Arguments**: + +- `query`: The query string. +- `filters`: Filters applied to the retrieved documents. The way runtime filters are applied depends on +the `filter_policy` specified at Retriever's initialization. +- `all_terms_must_match`: If `True`, all terms in the query string must be present in the +retrieved documents. +- `top_k`: Maximum number of documents to return. +- `fuzziness`: Fuzziness parameter for full-text queries to apply approximate string matching. +For more information, see [OpenSearch fuzzy query](https://opensearch.org/docs/latest/query-dsl/term/fuzzy/). +- `scale_score`: If `True`, scales the score of retrieved documents to a range between 0 and 1. +This is useful when comparing documents across different indexes. +- `custom_query`: A custom OpenSearch query. It must include a `$query` and may optionally +include a `$filters` placeholder. +- `document_store`: Optionally, an instance of OpenSearchDocumentStore to use with the Retriever + +**Returns**: + +A dictionary containing the retrieved documents with the following structure: +- documents: List of retrieved Documents. + + + +## Module haystack\_integrations.components.retrievers.opensearch.embedding\_retriever + + + +### OpenSearchEmbeddingRetriever + +Retrieves documents from the OpenSearchDocumentStore using a vector similarity metric. + + Must be connected to the OpenSearchDocumentStore to run. + + + +#### OpenSearchEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: OpenSearchDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + custom_query: Optional[Dict[str, Any]] = None, + raise_on_failure: bool = True, + efficient_filtering: bool = False) +``` + +Create the OpenSearchEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of OpenSearchDocumentStore to use with the Retriever. +- `filters`: Filters applied when fetching documents from the Document Store. +Filters are applied during the approximate kNN search to ensure the Retriever returns +`top_k` matching documents. +- `top_k`: Maximum number of documents to return. +- `filter_policy`: Policy to determine how filters are applied. Possible options: +- `merge`: Runtime filters are merged with initialization filters. +- `replace`: Runtime filters replace initialization filters. Use this policy to change the filtering scope. +- `custom_query`: The custom OpenSearch query containing a mandatory `$query_embedding` and +an optional `$filters` placeholder. + + **An example custom_query:** + + ```python + { + "query": { + "bool": { + "must": [ + { + "knn": { + "embedding": { + "vector": "$query_embedding", // mandatory query placeholder + "k": 10000, + } + } + } + ], + "filter": "$filters" // optional filter placeholder + } + } + } + ``` + +For this `custom_query`, an example `run()` could be: + +```python +retriever.run( + query_embedding=embedding, + filters={ + "operator": "AND", + "conditions": [ + {"field": "meta.years", "operator": "==", "value": "2019"}, + {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]}, + ], + }, +) +``` +- `raise_on_failure`: If `True`, raises an exception if the API call fails. +If `False`, logs a warning and returns an empty list. +- `efficient_filtering`: If `True`, the filter will be applied during the approximate kNN search. +This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib". + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of OpenSearchDocumentStore. + + + +#### OpenSearchEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenSearchEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OpenSearchEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OpenSearchEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run( + query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + custom_query: Optional[Dict[str, Any]] = None, + efficient_filtering: Optional[bool] = None, + document_store: Optional[OpenSearchDocumentStore] = None +) -> Dict[str, List[Document]] +``` + +Retrieve documents using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied when fetching documents from the Document Store. +Filters are applied during the approximate kNN search to ensure the Retriever returns `top_k` matching +documents. +The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever. +- `top_k`: Maximum number of documents to return. +- `custom_query`: A custom OpenSearch query containing a mandatory `$query_embedding` and an +optional `$filters` placeholder. + + **An example custom_query:** + + ```python + { + "query": { + "bool": { + "must": [ + { + "knn": { + "embedding": { + "vector": "$query_embedding", // mandatory query placeholder + "k": 10000, + } + } + } + ], + "filter": "$filters" // optional filter placeholder + } + } + } + ``` + +For this `custom_query`, an example `run()` could be: + +```python +retriever.run( + query_embedding=embedding, + filters={ + "operator": "AND", + "conditions": [ + {"field": "meta.years", "operator": "==", "value": "2019"}, + {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]}, + ], + }, +) +``` +- `efficient_filtering`: If `True`, the filter will be applied during the approximate kNN search. +This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib". +- `document_store`: Optional instance of OpenSearchDocumentStore to use with the Retriever. + +**Returns**: + +Dictionary with key "documents" containing the retrieved Documents. +- documents: List of Document similar to `query_embedding`. + + + +#### OpenSearchEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + custom_query: Optional[Dict[str, Any]] = None, + efficient_filtering: Optional[bool] = None, + document_store: Optional[OpenSearchDocumentStore] = None +) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents using a vector similarity metric. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied when fetching documents from the Document Store. +Filters are applied during the approximate kNN search to ensure the Retriever + returns `top_k` matching documents. +The way runtime filters are applied depends on the `filter_policy` selected when initializing the Retriever. +- `top_k`: Maximum number of documents to return. +- `custom_query`: A custom OpenSearch query containing a mandatory `$query_embedding` and an +optional `$filters` placeholder. + + **An example custom_query:** + + ```python + { + "query": { + "bool": { + "must": [ + { + "knn": { + "embedding": { + "vector": "$query_embedding", // mandatory query placeholder + "k": 10000, + } + } + } + ], + "filter": "$filters" // optional filter placeholder + } + } + } + ``` + +For this `custom_query`, an example `run()` could be: + +```python +retriever.run( + query_embedding=embedding, + filters={ + "operator": "AND", + "conditions": [ + {"field": "meta.years", "operator": "==", "value": "2019"}, + {"field": "meta.quarters", "operator": "in", "value": ["Q1", "Q2"]}, + ], + }, +) +``` +- `efficient_filtering`: If `True`, the filter will be applied during the approximate kNN search. +This is only supported for knn engines "faiss" and "lucene" and does not work with the default "nmslib". +- `document_store`: Optional instance of OpenSearchDocumentStore to use with the Retriever. + +**Returns**: + +Dictionary with key "documents" containing the retrieved Documents. +- documents: List of Document similar to `query_embedding`. + + + +## Module haystack\_integrations.components.retrievers.opensearch.open\_search\_hybrid\_retriever + + + +### OpenSearchHybridRetriever + +A hybrid retriever that combines embedding-based and keyword-based retrieval from OpenSearch. + +Example usage: + +Make sure you have "sentence-transformers>=3.0.0": + + pip install haystack-ai datasets "sentence-transformers>=3.0.0" + + +And OpenSearch running. You can run OpenSearch with Docker: + + docker run -d --name opensearch-nosec -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" + -e "DISABLE_SECURITY_PLUGIN=true" opensearchproject/opensearch:2.12.0 + +```python +from haystack import Document +from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder +from haystack_integrations.components.retrievers.opensearch import OpenSearchHybridRetriever +from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore + +# Initialize the document store +doc_store = OpenSearchDocumentStore( + hosts=[""], + index="document_store", + embedding_dim=384, +) + +# Create some sample documents +docs = [ + Document(content="Machine learning is a subset of artificial intelligence."), + Document(content="Deep learning is a subset of machine learning."), + Document(content="Natural language processing is a field of AI."), + Document(content="Reinforcement learning is a type of machine learning."), + Document(content="Supervised learning is a type of machine learning."), +] + +# Embed the documents and add them to the document store +doc_embedder = SentenceTransformersDocumentEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") +doc_embedder.warm_up() +docs = doc_embedder.run(docs) +doc_store.write_documents(docs['documents']) + +# Initialize some haystack text embedder, in this case the SentenceTransformersTextEmbedder +embedder = SentenceTransformersTextEmbedder(model="sentence-transformers/all-MiniLM-L6-v2") + +# Initialize the hybrid retriever +retriever = OpenSearchHybridRetriever( + document_store=doc_store, + embedder=embedder, + top_k_bm25=3, + top_k_embedding=3, + join_mode="reciprocal_rank_fusion" +) + +# Run the retriever +results = retriever.run(query="What is reinforcement learning?", filters_bm25=None, filters_embedding=None) + +>> results['documents'] +{'documents': [Document(id=..., content: 'Reinforcement learning is a type of machine learning.', score: 1.0), + Document(id=..., content: 'Supervised learning is a type of machine learning.', score: 0.9760624679979518), + Document(id=..., content: 'Deep learning is a subset of machine learning.', score: 0.4919354838709677), + Document(id=..., content: 'Machine learning is a subset of artificial intelligence.', score: 0.4841269841269841)]} + ``` + + + +#### OpenSearchHybridRetriever.\_\_init\_\_ + +```python +def __init__(document_store: OpenSearchDocumentStore, + *, + embedder: TextEmbedder, + filters_bm25: Optional[Dict[str, Any]] = None, + fuzziness: Union[int, str] = "AUTO", + top_k_bm25: int = 10, + scale_score: bool = False, + all_terms_must_match: bool = False, + filter_policy_bm25: Union[str, + FilterPolicy] = FilterPolicy.REPLACE, + custom_query_bm25: Optional[Dict[str, Any]] = None, + filters_embedding: Optional[Dict[str, Any]] = None, + top_k_embedding: int = 10, + filter_policy_embedding: Union[ + str, FilterPolicy] = FilterPolicy.REPLACE, + custom_query_embedding: Optional[Dict[str, Any]] = None, + join_mode: Union[str, JoinMode] = JoinMode.RECIPROCAL_RANK_FUSION, + weights: Optional[List[float]] = None, + top_k: Optional[int] = None, + sort_by_score: bool = True, + **kwargs: Any) -> None +``` + +Initialize the OpenSearchHybridRetriever, a super component to retrieve documents from OpenSearch using + +both embedding-based and keyword-based retrieval methods. + +We don't explicitly define all the init parameters of the components in the constructor, for each +of the components, since that would be around 20+ parameters. Instead, we define the most important ones +and pass the rest as kwargs. This is to keep the constructor clean and easy to read. + +If you need to pass extra parameters to the components, you can do so by passing them as kwargs. It expects +a dictionary with the component name as the key and the parameters as the value. The component name should be: + + - "bm25_retriever" -> OpenSearchBM25Retriever + - "embedding_retriever" -> OpenSearchEmbeddingRetriever + +**Arguments**: + +- `document_store`: The OpenSearchDocumentStore to use for retrieval. +- `embedder`: A TextEmbedder to use for embedding the query. +See `haystack.components.embedders.types.protocol.TextEmbedder` for more information. +- `filters_bm25`: Filters for the BM25 retriever. +- `fuzziness`: The fuzziness for the BM25 retriever. +- `top_k_bm25`: The number of results to return from the BM25 retriever. +- `scale_score`: Whether to scale the score for the BM25 retriever. +- `all_terms_must_match`: Whether all terms must match for the BM25 retriever. +- `filter_policy_bm25`: The filter policy for the BM25 retriever. +- `custom_query_bm25`: A custom query for the BM25 retriever. +- `filters_embedding`: Filters for the embedding retriever. +- `top_k_embedding`: The number of results to return from the embedding retriever. +- `filter_policy_embedding`: The filter policy for the embedding retriever. +- `custom_query_embedding`: A custom query for the embedding retriever. +- `join_mode`: The mode to use for joining the results from the BM25 and embedding retrievers. +- `weights`: The weights for the joiner. +- `top_k`: The number of results to return from the joiner. +- `sort_by_score`: Whether to sort the results by score. +- `**kwargs`: Additional keyword arguments. Use the following keys to pass extra parameters to the retrievers: +- "bm25_retriever" -> OpenSearchBM25Retriever +- "embedding_retriever" -> OpenSearchEmbeddingRetriever + + + +#### OpenSearchHybridRetriever.to\_dict + +```python +def to_dict() +``` + +Serialize OpenSearchHybridRetriever to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +## Module haystack\_integrations.document\_stores.opensearch.document\_store + + + +### OpenSearchDocumentStore + +An instance of an OpenSearch database you can use to store all types of data. + +This document store is a thin wrapper around the OpenSearch client. +It allows you to store and retrieve documents from an OpenSearch index. + +Usage example: +```python +from haystack_integrations.document_stores.opensearch import OpenSearchDocumentStore +from haystack import Document + +document_store = OpenSearchDocumentStore(hosts="localhost:9200") + +document_store.write_documents( + [ + Document(content="My first document", id="1"), + Document(content="My second document", id="2"), + ] +) + +print(document_store.count_documents()) +# 2 + +print(document_store.filter_documents()) +# [Document(id='1', content='My first document', ...), Document(id='2', content='My second document', ...)] +``` + + + +#### OpenSearchDocumentStore.\_\_init\_\_ + +```python +def __init__( + *, + hosts: Optional[Hosts] = None, + index: str = "default", + max_chunk_bytes: int = DEFAULT_MAX_CHUNK_BYTES, + embedding_dim: int = 768, + return_embedding: bool = False, + method: Optional[Dict[str, Any]] = None, + mappings: Optional[Dict[str, Any]] = None, + settings: Optional[Dict[str, Any]] = DEFAULT_SETTINGS, + create_index: bool = True, + http_auth: Any = ( + Secret.from_env_var("OPENSEARCH_USERNAME", + strict=False), # noqa: B008 + Secret.from_env_var("OPENSEARCH_PASSWORD", + strict=False), # noqa: B008 + ), + use_ssl: Optional[bool] = None, + verify_certs: Optional[bool] = None, + timeout: Optional[int] = None, + **kwargs: Any) -> None +``` + +Creates a new OpenSearchDocumentStore instance. + +The ``embeddings_dim``, ``method``, ``mappings``, and ``settings`` arguments are only used if the index does not +exist and needs to be created. If the index already exists, its current configurations will be used. + +For more information on connection parameters, see the [official OpenSearch documentation](https://opensearch.org/docs/latest/clients/python-low-level/`connecting`-to-opensearch) + +**Arguments**: + +- `hosts`: List of hosts running the OpenSearch client. Defaults to None +- `index`: Name of index in OpenSearch, if it doesn't exist it will be created. Defaults to "default" +- `max_chunk_bytes`: Maximum size of the requests in bytes. Defaults to 100MB +- `embedding_dim`: Dimension of the embeddings. Defaults to 768 +- `return_embedding`: Whether to return the embedding of the retrieved Documents. This parameter also applies to the +`filter_documents` and `filter_documents_async` methods. +- `method`: The method definition of the underlying configuration of the approximate k-NN algorithm. Please +see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/`method`-definitions) +for more information. Defaults to None +- `mappings`: The mapping of how the documents are stored and indexed. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/field-types/) +for more information. If None, it uses the embedding_dim and method arguments to create default mappings. +Defaults to None +- `settings`: The settings of the index to be created. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/`index`-settings) +for more information. Defaults to `{"index.knn": True}`. +- `create_index`: Whether to create the index if it doesn't exist. Defaults to True +- `http_auth`: http_auth param passed to the underlying connection class. +For basic authentication with default connection class `Urllib3HttpConnection` this can be +- a tuple of (username, password) +- a list of [username, password] +- a string of "username:password" +If not provided, will read values from OPENSEARCH_USERNAME and OPENSEARCH_PASSWORD environment variables. +For AWS authentication with `Urllib3HttpConnection` pass an instance of `AWSAuth`. +Defaults to None +- `use_ssl`: Whether to use SSL. Defaults to None +- `verify_certs`: Whether to verify certificates. Defaults to None +- `timeout`: Timeout in seconds. Defaults to None +- `**kwargs`: Optional arguments that ``OpenSearch`` takes. For the full list of supported kwargs, +see the [official OpenSearch reference](https://opensearch-project.github.io/opensearch-py/api-ref/clients/opensearch_client.html) + + + +#### OpenSearchDocumentStore.create\_index + +```python +def create_index(index: Optional[str] = None, + mappings: Optional[Dict[str, Any]] = None, + settings: Optional[Dict[str, Any]] = None) -> None +``` + +Creates an index in OpenSearch. + +Note that this method ignores the `create_index` argument from the constructor. + +**Arguments**: + +- `index`: Name of the index to create. If None, the index name from the constructor is used. +- `mappings`: The mapping of how the documents are stored and indexed. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/field-types/) +for more information. If None, the mappings from the constructor are used. +- `settings`: The settings of the index to be created. Please see the [official OpenSearch docs](https://opensearch.org/docs/latest/search-plugins/knn/knn-index/`index`-settings) +for more information. If None, the settings from the constructor are used. + + + +#### OpenSearchDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OpenSearchDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OpenSearchDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### OpenSearchDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + + + +#### OpenSearchDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns the total number of documents in the document store. + + + +#### OpenSearchDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### OpenSearchDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### OpenSearchDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes documents to the document store. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Raises**: + +- `DuplicateDocumentError`: If a document with the same id already exists in the document store +and the policy is set to `DuplicatePolicy.FAIL` (or not specified). + +**Returns**: + +The number of documents written to the document store. + + + +#### OpenSearchDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Asynchronously writes documents to the document store. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Returns**: + +The number of documents written to the document store. + + + +#### OpenSearchDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### OpenSearchDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### OpenSearchDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(recreate_index: bool = False) -> None +``` + +Deletes all documents in the document store. + +**Arguments**: + +- `recreate_index`: If True, the index will be deleted and recreated with the original mappings and +settings. If False, all documents will be deleted using the `delete_by_query` API. + + + +#### OpenSearchDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async(recreate_index: bool = False) -> None +``` + +Asynchronously deletes all documents in the document store. + +**Arguments**: + +- `recreate_index`: If True, the index will be deleted and recreated with the original mappings and +settings. If False, all documents will be deleted using the `delete_by_query` API. + + + +#### OpenSearchDocumentStore.delete\_by\_filter + +```python +def delete_by_filter(filters: Dict[str, Any]) -> int +``` + +Deletes all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for deletion. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Returns**: + +The number of documents deleted. + + + +#### OpenSearchDocumentStore.delete\_by\_filter\_async + +```python +async def delete_by_filter_async(filters: Dict[str, Any]) -> int +``` + +Asynchronously deletes all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for deletion. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Returns**: + +The number of documents deleted. + + + +#### OpenSearchDocumentStore.update\_by\_filter + +```python +def update_by_filter(filters: Dict[str, Any], meta: Dict[str, Any]) -> int +``` + +Updates the metadata of all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for updating. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) +- `meta`: The metadata fields to update. + +**Returns**: + +The number of documents updated. + + + +#### OpenSearchDocumentStore.update\_by\_filter\_async + +```python +async def update_by_filter_async(filters: Dict[str, Any], + meta: Dict[str, Any]) -> int +``` + +Asynchronously updates the metadata of all documents that match the provided filters. + +**Arguments**: + +- `filters`: The filters to apply to select documents for updating. +For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering) +- `meta`: The metadata fields to update. + +**Returns**: + +The number of documents updated. + + + +## Module haystack\_integrations.document\_stores.opensearch.filters + + + +#### normalize\_filters + +```python +def normalize_filters(filters: Dict[str, Any]) -> Dict[str, Any] +``` + +Converts Haystack filters in OpenSearch compatible filters. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/optimum.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/optimum.md new file mode 100644 index 0000000000..8159e455d7 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/optimum.md @@ -0,0 +1,630 @@ +--- +title: "Optimum" +id: integrations-optimum +description: "Optimum integration for Haystack" +slug: "/integrations-optimum" +--- + + + +## Module haystack\_integrations.components.embedders.optimum.optimum\_document\_embedder + + + +### OptimumDocumentEmbedder + +A component for computing `Document` embeddings using models loaded with the +[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library, +leveraging the ONNX runtime for high-speed inference. + +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +from haystack.dataclasses import Document +from haystack_integrations.components.embedders.optimum import OptimumDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = OptimumDocumentEmbedder(model="sentence-transformers/all-mpnet-base-v2") +document_embedder.warm_up() + +result = document_embedder.run([doc]) +print(result["documents"][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### OptimumDocumentEmbedder.\_\_init\_\_ + +```python +def __init__( + model: str = "sentence-transformers/all-mpnet-base-v2", + token: Optional[Secret] = Secret.from_env_var("HF_API_TOKEN", + strict=False), + prefix: str = "", + suffix: str = "", + normalize_embeddings: bool = True, + onnx_execution_provider: str = "CPUExecutionProvider", + pooling_mode: Optional[Union[str, OptimumEmbedderPooling]] = None, + model_kwargs: Optional[Dict[str, Any]] = None, + working_dir: Optional[str] = None, + optimizer_settings: Optional[OptimumEmbedderOptimizationConfig] = None, + quantizer_settings: Optional[OptimumEmbedderQuantizationConfig] = None, + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n") +``` + +Create a OptimumDocumentEmbedder component. + +**Arguments**: + +- `model`: A string representing the model id on HF Hub. +- `token`: The HuggingFace token to use as HTTP bearer authorization. +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `normalize_embeddings`: Whether to normalize the embeddings to unit length. +- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/) +to use for ONNX models. + +Note: Using the TensorRT execution provider +TensorRT requires to build its inference engine ahead of inference, +which takes some time due to the model optimization and nodes fusion. +To avoid rebuilding the engine every time the model is loaded, ONNX +Runtime provides a pair of options to save the engine: `trt_engine_cache_enable` +and `trt_engine_cache_path`. We recommend setting these two provider +options using the `model_kwargs` parameter, when using the TensorRT execution provider. +The usage is as follows: +```python +embedder = OptimumDocumentEmbedder( + model="sentence-transformers/all-mpnet-base-v2", + onnx_execution_provider="TensorrtExecutionProvider", + model_kwargs={ + "provider_options": { + "trt_engine_cache_enable": True, + "trt_engine_cache_path": "tmp/trt_cache", + } + }, +) +``` +- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config. +- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model. +In case of duplication, these kwargs override `model`, `onnx_execution_provider` +and `token` initialization parameters. +- `working_dir`: The directory to use for storing intermediate files +generated during model optimization/quantization. Required +for optimization and quantization. +- `optimizer_settings`: Configuration for Optimum Embedder Optimization. +If `None`, no additional optimization is be applied. +- `quantizer_settings`: Configuration for Optimum Embedder Quantization. +If `None`, no quantization is be applied. +- `batch_size`: Number of Documents to encode at once. +- `progress_bar`: Whether to show a progress bar or not. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. + + + +#### OptimumDocumentEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### OptimumDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OptimumDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OptimumDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### OptimumDocumentEmbedder.run + +```python +@component.output_types(documents=List[Document]) +def run(documents: List[Document]) -> Dict[str, List[Document]] +``` + +Embed a list of Documents. + +The embedding of each Document is stored in the `embedding` field of the Document. + +**Arguments**: + +- `documents`: A list of Documents to embed. + +**Raises**: + +- `RuntimeError`: If the component was not initialized. +- `TypeError`: If the input is not a list of Documents. + +**Returns**: + +The updated Documents with their embeddings. + + + +## Module haystack\_integrations.components.embedders.optimum.optimum\_text\_embedder + + + +### OptimumTextEmbedder + +A component to embed text using models loaded with the +[HuggingFace Optimum](https://huggingface.co/docs/optimum/index) library, +leveraging the ONNX runtime for high-speed inference. + +Usage example: +```python +from haystack_integrations.components.embedders.optimum import OptimumTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = OptimumTextEmbedder(model="sentence-transformers/all-mpnet-base-v2") +text_embedder.warm_up() + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [-0.07804739475250244, 0.1498992145061493,, ...]} +``` + + + +#### OptimumTextEmbedder.\_\_init\_\_ + +```python +def __init__( + model: str = "sentence-transformers/all-mpnet-base-v2", + token: Optional[Secret] = Secret.from_env_var("HF_API_TOKEN", + strict=False), + prefix: str = "", + suffix: str = "", + normalize_embeddings: bool = True, + onnx_execution_provider: str = "CPUExecutionProvider", + pooling_mode: Optional[Union[str, OptimumEmbedderPooling]] = None, + model_kwargs: Optional[Dict[str, Any]] = None, + working_dir: Optional[str] = None, + optimizer_settings: Optional[OptimumEmbedderOptimizationConfig] = None, + quantizer_settings: Optional[OptimumEmbedderQuantizationConfig] = None +) +``` + +Create a OptimumTextEmbedder component. + +**Arguments**: + +- `model`: A string representing the model id on HF Hub. +- `token`: The HuggingFace token to use as HTTP bearer authorization. +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `normalize_embeddings`: Whether to normalize the embeddings to unit length. +- `onnx_execution_provider`: The [execution provider](https://onnxruntime.ai/docs/execution-providers/) +to use for ONNX models. + +Note: Using the TensorRT execution provider +TensorRT requires to build its inference engine ahead of inference, +which takes some time due to the model optimization and nodes fusion. +To avoid rebuilding the engine every time the model is loaded, ONNX +Runtime provides a pair of options to save the engine: `trt_engine_cache_enable` +and `trt_engine_cache_path`. We recommend setting these two provider +options using the `model_kwargs` parameter, when using the TensorRT execution provider. +The usage is as follows: +```python +embedder = OptimumDocumentEmbedder( + model="sentence-transformers/all-mpnet-base-v2", + onnx_execution_provider="TensorrtExecutionProvider", + model_kwargs={ + "provider_options": { + "trt_engine_cache_enable": True, + "trt_engine_cache_path": "tmp/trt_cache", + } + }, +) +``` +- `pooling_mode`: The pooling mode to use. When `None`, pooling mode will be inferred from the model config. +- `model_kwargs`: Dictionary containing additional keyword arguments to pass to the model. +In case of duplication, these kwargs override `model`, `onnx_execution_provider` +and `token` initialization parameters. +- `working_dir`: The directory to use for storing intermediate files +generated during model optimization/quantization. Required +for optimization and quantization. +- `optimizer_settings`: Configuration for Optimum Embedder Optimization. +If `None`, no additional optimization is be applied. +- `quantizer_settings`: Configuration for Optimum Embedder Quantization. +If `None`, no quantization is be applied. + + + +#### OptimumTextEmbedder.warm\_up + +```python +def warm_up() +``` + +Initializes the component. + + + +#### OptimumTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OptimumTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "OptimumTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### OptimumTextEmbedder.run + +```python +@component.output_types(embedding=List[float]) +def run(text: str) -> Dict[str, List[float]] +``` + +Embed a string. + +**Arguments**: + +- `text`: The text to embed. + +**Raises**: + +- `RuntimeError`: If the component was not initialized. +- `TypeError`: If the input is not a string. + +**Returns**: + +The embeddings of the text. + + + +## Module haystack\_integrations.components.embedders.optimum.pooling + + + +### OptimumEmbedderPooling + +Pooling modes support by the Optimum Embedders. + + + +#### CLS + +Perform CLS Pooling on the output of the embedding model +using the first token (CLS token). + + + +#### MEAN + +Perform Mean Pooling on the output of the embedding model. + + + +#### MAX + +Perform Max Pooling on the output of the embedding model +using the maximum value in each dimension over all the tokens. + + + +#### MEAN\_SQRT\_LEN + +Perform mean-pooling on the output of the embedding model but +divide by the square root of the sequence length. + + + +#### WEIGHTED\_MEAN + +Perform weighted (position) mean pooling on the output of the +embedding model. + + + +#### LAST\_TOKEN + +Perform Last Token Pooling on the output of the embedding model. + + + +#### OptimumEmbedderPooling.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "OptimumEmbedderPooling" +``` + +Create a pooling mode from a string. + +**Arguments**: + +- `string`: String to convert. + +**Returns**: + +Pooling mode. + + + +## Module haystack\_integrations.components.embedders.optimum.optimization + + + +### OptimumEmbedderOptimizationMode + +[ONXX Optimization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/optimization) +support by the Optimum Embedders. + + + +#### O1 + +Basic general optimizations. + + + +#### O2 + +Basic and extended general optimizations, transformers-specific fusions. + + + +#### O3 + +Same as O2 with Gelu approximation. + + + +#### O4 + +Same as O3 with mixed precision. + + + +#### OptimumEmbedderOptimizationMode.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "OptimumEmbedderOptimizationMode" +``` + +Create an optimization mode from a string. + +**Arguments**: + +- `string`: String to convert. + +**Returns**: + +Optimization mode. + + + +### OptimumEmbedderOptimizationConfig + +Configuration for Optimum Embedder Optimization. + +**Arguments**: + +- `mode`: Optimization mode. +- `for_gpu`: Whether to optimize for GPUs. + + + +#### OptimumEmbedderOptimizationConfig.to\_optimum\_config + +```python +def to_optimum_config() -> OptimizationConfig +``` + +Convert the configuration to a Optimum configuration. + +**Returns**: + +Optimum configuration. + + + +#### OptimumEmbedderOptimizationConfig.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Convert the configuration to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OptimumEmbedderOptimizationConfig.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, + Any]) -> "OptimumEmbedderOptimizationConfig" +``` + +Create an optimization configuration from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Optimization configuration. + + + +## Module haystack\_integrations.components.embedders.optimum.quantization + + + +### OptimumEmbedderQuantizationMode + +[Dynamic Quantization modes](https://huggingface.co/docs/optimum/onnxruntime/usage_guides/quantization) +support by the Optimum Embedders. + + + +#### ARM64 + +Quantization for the ARM64 architecture. + + + +#### AVX2 + +Quantization with AVX-2 instructions. + + + +#### AVX512 + +Quantization with AVX-512 instructions. + + + +#### AVX512\_VNNI + +Quantization with AVX-512 and VNNI instructions. + + + +#### OptimumEmbedderQuantizationMode.from\_str + +```python +@classmethod +def from_str(cls, string: str) -> "OptimumEmbedderQuantizationMode" +``` + +Create an quantization mode from a string. + +**Arguments**: + +- `string`: String to convert. + +**Returns**: + +Quantization mode. + + + +### OptimumEmbedderQuantizationConfig + +Configuration for Optimum Embedder Quantization. + +**Arguments**: + +- `mode`: Quantization mode. +- `per_channel`: Whether to apply per-channel quantization. + + + +#### OptimumEmbedderQuantizationConfig.to\_optimum\_config + +```python +def to_optimum_config() -> QuantizationConfig +``` + +Convert the configuration to a Optimum configuration. + +**Returns**: + +Optimum configuration. + + + +#### OptimumEmbedderQuantizationConfig.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Convert the configuration to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### OptimumEmbedderQuantizationConfig.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, + Any]) -> "OptimumEmbedderQuantizationConfig" +``` + +Create a configuration from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Quantization configuration. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pgvector.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pgvector.md new file mode 100644 index 0000000000..60120aa95b --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pgvector.md @@ -0,0 +1,666 @@ +--- +title: "Pgvector" +id: integrations-pgvector +description: "Pgvector integration for Haystack" +slug: "/integrations-pgvector" +--- + + + +## Module haystack\_integrations.components.retrievers.pgvector.embedding\_retriever + + + +### PgvectorEmbeddingRetriever + +Retrieves documents from the `PgvectorDocumentStore`, based on their dense embeddings. + +Example usage: +```python +from haystack.document_stores import DuplicatePolicy +from haystack import Document, Pipeline +from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder + +from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore +from haystack_integrations.components.retrievers.pgvector import PgvectorEmbeddingRetriever + +# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database. +# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME" + +document_store = PgvectorDocumentStore( + embedding_dimension=768, + vector_function="cosine_similarity", + recreate_table=True, +) + +documents = [Document(content="There are over 7,000 languages spoken around the world today."), + Document(content="Elephants have been observed to behave in a way that indicates..."), + Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")] + +document_embedder = SentenceTransformersDocumentEmbedder() +document_embedder.warm_up() +documents_with_embeddings = document_embedder.run(documents) + +document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE) + +query_pipeline = Pipeline() +query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder()) +query_pipeline.add_component("retriever", PgvectorEmbeddingRetriever(document_store=document_store)) +query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding") + +query = "How many languages are there?" + +res = query_pipeline.run({"text_embedder": {"text": query}}) + +assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today." +``` + + + +#### PgvectorEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: PgvectorDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + vector_function: Optional[Literal["cosine_similarity", + "inner_product", + "l2_distance"]] = None, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: An instance of `PgvectorDocumentStore`. +- `filters`: Filters applied to the retrieved Documents. +- `top_k`: Maximum number of Documents to return. +- `vector_function`: The similarity function to use when searching for similar embeddings. +Defaults to the one set in the `document_store` instance. +`"cosine_similarity"` and `"inner_product"` are similarity functions and +higher scores indicate greater similarity between the documents. +`"l2_distance"` returns the straight-line distance between vectors, +and the most similar documents are the ones with the smallest score. +**Important**: if the document store is using the `"hnsw"` search strategy, the vector function +should match the one utilized during index creation to take advantage of the index. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `PgvectorDocumentStore` or if `vector_function` +is not one of the valid options. + + + +#### PgvectorEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PgvectorEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "PgvectorEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### PgvectorEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run( + query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + vector_function: Optional[Literal["cosine_similarity", "inner_product", + "l2_distance"]] = None +) -> Dict[str, List[Document]] +``` + +Retrieve documents from the `PgvectorDocumentStore`, based on their embeddings. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. +- `vector_function`: The similarity function to use when searching for similar embeddings. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that are similar to `query_embedding`. + + + +#### PgvectorEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + vector_function: Optional[Literal["cosine_similarity", "inner_product", + "l2_distance"]] = None +) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on their embeddings. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. +- `vector_function`: The similarity function to use when searching for similar embeddings. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that are similar to `query_embedding`. + + + +## Module haystack\_integrations.components.retrievers.pgvector.keyword\_retriever + + + +### PgvectorKeywordRetriever + +Retrieve documents from the `PgvectorDocumentStore`, based on keywords. + +To rank the documents, the `ts_rank_cd` function of PostgreSQL is used. +It considers how often the query terms appear in the document, how close together the terms are in the document, +and how important is the part of the document where they occur. +For more details, see +[Postgres documentation](https://www.postgresql.org/docs/current/textsearch-controls.html#TEXTSEARCH-RANKING). + +Usage example: +```python +from haystack.document_stores import DuplicatePolicy +from haystack import Document + +from haystack_integrations.document_stores.pgvector import PgvectorDocumentStore +from haystack_integrations.components.retrievers.pgvector import PgvectorKeywordRetriever + +# Set an environment variable `PG_CONN_STR` with the connection string to your PostgreSQL database. +# e.g., "postgresql://USER:PASSWORD@HOST:PORT/DB_NAME" + +document_store = PgvectorDocumentStore(language="english", recreate_table=True) + +documents = [Document(content="There are over 7,000 languages spoken around the world today."), + Document(content="Elephants have been observed to behave in a way that indicates..."), + Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")] + +document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE) + +retriever = PgvectorKeywordRetriever(document_store=document_store) + +result = retriever.run(query="languages") + +assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today." + + + +#### PgvectorKeywordRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: PgvectorDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: An instance of `PgvectorDocumentStore`. +- `filters`: Filters applied to the retrieved Documents. +- `top_k`: Maximum number of Documents to return. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `PgvectorDocumentStore`. + + + +#### PgvectorKeywordRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PgvectorKeywordRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "PgvectorKeywordRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### PgvectorKeywordRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents from the `PgvectorDocumentStore`, based on keywords. + +**Arguments**: + +- `query`: String to search in `Document`s' content. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that match the query. + + + +#### PgvectorKeywordRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents from the `PgvectorDocumentStore`, based on keywords. + +**Arguments**: + +- `query`: String to search in `Document`s' content. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of Documents to return. + +**Returns**: + +A dictionary with the following keys: +- `documents`: List of `Document`s that match the query. + + + +## Module haystack\_integrations.document\_stores.pgvector.document\_store + + + +### PgvectorDocumentStore + +A Document Store using PostgreSQL with the [pgvector extension](https://github.com/pgvector/pgvector) installed. + + + +#### PgvectorDocumentStore.\_\_init\_\_ + +```python +def __init__(*, + connection_string: Secret = Secret.from_env_var("PG_CONN_STR"), + create_extension: bool = True, + schema_name: str = "public", + table_name: str = "haystack_documents", + language: str = "english", + embedding_dimension: int = 768, + vector_type: Literal["vector", "halfvec"] = "vector", + vector_function: Literal["cosine_similarity", "inner_product", + "l2_distance"] = "cosine_similarity", + recreate_table: bool = False, + search_strategy: Literal["exact_nearest_neighbor", + "hnsw"] = "exact_nearest_neighbor", + hnsw_recreate_index_if_exists: bool = False, + hnsw_index_creation_kwargs: Optional[Dict[str, int]] = None, + hnsw_index_name: str = "haystack_hnsw_index", + hnsw_ef_search: Optional[int] = None, + keyword_index_name: str = "haystack_keyword_index") +``` + +Creates a new PgvectorDocumentStore instance. + +It is meant to be connected to a PostgreSQL database with the pgvector extension installed. +A specific table to store Haystack documents will be created if it doesn't exist yet. + +**Arguments**: + +- `connection_string`: The connection string to use to connect to the PostgreSQL database, defined as an +environment variable. It can be provided in either URI format +e.g.: `PG_CONN_STR="postgresql://USER:PASSWORD@HOST:PORT/DB_NAME"`, or keyword/value format +e.g.: `PG_CONN_STR="host=HOST port=PORT dbname=DBNAME user=USER password=PASSWORD"` +See [PostgreSQL Documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) +for more details. +- `create_extension`: Whether to create the pgvector extension if it doesn't exist. +Set this to `True` (default) to automatically create the extension if it is missing. +Creating the extension may require superuser privileges. +If set to `False`, ensure the extension is already installed; otherwise, an error will be raised. +- `schema_name`: The name of the schema the table is created in. The schema must already exist. +- `table_name`: The name of the table to use to store Haystack documents. +- `language`: The language to be used to parse query and document content in keyword retrieval. +To see the list of available languages, you can run the following SQL query in your PostgreSQL database: +`SELECT cfgname FROM pg_ts_config;`. +More information can be found in this [StackOverflow answer](https://stackoverflow.com/a/39752553). +- `embedding_dimension`: The dimension of the embedding. +- `vector_type`: The type of vector used for embedding storage. +"vector" is the default. +"halfvec" stores embeddings in half-precision, which is particularly useful for high-dimensional embeddings +(dimension greater than 2,000 and up to 4,000). Requires pgvector versions 0.7.0 or later. For more +information, see the [pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file). +- `vector_function`: The similarity function to use when searching for similar embeddings. +`"cosine_similarity"` and `"inner_product"` are similarity functions and +higher scores indicate greater similarity between the documents. +`"l2_distance"` returns the straight-line distance between vectors, +and the most similar documents are the ones with the smallest score. +**Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the +`vector_function` passed here. Make sure subsequent queries will keep using the same +vector similarity function in order to take advantage of the index. +- `recreate_table`: Whether to recreate the table if it already exists. +- `search_strategy`: The search strategy to use when searching for similar embeddings. +`"exact_nearest_neighbor"` provides perfect recall but can be slow for large numbers of documents. +`"hnsw"` is an approximate nearest neighbor search strategy, +which trades off some accuracy for speed; it is recommended for large numbers of documents. +**Important**: when using the `"hnsw"` search strategy, an index will be created that depends on the +`vector_function` passed here. Make sure subsequent queries will keep using the same +vector similarity function in order to take advantage of the index. +- `hnsw_recreate_index_if_exists`: Whether to recreate the HNSW index if it already exists. +Only used if search_strategy is set to `"hnsw"`. +- `hnsw_index_creation_kwargs`: Additional keyword arguments to pass to the HNSW index creation. +Only used if search_strategy is set to `"hnsw"`. You can find the list of valid arguments in the +[pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw) +- `hnsw_index_name`: Index name for the HNSW index. +- `hnsw_ef_search`: The `ef_search` parameter to use at query time. Only used if search_strategy is set to +`"hnsw"`. You can find more information about this parameter in the +[pgvector documentation](https://github.com/pgvector/pgvector?tab=readme-ov-file#hnsw). +- `keyword_index_name`: Index name for the Keyword index. + + + +#### PgvectorDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PgvectorDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "PgvectorDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### PgvectorDocumentStore.delete\_table + +```python +def delete_table() +``` + +Deletes the table used to store Haystack documents. +The name of the schema (`schema_name`) and the name of the table (`table_name`) +are defined when initializing the `PgvectorDocumentStore`. + + + +#### PgvectorDocumentStore.delete\_table\_async + +```python +async def delete_table_async() +``` + +Async method to delete the table used to store Haystack documents. + + + +#### PgvectorDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + +**Returns**: + +Number of documents in the document store. + + + +#### PgvectorDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Returns how many documents are present in the document store. + +**Returns**: + +Number of documents in the document store. + + + +#### PgvectorDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Raises**: + +- `TypeError`: If `filters` is not a dictionary. +- `ValueError`: If `filters` syntax is invalid. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### PgvectorDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Raises**: + +- `TypeError`: If `filters` is not a dictionary. +- `ValueError`: If `filters` syntax is invalid. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### PgvectorDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes documents to the document store. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Raises**: + +- `ValueError`: If `documents` contains objects that are not of type `Document`. +- `DuplicateDocumentError`: If a document with the same id already exists in the document store +and the policy is set to `DuplicatePolicy.FAIL` (or not specified). +- `DocumentStoreError`: If the write operation fails for any other reason. + +**Returns**: + +The number of documents written to the document store. + + + +#### PgvectorDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Asynchronously writes documents to the document store. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. + +**Raises**: + +- `ValueError`: If `documents` contains objects that are not of type `Document`. +- `DuplicateDocumentError`: If a document with the same id already exists in the document store +and the policy is set to `DuplicatePolicy.FAIL` (or not specified). +- `DocumentStoreError`: If the write operation fails for any other reason. + +**Returns**: + +The number of documents written to the document store. + + + +#### PgvectorDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### PgvectorDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### PgvectorDocumentStore.delete\_all\_documents + +```python +def delete_all_documents() -> None +``` + +Deletes all documents in the document store. + + + +#### PgvectorDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async() -> None +``` + +Asynchronously deletes all documents in the document store. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pinecone.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pinecone.md new file mode 100644 index 0000000000..040d7279bf --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/pinecone.md @@ -0,0 +1,414 @@ +--- +title: "Pinecone" +id: integrations-pinecone +description: "Pinecone integration for Haystack" +slug: "/integrations-pinecone" +--- + + + +## Module haystack\_integrations.components.retrievers.pinecone.embedding\_retriever + + + +### PineconeEmbeddingRetriever + +Retrieves documents from the `PineconeDocumentStore`, based on their dense embeddings. + +Usage example: +```python +import os +from haystack.document_stores.types import DuplicatePolicy +from haystack import Document +from haystack import Pipeline +from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder +from haystack_integrations.components.retrievers.pinecone import PineconeEmbeddingRetriever +from haystack_integrations.document_stores.pinecone import PineconeDocumentStore + +os.environ["PINECONE_API_KEY"] = "YOUR_PINECONE_API_KEY" +document_store = PineconeDocumentStore(index="my_index", namespace="my_namespace", dimension=768) + +documents = [Document(content="There are over 7,000 languages spoken around the world today."), + Document(content="Elephants have been observed to behave in a way that indicates..."), + Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")] + +document_embedder = SentenceTransformersDocumentEmbedder() +document_embedder.warm_up() +documents_with_embeddings = document_embedder.run(documents) + +document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE) + +query_pipeline = Pipeline() +query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder()) +query_pipeline.add_component("retriever", PineconeEmbeddingRetriever(document_store=document_store)) +query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding") + +query = "How many languages are there?" + +res = query_pipeline.run({"text_embedder": {"text": query}}) +assert res['retriever']['documents'][0].content == "There are over 7,000 languages spoken around the world today." +``` + + + +#### PineconeEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: PineconeDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +**Arguments**: + +- `document_store`: The Pinecone Document Store. +- `filters`: Filters applied to the retrieved Documents. +- `top_k`: Maximum number of Documents to return. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `PineconeDocumentStore`. + + + +#### PineconeEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PineconeEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "PineconeEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### PineconeEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of `Document`s to return. + +**Returns**: + +List of Document similar to `query_embedding`. + + + +#### PineconeEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously retrieve documents from the `PineconeDocumentStore`, based on their dense embeddings. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: Maximum number of `Document`s to return. + +**Returns**: + +List of Document similar to `query_embedding`. + + + +## Module haystack\_integrations.document\_stores.pinecone.document\_store + + + +#### METADATA\_SUPPORTED\_TYPES + +List[str] is supported and checked separately + + + +### PineconeDocumentStore + +A Document Store using [Pinecone vector database](https://www.pinecone.io/). + + + +#### PineconeDocumentStore.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("PINECONE_API_KEY"), + index: str = "default", + namespace: str = "default", + batch_size: int = 100, + dimension: int = 768, + spec: Optional[Dict[str, Any]] = None, + metric: Literal["cosine", "euclidean", "dotproduct"] = "cosine") +``` + +Creates a new PineconeDocumentStore instance. + +It is meant to be connected to a Pinecone index and namespace. + +**Arguments**: + +- `api_key`: The Pinecone API key. +- `index`: The Pinecone index to connect to. If the index does not exist, it will be created. +- `namespace`: The Pinecone namespace to connect to. If the namespace does not exist, it will be created +at the first write. +- `batch_size`: The number of documents to write in a single batch. When setting this parameter, +consider [documented Pinecone limits](https://docs.pinecone.io/reference/quotas-and-limits). +- `dimension`: The dimension of the embeddings. This parameter is only used when creating a new index. +- `spec`: The Pinecone spec to use when creating a new index. Allows choosing between serverless and pod +deployment options and setting additional parameters. Refer to the +[Pinecone documentation](https://docs.pinecone.io/reference/api/control-plane/create_index) for more +details. +If not provided, a default spec with serverless deployment in the `us-east-1` region will be used +(compatible with the free tier). +- `metric`: The metric to use for similarity search. This parameter is only used when creating a new index. + + + +#### PineconeDocumentStore.close + +```python +def close() +``` + +Close the associated synchronous resources. + + + +#### PineconeDocumentStore.close\_async + +```python +async def close_async() +``` + +Close the associated asynchronous resources. To be invoked manually when the Document Store is no longer needed. + + + +#### PineconeDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "PineconeDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### PineconeDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### PineconeDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns how many documents are present in the document store. + + + +#### PineconeDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns how many documents are present in the document store. + + + +#### PineconeDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes Documents to Pinecone. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. +PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`. + +**Returns**: + +The number of documents written to the document store. + + + +#### PineconeDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Asynchronously writes Documents to Pinecone. + +**Arguments**: + +- `documents`: A list of Documents to write to the document store. +- `policy`: The duplicate policy to use when writing documents. +PineconeDocumentStore only supports `DuplicatePolicy.OVERWRITE`. + +**Returns**: + +The number of documents written to the document store. + + + +#### PineconeDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, +refer to the [documentation](https://docs.haystack.deepset.ai/v2.0/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### PineconeDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Asynchronously returns the documents that match the filters provided. + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### PineconeDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### PineconeDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### PineconeDocumentStore.delete\_all\_documents + +```python +def delete_all_documents() -> None +``` + +Deletes all documents in the document store. + + + +#### PineconeDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async() -> None +``` + +Asynchronously deletes all documents in the document store. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/qdrant.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/qdrant.md new file mode 100644 index 0000000000..1febb647cb --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/qdrant.md @@ -0,0 +1,1071 @@ +--- +title: "Qdrant" +id: integrations-qdrant +description: "Qdrant integration for Haystack" +slug: "/integrations-qdrant" +--- + + + +## Module haystack\_integrations.components.retrievers.qdrant.retriever + + + +### QdrantEmbeddingRetriever + +A component for retrieving documents from an QdrantDocumentStore using dense vectors. + +Usage example: +```python +from haystack.dataclasses import Document +from haystack_integrations.components.retrievers.qdrant import QdrantEmbeddingRetriever +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore + +document_store = QdrantDocumentStore( + ":memory:", + recreate_index=True, + return_embedding=True, +) + +document_store.write_documents([Document(content="test", embedding=[0.5]*768)]) + +retriever = QdrantEmbeddingRetriever(document_store=document_store) + +# using a fake vector to keep the example simple +retriever.run(query_embedding=[0.1]*768) +``` + + + +#### QdrantEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: QdrantDocumentStore, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: int = 10, + scale_score: bool = False, + return_embedding: bool = False, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> None +``` + +Create a QdrantEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of QdrantDocumentStore. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `filter_policy`: Policy to determine how filters are applied. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the `similarity` function specified in the Document Store. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `QdrantDocumentStore`. + + + +#### QdrantEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### QdrantEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "QdrantEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### QdrantEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Run the Embedding Retriever on the given input data. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +#### QdrantEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query_embedding: List[float], + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously run the Embedding Retriever on the given input data. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +### QdrantSparseEmbeddingRetriever + +A component for retrieving documents from an QdrantDocumentStore using sparse vectors. + +Usage example: +```python +from haystack_integrations.components.retrievers.qdrant import QdrantSparseEmbeddingRetriever +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore +from haystack.dataclasses import Document, SparseEmbedding + +document_store = QdrantDocumentStore( + ":memory:", + use_sparse_embeddings=True, + recreate_index=True, + return_embedding=True, +) + +doc = Document(content="test", sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12])) +document_store.write_documents([doc]) + +retriever = QdrantSparseEmbeddingRetriever(document_store=document_store) +sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33]) +retriever.run(query_sparse_embedding=sparse_embedding) +``` + + + +#### QdrantSparseEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(document_store: QdrantDocumentStore, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: int = 10, + scale_score: bool = False, + return_embedding: bool = False, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> None +``` + +Create a QdrantSparseEmbeddingRetriever component. + +**Arguments**: + +- `document_store`: An instance of QdrantDocumentStore. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the sparse embedding of the retrieved Documents. +- `filter_policy`: Policy to determine how filters are applied. Defaults to "replace". +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If `document_store` is not an instance of `QdrantDocumentStore`. + + + +#### QdrantSparseEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### QdrantSparseEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "QdrantSparseEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### QdrantSparseEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_sparse_embedding: SparseEmbedding, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Run the Sparse Embedding Retriever on the given input data. + +**Arguments**: + +- `query_sparse_embedding`: Sparse Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +#### QdrantSparseEmbeddingRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query_sparse_embedding: SparseEmbedding, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + scale_score: Optional[bool] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously run the Sparse Embedding Retriever on the given input data. + +**Arguments**: + +- `query_sparse_embedding`: Sparse Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `scale_score`: Whether to scale the scores of the retrieved documents or not. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +### QdrantHybridRetriever + +A component for retrieving documents from an QdrantDocumentStore using both dense and sparse vectors +and fusing the results using Reciprocal Rank Fusion. + +Usage example: +```python +from haystack_integrations.components.retrievers.qdrant import QdrantHybridRetriever +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore +from haystack.dataclasses import Document, SparseEmbedding + +document_store = QdrantDocumentStore( + ":memory:", + use_sparse_embeddings=True, + recreate_index=True, + return_embedding=True, + wait_result_from_api=True, +) + +doc = Document(content="test", + embedding=[0.5]*768, + sparse_embedding=SparseEmbedding(indices=[0, 3, 5], values=[0.1, 0.5, 0.12])) + +document_store.write_documents([doc]) + +retriever = QdrantHybridRetriever(document_store=document_store) +embedding = [0.1]*768 +sparse_embedding = SparseEmbedding(indices=[0, 1, 2, 3], values=[0.1, 0.8, 0.05, 0.33]) +retriever.run(query_embedding=embedding, query_sparse_embedding=sparse_embedding) +``` + + + +#### QdrantHybridRetriever.\_\_init\_\_ + +```python +def __init__(document_store: QdrantDocumentStore, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: int = 10, + return_embedding: bool = False, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> None +``` + +Create a QdrantHybridRetriever component. + +**Arguments**: + +- `document_store`: An instance of QdrantDocumentStore. +- `filters`: A dictionary with filters to narrow down the search space. +- `top_k`: The maximum number of documents to retrieve. If using `group_by` parameters, maximum number of +groups to return. +- `return_embedding`: Whether to return the embeddings of the retrieved Documents. +- `filter_policy`: Policy to determine how filters are applied. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'document_store' is not an instance of QdrantDocumentStore. + + + +#### QdrantHybridRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### QdrantHybridRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "QdrantHybridRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### QdrantHybridRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + query_sparse_embedding: SparseEmbedding, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Run the Sparse Embedding Retriever on the given input data. + +**Arguments**: + +- `query_embedding`: Dense embedding of the query. +- `query_sparse_embedding`: Sparse embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +#### QdrantHybridRetriever.run\_async + +```python +@component.output_types(documents=List[Document]) +async def run_async( + query_embedding: List[float], + query_sparse_embedding: SparseEmbedding, + filters: Optional[Union[Dict[str, Any], models.Filter]] = None, + top_k: Optional[int] = None, + return_embedding: Optional[bool] = None, + score_threshold: Optional[float] = None, + group_by: Optional[str] = None, + group_size: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Asynchronously run the Sparse Embedding Retriever on the given input data. + +**Arguments**: + +- `query_embedding`: Dense embedding of the query. +- `query_sparse_embedding`: Sparse embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. If using `group_by` parameters, maximum number of +groups to return. +- `return_embedding`: Whether to return the embedding of the retrieved Documents. +- `score_threshold`: A minimal score threshold for the result. +Score of the returned result might be higher or smaller than the threshold + depending on the Distance function used. +E.g. for cosine similarity only higher scores will be returned. +- `group_by`: Payload field to group by, must be a string or number field. If the field contains more than 1 +value, all values will be used for grouping. One point can be in multiple groups. +- `group_size`: Maximum amount of points to return per group. Default is 3. + +**Raises**: + +- `ValueError`: If 'filter_policy' is set to 'MERGE' and 'filters' is a native Qdrant filter. + +**Returns**: + +The retrieved documents. + + + +## Module haystack\_integrations.document\_stores.qdrant.document\_store + + + +#### get\_batches\_from\_generator + +```python +def get_batches_from_generator(iterable: List, n: int) -> Generator +``` + +Batch elements of an iterable into fixed-length chunks or blocks. + + + +### QdrantDocumentStore + +A QdrantDocumentStore implementation that you can use with any Qdrant instance: in-memory, disk-persisted, +Docker-based, and Qdrant Cloud Cluster deployments. + +Usage example by creating an in-memory instance: + +```python +from haystack.dataclasses.document import Document +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore + +document_store = QdrantDocumentStore( + ":memory:", + recreate_index=True, + embedding_dim=5 +) +document_store.write_documents([ + Document(content="This is first", embedding=[0.0]*5), + Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5]) +]) +``` + +Usage example with Qdrant Cloud: + +```python +from haystack.dataclasses.document import Document +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore + +document_store = QdrantDocumentStore( + url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333", + api_key="", +) +document_store.write_documents([ + Document(content="This is first", embedding=[0.0]*5), + Document(content="This is second", embedding=[0.1, 0.2, 0.3, 0.4, 0.5]) +]) +``` + + + +#### QdrantDocumentStore.\_\_init\_\_ + +```python +def __init__(location: Optional[str] = None, + url: Optional[str] = None, + port: int = 6333, + grpc_port: int = 6334, + prefer_grpc: bool = False, + https: Optional[bool] = None, + api_key: Optional[Secret] = None, + prefix: Optional[str] = None, + timeout: Optional[int] = None, + host: Optional[str] = None, + path: Optional[str] = None, + force_disable_check_same_thread: bool = False, + index: str = "Document", + embedding_dim: int = 768, + on_disk: bool = False, + use_sparse_embeddings: bool = False, + sparse_idf: bool = False, + similarity: str = "cosine", + return_embedding: bool = False, + progress_bar: bool = True, + recreate_index: bool = False, + shard_number: Optional[int] = None, + replication_factor: Optional[int] = None, + write_consistency_factor: Optional[int] = None, + on_disk_payload: Optional[bool] = None, + hnsw_config: Optional[dict] = None, + optimizers_config: Optional[dict] = None, + wal_config: Optional[dict] = None, + quantization_config: Optional[dict] = None, + init_from: Optional[dict] = None, + wait_result_from_api: bool = True, + metadata: Optional[dict] = None, + write_batch_size: int = 100, + scroll_size: int = 10_000, + payload_fields_to_index: Optional[List[dict]] = None) -> None +``` + +Initializes a QdrantDocumentStore. + +**Arguments**: + +- `location`: If `":memory:"` - use in-memory Qdrant instance. +If `str` - use it as a URL parameter. +If `None` - use default values for host and port. +- `url`: Either host or str of `Optional[scheme], host, Optional[port], Optional[prefix]`. +- `port`: Port of the REST API interface. +- `grpc_port`: Port of the gRPC interface. +- `prefer_grpc`: If `True` - use gRPC interface whenever possible in custom methods. +- `https`: If `True` - use HTTPS(SSL) protocol. +- `api_key`: API key for authentication in Qdrant Cloud. +- `prefix`: If not `None` - add prefix to the REST URL path. +Example: service/v1 will result in http://localhost:6333/service/v1/{qdrant-endpoint} +for REST API. +- `timeout`: Timeout for REST and gRPC API requests. +- `host`: Host name of Qdrant service. If ùrl` and `host` are `None`, set to `localhost`. +- `path`: Persistence path for QdrantLocal. +- `force_disable_check_same_thread`: For QdrantLocal, force disable check_same_thread. +Only use this if you can guarantee that you can resolve the thread safety outside QdrantClient. +- `index`: Name of the index. +- `embedding_dim`: Dimension of the embeddings. +- `on_disk`: Whether to store the collection on disk. +- `use_sparse_embeddings`: If set to `True`, enables support for sparse embeddings. +- `sparse_idf`: If set to `True`, computes the Inverse Document Frequency (IDF) when using sparse embeddings. +It is required to use techniques like BM42. It is ignored if `use_sparse_embeddings` is `False`. +- `similarity`: The similarity metric to use. +- `return_embedding`: Whether to return embeddings in the search results. +- `progress_bar`: Whether to show a progress bar or not. +- `recreate_index`: Whether to recreate the index. +- `shard_number`: Number of shards in the collection. +- `replication_factor`: Replication factor for the collection. +Defines how many copies of each shard will be created. Effective only in distributed mode. +- `write_consistency_factor`: Write consistency factor for the collection. Minimum value is 1. +Defines how many replicas should apply to the operation for it to be considered successful. +Increasing this number makes the collection more resilient to inconsistencies +but will cause failures if not enough replicas are available. +Effective only in distributed mode. +- `on_disk_payload`: If `True`, the point's payload will not be stored in memory and +will be read from the disk every time it is requested. +This setting saves RAM by slightly increasing response time. +Note: indexed payload values remain in RAM. +- `hnsw_config`: Params for HNSW index. +- `optimizers_config`: Params for optimizer. +- `wal_config`: Params for Write-Ahead-Log. +- `quantization_config`: Params for quantization. If `None`, quantization will be disabled. +- `init_from`: Use data stored in another collection to initialize this collection. +- `wait_result_from_api`: Whether to wait for the result from the API after each request. +- `metadata`: Additional metadata to include with the documents. +- `write_batch_size`: The batch size for writing documents. +- `scroll_size`: The scroll size for reading documents. +- `payload_fields_to_index`: List of payload fields to index. + + + +#### QdrantDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns the number of documents present in the Document Store. + + + +#### QdrantDocumentStore.count\_documents\_async + +```python +async def count_documents_async() -> int +``` + +Asynchronously returns the number of documents present in the document dtore. + + + +#### QdrantDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Union[Dict[str, Any], rest.Filter]] = None +) -> List[Document] +``` + +Returns the documents that match the provided filters. + +For a detailed specification of the filters, refer to the +[documentation](https://docs.haystack.deepset.ai/docs/metadata-filtering) + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of documents that match the given filters. + + + +#### QdrantDocumentStore.filter\_documents\_async + +```python +async def filter_documents_async( + filters: Optional[Union[Dict[str, Any], rest.Filter]] = None +) -> List[Document] +``` + +Asynchronously returns the documents that match the provided filters. + + + +#### QdrantDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> int +``` + +Writes documents to Qdrant using the specified policy. + +The QdrantDocumentStore can handle duplicate documents based on the given policy. +The available policies are: +- `FAIL`: The operation will raise an error if any document already exists. +- `OVERWRITE`: Existing documents will be overwritten with the new ones. +- `SKIP`: Existing documents will be skipped, and only new documents will be added. + +**Arguments**: + +- `documents`: A list of Document objects to write to Qdrant. +- `policy`: The policy for handling duplicate documents. + +**Returns**: + +The number of documents written to the document store. + + + +#### QdrantDocumentStore.write\_documents\_async + +```python +async def write_documents_async( + documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.FAIL) -> int +``` + +Asynchronously writes documents to Qdrant using the specified policy. + +The QdrantDocumentStore can handle duplicate documents based on the given policy. +The available policies are: +- `FAIL`: The operation will raise an error if any document already exists. +- `OVERWRITE`: Existing documents will be overwritten with the new ones. +- `SKIP`: Existing documents will be skipped, and only new documents will be added. + +**Arguments**: + +- `documents`: A list of Document objects to write to Qdrant. +- `policy`: The policy for handling duplicate documents. + +**Returns**: + +The number of documents written to the document store. + + + +#### QdrantDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### QdrantDocumentStore.delete\_documents\_async + +```python +async def delete_documents_async(document_ids: List[str]) -> None +``` + +Asynchronously deletes documents that match the provided `document_ids` from the document store. + +**Arguments**: + +- `document_ids`: the document ids to delete + + + +#### QdrantDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(recreate_index: bool = False) -> None +``` + +Deletes all documents from the document store. + +**Arguments**: + +- `recreate_index`: Whether to recreate the index after deleting all documents. + + + +#### QdrantDocumentStore.delete\_all\_documents\_async + +```python +async def delete_all_documents_async(recreate_index: bool = False) -> None +``` + +Asynchronously deletes all documents from the document store. + +**Arguments**: + +- `recreate_index`: Whether to recreate the index after deleting all documents. + + + +#### QdrantDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "QdrantDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### QdrantDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### QdrantDocumentStore.get\_documents\_by\_id + +```python +def get_documents_by_id(ids: List[str]) -> List[Document] +``` + +Retrieves documents from Qdrant by their IDs. + +**Arguments**: + +- `ids`: A list of document IDs to retrieve. + +**Returns**: + +A list of documents. + + + +#### QdrantDocumentStore.get\_documents\_by\_id\_async + +```python +async def get_documents_by_id_async(ids: List[str]) -> List[Document] +``` + +Retrieves documents from Qdrant by their IDs. + +**Arguments**: + +- `ids`: A list of document IDs to retrieve. + +**Returns**: + +A list of documents. + + + +#### QdrantDocumentStore.get\_distance + +```python +def get_distance(similarity: str) -> rest.Distance +``` + +Retrieves the distance metric for the specified similarity measure. + +**Arguments**: + +- `similarity`: The similarity measure to retrieve the distance. + +**Raises**: + +- `QdrantStoreError`: If the provided similarity measure is not supported. + +**Returns**: + +The corresponding rest.Distance object. + + + +#### QdrantDocumentStore.recreate\_collection + +```python +def recreate_collection(collection_name: str, + distance: rest.Distance, + embedding_dim: int, + on_disk: Optional[bool] = None, + use_sparse_embeddings: Optional[bool] = None, + sparse_idf: bool = False) -> None +``` + +Recreates the Qdrant collection with the specified parameters. + +**Arguments**: + +- `collection_name`: The name of the collection to recreate. +- `distance`: The distance metric to use for the collection. +- `embedding_dim`: The dimension of the embeddings. +- `on_disk`: Whether to store the collection on disk. +- `use_sparse_embeddings`: Whether to use sparse embeddings. +- `sparse_idf`: Whether to compute the Inverse Document Frequency (IDF) when using sparse embeddings. Required for BM42. + + + +#### QdrantDocumentStore.recreate\_collection\_async + +```python +async def recreate_collection_async( + collection_name: str, + distance: rest.Distance, + embedding_dim: int, + on_disk: Optional[bool] = None, + use_sparse_embeddings: Optional[bool] = None, + sparse_idf: bool = False) -> None +``` + +Asynchronously recreates the Qdrant collection with the specified parameters. + +**Arguments**: + +- `collection_name`: The name of the collection to recreate. +- `distance`: The distance metric to use for the collection. +- `embedding_dim`: The dimension of the embeddings. +- `on_disk`: Whether to store the collection on disk. +- `use_sparse_embeddings`: Whether to use sparse embeddings. +- `sparse_idf`: Whether to compute the Inverse Document Frequency (IDF) when using sparse embeddings. Required for BM42. + + + +## Module haystack\_integrations.document\_stores.qdrant.migrate\_to\_sparse + + + +#### migrate\_to\_sparse\_embeddings\_support + +```python +def migrate_to_sparse_embeddings_support( + old_document_store: QdrantDocumentStore, new_index: str) -> None +``` + +Utility function to migrate an existing `QdrantDocumentStore` to a new one with support for sparse embeddings. + +With qdrant-hasytack v3.3.0, support for sparse embeddings has been added to `QdrantDocumentStore`. +This feature is disabled by default and can be enabled by setting `use_sparse_embeddings=True` in the init +parameters. To store sparse embeddings, Document stores/collections created with this feature disabled must be +migrated to a new collection with the feature enabled. + +This utility function applies to on-premise and cloud instances of Qdrant. +It does not work for local in-memory/disk-persisted instances. + +The utility function merely migrates the existing documents so that they are ready to store sparse embeddings. +It does not compute sparse embeddings. To do this, you need to use a Sparse Embedder component. + +Example usage: +```python +from haystack_integrations.document_stores.qdrant import QdrantDocumentStore +from haystack_integrations.document_stores.qdrant import migrate_to_sparse_embeddings_support + +old_document_store = QdrantDocumentStore(url="http://localhost:6333", + index="Document", + use_sparse_embeddings=False) +new_index = "Document_sparse" + +migrate_to_sparse_embeddings_support(old_document_store, new_index) + +# now you can use the new document store with sparse embeddings support +new_document_store = QdrantDocumentStore(url="http://localhost:6333", + index=new_index, + use_sparse_embeddings=True) +``` + +**Arguments**: + +- `old_document_store`: The existing QdrantDocumentStore instance to migrate from. +- `new_index`: The name of the new index/collection to create with sparse embeddings support. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ragas.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ragas.md new file mode 100644 index 0000000000..a9bcf5de31 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/ragas.md @@ -0,0 +1,96 @@ +--- +title: "Ragas" +id: integrations-ragas +description: "Ragas integration for Haystack" +slug: "/integrations-ragas" +--- + + + +## Module haystack\_integrations.components.evaluators.ragas.evaluator + + + +### RagasEvaluator + +A component that uses the [Ragas framework](https://docs.ragas.io/) to evaluate +inputs against specified Ragas metrics. + +Usage example: +```python +from haystack.components.generators import OpenAIGenerator +from haystack_integrations.components.evaluators.ragas import RagasEvaluator +from ragas.metrics import ContextPrecision +from ragas.llms import HaystackLLMWrapper + +llm = OpenAIGenerator(model="gpt-4o-mini") +evaluator_llm = HaystackLLMWrapper(llm) + +evaluator = RagasEvaluator( + ragas_metrics=[ContextPrecision()], + evaluator_llm=evaluator_llm +) +output = evaluator.run( + query="Which is the most popular global sport?", + documents=[ + "Football is undoubtedly the world's most popular sport with" + " major events like the FIFA World Cup and sports personalities" + " like Ronaldo and Messi, drawing a followership of more than 4" + " billion people." + ], + reference="Football is the most popular sport with around 4 billion" + " followers worldwide", +) + +output['result'] +``` + + + +#### RagasEvaluator.\_\_init\_\_ + +```python +def __init__(ragas_metrics: List[Metric], + evaluator_llm: Optional[BaseRagasLLM] = None, + evaluator_embedding: Optional[BaseRagasEmbeddings] = None) +``` + +Constructs a new Ragas evaluator. + +**Arguments**: + +- `ragas_metrics`: A list of evaluation metrics from the [Ragas](https://docs.ragas.io/) library. +- `evaluator_llm`: A language model used by metrics that require LLMs for evaluation. +- `evaluator_embedding`: An embedding model used by metrics that require embeddings for evaluation. + + + +#### RagasEvaluator.run + +```python +@component.output_types(result=EvaluationResult) +def run(query: Optional[str] = None, + response: Optional[Union[List[ChatMessage], str]] = None, + documents: Optional[List[Union[Document, str]]] = None, + reference_contexts: Optional[List[str]] = None, + multi_responses: Optional[List[str]] = None, + reference: Optional[str] = None, + rubrics: Optional[Dict[str, str]] = None) -> Dict[str, Any] +``` + +Evaluates the provided query against the documents and returns the evaluation result. + +**Arguments**: + +- `query`: The input query from the user. +- `response`: A list of ChatMessage responses (typically from a language model or agent). +- `documents`: A list of Haystack Document or strings that were retrieved for the query. +- `reference_contexts`: A list of reference contexts that should have been retrieved for the query. +- `multi_responses`: List of multiple responses generated for the query. +- `reference`: A string reference answer for the query. +- `rubrics`: A dictionary of evaluation rubric, where keys represent the score +and the values represent the corresponding evaluation criteria. + +**Returns**: + +A dictionary containing the evaluation result. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/snowflake.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/snowflake.md new file mode 100644 index 0000000000..45e4f73551 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/snowflake.md @@ -0,0 +1,207 @@ +--- +title: "Snowflake" +id: integrations-snowflake +description: "Snowflake integration for Haystack" +slug: "/integrations-snowflake" +--- + + + +## Module haystack\_integrations.components.retrievers.snowflake.snowflake\_table\_retriever + + + +### SnowflakeTableRetriever + +Connects to a Snowflake database to execute a SQL query using ADBC and Polars. +Returns the results as a Pandas DataFrame (converted from a Polars DataFrame) +along with a Markdown-formatted string. +For more information, see [Polars documentation](https://docs.pola.rs/api/python/dev/reference/api/polars.read_database_uri.html). +and [ADBC documentation](https://arrow.apache.org/adbc/main/driver/snowflake.html). + +### Usage examples: + +#### Password Authentication: +```python +executor = SnowflakeTableRetriever( + user="", + account="", + authenticator="SNOWFLAKE", + api_key=Secret.from_env_var("SNOWFLAKE_API_KEY"), + database="", + db_schema="", + warehouse="", +) +executor.warm_up() +``` + +#### Key-pair Authentication (MFA): +```python +executor = SnowflakeTableRetriever( + user="", + account="", + authenticator="SNOWFLAKE_JWT", + private_key_file=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_FILE"), + private_key_file_pwd=Secret.from_env_var("SNOWFLAKE_PRIVATE_KEY_PWD"), + database="", + db_schema="", + warehouse="", +) +executor.warm_up() +``` + +#### OAuth Authentication (MFA): +```python +executor = SnowflakeTableRetriever( + user="", + account="", + authenticator="OAUTH", + oauth_client_id=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_ID"), + oauth_client_secret=Secret.from_env_var("SNOWFLAKE_OAUTH_CLIENT_SECRET"), + oauth_token_request_url="", + database="", + db_schema="", + warehouse="", +) +executor.warm_up() +``` + +#### Running queries: +```python +query = "SELECT * FROM table_name" +results = executor.run(query=query) + +>> print(results["dataframe"].head(2)) + + column1 column2 column3 +0 123 'data1' 2024-03-20 +1 456 'data2' 2024-03-21 + +>> print(results["table"]) + +shape: (3, 3) +| column1 | column2 | column3 | +|---------|---------|------------| +| int | str | date | +|---------|---------|------------| +| 123 | data1 | 2024-03-20 | +| 456 | data2 | 2024-03-21 | +| 789 | data3 | 2024-03-22 | +``` + + + +#### SnowflakeTableRetriever.\_\_init\_\_ + +```python +def __init__(user: str, + account: str, + authenticator: Literal["SNOWFLAKE", "SNOWFLAKE_JWT", + "OAUTH"] = "SNOWFLAKE", + api_key: Optional[Secret] = Secret.from_env_var( + "SNOWFLAKE_API_KEY", strict=False), + database: Optional[str] = None, + db_schema: Optional[str] = None, + warehouse: Optional[str] = None, + login_timeout: Optional[int] = 60, + return_markdown: bool = True, + private_key_file: Optional[Secret] = Secret.from_env_var( + "SNOWFLAKE_PRIVATE_KEY_FILE", strict=False), + private_key_file_pwd: Optional[Secret] = Secret.from_env_var( + "SNOWFLAKE_PRIVATE_KEY_PWD", strict=False), + oauth_client_id: Optional[Secret] = Secret.from_env_var( + "SNOWFLAKE_OAUTH_CLIENT_ID", strict=False), + oauth_client_secret: Optional[Secret] = Secret.from_env_var( + "SNOWFLAKE_OAUTH_CLIENT_SECRET", strict=False), + oauth_token_request_url: Optional[str] = None, + oauth_authorization_url: Optional[str] = None) -> None +``` + +**Arguments**: + +- `user`: User's login. +- `account`: Snowflake account identifier. +- `authenticator`: Authentication method. Required. Options: "SNOWFLAKE" (password), +"SNOWFLAKE_JWT" (key-pair), or "OAUTH". +- `api_key`: Snowflake account password. Required for SNOWFLAKE authentication. +- `database`: Name of the database to use. +- `db_schema`: Name of the schema to use. +- `warehouse`: Name of the warehouse to use. +- `login_timeout`: Timeout in seconds for login. +- `return_markdown`: Whether to return a Markdown-formatted string of the DataFrame. +- `private_key_file`: Secret containing the path to private key file. +Required for SNOWFLAKE_JWT authentication. +- `private_key_file_pwd`: Secret containing the passphrase for private key file. +Required only when the private key file is encrypted. +- `oauth_client_id`: Secret containing the OAuth client ID. +Required for OAUTH authentication. +- `oauth_client_secret`: Secret containing the OAuth client secret. +Required for OAUTH authentication. +- `oauth_token_request_url`: OAuth token request URL for Client Credentials flow. +- `oauth_authorization_url`: OAuth authorization URL for Authorization Code flow. + + + +#### SnowflakeTableRetriever.warm\_up + +```python +def warm_up() -> None +``` + +Warm up the component by initializing the authenticator handler and testing the database connection. + + + +#### SnowflakeTableRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### SnowflakeTableRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "SnowflakeTableRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### SnowflakeTableRetriever.run + +```python +@component.output_types(dataframe=DataFrame, table=str) +def run(query: str, return_markdown: Optional[bool] = None) -> Dict[str, Any] +``` + +Executes a SQL query against a Snowflake database using ADBC and Polars. + +**Arguments**: + +- `query`: The SQL query to execute. +- `return_markdown`: Whether to return a Markdown-formatted string of the DataFrame. +If not provided, uses the value set during initialization. + +**Returns**: + +A dictionary containing: +- `"dataframe"`: A Pandas DataFrame with the query results. +- `"table"`: A Markdown-formatted string representation of the DataFrame. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/stackit.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/stackit.md new file mode 100644 index 0000000000..5dfc9aea80 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/stackit.md @@ -0,0 +1,468 @@ +--- +title: "STACKIT" +id: integrations-stackit +description: "STACKIT integration for Haystack" +slug: "/integrations-stackit" +--- + + + +## Module haystack\_integrations.components.generators.stackit.chat.chat\_generator + + + +### STACKITChatGenerator + +Enables text generation using STACKIT generative models through their model serving service. + +Users can pass any text generation parameters valid for the STACKIT Chat Completion API +directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) + +### Usage example +```python +from haystack_integrations.components.generators.stackit import STACKITChatGenerator +from haystack.dataclasses import ChatMessage + +generator = STACKITChatGenerator(model="neuralmagic/Meta-Llama-3.1-70B-Instruct-FP8") + +result = generator.run([ChatMessage.from_user("Tell me a joke.")]) +print(result) +``` + + + +#### STACKITChatGenerator.\_\_init\_\_ + +```python +def __init__( + model: str, + api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"), + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: + Optional[ + str] = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1", + generation_kwargs: Optional[Dict[str, Any]] = None, + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of STACKITChatGenerator class. + +**Arguments**: + +- `model`: The name of the chat completion model to use. +- `api_key`: The STACKIT API key. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The STACKIT API Base url. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the STACKIT endpoint. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `timeout`: Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment +variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact STACKIT after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### STACKITChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### STACKITChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### STACKITChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Invokes chat completion based on the provided messages and generation parameters. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### STACKITChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async(messages: list[ChatMessage], + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None, + *, + tools: Optional[ToolsType] = None, + tools_strict: Optional[bool] = None) +``` + +Asynchronously invokes chat completion based on the provided messages and generation parameters. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +Must be a coroutine. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will +override the parameters passed during component initialization. +For details on OpenAI API parameters, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat/create). +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +If set, it will override the `tools` parameter provided during initialization. +- `tools_strict`: Whether to enable strict schema adherence for tool calls. If set to `True`, the model will follow exactly +the schema provided in the `parameters` field of the tool definition, but this may increase latency. +If set, it will override the `tools_strict` parameter set during component initialization. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module haystack\_integrations.components.embedders.stackit.document\_embedder + + + +### STACKITDocumentEmbedder + +A component for computing Document embeddings using STACKIT as model provider. +The embedding of each Document is stored in the `embedding` field of the Document. + +Usage example: +```python +from haystack import Document +from haystack_integrations.components.embedders.stackit import STACKITDocumentEmbedder + +doc = Document(content="I love pizza!") + +document_embedder = STACKITDocumentEmbedder() + +result = document_embedder.run([doc]) +print(result['documents'][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### STACKITDocumentEmbedder.\_\_init\_\_ + +```python +def __init__( + model: str, + api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"), + api_base_url: + Optional[ + str] = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1", + prefix: str = "", + suffix: str = "", + batch_size: int = 32, + progress_bar: bool = True, + meta_fields_to_embed: Optional[List[str]] = None, + embedding_separator: str = "\n", + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates a STACKITDocumentEmbedder component. + +**Arguments**: + +- `api_key`: The STACKIT API key. +- `model`: The name of the model to use. +- `api_base_url`: The STACKIT API Base url. +For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `batch_size`: Number of Documents to encode at once. +- `progress_bar`: Whether to show a progress bar or not. Can be helpful to disable in production deployments to keep +the logs clean. +- `meta_fields_to_embed`: List of meta fields that should be embedded along with the Document text. +- `embedding_separator`: Separator used to concatenate the meta fields to the Document text. +- `timeout`: Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment +variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact STACKIT after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### STACKITDocumentEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### STACKITDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAIDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### STACKITDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +def run(documents: list[Document]) +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +#### STACKITDocumentEmbedder.run\_async + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +async def run_async(documents: list[Document]) +``` + +Embeds a list of documents asynchronously. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with the following keys: +- `documents`: A list of documents with embeddings. +- `meta`: Information about the usage of the model. + + + +## Module haystack\_integrations.components.embedders.stackit.text\_embedder + + + +### STACKITTextEmbedder + +A component for embedding strings using STACKIT as model provider. + +Usage example: + ```python +from haystack_integrations.components.embedders.stackit import STACKITTextEmbedder + +text_to_embed = "I love pizza!" +text_embedder = STACKITTextEmbedder() +print(text_embedder.run(text_to_embed)) +``` + + + +#### STACKITTextEmbedder.\_\_init\_\_ + +```python +def __init__( + model: str, + api_key: Secret = Secret.from_env_var("STACKIT_API_KEY"), + api_base_url: + Optional[ + str] = "https://api.openai-compat.model-serving.eu01.onstackit.cloud/v1", + prefix: str = "", + suffix: str = "", + *, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates a STACKITTextEmbedder component. + +**Arguments**: + +- `api_key`: The STACKIT API key. +- `model`: The name of the STACKIT embedding model to be used. +- `api_base_url`: The STACKIT API Base url. +For more details, see STACKIT [docs](https://docs.stackit.cloud/stackit/en/basic-concepts-stackit-model-serving-319914567.html). +- `prefix`: A string to add to the beginning of each text. +- `suffix`: A string to add to the end of each text. +- `timeout`: Timeout for STACKIT client calls. If not set, it defaults to either the `OPENAI_TIMEOUT` environment +variable, or 30 seconds. +- `max_retries`: Maximum number of retries to contact STACKIT after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### STACKITTextEmbedder.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### STACKITTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "OpenAITextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### STACKITTextEmbedder.run + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +def run(text: str) +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. + + + +#### STACKITTextEmbedder.run\_async + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +async def run_async(text: str) +``` + +Asynchronously embed a single string. + +This is the asynchronous version of the `run` method. It has the same parameters and return values +but can be used with `await` in async code. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with the following keys: +- `embedding`: The embedding of the input text. +- `meta`: Information about the usage of the model. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/togetherai.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/togetherai.md new file mode 100644 index 0000000000..2b264d8423 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/togetherai.md @@ -0,0 +1,287 @@ +--- +title: "Together AI" +id: integrations-togetherai +description: "Together AI integration for Haystack" +slug: "/integrations-togetherai" +--- + + + +## Module haystack\_integrations.components.generators.togetherai.generator + + + +### TogetherAIGenerator + +Provides an interface to generate text using an LLM running on Together AI. + +Usage example: +```python +from haystack_integrations.components.generators.togetherai import TogetherAIGenerator + +generator = TogetherAIGenerator(model="deepseek-ai/DeepSeek-R1", + generation_kwargs={ + "temperature": 0.9, + }) + +print(generator.run("Who is the best Italian actor?")) +``` + + + +#### TogetherAIGenerator.\_\_init\_\_ + +```python +def __init__(api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"), + model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo", + api_base_url: Optional[str] = "https://api.together.xyz/v1", + streaming_callback: Optional[StreamingCallbackT] = None, + system_prompt: Optional[str] = None, + generation_kwargs: Optional[Dict[str, Any]] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None) +``` + +Initialize the TogetherAIGenerator. + +**Arguments**: + +- `api_key`: The Together API key. +- `model`: The name of the model to use. +- `api_base_url`: The base URL of the Together AI API. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `system_prompt`: The system prompt to use for text generation. If not provided, the system prompt is +omitted, and the default system prompt of the model is used. +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Together AI endpoint. See Together AI +[documentation](https://docs.together.ai/reference/chat-completions-1) for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So, 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `n`: How many completions to generate for each prompt. For example, if the LLM gets 3 prompts and n is 2, + it will generate two completions for each of the three prompts, ending up with 6 completions in total. +- `stop`: One or more sequences after which the LLM should stop generating tokens. +- `presence_penalty`: What penalty to apply if a token is already present at all. Bigger values mean + the model will be less likely to repeat the same token in the text. +- `frequency_penalty`: What penalty to apply if a token has already been generated in the text. + Bigger values mean the model will be less likely to repeat the same token in the text. +- `logit_bias`: Add a logit bias to specific tokens. The keys of the dictionary are tokens, and the + values are the bias to add to that token. +- `timeout`: Timeout for together.ai Client calls, if not set it is inferred from the `OPENAI_TIMEOUT` environment +variable or set to 30. +- `max_retries`: Maximum retries to establish contact with Together AI if it returns an internal error, if not set it is +inferred from the `OPENAI_MAX_RETRIES` environment variable or set to 5. + + + +#### TogetherAIGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### TogetherAIGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "TogetherAIGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### TogetherAIGenerator.run + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +def run(*, + prompt: str, + system_prompt: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) -> dict[str, Any] +``` + +Generate text completions synchronously. + +**Arguments**: + +- `prompt`: The input prompt string for text generation. +- `system_prompt`: An optional system prompt to provide context or instructions for the generation. +If not provided, the system prompt set in the `__init__` method will be used. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided, this will override the `streaming_callback` set in the `__init__` method. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated text completions as strings. +- `meta`: A list of metadata dictionaries containing information about each generation, +including model name, finish reason, and token usage statistics. + + + +#### TogetherAIGenerator.run\_async + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +async def run_async( + *, + prompt: str, + system_prompt: Optional[str] = None, + streaming_callback: Optional[StreamingCallbackT] = None, + generation_kwargs: Optional[dict[str, Any]] = None) -> dict[str, Any] +``` + +Generate text completions asynchronously. + +**Arguments**: + +- `prompt`: The input prompt string for text generation. +- `system_prompt`: An optional system prompt to provide context or instructions for the generation. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided, this will override the `streaming_callback` set in the `__init__` method. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated text completions as strings. +- `meta`: A list of metadata dictionaries containing information about each generation, +including model name, finish reason, and token usage statistics. + + + +## Module haystack\_integrations.components.generators.togetherai.chat.chat\_generator + + + +### TogetherAIChatGenerator + +Enables text generation using Together AI generative models. +For supported models, see [Together AI docs](https://docs.together.ai/docs). + +Users can pass any text generation parameters valid for the Together AI chat completion API +directly to this component using the `generation_kwargs` parameter in `__init__` or the `generation_kwargs` +parameter in `run` method. + +Key Features and Compatibility: +- **Primary Compatibility**: Designed to work seamlessly with the Together AI chat completion endpoint. +- **Streaming Support**: Supports streaming responses from the Together AI chat completion endpoint. +- **Customizability**: Supports all parameters supported by the Together AI chat completion endpoint. + +This component uses the ChatMessage format for structuring both input and output, +ensuring coherent and contextually relevant responses in chat-based text generation scenarios. +Details on the ChatMessage format can be found in the +[Haystack docs](https://docs.haystack.deepset.ai/docs/chatmessage) + +For more details on the parameters supported by the Together AI API, refer to the +[Together AI API Docs](https://docs.together.ai/reference/chat-completions-1). + +Usage example: +```python +from haystack_integrations.components.generators.togetherai import TogetherAIChatGenerator +from haystack.dataclasses import ChatMessage + +messages = [ChatMessage.from_user("What's Natural Language Processing?")] + +client = TogetherAIChatGenerator() +response = client.run(messages) +print(response) + +>>{'replies': [ChatMessage(_content='Natural Language Processing (NLP) is a branch of artificial intelligence +>>that focuses on enabling computers to understand, interpret, and generate human language in a way that is +>>meaningful and useful.', _role=, _name=None, +>>_meta={'model': 'meta-llama/Llama-3.3-70B-Instruct-Turbo', 'index': 0, 'finish_reason': 'stop', +>>'usage': {'prompt_tokens': 15, 'completion_tokens': 36, 'total_tokens': 51}})]} +``` + + + +#### TogetherAIChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("TOGETHER_API_KEY"), + model: str = "meta-llama/Llama-3.3-70B-Instruct-Turbo", + streaming_callback: Optional[StreamingCallbackT] = None, + api_base_url: Optional[str] = "https://api.together.xyz/v1", + generation_kwargs: Optional[Dict[str, Any]] = None, + tools: Optional[ToolsType] = None, + timeout: Optional[float] = None, + max_retries: Optional[int] = None, + http_client_kwargs: Optional[Dict[str, Any]] = None) +``` + +Creates an instance of TogetherAIChatGenerator. Unless specified otherwise, + +the default model is `meta-llama/Llama-3.3-70B-Instruct-Turbo`. + +**Arguments**: + +- `api_key`: The Together API key. +- `model`: The name of the Together AI chat completion model to use. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +The callback function accepts StreamingChunk as an argument. +- `api_base_url`: The Together AI API Base url. +For more details, see Together AI [docs](https://docs.together.ai/docs/openai-api-compatibility). +- `generation_kwargs`: Other parameters to use for the model. These parameters are all sent directly to +the Together AI endpoint. See [Together AI API docs](https://docs.together.ai/reference/chat-completions-1) +for more details. +Some of the supported parameters: +- `max_tokens`: The maximum number of tokens the output text can have. +- `temperature`: What sampling temperature to use. Higher values mean the model will take more risks. + Try 0.9 for more creative applications and 0 (argmax sampling) for ones with a well-defined answer. +- `top_p`: An alternative to sampling with temperature, called nucleus sampling, where the model + considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens + comprising the top 10% probability mass are considered. +- `stream`: Whether to stream back partial progress. If set, tokens will be sent as data-only server-sent + events as they become available, with the stream terminated by a data: [DONE] message. +- `safe_prompt`: Whether to inject a safety prompt before all conversations. +- `random_seed`: The seed to use for random sampling. +- `tools`: A list of Tool and/or Toolset objects, or a single Toolset for which the model can prepare calls. +Each tool should have a unique name. +- `timeout`: The timeout for the Together AI API call. +- `max_retries`: Maximum number of retries to contact Together AI after an internal error. +If not set, it defaults to either the `OPENAI_MAX_RETRIES` environment variable, or set to 5. +- `http_client_kwargs`: A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`. +For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/`client`). + + + +#### TogetherAIChatGenerator.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serialize this component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/unstructured.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/unstructured.md new file mode 100644 index 0000000000..6026051a05 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/unstructured.md @@ -0,0 +1,135 @@ +--- +title: "Unstructured" +id: integrations-unstructured +description: "Unstructured integration for Haystack" +slug: "/integrations-unstructured" +--- + + + +## Module haystack\_integrations.components.converters.unstructured.converter + + + +### UnstructuredFileConverter + +A component for converting files to Haystack Documents using the Unstructured API (hosted or running locally). + +For the supported file types and the specific API parameters, see +[Unstructured docs](https://docs.unstructured.io/api-reference/api-services/overview). + +Usage example: +```python +from haystack_integrations.components.converters.unstructured import UnstructuredFileConverter + +# make sure to either set the environment variable UNSTRUCTURED_API_KEY +# or run the Unstructured API locally: +# docker run -p 8000:8000 -d --rm --name unstructured-api quay.io/unstructured-io/unstructured-api:latest +# --port 8000 --host 0.0.0.0 + +converter = UnstructuredFileConverter( + # api_url="http://localhost:8000/general/v0/general" # <-- Uncomment this if running Unstructured locally +) +documents = converter.run(paths = ["a/file/path.pdf", "a/directory/path"])["documents"] +``` + + + +#### UnstructuredFileConverter.\_\_init\_\_ + +```python +def __init__(api_url: str = UNSTRUCTURED_HOSTED_API_URL, + api_key: Optional[Secret] = Secret.from_env_var( + "UNSTRUCTURED_API_KEY", strict=False), + document_creation_mode: Literal[ + "one-doc-per-file", "one-doc-per-page", + "one-doc-per-element"] = "one-doc-per-file", + separator: str = "\n\n", + unstructured_kwargs: Optional[Dict[str, Any]] = None, + progress_bar: bool = True) +``` + +**Arguments**: + +- `api_url`: URL of the Unstructured API. Defaults to the URL of the hosted version. +If you run the API locally, specify the URL of your local API (e.g. `"http://localhost:8000/general/v0/general"`). +- `api_key`: API key for the Unstructured API. +It can be explicitly passed or read the environment variable `UNSTRUCTURED_API_KEY` (recommended). +If you run the API locally, it is not needed. +- `document_creation_mode`: How to create Haystack Documents from the elements returned by Unstructured. +`"one-doc-per-file"`: One Haystack Document per file. All elements are concatenated into one text field. +`"one-doc-per-page"`: One Haystack Document per page. +All elements on a page are concatenated into one text field. +`"one-doc-per-element"`: One Haystack Document per element. Each element is converted to a Haystack Document. +- `separator`: Separator between elements when concatenating them into one text field. +- `unstructured_kwargs`: Additional parameters that are passed to the Unstructured API. +For the available parameters, see +[Unstructured API docs](https://docs.unstructured.io/api-reference/api-services/api-parameters). +- `progress_bar`: Whether to show a progress bar during the conversion. + + + +#### UnstructuredFileConverter.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### UnstructuredFileConverter.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "UnstructuredFileConverter" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### UnstructuredFileConverter.run + +```python +@component.output_types(documents=List[Document]) +def run( + paths: Union[List[str], List[os.PathLike]], + meta: Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] = None +) -> Dict[str, List[Document]] +``` + +Convert files to Haystack Documents using the Unstructured API. + +**Arguments**: + +- `paths`: List of paths to convert. Paths can be files or directories. +If a path is a directory, all files in the directory are converted. Subdirectories are ignored. +- `meta`: Optional metadata to attach to the Documents. +This value can be either a list of dictionaries or a single dictionary. +If it's a single dictionary, its content is added to the metadata of all produced Documents. +If it's a list, the length of the list must match the number of paths, because the two lists will be zipped. +Please note that if the paths contain directories, `meta` can only be a single dictionary +(same metadata for all files). + +**Raises**: + +- `ValueError`: If `meta` is a list and `paths` contains directories. + +**Returns**: + +A dictionary with the following key: +- `documents`: List of Haystack Documents. diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/watsonx.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/watsonx.md new file mode 100644 index 0000000000..1c91ab14e6 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/watsonx.md @@ -0,0 +1,685 @@ +--- +title: "IBM watsonx.ai" +id: integrations-watsonx +description: "IBM watsonx.ai integration for Haystack" +slug: "/integrations-watsonx" +--- + + + +## Module haystack\_integrations.components.generators.watsonx.generator + + + +### WatsonxGenerator + +Enables text completions using IBM's watsonx.ai foundation models. + +This component extends WatsonxChatGenerator to provide the standard Generator interface that works with prompt +strings instead of ChatMessage objects. + +The generator works with IBM's foundation models including: +- granite-13b-chat-v2 +- llama-2-70b-chat +- llama-3-70b-instruct +- Other watsonx.ai chat models + +You can customize the generation behavior by passing parameters to the watsonx.ai API through the +`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint. + +For details on watsonx.ai API parameters, see +[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html). + +### Usage example + +```python +from haystack_integrations.components.generators.watsonx.generator import WatsonxGenerator +from haystack.utils import Secret + +generator = WatsonxGenerator( + api_key=Secret.from_env_var("WATSONX_API_KEY"), + model="ibm/granite-13b-chat-v2", + project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), +) + +response = generator.run( + prompt="Explain quantum computing in simple terms", + system_prompt="You are a helpful physics teacher.", +) +print(response) +``` +Output: +``` +{ + "replies": ["Quantum computing uses quantum-mechanical phenomena like...."], + "meta": [ + { + "model": "ibm/granite-13b-chat-v2", + "project_id": "your-project-id", + "usage": { + "prompt_tokens": 12, + "completion_tokens": 45, + "total_tokens": 57, + }, + } + ], +} +``` + + + +#### WatsonxGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"), + model: str = "ibm/granite-3-2b-instruct", + project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"), + api_base_url: str = "https://us-south.ml.cloud.ibm.com", + system_prompt: str | None = None, + generation_kwargs: dict[str, Any] | None = None, + timeout: float | None = None, + max_retries: int | None = None, + verify: bool | str | None = None, + streaming_callback: StreamingCallbackT | None = None) -> None +``` + +Creates an instance of WatsonxGenerator. + +Before initializing the component, you can set environment variables: +- `WATSONX_TIMEOUT` to override the default timeout +- `WATSONX_MAX_RETRIES` to override the default retry count + +**Arguments**: + +- `api_key`: IBM Cloud API key for watsonx.ai access. +Can be set via `WATSONX_API_KEY` environment variable or passed directly. +- `model`: The model ID to use for completions. Defaults to "ibm/granite-13b-chat-v2". +Available models can be found in your IBM Cloud account. +- `project_id`: IBM Cloud project ID +- `api_base_url`: Custom base URL for the API endpoint. +Defaults to "https://us-south.ml.cloud.ibm.com". +- `system_prompt`: The system prompt to use for text generation. +- `generation_kwargs`: Additional parameters to control text generation. +These parameters are passed directly to the watsonx.ai inference endpoint. +Supported parameters include: +- `temperature`: Controls randomness (lower = more deterministic) +- `max_new_tokens`: Maximum number of tokens to generate +- `min_new_tokens`: Minimum number of tokens to generate +- `top_p`: Nucleus sampling probability threshold +- `top_k`: Number of highest probability tokens to consider +- `repetition_penalty`: Penalty for repeated tokens +- `length_penalty`: Penalty based on output length +- `stop_sequences`: List of sequences where generation should stop +- `random_seed`: Seed for reproducible results +- `timeout`: Timeout in seconds for API requests. +Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds. +- `max_retries`: Maximum number of retry attempts for failed requests. +Defaults to environment variable `WATSONX_MAX_RETRIES` or 5. +- `verify`: SSL verification setting. Can be: +- True: Verify SSL certificates (default) +- False: Skip verification (insecure) +- Path to CA bundle for custom certificates +- `streaming_callback`: A callback function for streaming responses. + + + +#### WatsonxGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### WatsonxGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "WatsonxGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### WatsonxGenerator.run + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +def run(*, + prompt: str, + system_prompt: str | None = None, + streaming_callback: StreamingCallbackT | None = None, + generation_kwargs: dict[str, Any] | None = None) -> dict[str, Any] +``` + +Generate text completions synchronously. + +**Arguments**: + +- `prompt`: The input prompt string for text generation. +- `system_prompt`: An optional system prompt to provide context or instructions for the generation. +If not provided, the system prompt set in the `__init__` method will be used. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided, this will override the `streaming_callback` set in the `__init__` method. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated text completions as strings. +- `meta`: A list of metadata dictionaries containing information about each generation, +including model name, finish reason, and token usage statistics. + + + +#### WatsonxGenerator.run\_async + +```python +@component.output_types(replies=list[str], meta=list[dict[str, Any]]) +async def run_async( + *, + prompt: str, + system_prompt: str | None = None, + streaming_callback: StreamingCallbackT | None = None, + generation_kwargs: dict[str, Any] | None = None) -> dict[str, Any] +``` + +Generate text completions asynchronously. + +**Arguments**: + +- `prompt`: The input prompt string for text generation. +- `system_prompt`: An optional system prompt to provide context or instructions for the generation. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided, this will override the `streaming_callback` set in the `__init__` method. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. Supported parameters include temperature, max_new_tokens, top_p, etc. + +**Returns**: + +A dictionary with the following keys: +- `replies`: A list of generated text completions as strings. +- `meta`: A list of metadata dictionaries containing information about each generation, +including model name, finish reason, and token usage statistics. + + + +## Module haystack\_integrations.components.generators.watsonx.chat.chat\_generator + + + +### WatsonxChatGenerator + +Enables chat completions using IBM's watsonx.ai foundation models. + +This component interacts with IBM's watsonx.ai platform to generate chat responses using various foundation +models. It supports the [ChatMessage](https://docs.haystack.deepset.ai/docs/chatmessage) format for both input +and output, including multimodal inputs with text and images. + +The generator works with IBM's foundation models including: +- granite-13b-chat-v2 +- llama-2-70b-chat +- llama-3-70b-instruct +- llama-3-2-11b-vision-instruct (multimodal) +- llama-3-2-90b-vision-instruct (multimodal) +- pixtral-12b (multimodal) +- Other watsonx.ai chat models + +You can customize the generation behavior by passing parameters to the watsonx.ai API through the +`generation_kwargs` argument. These parameters are passed directly to the watsonx.ai inference endpoint. + +For details on watsonx.ai API parameters, see +[IBM watsonx.ai documentation](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-parameters.html). + +### Usage example + +```python +from haystack_integrations.components.generators.watsonx.chat.chat_generator import WatsonxChatGenerator +from haystack.dataclasses import ChatMessage +from haystack.utils import Secret + +messages = [ChatMessage.from_user("Explain quantum computing in simple terms")] + +client = WatsonxChatGenerator( + api_key=Secret.from_env_var("WATSONX_API_KEY"), + model="ibm/granite-13b-chat-v2", + project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), +) +response = client.run(messages) +print(response) +``` + +### Multimodal usage example + +```python +from haystack.dataclasses import ChatMessage, ImageContent + +# Create an image from file path or base64 +image_content = ImageContent.from_file_path("path/to/your/image.jpg") + +# Create a multimodal message with both text and image +messages = [ChatMessage.from_user(content_parts=["What's in this image?", image_content])] + +# Use a multimodal model +client = WatsonxChatGenerator( + api_key=Secret.from_env_var("WATSONX_API_KEY"), + model="meta-llama/llama-3-2-11b-vision-instruct", + project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), +) +response = client.run(messages) +print(response) +``` + + + +#### WatsonxChatGenerator.\_\_init\_\_ + +```python +def __init__(*, + api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"), + model: str = "ibm/granite-3-2b-instruct", + project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"), + api_base_url: str = "https://us-south.ml.cloud.ibm.com", + generation_kwargs: dict[str, Any] | None = None, + timeout: float | None = None, + max_retries: int | None = None, + verify: bool | str | None = None, + streaming_callback: StreamingCallbackT | None = None) -> None +``` + +Creates an instance of WatsonxChatGenerator. + +Before initializing the component, you can set environment variables: +- `WATSONX_TIMEOUT` to override the default timeout +- `WATSONX_MAX_RETRIES` to override the default retry count + +**Arguments**: + +- `api_key`: IBM Cloud API key for watsonx.ai access. +Can be set via `WATSONX_API_KEY` environment variable or passed directly. +- `model`: The model ID to use for completions. Defaults to "ibm/granite-13b-chat-v2". +Available models can be found in your IBM Cloud account. +- `project_id`: IBM Cloud project ID +- `api_base_url`: Custom base URL for the API endpoint. +Defaults to "https://us-south.ml.cloud.ibm.com". +- `generation_kwargs`: Additional parameters to control text generation. +These parameters are passed directly to the watsonx.ai inference endpoint. +Supported parameters include: +- `temperature`: Controls randomness (lower = more deterministic) +- `max_new_tokens`: Maximum number of tokens to generate +- `min_new_tokens`: Minimum number of tokens to generate +- `top_p`: Nucleus sampling probability threshold +- `top_k`: Number of highest probability tokens to consider +- `repetition_penalty`: Penalty for repeated tokens +- `length_penalty`: Penalty based on output length +- `stop_sequences`: List of sequences where generation should stop +- `random_seed`: Seed for reproducible results +- `timeout`: Timeout in seconds for API requests. +Defaults to environment variable `WATSONX_TIMEOUT` or 30 seconds. +- `max_retries`: Maximum number of retry attempts for failed requests. +Defaults to environment variable `WATSONX_MAX_RETRIES` or 5. +- `verify`: SSL verification setting. Can be: +- True: Verify SSL certificates (default) +- False: Skip verification (insecure) +- Path to CA bundle for custom certificates +- `streaming_callback`: A callback function for streaming responses. + + + +#### WatsonxChatGenerator.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### WatsonxChatGenerator.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "WatsonxChatGenerator" +``` + +Deserialize this component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### WatsonxChatGenerator.run + +```python +@component.output_types(replies=list[ChatMessage]) +def run( + *, + messages: list[ChatMessage], + generation_kwargs: dict[str, Any] | None = None, + streaming_callback: StreamingCallbackT | None = None +) -> dict[str, list[ChatMessage]] +``` + +Generate chat completions synchronously. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided this will override the `streaming_callback` set in the `__init__` method. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +#### WatsonxChatGenerator.run\_async + +```python +@component.output_types(replies=list[ChatMessage]) +async def run_async( + *, + messages: list[ChatMessage], + generation_kwargs: dict[str, Any] | None = None, + streaming_callback: StreamingCallbackT | None = None +) -> dict[str, list[ChatMessage]] +``` + +Generate chat completions asynchronously. + +**Arguments**: + +- `messages`: A list of ChatMessage instances representing the input messages. +- `generation_kwargs`: Additional keyword arguments for text generation. These parameters will potentially override the parameters +passed in the `__init__` method. +- `streaming_callback`: A callback function that is called when a new token is received from the stream. +If provided this will override the `streaming_callback` set in the `__init__` method. + +**Returns**: + +A dictionary with the following key: +- `replies`: A list containing the generated responses as ChatMessage instances. + + + +## Module haystack\_integrations.components.embedders.watsonx.document\_embedder + + + +### WatsonxDocumentEmbedder + +Computes document embeddings using IBM watsonx.ai models. + +### Usage example + +```python +from haystack import Document +from haystack_integrations.components.embedders.watsonx.document_embedder import WatsonxDocumentEmbedder + +documents = [ + Document(content="I love pizza!"), + Document(content="Pasta is great too"), +] + +document_embedder = WatsonxDocumentEmbedder( + model="ibm/slate-30m-english-rtrvr", + api_key=Secret.from_env_var("WATSONX_API_KEY"), + api_base_url="https://us-south.ml.cloud.ibm.com", + project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), +) + +result = document_embedder.run(documents=documents) +print(result["documents"][0].embedding) + +# [0.017020374536514282, -0.023255806416273117, ...] +``` + + + +#### WatsonxDocumentEmbedder.\_\_init\_\_ + +```python +def __init__(*, + model: str = "ibm/slate-30m-english-rtrvr", + api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"), + api_base_url: str = "https://us-south.ml.cloud.ibm.com", + project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"), + truncate_input_tokens: int | None = None, + prefix: str = "", + suffix: str = "", + batch_size: int = 1000, + concurrency_limit: int = 5, + timeout: float | None = None, + max_retries: int | None = None, + meta_fields_to_embed: list[str] | None = None, + embedding_separator: str = "\n") +``` + +Creates a WatsonxDocumentEmbedder component. + +**Arguments**: + +- `model`: The name of the model to use for calculating embeddings. +Default is "ibm/slate-30m-english-rtrvr". +- `api_key`: The WATSONX API key. Can be set via environment variable WATSONX_API_KEY. +- `api_base_url`: The WATSONX URL for the watsonx.ai service. +Default is "https://us-south.ml.cloud.ibm.com". +- `project_id`: The ID of the Watson Studio project. +Can be set via environment variable WATSONX_PROJECT_ID. +- `truncate_input_tokens`: Maximum number of tokens to use from the input text. +If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit. +- `prefix`: A string to add at the beginning of each text. +- `suffix`: A string to add at the end of each text. +- `batch_size`: Number of documents to embed in one API call. Default is 1000. +- `concurrency_limit`: Number of parallel requests to make. Default is 5. +- `timeout`: Timeout for API requests in seconds. +- `max_retries`: Maximum number of retries for API requests. + + + +#### WatsonxDocumentEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### WatsonxDocumentEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "WatsonxDocumentEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### WatsonxDocumentEmbedder.run + +```python +@component.output_types(documents=list[Document], meta=dict[str, Any]) +def run(documents: list[Document] + ) -> dict[str, list[Document] | dict[str, Any]] +``` + +Embeds a list of documents. + +**Arguments**: + +- `documents`: A list of documents to embed. + +**Returns**: + +A dictionary with: +- 'documents': List of Documents with embeddings added +- 'meta': Information about the model usage + + + +## Module haystack\_integrations.components.embedders.watsonx.text\_embedder + + + +### WatsonxTextEmbedder + +Embeds strings using IBM watsonx.ai foundation models. + +You can use it to embed user query and send it to an embedding Retriever. + +### Usage example + +```python +from haystack_integrations.components.embedders.watsonx.text_embedder import WatsonxTextEmbedder + +text_to_embed = "I love pizza!" + +text_embedder = WatsonxTextEmbedder( + model="ibm/slate-30m-english-rtrvr", + api_key=Secret.from_env_var("WATSONX_API_KEY"), + api_base_url="https://us-south.ml.cloud.ibm.com", + project_id=Secret.from_env_var("WATSONX_PROJECT_ID"), +) + +print(text_embedder.run(text_to_embed)) + +# {'embedding': [0.017020374536514282, -0.023255806416273117, ...], +# 'meta': {'model': 'ibm/slate-30m-english-rtrvr', +# 'truncated_input_tokens': 3}} +``` + + + +#### WatsonxTextEmbedder.\_\_init\_\_ + +```python +def __init__(*, + model: str = "ibm/slate-30m-english-rtrvr", + api_key: Secret = Secret.from_env_var("WATSONX_API_KEY"), + api_base_url: str = "https://us-south.ml.cloud.ibm.com", + project_id: Secret = Secret.from_env_var("WATSONX_PROJECT_ID"), + truncate_input_tokens: int | None = None, + prefix: str = "", + suffix: str = "", + timeout: float | None = None, + max_retries: int | None = None) +``` + +Creates an WatsonxTextEmbedder component. + +**Arguments**: + +- `model`: The name of the IBM watsonx model to use for calculating embeddings. +Default is "ibm/slate-30m-english-rtrvr". +- `api_key`: The WATSONX API key. Can be set via environment variable WATSONX_API_KEY. +- `api_base_url`: The WATSONX URL for the watsonx.ai service. +Default is "https://us-south.ml.cloud.ibm.com". +- `project_id`: The ID of the Watson Studio project. +Can be set via environment variable WATSONX_PROJECT_ID. +- `truncate_input_tokens`: Maximum number of tokens to use from the input text. +If set to `None` (or not provided), the full input text is used, up to the model's maximum token limit. +- `prefix`: A string to add at the beginning of each text to embed. +- `suffix`: A string to add at the end of each text to embed. +- `timeout`: Timeout for API requests in seconds. +- `max_retries`: Maximum number of retries for API requests. + + + +#### WatsonxTextEmbedder.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serialize the component to a dictionary. + +**Returns**: + +The serialized component as a dictionary. + + + +#### WatsonxTextEmbedder.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "WatsonxTextEmbedder" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary representation of this component. + +**Returns**: + +The deserialized component instance. + + + +#### WatsonxTextEmbedder.run + +```python +@component.output_types(embedding=list[float], meta=dict[str, Any]) +def run(text: str) -> dict[str, list[float] | dict[str, Any]] +``` + +Embeds a single string. + +**Arguments**: + +- `text`: Text to embed. + +**Returns**: + +A dictionary with: +- 'embedding': The embedding of the input text +- 'meta': Information about the model usage diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weaviate.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weaviate.md new file mode 100644 index 0000000000..cb3fc1df89 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weaviate.md @@ -0,0 +1,635 @@ +--- +title: "Weaviate" +id: integrations-weaviate +description: "Weaviate integration for Haystack" +slug: "/integrations-weaviate" +--- + + + +## Module haystack\_integrations.document\_stores.weaviate.auth + + + +### SupportedAuthTypes + +Supported auth credentials for WeaviateDocumentStore. + + + +### AuthCredentials + +Base class for all auth credentials supported by WeaviateDocumentStore. +Can be used to deserialize from dict any of the supported auth credentials. + + + +#### AuthCredentials.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Converts the object to a dictionary representation for serialization. + + + +#### AuthCredentials.from\_dict + +```python +@staticmethod +def from_dict(data: Dict[str, Any]) -> "AuthCredentials" +``` + +Converts a dictionary representation to an auth credentials object. + + + +#### AuthCredentials.resolve\_value + +```python +@abstractmethod +def resolve_value() +``` + +Resolves all the secrets in the auth credentials object and returns the corresponding Weaviate object. +All subclasses must implement this method. + + + +### AuthApiKey + +AuthCredentials for API key authentication. +By default it will load `api_key` from the environment variable `WEAVIATE_API_KEY`. + + + +### AuthBearerToken + +AuthCredentials for Bearer token authentication. +By default it will load `access_token` from the environment variable `WEAVIATE_ACCESS_TOKEN`, +and `refresh_token` from the environment variable +`WEAVIATE_REFRESH_TOKEN`. +`WEAVIATE_REFRESH_TOKEN` environment variable is optional. + + + +### AuthClientCredentials + +AuthCredentials for client credentials authentication. +By default it will load `client_secret` from the environment variable `WEAVIATE_CLIENT_SECRET`, and +`scope` from the environment variable `WEAVIATE_SCOPE`. +`WEAVIATE_SCOPE` environment variable is optional, if set it can either be a string or a list of space +separated strings. e.g "scope1" or "scope1 scope2". + + + +### AuthClientPassword + +AuthCredentials for username and password authentication. +By default it will load `username` from the environment variable `WEAVIATE_USERNAME`, +`password` from the environment variable `WEAVIATE_PASSWORD`, and +`scope` from the environment variable `WEAVIATE_SCOPE`. +`WEAVIATE_SCOPE` environment variable is optional, if set it can either be a string or a list of space +separated strings. e.g "scope1" or "scope1 scope2". + + + +## Module haystack\_integrations.document\_stores.weaviate.document\_store + + + +### WeaviateDocumentStore + +A WeaviateDocumentStore instance you +can use with Weaviate Cloud Services or self-hosted instances. + +Usage example with Weaviate Cloud Services: +```python +import os +from haystack_integrations.document_stores.weaviate.auth import AuthApiKey +from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore + +os.environ["WEAVIATE_API_KEY"] = "MY_API_KEY" + +document_store = WeaviateDocumentStore( + url="rAnD0mD1g1t5.something.weaviate.cloud", + auth_client_secret=AuthApiKey(), +) +``` + +Usage example with self-hosted Weaviate: +```python +from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore + +document_store = WeaviateDocumentStore(url="http://localhost:8080") +``` + + + +#### WeaviateDocumentStore.\_\_init\_\_ + +```python +def __init__(*, + url: Optional[str] = None, + collection_settings: Optional[Dict[str, Any]] = None, + auth_client_secret: Optional[AuthCredentials] = None, + additional_headers: Optional[Dict] = None, + embedded_options: Optional[EmbeddedOptions] = None, + additional_config: Optional[AdditionalConfig] = None, + grpc_port: int = 50051, + grpc_secure: bool = False) +``` + +Create a new instance of WeaviateDocumentStore and connects to the Weaviate instance. + +**Arguments**: + +- `url`: The URL to the weaviate instance. +- `collection_settings`: The collection settings to use. If `None`, it will use a collection named `default` with the following +properties: +- _original_id: text +- content: text +- blob_data: blob +- blob_mime_type: text +- score: number +The Document `meta` fields are omitted in the default collection settings as we can't make assumptions +on the structure of the meta field. +We heavily recommend to create a custom collection with the correct meta properties +for your use case. +Another option is relying on the automatic schema generation, but that's not recommended for +production use. +See the official `Weaviate documentation`_ +for more information on collections and their properties. +- `auth_client_secret`: Authentication credentials. Can be one of the following types depending on the authentication mode: +- `AuthBearerToken` to use existing access and (optionally, but recommended) refresh tokens +- `AuthClientPassword` to use username and password for oidc Resource Owner Password flow +- `AuthClientCredentials` to use a client secret for oidc client credential flow +- `AuthApiKey` to use an API key +- `additional_headers`: Additional headers to include in the requests. Can be used to set OpenAI/HuggingFace keys. +OpenAI/HuggingFace key looks like this: +``` +{"X-OpenAI-Api-Key": ""}, {"X-HuggingFace-Api-Key": ""} +``` +- `embedded_options`: If set, create an embedded Weaviate cluster inside the client. For a full list of options see +`weaviate.embedded.EmbeddedOptions`. +- `additional_config`: Additional and advanced configuration options for weaviate. +- `grpc_port`: The port to use for the gRPC connection. +- `grpc_secure`: Whether to use a secure channel for the underlying gRPC API. + + + +#### WeaviateDocumentStore.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### WeaviateDocumentStore.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "WeaviateDocumentStore" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: The dictionary to deserialize from. + +**Returns**: + +The deserialized component. + + + +#### WeaviateDocumentStore.count\_documents + +```python +def count_documents() -> int +``` + +Returns the number of documents present in the DocumentStore. + + + +#### WeaviateDocumentStore.filter\_documents + +```python +def filter_documents( + filters: Optional[Dict[str, Any]] = None) -> List[Document] +``` + +Returns the documents that match the filters provided. + +For a detailed specification of the filters, refer to the +DocumentStore.filter_documents() protocol documentation. + +**Arguments**: + +- `filters`: The filters to apply to the document list. + +**Returns**: + +A list of Documents that match the given filters. + + + +#### WeaviateDocumentStore.write\_documents + +```python +def write_documents(documents: List[Document], + policy: DuplicatePolicy = DuplicatePolicy.NONE) -> int +``` + +Writes documents to Weaviate using the specified policy. +We recommend using a OVERWRITE policy as it's faster than other policies for Weaviate since it uses +the batch API. +We can't use the batch API for other policies as it doesn't return any information whether the document +already exists or not. That prevents us from returning errors when using the FAIL policy or skipping a +Document when using the SKIP policy. + + + +#### WeaviateDocumentStore.delete\_documents + +```python +def delete_documents(document_ids: List[str]) -> None +``` + +Deletes all documents with matching document_ids from the DocumentStore. + +**Arguments**: + +- `document_ids`: The object_ids to delete. + + + +#### WeaviateDocumentStore.delete\_all\_documents + +```python +def delete_all_documents(*, + recreate_index: bool = False, + batch_size: int = 1000) -> None +``` + +Deletes all documents in a collection. + +If recreate_index is False, it keeps the collection but deletes documents iteratively. +If recreate_index is True, the collection is dropped and faithfully recreated. +This is recommended for performance reasons. + +**Arguments**: + +- `recreate_index`: Use drop and recreate strategy. (recommended for performance) +- `batch_size`: Only relevant if recreate_index is false. Defines the deletion batch size. +Note that this parameter needs to be less or equal to the set `QUERY_MAXIMUM_RESULTS` variable +set for the weaviate deployment (default is 10000). +Reference: https://docs.weaviate.io/weaviate/manage-objects/delete#delete-all-objects + + + +## Module haystack\_integrations.components.retrievers.weaviate.bm25\_retriever + + + +### WeaviateBM25Retriever + +A component for retrieving documents from Weaviate using the BM25 algorithm. + +Example usage: +```python +from haystack_integrations.document_stores.weaviate.document_store import WeaviateDocumentStore +from haystack_integrations.components.retrievers.weaviate.bm25_retriever import WeaviateBM25Retriever + +document_store = WeaviateDocumentStore(url="http://localhost:8080") +retriever = WeaviateBM25Retriever(document_store=document_store) +retriever.run(query="How to make a pizza", top_k=3) +``` + + + +#### WeaviateBM25Retriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: WeaviateDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Create a new instance of WeaviateBM25Retriever. + +**Arguments**: + +- `document_store`: Instance of WeaviateDocumentStore that will be used from this retriever. +- `filters`: Custom filters applied when running the retriever +- `top_k`: Maximum number of documents to return +- `filter_policy`: Policy to determine how filters are applied. + + + +#### WeaviateBM25Retriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### WeaviateBM25Retriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "WeaviateBM25Retriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### WeaviateBM25Retriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None) -> Dict[str, List[Document]] +``` + +Retrieves documents from Weaviate using the BM25 algorithm. + +**Arguments**: + +- `query`: The query text. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. + + + +## Module haystack\_integrations.components.retrievers.weaviate.embedding\_retriever + + + +### WeaviateEmbeddingRetriever + +A retriever that uses Weaviate's vector search to find similar documents based on the embeddings of the query. + + + +#### WeaviateEmbeddingRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: WeaviateDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + distance: Optional[float] = None, + certainty: Optional[float] = None, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Creates a new instance of WeaviateEmbeddingRetriever. + +**Arguments**: + +- `document_store`: Instance of WeaviateDocumentStore that will be used from this retriever. +- `filters`: Custom filters applied when running the retriever. +- `top_k`: Maximum number of documents to return. +- `distance`: The maximum allowed distance between Documents' embeddings. +- `certainty`: Normalized distance between the result item and the search vector. +- `filter_policy`: Policy to determine how filters are applied. + +**Raises**: + +- `ValueError`: If both `distance` and `certainty` are provided. +See https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables to learn more about +`distance` and `certainty` parameters. + + + +#### WeaviateEmbeddingRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### WeaviateEmbeddingRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "WeaviateEmbeddingRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### WeaviateEmbeddingRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + distance: Optional[float] = None, + certainty: Optional[float] = None) -> Dict[str, List[Document]] +``` + +Retrieves documents from Weaviate using the vector search. + +**Arguments**: + +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. +- `distance`: The maximum allowed distance between Documents' embeddings. +- `certainty`: Normalized distance between the result item and the search vector. + +**Raises**: + +- `ValueError`: If both `distance` and `certainty` are provided. +See https://weaviate.io/developers/weaviate/api/graphql/search-operators#variables to learn more about +`distance` and `certainty` parameters. + + + +## Module haystack\_integrations.components.retrievers.weaviate.hybrid\_retriever + + + +### WeaviateHybridRetriever + +A retriever that uses Weaviate's hybrid search to find similar documents based on the embeddings of the query. + + + +#### WeaviateHybridRetriever.\_\_init\_\_ + +```python +def __init__(*, + document_store: WeaviateDocumentStore, + filters: Optional[Dict[str, Any]] = None, + top_k: int = 10, + alpha: Optional[float] = None, + max_vector_distance: Optional[float] = None, + filter_policy: Union[str, FilterPolicy] = FilterPolicy.REPLACE) +``` + +Creates a new instance of WeaviateHybridRetriever. + +**Arguments**: + +- `document_store`: Instance of WeaviateDocumentStore that will be used from this retriever. +- `filters`: Custom filters applied when running the retriever. +- `top_k`: Maximum number of documents to return. +- `alpha`: Blending factor for hybrid retrieval in Weaviate. Must be in the range ``[0.0, 1.0]``. +Weaviate hybrid search combines keyword (BM25) and vector scores into a single ranking. ``alpha`` controls +how much each part contributes to the final score: + +- ``alpha = 0.0``: only keyword (BM25) scoring is used. +- ``alpha = 1.0``: only vector similarity scoring is used. +- Values in between blend the two; higher values favor the vector score, lower values favor BM25. + +If ``None``, the Weaviate server default is used. + +See the official Weaviate docs on Hybrid Search parameters for more details: +`Hybrid search parameters `_ +`Hybrid Search `_ +- `max_vector_distance`: Optional threshold that restricts the vector part of the hybrid search to candidates within a maximum +vector distance. Candidates with a distance larger than this threshold are excluded from the vector portion +before blending. + +Use this to prune low-quality vector matches while still benefitting from keyword recall. Leave ``None`` to +use Weaviate's default behavior without an explicit cutoff. + +See the official Weaviate docs on Hybrid Search parameters for more details: +- `Hybrid search parameters `_ +- `Hybrid Search `_ +- `filter_policy`: Policy to determine how filters are applied. + + + +#### WeaviateHybridRetriever.to\_dict + +```python +def to_dict() -> Dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with serialized data. + + + +#### WeaviateHybridRetriever.from\_dict + +```python +@classmethod +def from_dict(cls, data: Dict[str, Any]) -> "WeaviateHybridRetriever" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +#### WeaviateHybridRetriever.run + +```python +@component.output_types(documents=List[Document]) +def run(query: str, + query_embedding: List[float], + filters: Optional[Dict[str, Any]] = None, + top_k: Optional[int] = None, + alpha: Optional[float] = None, + max_vector_distance: Optional[float] = None + ) -> Dict[str, List[Document]] +``` + +Retrieves documents from Weaviate using hybrid search. + +**Arguments**: + +- `query`: The query text. +- `query_embedding`: Embedding of the query. +- `filters`: Filters applied to the retrieved Documents. The way runtime filters are applied depends on +the `filter_policy` chosen at retriever initialization. See init method docstring for more +details. +- `top_k`: The maximum number of documents to return. +- `alpha`: Blending factor for hybrid retrieval in Weaviate. Must be in the range ``[0.0, 1.0]``. +Weaviate hybrid search combines keyword (BM25) and vector scores into a single ranking. ``alpha`` controls +how much each part contributes to the final score: + +- ``alpha = 0.0``: only keyword (BM25) scoring is used. +- ``alpha = 1.0``: only vector similarity scoring is used. +- Values in between blend the two; higher values favor the vector score, lower values favor BM25. + +If ``None``, the Weaviate server default is used. + +See the official Weaviate docs on Hybrid Search parameters for more details: +`Hybrid search parameters `_ +`Hybrid Search `_ +- `max_vector_distance`: Optional threshold that restricts the vector part of the hybrid search to candidates within a maximum +vector distance. Candidates with a distance larger than this threshold are excluded from the vector portion +before blending. + +Use this to prune low-quality vector matches while still benefitting from keyword recall. Leave ``None`` to +use Weaviate's default behavior without an explicit cutoff. + +See the official Weaviate docs on Hybrid Search parameters for more details: +- `Hybrid search parameters `_ +- `Hybrid Search `_ diff --git a/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weights_and_bias.md b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weights_and_bias.md new file mode 100644 index 0000000000..c18314d513 --- /dev/null +++ b/docs-website/reference_versioned_docs/version-2.20-unstable/integrations-api/weights_and_bias.md @@ -0,0 +1,271 @@ +--- +title: "weights and bias" +id: integrations-weights-bias +description: "Weights & Bias integration for Haystack" +slug: "/integrations-weights-bias" +--- + + + +## Module haystack\_integrations.components.connectors.weave.weave\_connector + + + +### WeaveConnector + +Collects traces from your pipeline and sends them to Weights & Biases. + +Add this component to your pipeline to integrate with the Weights & Biases Weave framework for tracing and +monitoring your pipeline components. + +Note that you need to have the `WANDB_API_KEY` environment variable set to your Weights & Biases API key. + +NOTE: If you don't have a Weights & Biases account it will interactively ask you to set one and your input +will then be stored in ~/.netrc + +In addition, you need to set the `HAYSTACK_CONTENT_TRACING_ENABLED` environment variable to `true` in order to +enable Haystack tracing in your pipeline. + +To use this connector simply add it to your pipeline without any connections, and it will automatically start +sending traces to Weights & Biases. + +**Example**: + +```python +import os + +from haystack import Pipeline +from haystack.components.builders import ChatPromptBuilder +from haystack.components.generators.chat import OpenAIChatGenerator +from haystack.dataclasses import ChatMessage + +from haystack_integrations.components.connectors import WeaveConnector + +os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true" + +pipe = Pipeline() +pipe.add_component("prompt_builder", ChatPromptBuilder()) +pipe.add_component("llm", OpenAIChatGenerator(model="gpt-3.5-turbo")) +pipe.connect("prompt_builder.prompt", "llm.messages") + +connector = WeaveConnector(pipeline_name="test_pipeline") +pipe.add_component("weave", connector) + +messages = [ + ChatMessage.from_system( + "Always respond in German even if some input data is in other languages." + ), + ChatMessage.from_user("Tell me about {{location}}"), +] + +response = pipe.run( + data={ + "prompt_builder": { + "template_variables": {"location": "Berlin"}, + "template": messages, + } + } +) +print(response["llm"]["replies"][0]) +``` + + You should then head to `https://wandb.ai//projects` and see the complete trace for your pipeline under + the pipeline name you specified, when creating the `WeaveConnector` + + + +#### WeaveConnector.\_\_init\_\_ + +```python +def __init__(pipeline_name: str, + weave_init_kwargs: Optional[dict[str, Any]] = None) -> None +``` + +Initialize WeaveConnector. + +**Arguments**: + +- `pipeline_name`: The name of the pipeline you want to trace. +- `weave_init_kwargs`: Additional arguments to pass to the WeaveTracer client. + + + +#### WeaveConnector.warm\_up + +```python +def warm_up() -> None +``` + +Initialize the WeaveTracer. + + + +#### WeaveConnector.to\_dict + +```python +def to_dict() -> dict[str, Any] +``` + +Serializes the component to a dictionary. + +**Returns**: + +Dictionary with all the necessary information to recreate this component. + + + +#### WeaveConnector.from\_dict + +```python +@classmethod +def from_dict(cls, data: dict[str, Any]) -> "WeaveConnector" +``` + +Deserializes the component from a dictionary. + +**Arguments**: + +- `data`: Dictionary to deserialize from. + +**Returns**: + +Deserialized component. + + + +## Module haystack\_integrations.tracing.weave.tracer + + + +### WeaveSpan + +A bridge between Haystack's Span interface and Weave's Call object. + +Stores metadata about a component execution and its inputs and outputs, and manages the attributes/tags +that describe the operation. + + + +#### WeaveSpan.set\_tag + +```python +def set_tag(key: str, value: Any) -> None +``` + +Set a tag by adding it to the call's inputs. + +**Arguments**: + +- `key`: The tag key. +- `value`: The tag value. + + + +#### WeaveSpan.raw\_span + +```python +def raw_span() -> Any +``` + +Access to the underlying Weave Call object. + + + +#### WeaveSpan.get\_correlation\_data\_for\_logs + +```python +def get_correlation_data_for_logs() -> dict[str, Any] +``` + +Correlation data for logging. + + + +#### WeaveSpan.set\_content\_tag + +```python +def set_content_tag(key: str, value: Any) -> None +``` + +Set a single tag containing content information. + +Content is sensitive information such as +- the content of a query +- the content of a document +- the content of an answer + +By default, this behavior is disabled. To enable it +- set the environment variable `HAYSTACK_CONTENT_TRACING_ENABLED` to `true` or +- override the `set_content_tag` method in a custom tracer implementation. + +**Arguments**: + +- `key`: the name of the tag. +- `value`: the value of the tag. + + + +### WeaveTracer + +Implements a Haystack's Tracer to make an interface with Weights and Bias Weave. + +It's responsible for creating and managing Weave calls, and for converting Haystack spans +to Weave spans. It creates spans for each Haystack component run. + + + +#### WeaveTracer.\_\_init\_\_ + +```python +def __init__(project_name: str, **weave_init_kwargs: Any) -> None +``` + +Initialize the WeaveTracer. + +**Arguments**: + +- `project_name`: The name of the project to trace, this is will be the name appearing in Weave project. +- `weave_init_kwargs`: Additional arguments to pass to the Weave client. + + + +#### WeaveTracer.current\_span + +```python +def current_span() -> Optional[Span] +``` + +Get the current active span. + + + +#### WeaveTracer.trace + +```python +@contextlib.contextmanager +def trace(operation_name: str, + tags: Optional[dict[str, Any]] = None, + parent_span: Optional[WeaveSpan] = None) -> Iterator[WeaveSpan] +``` + +A context manager that creates and manages spans for tracking operations in Weights & Biases Weave. + +It has two main workflows: + +A) For regular operations (operation_name != "haystack.component.run"): + Creates a Weave Call immediately + Creates a WeaveSpan with this call + Sets any provided tags + Yields the span for use in the with block + When the block ends, updates the call with pipeline output data + +B) For component runs (operation_name == "haystack.component.run"): + Creates a WeaveSpan WITHOUT a call initially (deferred creation) + Sets any provided tags + Yields the span for use in the with block + Creates the actual Weave Call only at the end, when all component information is available + Updates the call with component output data + +This distinction is important because Weave's calls can't be updated once created, but the content +tags are only set on the Span at a later stage. To get the inputs on call creation, we need to create +the call after we yield the span. diff --git a/docs-website/reference_versioned_sidebars/version-2.20-unstable-sidebars.json b/docs-website/reference_versioned_sidebars/version-2.20-unstable-sidebars.json new file mode 100644 index 0000000000..f7d77df3d5 --- /dev/null +++ b/docs-website/reference_versioned_sidebars/version-2.20-unstable-sidebars.json @@ -0,0 +1,51 @@ +{ + "reference": [ + { + "type": "doc", + "id": "api-index", + "label": "API Overview" + }, + { + "type": "category", + "label": "Haystack API", + "link": { + "type": "generated-index", + "title": "Haystack API" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "haystack-api" + } + ] + }, + { + "type": "category", + "label": "Integrations API", + "link": { + "type": "generated-index", + "title": "Integrations API" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "integrations-api" + } + ] + }, + { + "type": "category", + "label": "Experiments API", + "link": { + "type": "generated-index", + "title": "Experiments API" + }, + "items": [ + { + "type": "autogenerated", + "dirName": "experiments-api" + } + ] + } + ] +} diff --git a/docs-website/reference_versions.json b/docs-website/reference_versions.json index ecf3cdfd83..9272f6bf28 100644 --- a/docs-website/reference_versions.json +++ b/docs-website/reference_versions.json @@ -1,5 +1 @@ -[ - "2.19", - "2.18", - "2.17" -] +["2.20-unstable", "2.19", "2.18", "2.17"] \ No newline at end of file diff --git a/docs-website/src/pages/versions.js b/docs-website/src/pages/versions.js index 8ce6fd957f..bfc29d1664 100644 --- a/docs-website/src/pages/versions.js +++ b/docs-website/src/pages/versions.js @@ -4,13 +4,24 @@ import React from 'react'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; +import {useVersions} from '@docusaurus/plugin-content-docs/client'; import Link from '@docusaurus/Link'; import Layout from '@theme/Layout'; export default function Versions() { const {siteConfig} = useDocusaurusContext(); - const versions = require('../../versions.json'); - const currentVersion = versions[0]; + const allVersions = useVersions('default'); + + // Filter out unstable versions, "next", and "current" to get stable versions + const stableVersions = allVersions.filter(v => + !v.name.includes('unstable') && + v.name !== 'next' && + v.name !== 'current' + ); + + // Find the lastVersion (current stable) - it's the one with isLast: true or the first stable version + const lastVersion = stableVersions.find(v => v.isLast) || stableVersions[0]; + const pastVersions = stableVersions.filter(v => v !== lastVersion); return (

Current version (Stable)

-

Documentation for the current stable release (v{currentVersion}).

+

Documentation for the current stable release (v{lastVersion?.name || lastVersion?.label}).

  • Documentation @@ -39,17 +50,17 @@ export default function Versions() {
- {versions.length > 1 && ( + {pastVersions.length > 0 && (

Past Versions

Here you can find documentation for previous versions of Haystack.