# deepset AI Platform Documentation
> Everything you need to build with deepset.
This file contains all documentation content in a single document following the llmstxt.org standard.
## FAQ overview
# FAQ
Find answers to common questions, including topics that often come up with support.
## Available FAQs
{useCurrentSidebarCategory().items.map((item) => (
{'href' in item ?
```
To retrieve more files, make another request with updated pagination parameters. If you're using a script or app, iterate through the pages until you retrieve all the items or reach the desired number.
In cursor-based pagination, you can use the `before` or `after` parameter to view items preceding or following a specific item ID. For instance, to display 10 evaluation sets preceding the one with ID ab61f0cd-316a-4c66-879f-65dbe28ced1e, include this ID in the before parameter as shown below:
```
curl --request GET \
--url 'https://api.cloud.deepset.ai/api/v1/workspaces/workspace_name/evaluation_sets?limit=10&before=ab61f0cd-316a-4c66-879f-65dbe28ced1e' \
--header 'accept: application/json' \
--header 'authorization: Bearer
```
### Date-Time
All date-time values are in the UTC time in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format, which follows the convention: `YYYY-MM-DDTHH:MM:SS.sssZ`, where:
- `YYYY` is the year
- `MM` is the month
- `DD` is the day
- `T` is the delimiter that separates the date from time
- `HH` is the hour in a 24-hour clock format
- `MM` is minutes
- `SS` is seconds
- `.sss` is fractional seconds, can be one or more digits, represent a decimal fraction of a second
- `Z` is a suffix that indicates that the time is in UTC.
For example, `2023-04-25T07:37:58.326042Z` represents 25th April 2023, 7:37 and 58.326042 seconds in UTC.
### Timeouts
The timeout for search is 2 minutes. The timeout for other requests is 3 minutes.
## Status and Error Codes
Creates a job.
---
## Create Shared Job
Creates a link to a job prototype you can then share with others to see a query results report.
---
## Delete Job
Deletes a job.
---
## Delete Query Set
Deletes a query set.
---
## Edit Shared Job
Update a shared job.
---
## Get Export Job Results To Csv
Exports job results as csv file.
---
## Get Job
Returns a job.
---
## Get Job Results
Returns job results.
---
## Get Jobs
Returns jobs.
---
## Get Presigned Download Url
Returns a presigned URL to download job results as a CSV file. Use for large job results.
---
## Get Query Set
Returns a query set.
---
## Get Query Sets
Returns query sets.
---
## Get Shared Job
Get a shared job.
---
## Get Shared Jobs
Get a list of shared jobs.
---
## Import Query Set
Imports a query set into deepset Cloud.
---
## Jobs
deepset Cloud jobs API
Security Scheme Type:
http
HTTP Authorization Scheme:
bearer
---
## Revoke Shared Job
Revoke a shared job.
---
## Start Job
Starts a job.
"}],"title":"Headers","type":"object"},"url":{"description":"The URL that receives the callback. deepset will send a POST request to this URL when the job finishes. The request will contain the following JSON Body: {'job_id': , 'status': }'.","examples":["https://example.com"],"title":"URL","type":"string"}},"required":["url"],"title":"JobCallback","type":"object"},"title":"Callbacks","type":"array"}},"title":"StartJobBody","type":"object"}}}}}
>
---
## Update Job
Updates a job.
---
## Activate Pipeline
Activates the pipeline.
---
## Add Exposed Pipeline
Expose a pipeline as an MCP tool.
The pipeline must exist in the same workspace. Optionally provide
a custom tool name and description that will be shown to MCP clients.
---
## Add Files
Adds files to a dataset by calling the file service's add_file method for each file.
---
## Add OpenSearch credentials
Add credentials to your own OpenSearch cluster.
---
## Add Role
Adds a role to the specified organization.
---
## Add S3 Credentials
Add credentials to your own S3 bucket.
---
## Apply Pipeline Migrations
Apply detected migrations to a pipeline asynchronously.
Creates a migration job and dispatches it to a background worker.
Poll the migrations endpoint to track progress.
---
## Assign Role
Assign Role
---
## Assign Search History Labels
Assigns one or more labels to a search history record. Existing labels are preserved.
---
## Bulk Assign Search History Labels
Assigns one or more labels to multiple search history records at once.
---
## Bulk Unassign Search History Labels
Removes one or more labels from multiple search history records at once.
---
## Chat
Run a chat query. Chat pipelines are based on the `chat` template that uses a search session to include search
history in the chat. You can then specify how many search history items (query and answer) from a given search
session you want to display in the chat. You'll need a search session ID to run the query. Use the search session
endpoints to list or create search sessions.
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Parameters you can use to customize the pipeline. For details, see [Haystack documentation for the pipeline `run()` method](https://docs.haystack.deepset.ai/reference/pipeline-api). These filters can be used to pass additional parameters to the pipeline.(Haystack is the underlying technology for deepset.) ","title":"Pipeline Parameters"},"queries":{"description":"A list of queries you want to run through the pipeline.","items":{"type":"string"},"title":"Queries","type":"array"},"search_session_id":{"description":"The ID of the search session you want to use for chat.","format":"uuid","title":"Search Session ID","type":"string"},"view_prompts":{"default":false,"description":"Adds the runtime prompts of all nodes to the response. (Pipeline runs in debug mode.)","title":"View prompts","type":"boolean"}},"required":["queries","search_session_id"],"title":"ChatQuery","type":"object"}}},"required":true}}
>
---
## Chat Stream
Run a chat query and return the answer as stream. Chat pipelines are based on the `chat` template that uses a search
session to include search history in the chat. You can then specify how many search history items (query and answer)
from a given search session you want to display in the chat. You'll need a search session ID to run the query.
Use the search session endpoints to list or create search sessions.
Options:
- The full result can be accessed as the last stream message if `include_result=True`.
- Tool calls are streamed if `include_tool_calls=True`. Defaults to `rendered` where tool calls are converted to
markdown text deltas.
- Tool call results are streamed if `include_tool_call_result=True`.
- Reasoning output is streamed if `include_reasoning=True`.
Event data format where `delta`, `result`, `tool_call_delta`, `tool_call_result`, `reasoning`, `ping` and `error`
are mutually exclusive:
```
{
"query_id": UUID,
"type": Literal["delta", "result", "error", "tool_call_delta", "tool_call_result", "reasoning", "ping"],
"delta": Optional[StreamDelta],
"result": Optional[DeepsetCloudQueryResponse],
"error": Optional[str],
"tool_call_delta": Optional[ToolCallDelta],
"tool_call_result": Optional[ToolCallResult],
"reasoning": Optional[ReasoningDelta],
"index": Optional[int],
"start": Optional[bool],
"finish_reason": Optional[str],
}
```
StreamDelta format:
```
{
"text": str,
"meta": Optional[dict[str, Any]],
}
```
ToolCallDelta format:
```
{
"index": int,
"tool_name": Optional[str],
"id": Optional[str],
"arguments": Optional[str],
}
```
ToolCallResult format:
```
{
"result": str,
"origin": {
"tool_name": str,
"arguments": dict[str, Any],
"id": Optional[str],
},
"error": bool,
}
```
ReasoningDelta format:
```
{
"reasoning_text": str,
"extra": dict[str, Any],
}
```
Example code to consume the stream in Python:
```python
from httpx_sse import EventSource
TOKEN = "MY_TOKEN"
PIPELINE_URL = "https://api.cloud.deepset.ai/api/v1/workspaces/MY_WORKSPACE/pipelines/MY_PIPELINE"
SEARCH_SESSION_ID = "MY_SEARCH_SESSION_ID"
async def main():
query = {
"query": "How does streaming work with deepset?",
"include_result": True,
"include_tool_calls": True,
"include_tool_call_results": True,
"search_session_id": SEARCH_SESSION_ID
}
headers = {
"Authorization": f"Bearer {TOKEN}"
}
async with httpx.AsyncClient(base_url=PIPELINE_URL, headers=headers, timeout=httpx.Timeout(300.0)) as client:
async with client.stream("POST", "/chat-stream", json=query) as response:
# Check if the response is successful
if response.status_code != 200:
await response.aread()
print(f"An error occured with status code: {response.status_code}")
print(response.json()["errors"][0])
return
event_source = EventSource(response)
# Stream the response
async for event in event_source.aiter_sse():
event_data = json.loads(event.data)
chunk_type = event_data["type"]
# Check the type of the chunk and print the data accordingly
match chunk_type:
# Delta chunk contains the next text chunk of the answer
case "delta":
delta = event_data["delta"]
if event_data.get("start"):
print(f"\n\nAnswer: ", flush=True, end="")
token: str = delta["text"]
print(token, flush=True, end="\n" if event_data.get("finish_reason") else "")
# Result chunk contains the final pipeline result
case "result":
print("\n\nPipeline result: ")
print(json.dumps(event_data["result"]))
# Error chunk contains the error message
case "error":
print("\n\nAn error occurred while streaming:")
print(event_data["error"])
case "tool_call_delta":
tool_call_delta = event_data["tool_call_delta"]
if tool_call_delta["tool_name"]:
tool_id = tool_call_delta["id"]
tool_name = tool_call_delta["tool_name"]
print(f"\n\nTool call {tool_id} started {tool_name} with arguments: ")
elif tool_call_delta["arguments"]:
print(tool_call_delta["arguments"], flush=True, end="")
case "tool_call_result":
tool_call_result = event_data["tool_call_result"]
tool_id = tool_call_result["origin"]["id"]
tool_name = tool_call_result["origin"]["tool_name"]
if tool_call_result["error"]:
print(f"\n\nTool call {tool_name} with id {tool_id} failed.")
else:
print(f"\n\nTool call {tool_name} with id {tool_id} result:")
print(tool_call_result["result"])
case "reasoning":
reasoning = event_data["reasoning"]
if event_data.get("start"):
print(f"\n\nReasoning: ")
print(f"{reasoning['reasoning_text']}", flush=True, end="")
asyncio.run(main())
```
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"include_reasoning":{"default":false,"description":"Includes the reasoning output under key 'reasoning' when set to `true`. Defaults to `false`.\nThe reasoning output may include the intermediate steps taken by the model to arrive at the final answer. Example reasoning output:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"reasoning\", \"reasoning\": {\"reasoning_text\": \"This is the plan:\\nStep 1: Retrieve documents\\nStep 2: Process documents\\nStep 3: Generate answer\", \"extra\": {}}}\n```","title":"Include Reasoning","type":"boolean"},"include_result":{"default":false,"description":"Includes the result of the pipeline at the end of the stream under key 'result'.","title":"Include Result","type":"boolean"},"include_tool_call_results":{"default":false,"description":"Includes the tool call results under key 'tool_call_result' when set to `true`. Defaults to `false`.\nExample tool call result event:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_result\", \"tool_call_result\": {\"origin\": {\"tool_name\": \"example_tool\", \"arguments\": {\"arg1\": \"val1\"}, \"index\": 0}, \"result\": \"This is an example result.\", \"error\": false}}\n```","title":"Include Tool Call Results","type":"boolean"},"include_tool_calls":{"anyOf":[{"type":"boolean"},{"const":"rendered","type":"string"}],"default":"rendered","description":"Includes tool calls as tool call delta objects under key 'tool_call_delta' when set to `true`. When set to `rendered`, tool call events are rendered as markdown text instead. This parameter only affects the stream (not the final result) and is only effective when the pipeline makes tool calls (e.g. using the Agent component). Defaults to `rendered`.\nExample tool call delta events:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"tool_name\": \"example_tool\", \"index\": 0, \"id\": \"tool_call_01\"}}\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"arguments\": \"{\\\"arg1\\\": \", \"index\": 0}}\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"arguments\": \"\\\"val1\\\"}\", \"index\": 0}}\n```","title":"Include Tool Calls"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Parameters you can use to customize the pipeline. For details, see [Haystack documentation for the pipeline `run()` method](https://docs.haystack.deepset.ai/reference/pipeline-api). These filters can be used to pass additional parameters to the pipeline.(Haystack is the underlying technology for deepset.) ","title":"Pipeline Parameters"},"pipeline_version_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The pipeline version ID to use for serverless execution. Only valid when serverless is True. If not provided, the pipeline's default version is used.","title":"Pipeline Version Id"},"query":{"description":"The search query.","title":"Query","type":"string"},"search_session_id":{"description":"The ID of the search session you want to use for chat.","format":"uuid","title":"Search Session ID","type":"string"},"serverless":{"default":false,"description":"If True, run the pipeline via utilities without requiring deployment.","title":"Serverless","type":"boolean"},"store_search_history":{"default":true,"description":"If False, the query and response are not persisted to the chat history for the given search_session_id. Currently only honored in serverless mode.","title":"Store Search History","type":"boolean"},"view_prompts":{"default":false,"description":"Adds the runtime prompts of all nodes to the response. (Pipeline runs in debug mode.)","title":"View prompts","type":"boolean"}},"required":["query","search_session_id"],"title":"ChatStreamingQuery","type":"object"}}},"required":true}}
>
---
## Clear Search History Note
Removes the note from a search history record.
---
## Close Session
Closes the session and starts the ingestion process.
If the session is not closed explicitly, the session will be automatically closed after 24 hours.
---
## Connect Integration
Connects a secret to a provider.
---
## Connect Workspace Integration
Connects a secret to a provider for a workspace.
---
## Count Documents
Counts the number of documents in the pipeline.
---
## Create Components Dynamic Input Output
Returns updated input output schemas for Haystack components containing dynamic parameters.
Dynamic parameters are component input output parameters, which are postulated by component init params.
---
## Create Feedback
Adds user feedback to a specific response.
Use this endpoint to collect and store user ratings, comments, "
"or other feedback about the quality or relevance of a response.
---
## Create Index
Creates a new pipeline index.
---
## Create Mcp Config
Create an MCP server configuration for a workspace.
This enables the workspace to expose selected pipelines as MCP tools
that external clients (Claude, ChatGPT, etc.) can invoke.
---
## Create Organization Model
Creates a new organization-level custom model definition.
---
## Create Pipeline
Creates a pipeline YAML file.
---
## Create Prompt Template
Creates a prompt template. The template is saved under custom templates in Prompt Studio.
---
## Create Prototype
Creates a link to a pipeline prototype you can then share with others to try out.
---
## Create Query Pipeline Version
Create Query Pipeline Version
---
## Create Search Session
Creates a search session you can later use in chat as chat history.
---
## Create Secret
Stores your secret in Haystack Enterprise Platform and returns the unique identifier for the secret.
---
## Create Skill
Create Skill
---
## Create Support Request
Reach out to our support team for help with your issue.
---
## Create Tags
Creates tags for a specified pipeline.
Users will be able to choose these tags when giving feedback "
"on reponses generated by this pipeline.
Use tags to structure and categorize user feedback.
---
## Create Token
Creates the API key that you can use to connect Haystack Enterprise Platform to your application.
---
## Create Tool
Create a new tool.
This unified endpoint handles creation for all tool types
(MCP server tools and pipeline tools).
For MCP server tools, provide mcp_server data with URL, transport type, and
optional secret ID. For pipeline tools, provide pipeline data with pipeline ID
and optional input/output mappings.
---
## Create Upload Session
Creates a session for uploading files and file metadata. The session remains active for 24 hours. You can upload up to 10 000 files in a session.
///${filename}`, where filename is . or ..meta.json for meta files.","title":"AWS Prefix","properties":{"fields":{"additionalProperties":{"type":"string"},"description":"The fields to include in the request to the presigned URL. These fields are required in the body of each request.","examples":[{"key":"7a3749f5-448a-475f-8d94-b87872a0342d/7d0a7027-5b3d-48f2-97d6-28fc138f2821/upload_sessions/5c38259b-19ee-4a99-8f38-7c3007dcaaae/","policy":"","x-amz-algorithm":"AWS4-HMAC-SHA256","x-amz-credential":"","x-amz-date":"20230419T152408Z","x-amz-security-token":"","x-amz-signature":""}],"title":"Request fields","type":"object"},"url":{"description":"The presigned URL to upload the file to. This URL was generated using the AWS ShareObjectPresignedUrl feature. To learn more, see [AWS Documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html).","title":"Presigned URL","type":"string"}},"required":["url","fields"],"type":"object"},"documentation_url":{"default":"https://docs.cloud.deepset.ai/docs/upload-files","description":"The URL to the documentation of the session.","title":"Session Documentation URL","type":"string"},"expires_at":{"description":"The time when the session expires.","format":"date-time","title":"Session Expires At","type":"string"},"session_id":{"description":"Unique identifier of a session.","format":"uuid","title":"Session ID","type":"string"}},"required":["expires_at","aws_prefixed_request_config"],"title":"UploadSession","type":"object"}}},"description":"Your session is created."},"402":{"description":"You can't upload to this workspace through upload sessions on a free plan. To use this feature, upgrade to a paid plan. You can still upload files through the UI at no cost."},"406":{"description":"You can't upload files because you've reached the maximum number of upload sessions allowed per user. Close existing sessions using the Close Session endpoint before starting a new one."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"}}}
>
---
## Create Workspace
Creates a workspace within an organization.
---
## Create Workspace Model
Creates a new custom model definition in the workspace.
---
## Create Workspace Secret
Stores your secret in Haystack Enterprise Platform and returns the unique identifier for the secret.
---
## Create Workspace Token
Create Workspace Token
---
## Delete Exposed Pipeline
Remove a pipeline from the MCP server (stop exposing it as a tool).
---
## Delete Feedback
Deletes a feedback entry. You can't bring back a deleted feedback entry.
---
## Delete File
Removes the file from the workspace.
---
## Delete Files
Deletes files specified in the `names` parameter from a workspace. If `names` is empty, it deletes all files.
---
## Delete Index
Deletes a pipeline index.
---
## Delete Mcp Config
Delete the MCP server configuration, disabling MCP access for this workspace.
---
## Delete OpenSearch credentials
Delete credentials to your own OpenSearch cluster.
---
## Delete Organization Model
Deletes an organization-level custom model definition.
---
## Delete Pipeline
Removes a pipeline from deepset within the specified workspace.
---
## Delete Pipeline Search History
Deletes search history for a specific pipeline.
Provide search_history_ids in the request body: \{"search_history_ids": ["uuid1", "uuid2", ...]\}
Maximum 100 IDs allowed. If no body is provided or search_history_ids is null,
deletes all search history for the pipeline.
Deletion is done in the background and may take a few seconds to take effect.
---
## Delete Prompt Templates
Deletes the prompt template with the given ID.
---
## Delete Role
Deletes a role from the specified organization.
user(s)."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"}}}
>
---
## Delete S3 Credentials
Delete credentials to your own S3 bucket.
---
## Delete Search History Label
Removes a label from all search history records in a pipeline.
---
## Delete Search Session
Delete a search session together with its search history.
---
## Delete Skill
Delete Skill
---
## Delete Tags
Permanently deletes tags with the given IDs. You can only delete tags that aren't connected to feedback entries.
---
## Delete Tool
Delete a tool.
Permanently removes a tool from the workspace. This operation cannot be undone.
The tool will no longer be available for use by agents in this workspace.
---
## Delete User
Deletes a user from Haystack Enterprise Platform.
---
## Delete User Search History
Deletes all search history for a specific user.
Callers may always delete their own search history; deleting another user's
search history requires SEARCH_HISTORY:WRITE on the workspace.
Deletion is done in the background and may take a few seconds to take effect.
---
## Delete Workspace
Deletes a workspace and everything that is associated with it. Be careful as this action cannot be undone.
---
## Delete Workspace Model
Deletes a workspace-scoped custom model definition.
---
## Delete Workspace Token
Deletes a workspace-scoped API token.
---
## Deploy Index
Deploys a pipeline index to deepset.
---
## Deploy Pipeline
Deploys a pipeline in deepset.
---
## Detect Pipeline Migrations
Detect possible migrations in a pipeline.
Call this endpoint after a successful validation to check if the pipeline
contains components that can be removed/migrated.
---
## Disconnect Integration
Disconnects an connected integration.
---
## Disconnect Workspace Integration
Disconnects a connected integration for a workspace.
---
## Edit Shared Prototype
Updates the shared prototype description and file options.
---
## Export Feedback
Exports feedback to a csv file.
---
## Export Search History
Exports the search history to a downloadable CSV file. The file includes search queries, answers, prompts,feedback, and other metadata. If a single search entry has multiple feedback entries,each feedback entry appears in a separate row.
prefix (for example, meta.model or meta.finish_reason).","in":"query","name":"columns","required":false,"schema":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"description":"List of columns to include in the CSV. If omitted, all columns are included. Supported fixed columns: query, answer, prompt, feedback_score, feedback_comment, feedback_tags, rank, file_name, file_id, query_id, result_id, created_at, duration, session_id, user_given_name, user_family_name, pipeline_name, api_key_name, filters, params, result_type, result_score, documents, context, feedback_id, feedback_bookmarked, feedback_created_at, feedback_created_by_user_id, labels. Dynamic pipeline meta fields can be included using the meta. prefix (for example, meta.model or meta.finish_reason).","title":"Columns"}},{"description":"Maximum number of search history items to export. Defaults to 10,000.","in":"query","name":"limit","required":false,"schema":{"default":100000,"description":"Maximum number of search history items to export. Defaults to 10,000.","title":"Limit","type":"integer"}},{"description":"Optional pipeline ID to filter search history","in":"query","name":"pipeline_id","required":false,"schema":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"Optional pipeline ID to filter search history","title":"Pipeline Id"}},{"description":"The OData filter you want to use to in your query. It supports exact match and `AND` operations. For example, to filter for a metadata `category:news` and `published_date` greater than or equal to January 1 2025, here's what the URL could look like: 'url = \"https://api.cloud.deepset.ai/api/v1/workspaces/production/files?limit=10&filter=category eq 'news' and published_date ge '2025-01-01' \"'. OData filters only work with cursor-based pagination (leave the `page_number` field blank to enable it).To learn more about the OData filter syntax, see: [Querying Data](https://www.odata.org/getting-started/basic-tutorial/#queryData).Supported filter fields:`answer``api_key``client_source_path``created_at``created_by``deployment_id``duration``feedbacks``feedbacks/bookmarked``feedbacks/comment``feedbacks/result_id``feedbacks/score``labels``note``pipeline_version_id``query``query_id``request/filters``request/params``search_session_id``session_id``status``tags/tag_id``trace_id`","in":"query","name":"filter","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The OData filter you want to use to in your query. It supports exact match and `AND` operations. For example, to filter for a metadata `category:news` and `published_date` greater than or equal to January 1 2025, here's what the URL could look like: 'url = \"https://api.cloud.deepset.ai/api/v1/workspaces/production/files?limit=10&filter=category eq 'news' and published_date ge '2025-01-01' \"'. OData filters only work with cursor-based pagination (leave the `page_number` field blank to enable it).To learn more about the OData filter syntax, see: [Querying Data](https://www.odata.org/getting-started/basic-tutorial/#queryData).Supported filter fields:`answer``api_key``client_source_path``created_at``created_by``deployment_id``duration``feedbacks``feedbacks/bookmarked``feedbacks/comment``feedbacks/result_id``feedbacks/score``labels``note``pipeline_version_id``query``query_id``request/filters``request/params``search_session_id``session_id``status``tags/tag_id``trace_id`","title":"Filter"}}]}
>
---
## Generate Integrated Pipeline Yaml
:::caution deprecated
This endpoint has been deprecated and may be replaced or removed in future versions of the API.
:::
Generate Integrated Pipeline Yaml
---
## Get All Documents Stream
Returns documents created for a pipeline.
Without pagination parameters, all documents are streamed. To paginate, pass `page_number`
(1-indexed) together with `limit` in the request body. Paginated responses include
`X-Total-Count` and `X-Has-More` response headers.
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"limit":{"anyOf":[{"exclusiveMinimum":0,"type":"integer"},{"type":"null"}],"description":"Limits the number of documents returned.","title":"Limit"},"page_number":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"The page number to return when paginating. Requires 'limit' to be set. Pages are 1-indexed.","title":"Page Number"},"return_embedding":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Returns vector representations of the documents.","title":"Return Embedding"},"use_prefiltering":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Specifies if documents should be prefiltered in the document store instead of within the retriever. DEPRECATED: This parameter will be removed in a future version. Use efficient_filtering parameter instead.","title":"Use Prefiltering"}},"title":"FetchDocumentsParams","type":"object"}}},"required":true}}
>
---
## Get Available Components
Returns components available to be used in Haystack Enterprise Platform.
By default, it returns the components for the deepset domain.
---
## Get Components Input Output
Returns the haystack components available for the domain of the current version.
This can be used to identify the input values required for each component and the output
values that will be returned.
By default, it returns the components for the deepset domain.
If names are provided, it will return the input/output schema for the provided components.
We use exact match for the component names.
If no names are provided, it will return the input/output schema for all available components.
---
## Get Custom Component
Get the details of a custom component with a specific ID. The details include the component version and status.
You may need to use the Get Custom Components endpoint first to obtain the component's ID.
---
## Get Custom Component Logs
Get custom component installation logs as plain text.
---
## Get Custom Components
Get a list of custom components currently uploaded to Haystack Enterprise Platform.
The list includes all the details of each component, such as its status and version.
---
## Get Document
Displays the document content and its properties.
---
## Get File
Retrieves the file contents.
' in the workspace. Check if the ID is correct. You can use the `list_files` endpoint to check file IDs."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"},"500":{"description":"File with the ID '{file_id}' doesn't have a type."}}}
>
---
## Get File Meta
Displays the metadata of a file.
---
## Get Index By Name
Get a single pipeline index by ID.
---
## Get Indexed Files By Status
Returns IDs of all files with a specific status and processed by a specified index.
---
## Get Indexes
Get Indexes
---
## Get Integrations
Returns the existing integrations.
---
## Get Mcp Config
Get the MCP server configuration for a workspace.
---
## Get Migration By Id
Return a specific migration job by its ID.
---
## Get Organization
Returns the name of the current deepset organization.
---
## Get Organization Custom Models
Returns organization-level custom model definitions.
Supports OData ``$filter`` on ``name`` and ``provider``.
---
## Get Paginated Feedback
Retrieves a paginated list of user feedback.
Use this endpoint to fetch batches of feedback entries, sorted and filtered according to your preference.
---
## Get Paginated Tags
Retrieves a paginated list of tags.
Use this endpoint to fetch batches of feedback entries, "
"sorted and filtered according to your preference.
---
## Get Permissions
Returns the permissions that exist in the organization.
---
## Get Pipeline
Returns a pipeline.
---
## Get Pipeline Feedback Stats
Return feedback stats for a pipeline.
---
## Get Pipeline Index Logs
Fetches pipeline index logs as JSON or CSV.
. Check if the index name is correct and if the index exists."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"},"504":{"description":"The pipeline index logs could not be retrieved within the timeout period. Try again in a couple of minutes."}}}
>
---
## Get Pipeline Index Metadata Types
Returns the metadata keys and their types for a pipeline's connected index.
For multi-index pipelines, the first found index's metadata is returned.
---
## Get Pipeline Issues
Fetches pipeline runtime issues from pipeline logs.
---
## Get Pipeline Logs
Fetches pipeline logs as JSON or CSV.
---
## Get Pipeline Metadata Field Values
Returns metadata field values for a specified key across all files of a pipeline's connected index.
Specify the metadata field key and the pipeline and workspace names to retrieve the corresponding values for
each file.
For multi-index pipelines, the first found index's metadata is searched.
---
## Get Pipeline Min Max Aggregation Metadata
Returns the minimum and maximum values of a metadata field for the connected index of a given pipeline.
---
## Get Pipeline Stats
Returns pipeline statistics.
---
## Get Pipeline Template
Return pipeline template by pipeline_name.
---
## Get Pipeline Visualization
Get Pipeline Visualization
---
## Get Pipeline Visualization(Main)
Get Pipeline Visualization
---
## Get Pipeline Yaml Configs
Displays the pipeline YAML configurations.
---
## Get Prompt
Returns the prompt of the pipeline.
---
## Get Prompts
Returns the prompts of the pipeline as a dictionary of prompt node names and their respective prompts.
---
## Get Query Pipeline Version
Get Query Pipeline Version
---
## Get Query Pipeline Version Visualization
Get Query Pipeline Version Visualization
---
## Get Roles
Returns the roles that exist in the specified organization.
---
## Get Search History Labels
Returns all unique labels used across a pipeline's search history records.
---
## Get Search Sessions
Returns all search sessions. Search sessions are used in chat as chat history.
---
## Get Secret
Returns the secret with the given id.
---
## Get Secrets
Returns the existing secrets.
---
## Get Session Files
Displays the file details of a session. Use this endpoint to check the status of the files in a session or the session expiration date.
---
## Get Session Status
Displays the details of a session. Use this endpoint to check the status of the files in a session or the session
expiration date.
---
## Get Shared Prototype
Returns the shared pipeline prototype by ID.
---
## Get Skill
Get Skill
---
## Get Temporary File
Retrieves the file contents of temporary files.
:param session: The database session.
:param file_id: The ID of the file to retrieve.
:param workspace: The workspace from which to retrieve the file.
' in the workspace. Check if the ID is correct. You can use the `list_files` endpoint to check file IDs."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"},"500":{"description":"File with the ID '{file_id}' doesn't have a type."}}}
>
---
## Get Tokens
Returns all API keys present in Haystack Enterprise Platform together with their properties.
---
## Get Tool
Get a specific tool by ID.
Retrieves detailed information about a specific tool, including its type-specific
configuration (MCP server details or pipeline configuration).
---
## Get Tools
Get all tools in a workspace.
Returns a paginated list of tools (both MCP server tools and pipeline tools)
available in the specified workspace. Tools are used in agent contexts to
provide additional capabilities.
---
## Get Upload Sessions
Returns a list of all active upload sessions.
---
## Get User
Retrieve the properties of the specified user.
---
## Get Users
Retrieve the properties of all user objects in your organization.
---
## Get Workspace By Name
Returns the specified workspace and its properties.
---
## Get Workspace Custom Models
Returns workspace-scoped custom model definitions.
Supports OData ``$filter`` on ``name`` and ``provider``.
---
## Get Workspace Integrations
Returns the existing integrations for a workspace.
---
## Get Workspace Models
Returns the available models for a workspace.
Custom models (workspace- and org-scoped) are listed first, followed by
predefined models from the integration gateway.
---
## Get Workspace Secret
Returns the secret with the given id.
---
## Get Workspace Secrets
Returns the existing secrets.
---
## Get Workspace Stats
Displays the number of files and documents in a workspace, the number of search requests, and the average response time.
---
## Get Workspace Token
Returns the API key with the specified ID that is exclusively scoped to the workspace.
---
## Get Workspace Tokens
Returns all API keys that are exclusively scoped to the specified workspace.
---
## Haystack Enterprise Platform
deepset API description
Security Scheme Type:
http
HTTP Authorization Scheme:
bearer
---
## Health
Checks if the API and database connection work correctly.
It is enough to use the Depends, since we configured the database with `pre_ping`.
Therefore the creation of the session will fail if the DB is not available.
---
## Import Custom Components
Imports a custom component as a zip file.
Use the [Custom component template](https://github.com/deepset-ai/dc-custom-component-template)
to write your component, and then upload the zipped template.
---
## Invite User To Organization
Sends an email to the user inviting them to your deepset organization.
---
## Invite User To Workspace
Invites a user directly to a specific workspace with the specified role.
This endpoint allows workspace administrators to invite users directly to their workspace,
bypassing the organization-level invitation process. The user will be:
1. Created in the Haystack Enterprise Platform if they don't already exist
2. Added to the organization if they're not already a member
3. Assigned the specified role within the target workspace
**Required Permissions:** WORKSPACE_MEMBERS write permission on the target workspace.
**Valid preset roles are:** ADMIN, EDITOR
---
## List all query pipeline versions in a workspace.
Lists query pipeline versions across all pipelines in the selected workspace. Supports OData filtering, pagination, and sorting. Allowed filter fields: is_draft and pipeline/name. Alias supported: pipeline_name maps to pipeline/name. Default sorting is version_number DESC. Pagination supports limit, before, after, and page_number. before/after cannot be used together, and before/after cannot be combined with page_number. Examples: GET /workspaces/default/pipeline/versions, GET /workspaces/default/pipeline/versions?filter=is_draft%20eq%20true, GET /workspaces/default/pipeline/versions?filter=pipeline/name%20eq%20'my-pipeline', GET /workspaces/default/pipeline/versions?filter=pipeline_name%20eq%20'my-pipeline', GET /workspaces/default/pipeline/versions?field=version_number&order=DESC&limit=20&page_number=1.
---
## List OpenSearch credentials
List all OpenSearch credentials that exist for the current organization.
---
## List Available S3 Credentials
List all S3 bucket credentials that exist for the current organization.
---
## List Datasets
Lists all datasets in a workspace with their associated files.
Supports pagination.
---
## List Exposed Pipelines
List pipelines currently exposed as MCP tools in this workspace.
---
## List Files
Lists files in a workspace. This endpoint supports pagination and filtering by name and metadata.
---
## List Migrations
Return all migration jobs for a pipeline, optionally filtered by status.
---
## List Pipeline Templates
Retrieves the list of the pipeline templates.
---
## List Pipelines
Lists all the pipelines in the workspace.
---
## List Prompt Templates
Retrieves the list of prompt templates for the given workspace.
---
## List Prototypes
Lists active shared prototypes.
---
## List Public Prompt Templates
Lists public prompt templates available in Prompt Studio.
---
## List Query Pipeline Versions
List Query Pipeline Versions
---
## List Skills
List Skills
---
## List Workspaces
Lists all deepset workspaces and their properties.
---
## Parse Tools
Parse a tool definition from a pipeline (e.g. Agent).
This endpoint takes a tool definition as provided in a pipeline context (such as
when initializing an Agent with tools) and parses it into the format used by the
validate and create tool endpoints. This allows users to verify and create tools
based on definitions they are already using in their pipelines.
---
## Patch Query Pipeline Version
Patch Query Pipeline Version
---
## Patch Token
Updates the name of a token in the database.
---
## Pipeline Search History
Returns the search history for a pipeline, which includes information such as the query, the answer,
the pipeline used, and more. Supports pagination, filtering, and sorting.
---
## Pipeline Search History Archive
Retrieves pipeline's complete search history sorted by the most recent items first.
Pipeline's search history is only available 30 minutes after completing a search request.
To retrieve recent search history, use the
[Pipeline Search History](https://docs.cloud.deepset.ai/reference/pipeline_search_history_api_v1_workspaces__workspace_name__pipelines__pipeline_name__search_history_get)
endpoint.
---
## Pipeline Search History Result
Returns the search history for a specific query_id.
---
## Query Documents
Searches the documents for the specified query.
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The search query.","title":"Query"},"query_emb":{"anyOf":[{"items":{"type":"number"},"type":"array"},{"type":"null"}],"description":"The vector representation of the query.","title":"Query Emb"},"return_embedding":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Returns vector representations of the documents.","title":"Return Embedding"},"top_k":{"default":10,"description":"The number of results to return.","title":"Top K","type":"integer"},"use_prefiltering":{"anyOf":[{"type":"boolean"},{"type":"null"}],"deprecated":true,"description":"Specifies if documents should be prefiltered in the document store instead of within the retriever. DEPRECATED: This parameter will be removed in a future version. Use efficient_filtering parameter instead.","title":"Use Prefiltering"}},"title":"QueryDocumentsParams","type":"object"}}},"required":true}}
>
---
## Query Files
Executes an SQL query on the workspace's file index and returns the raw response. The query must follow the [OpenSearch SQL Query syntax](https://docs.opensearch.org/latest/search-plugins/sql/sql/index/).The table must be `file`.
---
## Read Users Me
Retrieve the properties of the current user.
---
## Read Users Me Workspace Permissions
Returns the permissions for the current user on the specified workspace.
It is a list of Permission objects, where each Permission has:
- "asset" is the type of the asset the user has permissions to.
- "action" is the action the user can perform on the asset.
Example:
```
for an admin: [{"asset": "pipelines", "action": "write"}]
for a search_user: [{"asset": "pipelines", "action": "read"}, ...]
```
---
## Remove Role
Remove Role
---
## Remove Secret
Deletes a secret from Haystack Enterprise Platform.
---
## Remove Token
Deletes the API key with the ID you specify.
---
## Remove Workspace Secret
Deletes a secret from Haystack Enterprise Platform.
---
## Restore Pipeline Version
Restore Pipeline Version
---
## Retrieve Token
Returns the API key with the ID you specify. This ID can be obtained by calling the list endpoint of this resource.
---
## Revoke Shared Prototype
Revokes a shared pipeline prototype. Once you revoke a prototype, users can no longer access it.
---
## Run Component
Runs a haystack component with the provided parameters.
This is useful for testing components or running them with specific input data.
---
## Run Component Workspace
Runs a haystack component with the provided parameters in workspace scope (e.g. using workspace secrets).
This is useful for testing components or running them with specific input data.
---
## Run Pipeline
Runs a haystack pipeline with the provided configuration and inputs.
This is useful for testing pipelines or running them with specific input data.
---
## Run Pipeline Workspace
Runs a haystack pipeline with the provided configuration and inputs in workspace scope.
This is useful for testing pipelines or running them with specific input data.
---
## Schedule Single File For Indexing
Reindexes a single file on a pipeline index.
---
## Search
Run a search query using a deployed pipeline. Use this endpoint for generative,
extractive, and document search pipelines. For chat pipelines, use the Chat endpoint.
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Parameters you can use to customize the pipeline. For details, see [Haystack documentation for the pipeline `run()` method](https://docs.haystack.deepset.ai/reference/pipeline-api). These filters can be used to pass additional parameters to the pipeline.(Haystack is the underlying technology for deepset.) ","title":"Pipeline Parameters"},"queries":{"description":"A list of queries you want to run through the pipeline.","items":{"type":"string"},"title":"Queries","type":"array"},"search_session_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the search session you want to use for chat.","title":"Search Session ID"},"view_prompts":{"default":false,"description":"Adds the runtime prompts of all nodes to the response. (Pipeline runs in debug mode.)","title":"View prompts","type":"boolean"}},"required":["queries"],"title":"PipelineQuery","type":"object"}}},"required":true}}
>
---
## Search Count
Returns the number of search requests per time bucket.
Supports daily or hourly granularity, optional pipeline filtering, and configurable time range.
---
## Search Files
Executes an OpenSearch query on the workspace's file index and returns the raw response. The query must follow the [OpenSearch Query DSL syntax](https://opensearch.org/docs/latest/query-dsl/).
---
## Search History
Returns the search history for a workspace. The history includes information such as the query, the answer,
the pipeline used, and more.
Supports two pagination methods:
- **Offset-based**: Use `offset` (integer) and `limit` parameters
- **Cursor-based**: Use `cursor` (opaque string from previous response) with `limit`
When `cursor` is provided, it takes precedence over `offset`.
You can filter the results using OData syntax via the `filter` query parameter. Supported fields include:
- `created_at`: Filter by timestamp (e.g., `filter=created_at ge 2025-11-21T00:00:00Z`)
- `query`: Filter by search query text
- `answer`: Filter by answer text
- `api_key`: Filter by API key
- `created_by`: Filter by user ID
- `session_id` or `search_session_id`: Filter by session ID
- `deployment_id`: Filter by deployment ID (e.g., `filter=deployment_id eq ''`)
- `tags/tag_id`: Filter by feedback tag ID
- `feedbacks/score`: Filter by feedback score
- `feedbacks/comment`: Filter by feedback comment
- `feedbacks/bookmarked`: Filter by bookmark status (e.g., `filter=feedbacks/bookmarked eq true`)
- `feedbacks`: Filter by feedback existence (e.g., `filter=feedbacks ne null` for entries with feedback)
Example date range filter: `?filter=created_at ge 2025-11-01T00:00:00Z and created_at le 2025-11-30T23:59:59Z`
Example bookmark filter: `?filter=feedbacks/bookmarked eq true`
---
## Search Stream
Run a search using a pipeline and return the answer as stream.
Options:
- The full result can be accessed as the last stream message if `include_result=True`.
- Tool calls are streamed if `include_tool_calls=True`. Defaults to `rendered` where tool calls are converted to
markdown text deltas.
- Tool call results are streamed if `include_tool_call_result=True`.
- Reasoning output is streamed if `include_reasoning=True`.
Event data format where `delta`, `result`, `tool_call_delta`, `tool_call_result`, `reasoning`, `ping` and `error`
are mutually exclusive:
```
{
"query_id": UUID,
"type": Literal["delta", "result", "error", "tool_call_delta", "tool_call_result", "reasoning", "ping"],
"delta": Optional[StreamDelta],
"result": Optional[DeepsetCloudQueryResponse],
"error": Optional[str],
"tool_call_delta": Optional[ToolCallDelta],
"tool_call_result": Optional[ToolCallResult],
"reasoning": Optional[ReasoningDelta],
"index": Optional[int],
"start": Optional[bool],
"finish_reason": Optional[str],
}
```
StreamDelta format:
```
{
"text": str,
"meta": Optional[dict[str, Any]],
}
```
ToolCallDelta format:
```
{
"index": int,
"tool_name": Optional[str],
"id": Optional[str],
"arguments": Optional[str],
}
```
ToolCallResult format:
```
{
"result": str,
"origin": {
"tool_name": str,
"arguments": dict[str, Any],
"id": Optional[str],
},
"error": bool,
}
```
ReasoningDelta format:
```
{
"reasoning_text": str,
"extra": dict[str, Any],
}
```
Example code to consume the stream in Python:
```python
from httpx_sse import EventSource
TOKEN = "MY_TOKEN"
PIPELINE_URL = "https://api.cloud.deepset.ai/api/v1/workspaces/MY_WORKSPACE/pipelines/MY_PIPELINE"
async def main():
query = {
"query": "How does streaming work with deepset?",
"include_result": True,
"include_tool_calls": True,
"include_tool_call_results": True,
}
headers = {
"Authorization": f"Bearer {TOKEN}"
}
async with httpx.AsyncClient(base_url=PIPELINE_URL, headers=headers, timeout=httpx.Timeout(300.0)) as client:
async with client.stream("POST", "/search-stream", json=query) as response:
# Check if the response is successful
if response.status_code != 200:
await response.aread()
print(f"An error occured with status code: {response.status_code}")
print(response.json()["errors"][0])
return
event_source = EventSource(response)
# Stream the response
async for event in event_source.aiter_sse():
event_data = json.loads(event.data)
chunk_type = event_data["type"]
# Check the type of the chunk and print the data accordingly
match chunk_type:
# Delta chunk contains the next text chunk of the answer
case "delta":
delta = event_data["delta"]
if event_data.get("start"):
print(f"\n\nAnswer: ", flush=True, end="")
token: str = delta["text"]
print(token, flush=True, end="\n" if event_data.get("finish_reason") else "")
# Result chunk contains the final pipeline result
case "result":
print("\n\nPipeline result: ")
print(json.dumps(event_data["result"]))
# Error chunk contains the error message
case "error":
print("\n\nAn error occurred while streaming:")
print(event_data["error"])
case "tool_call_delta":
tool_call_delta = event_data["tool_call_delta"]
if tool_call_delta["tool_name"]:
tool_id = tool_call_delta["id"]
tool_name = tool_call_delta["tool_name"]
print(f"\n\nTool call {tool_id} started {tool_name} with arguments: ")
elif tool_call_delta["arguments"]:
print(tool_call_delta["arguments"], flush=True, end="")
case "tool_call_result":
tool_call_result = event_data["tool_call_result"]
tool_id = tool_call_result["origin"]["id"]
tool_name = tool_call_result["origin"]["tool_name"]
if tool_call_result["error"]:
print(f"\n\nTool call {tool_name} with id {tool_id} failed.")
else:
print(f"\n\nTool call {tool_name} with id {tool_id} result:")
print(tool_call_result["result"])
case "reasoning":
reasoning = event_data["reasoning"]
if event_data.get("start"):
print(f"\n\nReasoning: ")
print(f"{reasoning['reasoning_text']}", flush=True, end="")
asyncio.run(main())
```
",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},"circular(LogicalCondition)"]},"title":"Conditions","type":"array"},"operator":{"description":"The operator you want to use for logical conditions.","title":"Logical Condition Operator","enum":["AND","OR","NOT"],"type":"string"}},"required":["operator","conditions"],"title":"LogicalCondition","type":"object"},{"properties":{"field":{"description":"The field you want to compare.","title":"Comparison Condition Field","type":"string"},"operator":{"description":"The operator you want to use for comparison.","title":"Comparison Condition Operator","enum":["==","!=",">",">=","<","<=","in","not in"],"type":"string"},"value":{"description":"The value you want to compare the field to.","title":"Comparison Condition Value"}},"required":["field","operator","value"],"title":"ComparisonCondition","type":"object"},{"additionalProperties":false,"properties":{},"title":"EmptyFilters","type":"object"},{"type":"null"}],"description":"Filters you can use to narrow down the search. For more information, see [filtering logic](https://docs.cloud.deepset.ai/docs/filtering-logic).","title":"Haystack Filters"},"include_reasoning":{"default":false,"description":"Includes the reasoning output under key 'reasoning' when set to `true`. Defaults to `false`.\nThe reasoning output may include the intermediate steps taken by the model to arrive at the final answer. Example reasoning output:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"reasoning\", \"reasoning\": {\"reasoning_text\": \"This is the plan:\\nStep 1: Retrieve documents\\nStep 2: Process documents\\nStep 3: Generate answer\", \"extra\": {}}}\n```","title":"Include Reasoning","type":"boolean"},"include_result":{"default":false,"description":"Includes the result of the pipeline at the end of the stream under key 'result'.","title":"Include Result","type":"boolean"},"include_tool_call_results":{"default":false,"description":"Includes the tool call results under key 'tool_call_result' when set to `true`. Defaults to `false`.\nExample tool call result event:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_result\", \"tool_call_result\": {\"origin\": {\"tool_name\": \"example_tool\", \"arguments\": {\"arg1\": \"val1\"}, \"index\": 0}, \"result\": \"This is an example result.\", \"error\": false}}\n```","title":"Include Tool Call Results","type":"boolean"},"include_tool_calls":{"anyOf":[{"type":"boolean"},{"const":"rendered","type":"string"}],"default":"rendered","description":"Includes tool calls as tool call delta objects under key 'tool_call_delta' when set to `true`. When set to `rendered`, tool call events are rendered as markdown text instead. This parameter only affects the stream (not the final result) and is only effective when the pipeline makes tool calls (e.g. using the Agent component). Defaults to `rendered`.\nExample tool call delta events:\n```json\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"tool_name\": \"example_tool\", \"index\": 0, \"id\": \"tool_call_01\"}}\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"arguments\": \"{\\\"arg1\\\": \", \"index\": 0}}\n{\"query_id\": \"e2084408-48f8-4f52-9b59-43dd924705ef\", \"type\": \"tool_call_delta\", \"tool_call_delta\": {\"arguments\": \"\\\"val1\\\"}\", \"index\": 0}}\n```","title":"Include Tool Calls"},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Parameters you can use to customize the pipeline. For details, see [Haystack documentation for the pipeline `run()` method](https://docs.haystack.deepset.ai/reference/pipeline-api). These filters can be used to pass additional parameters to the pipeline.(Haystack is the underlying technology for deepset.) ","title":"Pipeline Parameters"},"query":{"description":"The search query.","title":"Query","type":"string"},"search_session_id":{"anyOf":[{"format":"uuid","type":"string"},{"type":"null"}],"description":"The ID of the search session you want to use for chat.","title":"Search Session ID"},"view_prompts":{"default":false,"description":"Adds the runtime prompts of all nodes to the response. (Pipeline runs in debug mode.)","title":"View prompts","type":"boolean"}},"required":["query"],"title":"StreamingQuery","type":"object"}}},"required":true}}
>
---
## Set Default Pipeline
Sets a pipeline as the default pipeline for search.
---
## Set Search History Note
Sets or replaces the note on a search history record.
---
## Start Debug Tunnel
Start a debug tunnel for a pipeline.
If another debug tunnel is already running for this pipeline, the existing tunnel will be stopped and a new one will
be started.
---
## Stream Pipeline Workspace
Streams a haystack pipeline execution with Server-Sent Events (SSE) format in workspace scope.
This endpoint executes a Haystack pipeline and streams the results as they become available.
The response uses Server-Sent Events (SSE) format with the following event types:
- **delta**: Content chunks from streaming-capable components (e.g., LLM generators)
- **tool_call_delta**: Structured tool call events (if `include_tool_calls` is `true`)
- **tool_call_result**: Tool call results (if include_tool_call_results is True)
- **reasoning**: Reasoning steps emitted by the pipeline (if include_reasoning is True)
- **result**: Final pipeline result (if include_result is True)
- **error**: Error messages if pipeline execution fails
When `include_tool_calls` is set to `rendered`, tool calls are emitted as markdown text in `delta` events.
---
## Unassign Search History Labels
Removes one or more labels from a search history record.
---
## Undeploy Index
Disables a pipeline index in deepset.
---
## Undeploy Pipeline
Undeploys a pipeline in deepset. Undeployed pipelines cannot be used for search.
---
## Update Exposed Pipeline
Update the MCP tool metadata (name, description, instructions) for an exposed pipeline.
---
## Update Feedback
Modifies and existing feedback entry.
Use this endpoint to update the content and rating of a specific piece of user feedback.
---
## Update File Meta
Updates the metadata of a file and of the documents created from this file. You can modify existing metadata or add new ones. If you send a new metadata dictionary, it's merged with the existing dictionary. To change the value of an existing key, pass this key with the new value. To add a new key:value pair, simply pass it in the request. It will add the new metadata and keep the existing ones. To delete a key:value pair, pass the key with `None` as value, for example: "author":"None". (But to fully delete all metadata, upload the file again.)
---
## Update File Meta Bulk
Updates the metadata of the files and of the documents created from these files. You can modify existing metadata or add new ones. If you send a new metadata dictionary, it's merged with the existing dictionary. To change the value of an existing key, pass this key with the new value. To add a new key:value pair, simply pass it in the request. It will add the new metadata and keep the existing ones. To delete a key:value pair, pass the key with `None` as value, for example: "author":"None". (But to fully delete all metadata, upload the file again.)
---
## Update Index
Updates specific fields of a pipeline index. Only description can be updated while the index is deployed.
To update name or config_yaml, the index must be undeployed.
---
## Update Integration
Updates an already connected integration.
---
## Update Mcp Config
Update the MCP server configuration for a workspace.
---
## Update Organization Model
Updates an existing organization-level custom model definition.
---
## Update Pipeline
Updates the pipeline name, service level (development or production), or status.
Search users have permission to change pipeline status only.
---
## Update Pipeline Visualization
Update Pipeline Visualization
---
## Update Pipeline Visualization(Main)
Update Pipeline Visualization
---
## Update Pipeline Yaml
:::caution deprecated
This endpoint has been deprecated and may be replaced or removed in future versions of the API.
:::
**Deprecated.** Updates the pipeline YAML file.
This endpoint is deprecated and will be removed in a future release.
To update a pipeline, use the pipeline versions API instead:
fetch the latest version, create a new version if the latest is not a draft,
then patch it via `PATCH /workspaces/{workspace_name}/pipelines/{pipeline_name}/versions/{version_id}`.
---
## Update Prompt Template
Updates the prompt template with the given ID.
---
## Update Role
Adds a role to the specified organization.
---
## Update Secret
Updates your secret in Haystack Enterprise Platform.
---
## Update Skill
Update Skill
---
## Update Tool
Update an existing tool.
Allows partial updates to a tool's properties. Only the fields provided in the
request will be updated; other fields will remain unchanged. The tool type cannot
be changed after creation.
---
## Update User Organization Role
Update user permissions.
---
## Update User Settings
Update user settings.
Only the user themselves can update their own settings.
---
## Update Workspace Integration
Updates an already connected integration for a workspace.
---
## Update Workspace Model
Updates an existing workspace-scoped custom model definition.
---
## Update Workspace Secret
Updates your secret in Haystack Enterprise Platform.
---
## Update Workspace Token
Updates the name, role, and personal flag of a workspace-scoped API token.
---
## Upload File
Uploads a file into the workspace. You can also use this endpoint to create a text file. To do that, enter the file name and text as its contents.
' already exists in the workspace."},"413":{"description":"Too large payload.Either the file uploaded is larger than 200 MB or the metadata you tried to upload is too large. The string '' of key '' is longer than 32766 bytes, which approximately equals the same number of characters.To upload files larger than 200 MB, use the [deepset SDK](https://github.com/deepset-ai/deepset-cloud-sdk)."},"415":{"description":"Haystack Enterprise Platform supports .txt, .csv, .json, .xml, .html, .md, .pdf, .docx, .pptx, .xlsx, .xlsb, .xlsm, .msg, .zip and ..DS_Store files. Upload a file in the supported format."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"}}}
>
---
## Upload Temporary File
Uploads a file into the workspace. You can also use this endpoint to create a text file. To do that, enter the file name and text as its contents.
' of key '' is longer than 32766 bytes, which approximately equals the same number of characters.To upload files larger than 200 MB, use the [deepset SDK](https://github.com/deepset-ai/deepset-cloud-sdk)."},"415":{"description":"Haystack Enterprise Platform supports .txt, .csv, .json, .xml, .html, .md, .pdf, .docx, .pptx, .xlsx, .xlsb, .xlsm, .msg, .zip and ..DS_Store files. Upload a file in the supported format."},"422":{"content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"}}},"description":"Validation Error"}}}
>
---
## Validate Organization Generation Kwargs
Validates model parameters schema: checks that it is a valid JSON schema.
---
## Validate Organization Model
Validates the chat_generator_config for an organization-level custom model.
---
## Validate Pipeline
Validates a pipeline YAML. Use this endpoint to validate your pipeline configuration before saving it.
---
## Validate Tool
Validate a new tool configuration without saving it.
This unified endpoint handles validation for all tool types
(MCP server tools and pipeline tools).
For MCP server tools, provide mcp_server data with URL, transport type, and
optional secret ID. For pipeline tools, provide pipeline data with pipeline ID
and optional input/output mappings.
If a new secret is provided for MCP server authentication, this endpoint
creates and saves the secret.
---
## Validate Workspace Model
Validates the chat_generator_config for a workspace-scoped custom model.
---
## Workspace Remove Role
Workspace Remove Role
---
## Deploy with Hayhooks
# Deploy Pipelines with Hayhooks
Use Hayhooks to deploy your pipelines and agents. A pipeline must be deployed so that you can run searches with it.
***
## About This Task
To deploy a pipeline or agent created in self-hosted Builder, you must use Hayhooks. Hayhooks is
Example of a pipeline
```yaml
# haystack-pipeline
components:
retriever:
# Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: Standard-Index-English-EU-Demo-Schengen
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
index.knn: true
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
fuzziness: 0
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
# You can swap this for any other model. Switch to the Builder view and choose another model from the list on the component card.
chat_generator:
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
init_parameters:
model: "gpt-5.4"
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Just output the structured, informative and precise answer and nothing
else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using
information from a document, e.g. [3] for Document [3] .
Never name the documents, only enter a number in square brackets as a
reference.
The reference must only refer to the number that comes in square
brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the
number of the document without mentioning the word document.
These are the documents:
{%- if documents|length > 0 %}
{% for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor %}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found, please adjust the
filters or try a different question."
{% endif %}
Question: {{ question }}
Answer:
{% endmessage %}
required_variables: "*"
system_prompt: ""
attachments_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: List[haystack.Document]
custom_filters:
unsafe: true
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_converter.documents
receiver: splitter.documents
- sender: pdf_converter.documents
receiver: splitter.documents
- sender: markdown_converter.documents
receiver: splitter.documents
- sender: html_converter.documents
receiver: splitter.documents
- sender: pptx_converter.documents
receiver: splitter.documents
- sender: docx_converter.documents
receiver: splitter.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: multi_file_converter.documents
receiver: attachments_joiner.documents
- sender: meta_field_grouping_ranker.documents
receiver: attachments_joiner.documents
- sender: attachments_joiner.documents
receiver: llm.documents
inputs:
query:
- retriever.query
- ranker.query
- llm.question
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files:
- multi_file_converter.sources
outputs:
documents: attachments_joiner.documents
messages: llm.messages
max_runs_per_component: 100
metadata: {}
```
### Inputs
Pipelines always take `Input` as the first component. When working in Builder, click **Add** to open the component library and drag `Input` onto the canvas and then connect it to the components that should receive its outputs.
When working in YAML editor, you must explicitly specify the inputs and the components that receive them:
```yaml
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "bm25_retriever.query"
- "query_embedder.text"
- "ranker.query"
filters: # These components will receive a potential query filter as input
- "bm25_retriever.filters"
- "embedding_retriever.filters"
```
Filters are documents' metadata keys by default. This means that if your documents have the following metadata: `{"category": "news"}`, when searching in Playground, users can narrow down the search to the documents matching this category. You can also pass filters at search time with the [Search](/docs/api/main/search-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-post.api.mdx) endpoint. For more information about filters, see [Working with Metadata](/docs/how-to-guides/working-with-your-data/working-with-metadata/use-metadata-in-your-search-system.mdx).
### Outputs
The output of pipelines matches the output of the last component. However, it must be one of the following data classes:
- List of `Document` objects (usually document search pipelines)
- List of `Answer` objects, including the following subclasses:
- List of `ExtractedAnswer` objects (usually extractive question answering pipelines)
- List of `GeneratedAnswer` objects (pipelines that use Generator components)
- List of `ChatMessage` objects (usually pipelines that use large language models to generate answers)
The output can be a list of documents, a list of answers, a list of chat messages, or all of them. Ensure the last component in your pipeline produces at least one of these outputs.
In Builder, to finalize the pipeline with the correct output, drag the `Output` component onto the canvas and connect it to the components that produce the outputs you want to include.
When working in the YAML editor, you must explicitly specify the outputs and the components that provide them:
```yaml
outputs: # Defines the output of your pipeline
documents: "ranker.documents" # The output of the pipeline is the retrieved documents
messages: "llm.messages" # The output of the pipeline is the generated answers
```
## Pipeline Service Levels
To save costs and meet your infrastructure and service requirements, your pipelines are assigned service levels. There are three service levels available:
- **Draft**: This is a service level automatically assigned to new and undeployed pipelines, so that you can easily distinguish them from the deployed ones.
- **Development**: Pipelines at this level are designed for testing and running experiments. They have no replicas by default, and their time to standby is short, so they can save resources whenever these pipelines aren't used. When you deploy a draft pipeline, it becomes a development pipeline.
- **Production**: This level is recommended for business-critical scenarios where you need the pipeline to be scalable and reliable. Pipelines at this level include one replica by default and a longer time-to-standby period than other service levels. With heavy traffic, the number of replicas grows up to 10.
This table gives an overview of the default settings that come with each service level:
| Service level | Description | Idle Timeout | Scaling (replicas) | How to enable |
|---------------|-----------------------------------------------------------------------------|------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Production | Designed for critical business scenarios that require reliable and scalable pipelines. | 24 hours | 1 at all times, scales up to 10 if traffic is heavy | - In /.py`: This is where your component code is stored. The base path `./dc-custom-component-template/src/dc_custom_component/` must remain unchanged, but you can create additional subfolders to organize your custom components within the `dc_custom_component` folder.
You can create a separate folder for each component, with its own `.py` file, or group multiple components in a single folder and manage them through one `.py` file. Whatever works best for you.
The folder name appears as the group's name in the components library in Pipeline Builder, where you can find your custom component. For example, if you place your custom component under `./dc-custom-component-template/src/dc_custom_component/components/rankers/custom_ranker.py`, it will show up in Pipeline Builder in the Rankers group.
- `./dc-custom-component-template/src/dc_custom_component/__about__.py`: This is the component version. Make sure to update it here every time you upload a new version. The version is set for all components in the package.
- `./dc-custom-component-template/pyproject.toml`: If your component has any dependencies, you can add them in this file in the `dependencies` section.
### Versioning
Here's how pipelines use your custom component versions:
- New pipelines can only use the latest version of your components.
- Running pipelines use the component version that was the latest at the time when then were deployed. To use a new version of a custom component, undeploy the pipelines using the component and deploy them again.
To compare different versions of a component, upload a package with both versions included in the `.py` file, similar to how you would upload two components at once. Ensure each version has a unique name. After that, create multiple pipelines, each using a different component version, and compare their performance.
### Handling Non-JSON Serializable Types
If your component uses an input type that's not JSON-serializable, you must implement its serialization methods: `to_dict()` and `from_dict()`. These methods define how to convert the type into a dictionary, which is needed for storage or transmission.
One example is the `Secret` type. This type enhances security by preventing you from directly passing sensitive information, like API keys, into initialization parameters. Since it's not a JSON-serializable type, you must implement the `to_dict()` and `from_dict()` methods to convert it into a JSON-serializable string for proper handling.
For an example of a component that uses the `Secret` type, see the Examples section below.
### Using Components In a Pipeline
Once your component is in
YAML configuration
```yaml
components:
LLM:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are an expert at explaining complex topics to children. Your task is
to rewrite this contract summary so that a 6th grader (11-12 years old)
can understand it. Here is the contract summary:
{{ summary[0] }}
Follow these rules when simplifying the summary:
1. LANGUAGE RULES
- Use simple words that a 6th grader knows
- Keep sentences short (15 words or less)
- Use active voice instead of passive voice
- Replace legal terms with everyday words
- Define any complex words you must use
- Use "you" and "they" instead of formal names when possible
2. EXPLANATION STYLE
- Start each section with "This part is about..."
- Use real-life examples that kids understand
- Compare complex ideas to everyday situations
- Break long explanations into smaller chunks
- Use bullet points for lists
- Add helpful "Think of it like..." comparisons
3. ORGANIZATION
- Group similar ideas together
- Use friendly headers like "Money Stuff" instead of "Financial Terms"
- Put the most important information first
- Use numbered lists for steps or sequences
- Add transition words (first, next, finally)
4. MAKE IT RELATABLE
- Compare contract parts to things kids know:
* Compare deadlines to homework due dates
* Compare payments to allowance
* Compare obligations to classroom rules
* Compare penalties to time-outs
* Compare termination to quitting a sports team
5. REQUIRED SECTIONS
Simplify each of these areas:
- Who is involved (like players on a team)
- What each person must do (like chores)
- Money and payments (like saving allowance)
- Important dates (like calendar events)
- Rules everyone must follow (like game rules)
- What happens if someone breaks the rules
- How to end the agreement
- How to solve disagreements
6. FORMAT YOUR ANSWER LIKE THIS:
"Hi! I'm going to explain this contract in a way that's easy to understand. Think of a contract like a written promise between people or companies.
[Then break down each section with simple explanations and examples]
Remember: Even though we're making this simple, all parts of the original summary must be included - just explained in a kid-friendly way!"
IMPORTANT REMINDERS:
- Don't leave out any important information just because it's complex
- Double-check that your explanations are accurate
- Keep a friendly, encouraging tone
- Use emoji or simple symbols to mark important points (⭐, 📅, 💰, ⚠️)
- Break up long paragraphs
- End with a simple summary of the most important points
Your goal is to make the contract summary so clear that a 6th grader could explain it to their friend. Imagine you're the cool teacher who makes complicated stuff fun and easy to understand!
{% endmessage %}
required_variables: "*"
streaming_callback:
LLM_2:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a legal document analyzer specializing in contract
summarization. Your task is to analyze and summarize the following
contract comprehensively.
Contract to analyze: {{ contract }}
Provide a structured summary that includes ALL of the following components:
1. BASIC INFORMATION
- Contract type
- Parties involved (full legal names)
- Effective date
- Duration/term of contract
- Governing law/jurisdiction
2. KEY OBLIGATIONS
- List all major responsibilities for each party
- Highlight any conditional obligations
- Note any performance metrics or standards
- Identify delivery or service deadlines
- Specify any reporting requirements
3. FINANCIAL TERMS
- Payment amounts and schedules
- Currency specifications
- Payment methods
- Late payment penalties
- Price adjustment mechanisms
- Any additional fees or charges
4. CRITICAL DATES & DEADLINES
- Contract start date
- Contract end date
- Key milestone dates
- Notice period requirements
- Renewal deadlines
- Termination notice periods
5. TERMINATION & AMENDMENTS
- Termination conditions
- Early termination rights
- Amendment procedures
- Notice requirements
- Consequences of termination
6. WARRANTIES & REPRESENTATIONS
- List all warranties provided
- Duration of warranties
- Warranty limitations
- Representations made by each party
- Disclaimer provisions
7. LIABILITY & INDEMNIFICATION
- Liability limitations
- Indemnification obligations
- Insurance requirements
- Force majeure provisions
- Exclusions and exceptions
8. CONFIDENTIALITY & IP
- Scope of confidential information
- Duration of confidentiality
- Intellectual property rights
- Usage restrictions
- Return/destruction requirements
9. DISPUTE RESOLUTION
- Resolution process
- Arbitration requirements
- Mediation procedures
- Jurisdiction
- Governing law
10. SPECIAL PROVISIONS
- Any unique or unusual terms
- Special conditions
- Specific industry requirements
- Regulatory compliance requirements
- Any attachments or referenced documents
Format your response as follows:
- Use clear headings for each section
- Use bullet points for individual items
- Bold any critical terms, dates, or amounts
- Include section references from the original contract
- Note if any standard section appears to be missing from the contract
IMPORTANT GUIDELINES:
- If any of the above sections are not present in the contract, explicitly note their absence
- Flag any unusual or potentially problematic clauses
- Highlight any ambiguous terms that might need clarification
- Include exact quotes for crucial legal language
- Note any apparent gaps or inconsistencies in the contract
- Identify any terms that appear to deviate from standard industry practice
The summary must be comprehensive enough to serve as a quick reference for all material aspects of the contract while highlighting any areas requiring special attention or clarification.
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: LLM_2.last_message
receiver: LLM.summary
max_runs_per_component: 100
metadata: {}
inputs:
messages:
- LLM_2.contract
outputs:
messages: LLM.messages
```
## Merging Multiple Outputs
With [smart connections](/docs/concepts/about-pipelines/about-pipelines.mdx#smart-connections), components can accept connections from multiple lists of the same type. This means you no longer need `DocumentJoiner` or `ListJoiner` in most cases. For step-by-step instructions, see [Simplify Your Pipelines with Smart Connections](/docs/how-to-guides/designing-your-pipeline/simplify-pipelines.mdx).
If you still need to merge outputs in a specific way, you can use a component from the Joiners group. Options include `AnswerJoiner`, `DocumentJoiner`, `BranchJoiner`, and `StringJoiner`.
## Routing Data Based on a Condition
You can route a component’s output to different branches in your pipeline based on specific conditions. The `ConditionalRouter` component handles this by using rules that you define.
The conditions for routing are specified in the `ConditionalRouter`’s `routes` parameter. Each route includes the following elements:
- **`condition`**: A Jinja2 expression that determines if the route should be used.
- **`output`**: A Jinja2 expression that defines the data passed to the route.
- **`output_name`**: The name of the route output, used to connect to other components.
- **`output_type`**: The data type of the route output.
Imagine a pipeline that:
1. Uses an LLM to answer user queries based on provided documents.
2. Falls back to a web search if the LLM cannot find an answer.
You would need two routes:
- One for queries the LLM cannot answer (`no_answer` is present).
- One for queries the LLM can answer based on the documents.
This is how you could configure the routes:
```yaml
- condition: '{{"no_answer" in replies[0]}}'
output: '{{ query }}'
output_name: search_internet
output_type: str
- condition: '{{"no_answer" not in replies[0]}}'
output: '{{ replies }}'
output_name: answer
output_type: typing.List[str]
```
The first route is used if `no_answer` appears in the LLM’s replies. This route outputs the query and is labeled `search_internet`. The second route is used if `no_answer` is not present. This route outputs the LLM’s replies and is labeled `answer`.
In this setup:
- An `LLM` is configured to reply with `no_answer` if it cannot find an answer based on the documents.
- The `ConditionalRouter` checks the LLM's reply and decides:
- If the reply contains `no_answer`, the query is sent to the `SerperDevWebSearch` component to search the internet for an answer.
- If `no_answer` is not present, the reply is sent to the `AnswerBuilder` to format and output the LLM's response.
This is what this part of the pipeline configurationcould look like:
YAML configuration
```yaml
components:
SerperDevWebSearch:
# to use this component, you need a SerperDev API key
type: haystack.components.websearch.serper_dev.SerperDevWebSearch
init_parameters:
api_key:
type: env_var
env_vars:
- serper_dev
strict: false
top_k: 5
allowed_domains:
search_params:
ConditionalRouter:
type: haystack.components.routers.conditional_router.ConditionalRouter
init_parameters:
routes:
- condition: '{{"no_answer" in replies[0]}}'
output: '{{ query }}'
output_name: search_internet
output_type: str
- condition: '{{"no_answer" not in replies[0]}}'
output: '{{ replies }}'
output_name: answer
output_type: typing.List[str]
custom_filters: {}
unsafe: false
validate_output_type: false
OpenSearchEmbeddingRetriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
use_ssl: true
verify_certs: false
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
embedding_dim: 768
similarity: cosine
index: Standard-Index-English-EU-Demo-Schengen
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
index.knn: true
create_index: true
timeout:
filters:
top_k: 10
filter_policy: replace
custom_query:
raise_on_failure: true
efficient_filtering: false
AnswerJoiner:
type: haystack.components.joiners.answer_joiner.AnswerJoiner
init_parameters:
join_mode: concatenate
top_k:
sort_by_score: false
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters:
pattern:
reference_pattern:
AnswerBuilder_1:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters:
pattern:
reference_pattern:
SentenceTransformersTextEmbedder:
type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: intfloat/e5-base-v2
device:
token:
prefix: ''
suffix: ''
batch_size: 32
progress_bar: true
normalize_embeddings: false
trust_remote_code: false
truncate_dim:
model_kwargs:
tokenizer_kwargs:
config_kwargs:
precision: float32
LLM:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
Answer the following query given the documents.
If the answer is not contained within the documents reply with
'no_answer'
Query: {{query}}
Documents:
{% for document in documents %}
{{document.content}}
{% endfor %}
{% endmessage %}
required_variables: "*"
streaming_callback:
LLM_2:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
Answer the following query given the documents retrieved from the web.
Your answer shoud indicate that your answer was generated from
websearch.
Query: {{query}}
Documents:
{% for document in documents %}
{{document.content}}
{% endfor %}
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: AnswerBuilder.answers
receiver: AnswerJoiner.answers
- sender: AnswerBuilder_1.answers
receiver: AnswerJoiner.answers
- sender: SentenceTransformersTextEmbedder.embedding
receiver: OpenSearchEmbeddingRetriever.query_embedding
- sender: OpenSearchEmbeddingRetriever.documents
receiver: LLM.documents
- sender: LLM.messages
receiver: ConditionalRouter.replies
- sender: SerperDevWebSearch.documents
receiver: LLM_2.documents
- sender: ConditionalRouter.search_internet
receiver: LLM_2.query
- sender: LLM_2.messages
receiver: AnswerBuilder_1.replies
- sender: ConditionalRouter.answer
receiver: AnswerBuilder.replies
max_runs_per_component: 100
metadata: {}
inputs:
query:
- ConditionalRouter.query
- AnswerBuilder.query
- AnswerBuilder_1.query
- SerperDevWebSearch.query
- SentenceTransformersTextEmbedder.text
- LLM.query
outputs:
answers: AnswerJoiner.answers
```
---
## Pipeline Components
# Pipeline Components Overview
Components are the fundamental building blocks of your pipelines, dictating the flow of data. Each component performs a designated task on the data and then forwards the results to subsequent components.
***
## How Components Work
Components receive predefined inputs within the pipeline, execute a specific function, and produce outputs. For example, a component may take files, convert them into embeddings, and pass these embeddings on to the next connected component. You have the flexibility to mix, match, and interchange components in your pipelines.
Components are often powered by language models, like LLMs or transformer models, to perform their tasks.
:::tip GPU Acceleration
By default, components run on CPU. You can turn on GPU acceleration in the pipeline or index settings to speed up processing. For details, see [GPU Acceleration](/docs/enable-gpu-acceleration).
:::
## Connecting Components: Inputs and Outputs
Components accept specific inputs and produce defined outputs. You can connect components with matching intputs and outputs types. The output type from one component must be compatible with the input type of the subsequent one. For example, a retriever outputs `List[Document]` and a ranker accepts `List[Document]` as input, their types match so you can connect them. Builder guides you through the connections with connection validation. You can also use the Connections panel at the bottom of the canvas to manage, inspect, and edit component connections.
To connect components, drag a line between them or use the Connections panel.
AND ACCOUNT_NUMBER =
LIMIT 1;
You must provide only the SQL query in plain text, as non-SQL characters will break the database.
Your answer must not include ```sql or ```. If you cannot identify the client in this text, respond with an empty string "".
verification_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 1000
temperature: 0.0
seed: 0
client_database: # This is meant to access client information stored in Snowflake, from which the LLM will verify the information that the customer provided.
type: deepset_cloud_custom_nodes.retrievers.snowflake_retriever.DeepsetSnowflakeRetriever
init_parameters:
user: ""
account: ""
warehouse: ""
verification_success_adapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ replies[0] }}'
output_type: str
verification_router:
type: haystack.components.routers.conditional_router.ConditionalRouter
init_parameters:
routes:
- condition: '{{ dataframe.shape[0] == 0 }}'
output: '{{ table }}'
output_name: fail
output_type: str
- condition: '{{ dataframe.shape[0] > 0 }}'
output: '{{ table }}'
output_name: success
output_type: str
unsafe: false
verification_fail_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
I'm sorry, but I couldn't find a match for your first name, last name, and account number in our system.
Could you please double-check the information and provide it again? This will help us ensure we're connecting to the correct account.
Thank you for your patience!
{{ table }}
verification_fail_adapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ [prompt] }}'
output_type: typing.List[str]
verification_success_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at Deepset Bank responsible for negotiating auto loan payments with clients who have missed their payments.
Your task is to verify client details against the bank's records and start the discussion around paying the missed car loan payments.
Use the chat history below for guidance and context.
Instructions:
- Verify the user's identity by confirming their first name, last name, and account number.
- Extract critical financial information from the table and ask the user if they would like to make the missed payment.
- Provide them with an update on their loan, including details about the car, the loan amount, and the remaining balance to pay off the loan.
- Remember, the generated prompt will be used for a text-to-speech system, so you should sound like a human.
It's important to consider that the client you are discussing with has missed their payment.
Bank's records: {{ table }}
Chat history: {{ question }}
Prompt:
verification_success_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
verification_fail_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
verification_success_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
verification_answer_builder_joiner:
type: haystack.components.joiners.answer_joiner.AnswerJoiner
init_parameters: {}
# Components for detecting clients' sentiment
sentiment_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at Deepset Bank responsible for negotiating auto loan payments with clients who have missed their payments.
You have been provided with the chat history and the client's current question below to help you achieve your goal.
Instructions:
- Analyze the client's response in the chat history for emotional cues.
- Assess whether the sentiment is positive, neutral, or negative, and determine if the client is receptive, resistant, frustrated, or cooperative regarding commitment to payment or a payment arrangement.
Remember, the generated prompt will be used for a text-to-speech system, so you should sound like a human.
It's important to consider that the client you are discussing with has missed their payment.
It is also important to remember that you are already on the call with the client.
The chat history below refers to the previous conversation. That said, do not act as if this is the first time you are talking to the client.
{{ question }}
Prompt:
sentiment_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
sentiment_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
# components for conducting the payment negotiation
negotiation_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at Deepset Bank responsible for negotiating auto loan payments with clients who have missed their payments.
You have been provided with the chat history and the client's current question below to help you achieve your goal.
Instructions:
- Generate a response based on the client’s sentiment and willingness to discuss payment options, aiming to reach a mutually agreeable payment solution.
- Adjust your tone according to the client’s responses. The response should maintain a respectful tone and be solution-oriented, encouraging the client toward a payment commitment that meets their current capacity.
It's important to consider that the client you are discussing with has missed their payment.
Remember that you are already on the call with the client. The chat history below refers to the previous conversation, so do not act as if this is the first time you are talking to the client.
{{ question }}
Prompt:
negotiation_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
negotiation_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
# Components for escalations and handoffs
escalation_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at Deepset Bank responsible for negotiating auto loan payments with clients who have missed their payments.
You have been provided with the chat history and the client current question below to help you achieve your goal.
Instructions:
- The client’s response suggests they may need additional assistance from a human representative.
- Based on the tone of their message (e.g., frustration, confusion, or request for direct help), generate a response that politely acknowledges their concerns and reassures them that they will be connected with a team member who can help.
- Ensure the message conveys empathy and appreciation for their patience, maintaining a supportive and professional tone during the handoff."
Example response:
"Thank you for your patience, [Client’s Name].
I understand that this might be a bit complex, so I’m connecting you with a team member who can assist further.
We appreciate you working with us, and someone will be with you shortly to make sure your concerns are https://www.iana.org/assignments/media-types/application/vnd.openxmlformats-officedocument.wordprocessingml.documented."
It's important to consider that the client you are in discussion with has missed their payment.
It is also important to remember that you are already on the call with the client. The chat history below refers to the previous conversation. That said, do not act as if this is the first time you are talking to the client.
{{ question }}
Prompt:
escalation_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
escalation_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
# Components for extracting relevant financial details
info_extract_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at Deepset Bank, responsible for negotiating auto loan payments with clients who have missed their payments.
You have been provided with the chat history and the client's current question below to help you achieve your goal.
Instructions:
- Analyze the client’s response and extract relevant financial details that can guide the negotiation process.
- Look for information such as the client's ability or willingness to pay, along with specific payments.
It is important to consider that the client you are discussing with has missed their payment. It is also essential to remember that you are already on the call with the client.
The chat history below refers to the previous conversation. That said, do not act as if this is the first time you are talking to the client.
Example of extracted information: "The client indicated they can make a partial payment of $100 next week but cannot commit to the full balance at this time."
{{ question }}
Prompt:
info_extract_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
info_extract_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
# Component for handling the payment
payment_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a customer service agent at deepset Bank responsible for negotiating auto loan payments with clients who have missed their payments.
You have been provided with the chat history and the client current question below to help you achieve your goal.
Instructions:
- Based on the client’s agreement to make a payment or partial payment, generate a message that confirms their willingness and provides instructions for completing the payment.
- If they have chosen a specific payment plan, outline the details clearly. Include a secure payment link, and thank the client for their cooperation.
- Ensure the tone is positive and appreciative, encouraging a smooth completion of the payment process."
Payment Link: "https://www.deepset.ai"
Example response:
"Thank you for your cooperation, [Client’s Name]! You can complete your payment by following this secure link: [Payment Link]. If you have any questions, please let us know—we’re here to help!”
It is also important to remember that you are already on the call with the client.
The chat history below refers to the previous conversation. That said, do not act as if this is the first time you are talking to the client.
{{ question }}
Prompt:
payment_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0.0
seed: 0
payment_answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
answer_joiner:
type: haystack.components.joiners.answer_joiner.AnswerJoiner
init_parameters: {}
connections:
- sender: root_prompt_builder.prompt
receiver: root_llm.prompt
- sender: root_llm.replies
receiver: conditional_router.replies
- sender: conditional_router.call
receiver: initiate_call_prompt_builder.question
- sender: initiate_call_prompt_builder.prompt
receiver: initiate_call_llm.prompt
- sender: initiate_call_llm.replies
receiver: initiate_call_answer_builder.replies
- sender: conditional_router.call
receiver: initiate_call_answer_builder.query
- sender: conditional_router.verification
receiver: verification_prompt_builder.text
- sender: verification_prompt_builder.prompt
receiver: verification_llm.prompt
- sender: verification_llm.replies
receiver: verification_success_adapter.replies
- sender: verification_success_adapter.output
receiver: client_database.query
- sender: client_database.table
receiver: verification_router.table
- sender: verification_router.fail
receiver: verification_fail_prompt_builder.table
- sender: verification_fail_prompt_builder.prompt
receiver: verification_fail_adapter.prompt
- sender: verification_fail_adapter.output
receiver: verification_fail_answer_builder.replies
- sender: client_database.dataframe
receiver: verification_router.dataframe
- sender: verification_router.fail
receiver: verification_fail_answer_builder.query
- sender: verification_router.success
receiver: verification_success_prompt_builder.table
- sender: verification_success_prompt_builder.prompt
receiver: verification_success_llm.prompt
- sender: verification_success_llm.replies
receiver: verification_success_answer_builder.replies
- sender: verification_router.success
receiver: verification_success_answer_builder.query
- sender: verification_success_answer_builder.answers
receiver: verification_answer_builder_joiner.answers
- sender: verification_fail_answer_builder.answers
receiver: verification_answer_builder_joiner.answers
- sender: conditional_router.sentiment
receiver: sentiment_prompt_builder.question
- sender: sentiment_prompt_builder.prompt
receiver: sentiment_llm.prompt
- sender: sentiment_llm.replies
receiver: sentiment_answer_builder.replies
- sender: conditional_router.sentiment
receiver: sentiment_answer_builder.query
- sender: conditional_router.negotiation
receiver: negotiation_prompt_builder.question
- sender: negotiation_prompt_builder.prompt
receiver: negotiation_llm.prompt
- sender: negotiation_llm.replies
receiver: negotiation_answer_builder.replies
- sender: conditional_router.negotiation
receiver: negotiation_answer_builder.query
- sender: conditional_router.escalation
receiver: escalation_prompt_builder.question
- sender: escalation_prompt_builder.prompt
receiver: escalation_llm.prompt
- sender: escalation_llm.replies
receiver: escalation_answer_builder.replies
- sender: conditional_router.escalation
receiver: escalation_answer_builder.query
- sender: conditional_router.extract
receiver: info_extract_prompt_builder.question
- sender: info_extract_prompt_builder.prompt
receiver: info_extract_llm.prompt
- sender: info_extract_llm.replies
receiver: info_extract_answer_builder.replies
- sender: conditional_router.escalation
receiver: info_extract_answer_builder.query
- sender: conditional_router.payment
receiver: payment_prompt_builder.question
- sender: payment_prompt_builder.prompt
receiver: payment_llm.prompt
- sender: payment_llm.replies
receiver: payment_answer_builder.replies
- sender: conditional_router.payment
receiver: payment_answer_builder.query
- sender: verification_answer_builder_joiner.answers
receiver: answer_joiner.answers
- sender: initiate_call_answer_builder.answers
receiver: answer_joiner.answers
- sender: sentiment_answer_builder.answers
receiver: answer_joiner.answers
- sender: negotiation_answer_builder.answers
receiver: answer_joiner.answers
- sender: escalation_answer_builder.answers
receiver: answer_joiner.answers
- sender: info_extract_answer_builder.answers
receiver: answer_joiner.answers
- sender: payment_answer_builder.answers
receiver: answer_joiner.answers
max_runs_per_component: 100
metadata: {}
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "conditional_router.question"
- "root_prompt_builder.question"
- "verification_success_prompt_builder.question"
outputs: # Defines the output of your pipeline
answers: "answer_joiner.answers" # The output of the pipeline is the generated answers
````
---
## Pipeline Examples
Explore ready-to-use pipeline examples to get started quickly. Some may require an API key for hosted LLMs. Copy them directly to /pipelines/ \
--header 'accept: application/json' \
--header 'authorization: ' \
--header 'content-type: application/json' \
--data '
{
"service_level": "DEVELOPMENT" # to change to production, replace with "PRODUCTION"
}
'
```
For more details, see [Edit a Pipeline](./edit-a-pipeline.mdx).
## Change to Draft
Undeploying a pipeline changes its service level to draft.
Copy this code, replacing the workspace, pipeline name, and API key:
```curl
--request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces//pipelines//undeploy \
--header 'accept: application/json' \
--header 'authorization: '
```
---
## Create a Pipeline in Pipeline Builder
Use an intuitive, low code, drag-and-drop interface to build your pipelines. Easily switch between visual and code representations.
***
Expand to view the YAML explanation
Every pipeline is backed by a YAML configuration. You can access and edit it directly by switching to the YAML editor in Builder. Any changes you make in the visual editor are reflected in the YAML, and the other way around.
A pipeline YAML has four main sections:
- `components`: Defines the components in your pipeline and their parameters.
- `connections`: Defines how components pass data to each other.
- `inputs`: Maps pipeline-level inputs to the inputs of specific components.
- `outputs`: Maps component outputs to the pipeline's final output.
#### Components
Each entry under `components` defines a component by its name and type. The name is optional and is a label you choose; you reference it in `connections`, `inputs`, and `outputs`. The type is the fully qualified class path of the component, which you can find on the component's documentation page.
:::tip Component Information
You can drag a component from the Component Library onto the visual canvas and then switch to the YAML editor to see the component's definition.
:::
Use `init_parameters` to configure the component. Nested components, such as document stores, are also defined inline here:
```yaml
components:
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
top_k: 20
```
#### Connections
The `connections` section defines how data flows between components. Each connection specifies a `sender` and a `receiver` in the format `component_name.output_name` and `component_name.input_name`:
```yaml
connections:
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: ranker.documents
```
#### Inputs
The `inputs` section maps pipeline-level inputs to the inputs of specific components. Each key is a pipeline input name (for example, `query` or `filters`). The list under each key specifies which component inputs receive that value:
```yaml
inputs:
query:
- "query_embedder.text"
- "ranker.query"
filters:
- "embedding_retriever.filters"
```
#### Outputs
The `outputs` section maps the pipeline's named outputs to specific component outputs. Each key is the name of a pipeline output, and the value is a `component_name.output_name` reference:
```yaml
outputs:
documents: "ranker.documents"
```
#### Example: Semantic Document Search Pipeline
Here's a complete query pipeline that embeds the query, retrieves semantically similar documents, and re-ranks the results:
```yaml
components:
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
top_k: 20
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 20
connections:
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: ranker.documents
inputs:
query:
- "query_embedder.text"
- "ranker.query"
filters:
- "embedding_retriever.filters"
outputs:
documents: "ranker.documents"
```
This pipeline works as follows:
1. `query_embedder` converts the query into a vector embedding.
2. `embedding_retriever` uses that embedding to find the most semantically similar documents in the document store.
3. `ranker` re-ranks the retrieved documents by relevance.
4. The pipeline returns the re-ranked documents as its output.
## Prerequisites
- To learn about how pipelines and components work, see [Pipeline Components](https://docs.cloud.deepset.ai/docs/pipeline-components) and [Pipelines](https://docs.cloud.deepset.ai/docs/about-pipelines).
- To use a hosted model, [connect to model providers](/docs/how-to-guides/managing-access/connect-with-model-providers.mdx) first so that you don't have to pass the API key within the pipeline. For Hugging Face, this is only required for private models. Once
Pipeline YAML Explained
Your pipeline definition file is in the YAML format. Make sure that you follow the same indentation structure as in this example:
```yaml Query Pipeline
components: # This section defines your pipeline components and their settings
component_1: # Give your component a friendly name, you'll use it in the sections below
type: # You can find the component type in documentation on a component's page (here maybe a link to components' docs)
init_parameters: # Customize the component's settings, to use default values, skip this
component_2:
type:
init_parameters:
parameter1: value1
parameter2: value2
connections: # Define how the components are connected
# You must explicitly indicate the intpus and outputs you want to connect
# Input and output types must be the same to be connected
# You can check components outputs and inputs in documentation
- sender: component_1.output_name # Here you define the output name this component sends to the receiver component
receiver: component_2.input_name # Here you define the input name that receives the output of the sender component
inputs: # List all components that need query and filters as inputs but aren't getting them from any other component connected to them
query: # These components will receive the query as input
- "component_1.question"
filters: # These components will receive a potential query filter as input
- "component_1.filters"
outputs: # Defines the output of your pipeline, usually the output of the last component
documents: "component_2.documents" # The output of the pipeline is the retrieved documents
```
An example pipeline:
```yaml Query pipeline
components:
chat_summary_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
Rewrite the current question so that it is suitable for web search ONLY if chat history is provided.
If the chat history is empty, DO NOT reformulate the question.
Be cautious when reformulating the current question. Substantial changes to the current question that distort the meaning of the current question are undesirable.
It is possible that the current question does not need any changes.
The chat history can help to incorporate context into the reformulated question.
Make sure to incorporate that chat history into the reformulated question ONLY if needed.
The overall meaning of the reformulated question must remain the same as the current question.
You cannot change or dismiss keywords in the current question.
If you do not want to make changes, just output the current question.
Chat History: {{question}}
Reformulated Question:
chat_summary_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": False}
model: "gpt-3.5-turbo"
generation_kwargs:
max_tokens: 650
temperature: 0.0
seed: 0
replies_to_query:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: "{{ replies[0] }}"
output_type: str
bm25_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20 # The number of results to return
query_embedder:
type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: "intfloat/e5-base-v2"
device: null
embedding_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20 # The number of results to return
document_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
ranker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: "intfloat/simlm-msmarco-reranker"
top_k: 8
device: null
model_kwargs:
torch_dtype: "torch.float16"
qa_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{question}}
Answer:
qa_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": False}
model: "gpt-3.5-turbo"
generation_kwargs:
max_tokens: 400
temperature: 0.0
seed: 0
answer_builder:
init_parameters: {}
type: haystack.components.builders.answer_builder.AnswerBuilder
connections: # Defines how the components are connected
- sender: chat_summary_prompt_builder.prompt
receiver: chat_summary_llm.prompt
- sender: chat_summary_llm.replies
receiver: replies_to_query.replies
- sender: replies_to_query.output
receiver: bm25_retriever.query
- sender: replies_to_query.output
receiver: query_embedder.text
- sender: replies_to_query.output
receiver: ranker.query
- sender: replies_to_query.output
receiver: qa_prompt_builder.question
- sender: replies_to_query.output
receiver: answer_builder.query
- sender: bm25_retriever.documents
receiver: document_joiner.documents
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: document_joiner.documents
- sender: document_joiner.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: qa_prompt_builder.documents
- sender: ranker.documents
receiver: answer_builder.documents
- sender: qa_prompt_builder.prompt
receiver: qa_llm.prompt
- sender: qa_llm.replies
receiver: answer_builder.replies
max_loops_allowed: 100
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "chat_summary_prompt_builder.question"
filters: # These components will receive a potential query filter as input
- "bm25_retriever.filters"
- "embedding_retriever.filters"
outputs: # Defines the output of your pipeline
documents: "ranker.documents" # The output of the pipeline is the retrieved documents
answers: "answer_builder.answers" # The output of the pipeline is the retrieved documents
```
## Create a Pipeline
The endpoint accepts a JSON request body. Pass your pipeline YAML as the `query_yaml` string field, along with a unique pipeline `name`. You cannot create an empty pipeline.
Use the following code as a starting point for your API request:
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces//pipelines \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data "$(jq -n \
--arg name '' \
--rawfile query_yaml path/to/pipeline.yaml \
'{name: $name, query_yaml: $query_yaml, deepset_cloud_version: "v2"}')"
```
- In line 2, replace `` with the name of the workspace where you want to create the pipeline.
- In line 5, replace `` with the ` with a unique name for your pipeline.
- In line 8, replace `path/to/pipeline.yaml` with the path to your pipeline YAML file.
The example uses [jq](https://jqlang.org/) to read your YAML file and embed it in the JSON body. If you do not have jq installed, you can pass the YAML inline instead:
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces//pipelines \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ' \
--data '{
"name": "",
"query_yaml": "components:\n ...\nconnections: []\n",
"deepset_cloud_version": "v2"
}'
```
Replace the `query_yaml` value with your full pipeline YAML. Use `\n` for line breaks inside the string.
To validate your pipeline without saving it, add `?dry_run=true` to the request URL.
See the [REST API endpoint documentation](/docs/api/main/create-pipeline-api-v-1-workspaces-workspace-name-pipelines-post.api.mdx).
---
## Create a Pipeline
Create a pipeline from scratch or choose one of the available templates for an easy start. You can use a visual drag-and-drop editor or REST API.
## About This Task
There are two ways to create a pipeline:
- **[Using Builder](./create-a-pipeline-in-studio.mdx)**: Choose this method to create your own pipeline from one of the ready-made templates or from scratch using a visual drag-and-drop editor. Builder has a library of components you can choose from to build your pipeline.
- **[Using API](./create-a-pipeline-with-rest-api.mdx)**: Choose this way if you already have a pipeline YAML file and want to programmatically upload it to /pipelines//deploy \
--header 'Accept: application/json' \
--header 'Authorization: Bearer '
```
## What To Do Next
It may happen that the deployment fails, and the pipeline status is _failed to deploy_. This status means the pipeline wasn't deployed. If you encounter this error, you must take some [troubleshooting action](./troubleshooting-pipeline-deployment.mdx).
To view pipeline information, such as statistics or feedback, click the pipeline name. It opens in Builder. Switch to *Analytics*. It contains all the information you may need.
Deployed pipelines that haven't been used for a while become idle to save resources. The default idle timeout depends on the pipeline service level. By default, production pipelines go on standby after 24 hours of not being used and development pipelines after 20 minutes. You can customize the idle timeout in pipeline settings.
An idle pipeline gets automatically activated if you run a search with it or you can trigger the activation manually on the Pipelines page. For more information, see [Pipelines](/docs/concepts/about-pipelines/about-pipelines.mdx).
---
## Edit a Pipeline
Improve your pipeline to make your search faster and more accurate. You can edit pipelines in Pipeline Builder or through REST API.
***
## About This Task
You can edit a development pipeline while it remains deployed. You can make the following changes:
- Update components.
- Update the index a pipeline is using.
- Update the pipeline's name.
Any changes you make create a new, undeployed version of the pipeline.
:::info Production Pipelines
You can't edit production pipelines. You must change the pipeline's service level first.
:::
## One Editor at a Time
Only one person can edit a pipeline at a time. When someone saves changes, the pipeline is locked for 60 seconds so others cannot overwrite the same version.
- **If you try to edit while the pipeline is locked:** You see a message like "[User A] edited this pipeline 30 seconds ago. You can edit in 30 seconds."
- **After 60 seconds:** The lock expires. Click **Try again** to start editing.
- **Why 60 seconds?** The lock prevents situations where people rapidly overwrite each other's changes, while still allowing sequential collaboration.
The lock is based on time (60 seconds after the last save), not on whether the other person has the editor open. If someone leaves their browser open without saving, you can edit after 60 seconds from their last save.
:::tip Need to Edit at the Same Time?
If you often need multiple people to edit a pipeline at once, share your use case with us. We're tracking this to inform future collaboration features.
:::
## Prerequisites
- You must be an Admin to perform this task.
- If the changes you want to make require undeploying the pipeline, go to **Pipelines**, click the more actions button next to the pipeline name, and select **Undeploy**.
- If you're updating the index the pipeline uses, make sure the index is enabled. For instructions, see [Enable an Index](../working-with-indexes/enable-an-index.mdx).
- To edit pipelines using API endpoints, [generate an API Key](/docs/how-to-guides/managing-access/generate-api-key.mdx) first.
## Edit a Pipeline in Builder
This is the default way of editing pipelines. It opens the pipeline in the visual editor. You can use it to replace one component with another or update the parameters quickly.
1. Log in to /pipelines/ \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"name": "new_pipeline_name",
"service_level": "DEVELOPMENT",
"status": 1
}
'
```
### Update Pipeline YAML Configuration
For updating pipeline YAML configuration, use the pipeline versions API:
1. Fetch the latest version using [Get Query Pipeline Version](/docs/api/main/get-query-pipeline-version-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-versions-version-id-get.api.mdx).
2. Create a new draft version with [Create Query Pipeline Version](/docs/api/main/create-query-pipeline-version-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-versions-post.api.mdx). If a draft already exists, it is automatically finalized and a new draft is created. If the existing draft is currently locked by another user, the request returns a 409 Conflict error — wait for the lock to expire and try again.
3. Update the pipeline configuration using [Patch Query Pipeline Version](/docs/api/main/patch-query-pipeline-version-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-versions-version-id-patch.api.mdx).
## Related Information
- [Manage Pipeline Versions](/docs/how-to-guides/designing-your-pipeline/manage-pipeline-versions.mdx)
- [Deploy a Pipeline](/docs/how-to-guides/designing-your-pipeline/deploy-a-pipeline.mdx)
---
## Import a Pipeline
Import your Haystack pipeline into
Generative pipelines
For generative pipelines, the query input field is at the top of the page and the generated answers show below it:
Chat pipelines
Playground adjusts to the chat view:
Extractive pipelines
For extractive pipelines, the query input field is at the top and the extracted answers appear below it:
Document search pipelines
For document search pipelines, the query input field is at the top:
## Set the Pipeline Output Type
1. Log in to "
# Choose one of these options:
# pipeline_output_type: "generative"
# pipeline_output_type: "extractive"
# pipeline_output_type: "chat"
# pipeline_output_type: "document"
```
5. Save your pipeline.
## What To Do Next
You can [deploy](/docs/how-to-guides/designing-your-pipeline/deploy-a-pipeline.mdx) your pipeline and [try it out in Playground](/docs/how-to-guides/searching-with-your-pipeline/run-a-search.mdx).
---
## Simplify Pipelines with Smart Connections
# Simplify Your Pipelines
Remove unnecessary components from your pipelines by taking advantage of smart connections. Use this guide to learn how to simplify your pipelines.
***
## About This Task
Smart connections let the pipeline automatically merge lists and convert types between components. This means many "glue" components you used before are no longer needed. Your pipelines become shorter, easier to read, and simpler to debug.
| Component Previously Needed | Smart Connection Instead |
| :--- | :--- |
| `DocumentJoiner` | Connect all `document` outputs from sender components directly to one `list[Document]` input (example receiving components are `Ranker`, `PromptBuilder`, `DocumentSplitter`, `DocumentWriter`, `Embedder`, `AnswerBuilder`, typically to their `documents` input).|
| `ListJoiner` | Connect all sender components' outputs directly to one `list[ChatMessage]` input (example receiver is Agent's `messages` input).|
| `OutputAdapter` | Connect the LLM's `replies` output directly to the `Retriever`, `Ranker`, and other downstream components. |
| [`DeepsetChatHistoryParser`](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx) | Configure the `Input` component to produce `messages` and connect its `messages` output directly to the `Agent`'s `messages` input. |
For a full list of simplified components, see [Legacy Components](/docs/reference/pipeline-components/legacy-components.mdx).
For background on how smart connections work, see [Smart Connections](/docs/concepts/about-pipelines/about-pipelines.mdx#smart-connections).
## Remove DocumentJoiner
Components now accept multiple lists of documents, which eliminates the need for a `DocumentJoiner` in most cases. Below, you can find common use cases for `DocumentJoiner` and how to simplify them.
### Hybrid Retrieval Pipelines
If your pipeline uses multiple retrievers (for example, a BM25 retriever and an embedding retriever), you probably have a `DocumentJoiner` sitting between the retrievers and the next component. With smart connections, you can remove it and connect the retrievers directly to the downstream component.
The pipeline automatically merges the document lists into one before passing them along.
To simplify this pipeline:
1. Remove the `DocumentJoiner` component.
2. Reconnect `OpenSearchBM25Retriever`'s `documents` output to `TransformersSimilarityRanker`'s `documents` input.
3. Reconnect `OpenSearchEmbeddingRetriever`'s `documents` output to `TransformersSimilarityRanker`'s `documents` input.
Before: with DocumentJoiner
```yaml
components:
OpenSearchBM25Retriever:
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
- ${OPENSEARCH_HOST}
index: ''
embedding_dim: 768
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
use_ssl: true
verify_certs: false
top_k: 20
SentenceTransformersTextEmbedder:
type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: intfloat/e5-base-v2
OpenSearchEmbeddingRetriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
- ${OPENSEARCH_HOST}
index: ''
embedding_dim: 768
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
use_ssl: true
verify_certs: false
top_k: 20
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
TransformersSimilarityRanker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
Answer the question based on the provided documents.
Documents:
{% for document in documents %}
{{ document.content }}
{% endfor %}
Question: {{ question }}
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: gpt-4o
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
connections:
- sender: OpenSearchBM25Retriever.documents
receiver: DocumentJoiner.documents
- sender: SentenceTransformersTextEmbedder.embedding
receiver: OpenSearchEmbeddingRetriever.query_embedding
- sender: OpenSearchEmbeddingRetriever.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: TransformersSimilarityRanker.documents
- sender: TransformersSimilarityRanker.documents
receiver: PromptBuilder.documents
- sender: PromptBuilder.prompt
receiver: OpenAIGenerator.prompt
- sender: OpenAIGenerator.replies
receiver: AnswerBuilder.replies
inputs:
query:
- OpenSearchBM25Retriever.query
- SentenceTransformersTextEmbedder.text
- TransformersSimilarityRanker.query
- PromptBuilder.question
- AnswerBuilder.query
outputs:
answers: AnswerBuilder.answers
```
After: without DocumentJoiner
```yaml
components:
OpenSearchBM25Retriever:
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
- ${OPENSEARCH_HOST}
index: ''
embedding_dim: 768
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
use_ssl: true
verify_certs: false
top_k: 20
SentenceTransformersTextEmbedder:
type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: intfloat/e5-base-v2
OpenSearchEmbeddingRetriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
- ${OPENSEARCH_HOST}
index: ''
embedding_dim: 768
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
use_ssl: true
verify_certs: false
top_k: 20
TransformersSimilarityRanker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
Answer the question based on the provided documents.
Documents:
{% for document in documents %}
{{ document.content }}
{% endfor %}
Question: {{ question }}
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: gpt-4o
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
connections:
- sender: OpenSearchBM25Retriever.documents
receiver: TransformersSimilarityRanker.documents
- sender: SentenceTransformersTextEmbedder.embedding
receiver: OpenSearchEmbeddingRetriever.query_embedding
- sender: OpenSearchEmbeddingRetriever.documents
receiver: TransformersSimilarityRanker.documents
- sender: TransformersSimilarityRanker.documents
receiver: PromptBuilder.documents
- sender: PromptBuilder.prompt
receiver: OpenAIGenerator.prompt
- sender: OpenAIGenerator.replies
receiver: AnswerBuilder.replies
inputs:
query:
- OpenSearchBM25Retriever.query
- SentenceTransformersTextEmbedder.text
- TransformersSimilarityRanker.query
- PromptBuilder.question
- AnswerBuilder.query
outputs:
answers: AnswerBuilder.answers
```
### Indexes with Multiple File Converters
A common use case is to connect multiple file converters to a `DocumentWriter` in an index. To simplify such an index, do these steps:
1. Remove the `DocumentJoiner` component that collects documents from converters and sends them to `DocumentSplitter`.
2. Reconnect `TextFileToDocument`'s `documents` output (the converter for text files) to `DocumentSplitter`'s `documents` input.
3. Reconnect `PPTXToDocument`'s `documents` output to `DocumentSplitter`'s `documents` input.
4. Reconnect `PDFMinerToDocument`'s `documents` output to `DocumentSplitter`'s `documents` input.
5. Reconnect another `TextFileToDocument`'s `documents` output (the converter for Markdown files) to `DocumentSplitter`'s `documents` input.
6. Reconnect `HTMLToDocument`'s `documents` output to `DocumentSplitter`'s `documents` input.
7. Reconnect `DOCXToDocument`'s `documents` output to `DocumentSplitter`'s `documents` input.
8. Remove the second `DocumentJoiner` component that collects documents from `CSVToDocument`, `XLSXToDocument`, and `DocumentSplitter`, and sends them to `DeepsetNvidiaDocumentEmbedder`.
9. Reconnect `DocumentSplitter`'s `documents` output to `DeepsetNvidiaDocumentEmbedder`'s `documents` input.
10. Reconnect `CSVToDocument`'s `documents` output to `DeepsetNvidiaDocumentEmbedder`'s `documents` input.
11. Reconnect `XLSXToDocument`'s `documents` output to `DeepsetNvidiaDocumentEmbedder`'s `documents` input.
Before: with DocumentJoiner
```yaml
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
PDFMinerToDocument:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
HTMLToDocument:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
DOCXToDocument:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
PPTXToDocument:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
XLSXToDocument:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
CSVToDocument:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
DeepsetNvidiaDocumentEmbedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: ""
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
policy: OVERWRITE
connections:
- sender: FileTypeRouter.text/plain
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.application/pdf
receiver: PDFMinerToDocument.sources
- sender: FileTypeRouter.text/markdown
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.text/html
receiver: HTMLToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: DOCXToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: PPTXToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: XLSXToDocument.sources
- sender: FileTypeRouter.text/csv
receiver: CSVToDocument.sources
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: PDFMinerToDocument.documents
receiver: DocumentJoiner.documents
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: HTMLToDocument.documents
receiver: DocumentJoiner.documents
- sender: DOCXToDocument.documents
receiver: DocumentJoiner.documents
- sender: PPTXToDocument.documents
receiver: DocumentJoiner.documents
- sender: XLSXToDocument.documents
receiver: DocumentJoiner.documents
- sender: CSVToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DocumentJoiner.documents
- sender: XLSXToDocument.documents
receiver: DocumentJoiner.documents
- sender: CSVToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DeepsetNvidiaDocumentEmbedder.documents
- sender: DeepsetNvidiaDocumentEmbedder.documents
receiver: DocumentWriter.documents
inputs:
files:
- FileTypeRouter.sources
max_runs_per_component: 100
metadata: {}
```
After: without DocumentJoiner
```yaml
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
PDFMinerToDocument:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
HTMLToDocument:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
DOCXToDocument:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
PPTXToDocument:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
XLSXToDocument:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
CSVToDocument:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
DeepsetNvidiaDocumentEmbedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: ""
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
policy: OVERWRITE
connections:
- sender: FileTypeRouter.text/plain
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.application/pdf
receiver: PDFMinerToDocument.sources
- sender: FileTypeRouter.text/markdown
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.text/html
receiver: HTMLToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: DOCXToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: PPTXToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: XLSXToDocument.sources
- sender: FileTypeRouter.text/csv
receiver: CSVToDocument.sources
- sender: DeepsetNvidiaDocumentEmbedder.documents
receiver: DocumentWriter.documents
- sender: PPTXToDocument.documents
receiver: DocumentSplitter.documents
- sender: TextFileToDocument.documents
receiver: DocumentSplitter.documents
- sender: PDFMinerToDocument.documents
receiver: DocumentSplitter.documents
- sender: TextFileToDocument.documents
receiver: DocumentSplitter.documents
- sender: HTMLToDocument.documents
receiver: DocumentSplitter.documents
- sender: DOCXToDocument.documents
receiver: DocumentSplitter.documents
inputs:
files:
- FileTypeRouter.sources
max_runs_per_component: 100
metadata: {}
```
## Remove ListJoiner
Components now accept multiple lists of the same type, which means you can get rid of `ListJoiner` in most cases. Below, you can find common use cases for `ListJoiner` and how to simplify them.
### Joining ChatMessages
If you're joining multiple `list[ChatMessage]` using a `ListJoiner`, you can remove it. The pipeline now handles these conversions automatically. A common use case is joining messages from a [DeepsetChatHistoryParser](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx) with the current user's message to send them to the `Agent`, like in the RAG Research Agent template. You can now skip `ListJoiner` and connect the components directly. To do so, follow these steps:
1. Remove `ListJoiner`.
2. Connect [DeepsetChatHistoryParser](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx)'s `messages` output directly to the Agent's `messages` input.
3. Connect `ChatPromptBuilder`'s `prompt` output directly to the Agent's `messages` input.
Before: Joining ChatMessages with ListJoiner
```yaml
components:
adapter:
init_parameters:
custom_filters: {}
output_type: list[str]
template: '{{ [(messages|last).text] }}'
unsafe: false
type: haystack.components.converters.output_adapter.OutputAdapter
history_parser:
init_parameters: {}
type: deepset_cloud_custom_nodes.parsers.chat_history_parser.DeepsetChatHistoryParser
MultiFileConverter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: list[haystack.Document]
custom_filters:
unsafe: true
text_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_joiner.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: text_joiner.documents
- sender: pdf_converter.documents
receiver: text_joiner.documents
- sender: markdown_converter.documents
receiver: text_joiner.documents
- sender: html_converter.documents
receiver: text_joiner.documents
- sender: pptx_converter.documents
receiver: text_joiner.documents
- sender: docx_converter.documents
receiver: text_joiner.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
ChatPromptBuilder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template: |-
{% message role="user" %}
{%- if documents|length > 0 -%}
Here are documents provided by the user:
{% for document in documents -%}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{%- endfor -%}
{%- endif -%}
{% endmessage %}
ListJoiner:
type: haystack.components.joiners.list_joiner.ListJoiner
init_parameters:
list_type_: list[haystack.dataclasses.chat_message.ChatMessage]
Agent:
type: haystack.components.agents.agent.Agent
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.2
generation_kwargs:
reasoning:
effort: low
verbosity: low
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
exit_conditions:
- text
max_agent_steps: 100
raise_on_tool_invocation_failure: false
state_schema:
documents:
type: list[haystack.Document]
streaming_callback: deepset_cloud_custom_nodes.callbacks.streaming.streaming_callback
system_prompt: >-
You are a deep research assistant.
You create comprehensive research reports to answer the user's
questions.
You have one tool to gather data: 'local_search'.
The local_search tool supports hybrid retrieval using keywords, semantic
embeddings, and reranking.
Formulate natural language search queries that describe the full intent
of the question.
Use multiple varied searches to fully cover the topic.
Only information retrieved from local_search may be used to answer the
question.
If the question cannot be answered using this knowledge source,
explicitly state that it is not answerable and briefly explain why.
Do not use external knowledge, assumptions, or speculation.
When you use information from the local search, cite the source with the
documents reference number in square brackets where you use the
information (e.g. [5]).
This is IMPORTANT:
- Only use numbered citations for the local search results.
- Do NOT add a References section, cite directly in the text where you
use the information.
- For internal knowledge "some information" [3] as (taken from ).
- Format responses using markdown.
tools:
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: local_search
description: >-
Search the company's internal knowledge repository using hybrid
retrieval.
The search supports natural language queries, keyword matching,
semantic embeddings, and cross-encoder reranking.
Use descriptive, question-like queries to capture intent and
retrieve the most relevant documents.
input_mapping:
query:
- retriever.query
- ranker.query
documents:
- builder.existing_documents
output_mapping:
builder.prompt: formatted_docs
meta_field_grouping_ranker.documents: documents
inputs_from_state:
documents: documents
outputs_to_state:
documents:
source: documents
outputs_to_string:
source: formatted_docs
parameters:
is_pipeline_async: false
pipeline:
components:
builder:
init_parameters:
required_variables:
- existing_documents
- docs
template: |-
{%- if existing_documents is not none -%}
{%- set existing_doc_len = existing_documents|length -%}
{%- else -%}
{%- set existing_doc_len = 0 -%}
{%- endif -%}
{%- for doc in docs %}
{{ doc.content }}
{% endfor -%}
variables:
type: haystack.components.builders.prompt_builder.PromptBuilder
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
top_k: 20
fuzziness: 0
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: meta_field_grouping_ranker.documents
receiver: builder.docs
max_runs_per_component: 100
metadata: {}
DeepsetAnswerBuilder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: "{{ replies[0] }}"
output_type: str
custom_filters:
unsafe: false
connections:
- sender: MultiFileConverter.documents
receiver: ChatPromptBuilder.documents
- sender: ChatPromptBuilder.prompt
receiver: ListJoiner.values
- sender: history_parser.messages
receiver: ListJoiner.values
- sender: ListJoiner.values
receiver: Agent.messages
- sender: Agent.documents
receiver: DeepsetAnswerBuilder.documents
- sender: Agent.messages
receiver: OutputAdapter.replies
- sender: OutputAdapter.output
receiver: DeepsetAnswerBuilder.replies
inputs:
query:
- DeepsetAnswerBuilder.query
- history_parser.history_and_query
files:
- MultiFileConverter.sources
max_runs_per_component: 100
metadata: {}
outputs:
answers: DeepsetAnswerBuilder.answers
documents: Agent.documents
pipeline_output_type: chat
```
After: Joining ChatMessages without ListJoiner
```yaml
components:
adapter:
init_parameters:
custom_filters: {}
output_type: list[str]
template: '{{ [(messages|last).text] }}'
unsafe: false
type: haystack.components.converters.output_adapter.OutputAdapter
history_parser:
init_parameters: {}
type: deepset_cloud_custom_nodes.parsers.chat_history_parser.DeepsetChatHistoryParser
MultiFileConverter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: list[haystack.Document]
custom_filters:
unsafe: true
text_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_joiner.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: text_joiner.documents
- sender: pdf_converter.documents
receiver: text_joiner.documents
- sender: markdown_converter.documents
receiver: text_joiner.documents
- sender: html_converter.documents
receiver: text_joiner.documents
- sender: pptx_converter.documents
receiver: text_joiner.documents
- sender: docx_converter.documents
receiver: text_joiner.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
ChatPromptBuilder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template: |-
{% message role="user" %}
{%- if documents|length > 0 -%}
Here are documents provided by the user:
{% for document in documents -%}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{%- endfor -%}
{%- endif -%}
{% endmessage %}
Agent:
type: haystack.components.agents.agent.Agent
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.2
generation_kwargs:
reasoning:
effort: low
verbosity: low
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
exit_conditions:
- text
max_agent_steps: 100
raise_on_tool_invocation_failure: false
state_schema:
documents:
type: list[haystack.Document]
streaming_callback: deepset_cloud_custom_nodes.callbacks.streaming.streaming_callback
system_prompt: >-
You are a deep research assistant.
You create comprehensive research reports to answer the user's
questions.
You have one tool to gather data: 'local_search'.
The local_search tool supports hybrid retrieval using keywords, semantic
embeddings, and reranking.
Formulate natural language search queries that describe the full intent
of the question.
Use multiple varied searches to fully cover the topic.
Only information retrieved from local_search may be used to answer the
question.
If the question cannot be answered using this knowledge source,
explicitly state that it is not answerable and briefly explain why.
Do not use external knowledge, assumptions, or speculation.
When you use information from the local search, cite the source with the
documents reference number in square brackets where you use the
information (e.g. [5]).
This is IMPORTANT:
- Only use numbered citations for the local search results.
- Do NOT add a References section, cite directly in the text where you
use the information.
- For internal knowledge "some information" [3] as (taken from ).
- Format responses using markdown.
tools:
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: local_search
description: >-
Search the company's internal knowledge repository using hybrid
retrieval.
The search supports natural language queries, keyword matching,
semantic embeddings, and cross-encoder reranking.
Use descriptive, question-like queries to capture intent and
retrieve the most relevant documents.
input_mapping:
query:
- retriever.query
- ranker.query
documents:
- builder.existing_documents
output_mapping:
builder.prompt: formatted_docs
meta_field_grouping_ranker.documents: documents
inputs_from_state:
documents: documents
outputs_to_state:
documents:
source: documents
outputs_to_string:
source: formatted_docs
parameters:
is_pipeline_async: false
pipeline:
components:
builder:
init_parameters:
required_variables:
- existing_documents
- docs
template: |-
{%- if existing_documents is not none -%}
{%- set existing_doc_len = existing_documents|length -%}
{%- else -%}
{%- set existing_doc_len = 0 -%}
{%- endif -%}
{%- for doc in docs %}
{{ doc.content }}
{% endfor -%}
variables:
type: haystack.components.builders.prompt_builder.PromptBuilder
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
top_k: 20
fuzziness: 0
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: meta_field_grouping_ranker.documents
receiver: builder.docs
max_runs_per_component: 100
metadata: {}
DeepsetAnswerBuilder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: "{{ replies[0] }}"
output_type: str
custom_filters:
unsafe: false
connections:
- sender: MultiFileConverter.documents
receiver: ChatPromptBuilder.documents
- sender: Agent.documents
receiver: DeepsetAnswerBuilder.documents
- sender: Agent.messages
receiver: OutputAdapter.replies
- sender: OutputAdapter.output
receiver: DeepsetAnswerBuilder.replies
- sender: history_parser.messages
receiver: Agent.messages
- sender: ChatPromptBuilder.prompt
receiver: Agent.messages
inputs:
query:
- DeepsetAnswerBuilder.query
- history_parser.history_and_query
files:
- MultiFileConverter.sources
max_runs_per_component: 100
metadata: {}
outputs:
answers: DeepsetAnswerBuilder.answers
documents: Agent.documents
pipeline_output_type: chat
```
## Remove OutputAdapter for Type Conversions
### RAG Chat with LLM sending input to a Retriever and a Ranker
In chat pipelines, where the first LLM reformulates the query to be used for retrieval augmented generation, you can remove the `OutputAdapter` and connect the `ChatGenerator` directly to the `Retriever` or `Ranker`.
This is an example of a RAG chat pipeline with an `OutputAdapter` and a `DocumentJoiner` that you can simplify. Follow these steps:
1. Remove `OutputAdapter`.
2. Connect the `replies` output of the first `OpenAIGenerator` to the following components' inputs:
- `OpenSearchHybridRetriever`'s `query` input.
- `DeepsetNvidiaRanker`'s `query` input.
- `PromptBuilder`'s `question` input.
- `DeepsetAnswerBuilder`'s `query` input.
3. Remove `DocumentJoiner`.
4. Connect `MultiFileConverter`'s `documents` output to the following components' inputs:
- The second `PromptBuilder`'s `documents` input.
- `DeepsetAnswerBuilder`'s `documents` input.
- `Output`'s `documents` input.
5. Connect `DeepsetNvidiaRanker`'s `documents` output to the following components' inputs:
- The second `PromptBuilder`'s `documents` input.
- `DeepsetAnswerBuilder`'s `documents` input.
- `Output`'s `documents` input.
Before: LLM connected to a Retriever through an OutputAdapter
```yaml
components:
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
required_variables: "*"
template: |-
You are part of a chatbot.
You receive a question (Current Question) and a chat history.
Use the context from the chat history and reformulate the question so that it is suitable for retrieval augmented generation.
If X is followed by Y, only ask for Y and do not repeat X again.
If the question does not require any context from the chat history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key:
"type": "env_var"
"env_vars":
- "OPENAI_API_KEY"
"strict": False
model: "gpt-5.2"
generation_kwargs:
reasoning_effort: low
verbosity: low
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: "{{ replies[0] }}"
output_type: str
OpenSearchHybridRetriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: ""
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
DeepsetNvidiaRanker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
required_variables: '*'
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Just output the structured, informative and precise answer and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document [3] .
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found, please adjust the filters or try a different question."
{% endif %}
Question: {{ question }}
Answer:
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key:
"type": "env_var"
"env_vars":
- "OPENAI_API_KEY"
"strict": False
model: "gpt-5.2"
generation_kwargs:
reasoning_effort: low
verbosity: low
DeepsetAnswerBuilder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
MultiFileConverter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: List[haystack.Document]
custom_filters:
unsafe: true
text_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_joiner.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: text_joiner.documents
- sender: pdf_converter.documents
receiver: text_joiner.documents
- sender: markdown_converter.documents
receiver: text_joiner.documents
- sender: html_converter.documents
receiver: text_joiner.documents
- sender: pptx_converter.documents
receiver: text_joiner.documents
- sender: docx_converter.documents
receiver: text_joiner.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
connections:
- sender: PromptBuilder.prompt
receiver: OpenAIGenerator.prompt
- sender: OpenAIGenerator.replies
receiver: OutputAdapter.replies
- sender: OutputAdapter.output
receiver: OpenSearchHybridRetriever.query
- sender: OutputAdapter.output
receiver: DeepsetNvidiaRanker.query
- sender: OutputAdapter.output
receiver: PromptBuilder.question
- sender: OutputAdapter.output
receiver: DeepsetAnswerBuilder.query
- sender: retriever.documents
receiver: DeepsetNvidiaRanker.documents
- sender: PromptBuilder.prompt
receiver: OpenAIGenerator.prompt
- sender: PromptBuilder.prompt
receiver: DeepsetAnswerBuilder.prompt
- sender: OpenAIGenerator.replies
receiver: DeepsetAnswerBuilder.replies
- sender: MultiFileConverter.documents
receiver: DocumentJoiner.documents
- sender: DeepsetNvidiaRanker.documents
receiver: attachments_joiner.documents
- sender: DocumentJoiner.documents
receiver: DeepsetAnswerBuilder.documents
- sender: DocumentJoiner.documents
receiver: PromptBuilder.documents
inputs:
query:
- PromptBuilder.question
filters:
- OpenSearchHybridRetriever.filters_bm25
- OpenSearchHybridRetriever.filters_embedding
files:
- MultiFileConverter.sources
outputs:
documents: DocumentJoiner.documents
answers: DeepsetAnswerBuilder.answers
max_runs_per_component: 100
metadata: {}
```
After: LLM connected directly to a Retriever and a Ranker
This is a simplified version of the pipeline above. You can remove the `DocumentJoiner` and `OutputAdapter`and connect the components directly.
```yaml
components:
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
required_variables: "*"
template: |-
You are part of a chatbot.
You receive a question (Current Question) and a chat history.
Use the context from the chat history and reformulate the question so that it is suitable for retrieval augmented generation.
If X is followed by Y, only ask for Y and do not repeat X again.
If the question does not require any context from the chat history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key:
"type": "env_var"
"env_vars":
- "OPENAI_API_KEY"
"strict": False
model: "gpt-5.2"
generation_kwargs:
reasoning_effort: low
verbosity: low
OpenSearchHybridRetriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: ""
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
DeepsetNvidiaRanker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
required_variables: '*'
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Just output the structured, informative and precise answer and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document [3] .
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found, please adjust the filters or try a different question."
{% endif %}
Question: {{ question }}
Answer:
OpenAIGenerator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key:
"type": "env_var"
"env_vars":
- "OPENAI_API_KEY"
"strict": False
model: "gpt-5.2"
generation_kwargs:
reasoning_effort: low
verbosity: low
DeepsetAnswerBuilder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
MultiFileConverter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: List[haystack.Document]
custom_filters:
unsafe: true
text_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_joiner.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: text_joiner.documents
- sender: pdf_converter.documents
receiver: text_joiner.documents
- sender: markdown_converter.documents
receiver: text_joiner.documents
- sender: html_converter.documents
receiver: text_joiner.documents
- sender: pptx_converter.documents
receiver: text_joiner.documents
- sender: docx_converter.documents
receiver: text_joiner.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
connections:
- sender: PromptBuilder.prompt
receiver: OpenAIGenerator.prompt
- sender: OpenSearchHybridRetriever.documents
receiver: DeepsetNvidiaRanker.documents
- sender: PromptBuilder.prompt
receiver: DeepsetAnswerBuilder.prompt
- sender: OpenAIGenerator.replies
receiver: DeepsetAnswerBuilder.replies
- sender: DeepsetNvidiaRanker.documents
receiver: PromptBuilder.documents
- sender: DeepsetNvidiaRanker.documents
receiver: DeepsetAnswerBuilder.documents
- sender: OpenAIGenerator.replies
receiver: DeepsetNvidiaRanker.query
- sender: OpenAIGenerator.replies
receiver: DeepsetAnswerBuilder.query
- sender: MultiFileConverter.documents
receiver: DeepsetAnswerBuilder.documents
- sender: MultiFileConverter.documents
receiver: PromptBuilder.documents
- sender: MultiFileConverter.documents
receiver: Output.documents
inputs:
query:
- PromptBuilder.question
filters:
- OpenSearchHybridRetriever.filters_bm25
- OpenSearchHybridRetriever.filters_embedding
files:
- MultiFileConverter.sources
outputs:
answers: DeepsetAnswerBuilder.answers
max_runs_per_component: 100
metadata: {}
```
### When You Still Need OutputAdapter
You still need `OutputAdapter` when:
- You're converting between types that smart connections don't support (anything other than `string` and `ChatMessage`).
- You need explicit control over formatting, ordering, or extracting specific fields from the output.
## Remove DeepsetChatHistoryParser
[DeepsetChatHistoryParser](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx) was most commonly used with the `Agent` component to pass messages augmented with chat history to the `Agent`. Currently, this is done automatically. You can connect the `Input` component's `messages` output directly to the `Agent`'s `messages` input. `messages` include prior conversations from the search history.
To simplify pipelines that contain [DeepsetChatHistoryParser](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx):
1. Delete [DeepsetChatHistoryParser](/docs/reference/pipeline-components/legacy-components/DeepsetChatHistoryParser.mdx) from your pipeline.
2. On the `Input` component card, click **Configure** and `-messages` as a connection point.
3. Connect the `Input` component's `messages` output to the `Agent`'s `messages` input.
That's it. Your `Agent` will now receive messages augmented with chat history.
---
## Troubleshoot Pipelines and Indexes
Diagnose and resolve common issues with pipelines and indexes.
***
## Pipeline Issues
When creating or updating a pipeline, you may see validation errors that prevent deployment. Here are common errors and how to resolve them.
:::tip Find and Fix Issues Faster
Use the global Issues panel in Builder. You can find it at the bottom of the canvas. Expand the panel to view all validation and runtime issues in one place. Click **Inspect** next to any issue to jump directly to the affected component or connection. Click **Fix with AI** to open the AI assistant, which reasons through the fix and can apply it for you.
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack_integrations.components.embedders.cohere.document_embedder.CohereDocumentEmbedder
init_parameters:
model: embed-english-v3.0
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
```yaml Query Pipeline
components:
# ...
query_embedder:
type: haystack_integrations.components.embedders.cohere.text_embedder.CohereTextEmbedder
init_parameters:
model: embed-english-v3.0
retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20
ranker:
type: haystack_integrations.components.rankers.cohere.ranker.CohereRanker
init_parameters:
model: rerank-english-v3.0
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{question}}
Answer:
generator:
type: haystack_integrations.components.generators.cohere.generator.CohereGenerator
init_parameters:
generation_kwargs:
temperature: 0.0
model: command
answer_builder:
init_parameters: {}
type: haystack.components.builders.answer_builder.AnswerBuilder
connections: # Defines how the components are connected
# ...
- sender: query_embedder.embedding
receiver: retriever.query_embedding
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: prompt_builder.documents
- sender: prompt_builder.prompt
receiver: generator.prompt
- sender: generator.replies
receiver: answer_builder.replies
inputs:
query:
# ...
- "query_embedder.text" # TextEmbedder needs query as input and it's not getting it
- "retriever.query" # from any component it's connected to, so it needs to receive it from the pipeline.
- "prompt_builder.question"
- "answer_builder.query"
- "ranker.query"
```
---
## Use DeepL Translation Services
Translate your documents using DeepL services.
***
## Prerequisites
You need an active DeepL account and a DeepL API key. For guidance on how to obtain it, see [API Key for DeepL's API](https://support.deepl.com/hc/en-us/articles/360020695820-API-Key-for-DeepL-s-API).
## Use DeepL
First, connect
```yaml Pipeline
# haystack-pipeline
components:
# ...
query_embedder:
type: haystack_integrations.components.embedders.nvidia.text_embedder.NvidiaTextEmbedder
init_parameters:
api_url: "https://ai.api.nvidia.com/v1/retrieval/nvidia" # custom API URL for NVIDIA NIM.
model: "NV-Embed-QA" # the model to use
retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20
prompt_builder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template: >
- _content:
- text: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{ query }}
_role: user
required_variables:
variables:
generator:
type: haystack_integrations.components.generators.nvidia.chat.chat_generator.NvidiaChatGenerator
init_parameters:
model: "meta/llama3-70b-instruct" # here, pass the name of the model to use
api_base_url: "https://integrate.api.nvidia.com/v1"
generation_kwargs:
temperature: 0.2
top_p: 0.7
max_tokens: 1024
output_adapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ replies[0] }}'
output_type: List[str]
custom_filters:
unsafe: false
answer_builder:
init_parameters: {}
type: haystack.components.builders.answer_builder.AnswerBuilder
connections:
# ...
- sender: query_embedder.embedding
receiver: retriever.query_embedding
- sender: retriever.documents
receiver: prompt_builder.documents
- sender: prompt_builder.prompt
receiver: generator.messages
- sender: generator.replies
receiver: output_adapter.replies
- sender: output_adapter.output
receiver: answer_builder.replies
```
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack_integrations.components.embedders.nvidia.document_embedder.NvidiaDocumentEmbedder
init_parameters:
api_url: "https://ai.api.nvidia.com/v1/retrieval/nvidia" # A required custom NVIDIA API URL for NVIDIA NIM
model: "NV-Embed-QA" # the model to use
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
## Related Information
- [Add Custom Model Definitions](/docs/how-to-guides/managing-access/add-custom-model-definitions.mdx)
- [LLM](/docs/reference/pipeline-components/ai/LLM.mdx)
---
## Use OpenAI Models
Use OpenAI models in your pipelines.
***
## About This Task
You can use OpenAI's embedding models and LLMs:
- For a list of embedding models, see [OpenAI documentation](https://platform.openai.com/docs/guides/embeddings/embedding-models).
- For a list of LLMs, see [OpenAI model overview](https://platform.openai.com/docs/models/models-overview).
## Prerequisites
You need an API key from an active OpenAI account. For details on obtaining it, see [Secret keys in OpenAI](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key).
## Use OpenAI Models
First, connect
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack.components.embedders.openai_document_embedder.OpenAIDocumentEmbedder
init_parameters:
model: text-embedding-ada-002 # the model to use
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
```yaml Query Pipeline
# haystack-pipeline
pipeline_output_type: "chat"
components:
retriever:
# Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
index: Standard-Index-English
max_chunk_bytes: 104857600
return_embedding: false
create_index: true
settings:
index.knn: true
top_k: 20 # The number of results to return
embedder:
type: haystack.components.embedders.openai_text_embedder.OpenAITextEmbedder
init_parameters:
model: text-embedding-ada-002
fuzziness: 0
ranker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
device: null
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
qa_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
# You can swap this for any other model. Switch to the Builder view and choose another model from the list on the component card.
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Just output the structured, informative and precise answer and nothing
else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using
information from a document, e.g. [3] for Document [3] .
Never name the documents, only enter a number in square brackets as a
reference.
The reference must only refer to the number that comes in square
brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the
number of the document without mentioning the word document.
These are the documents:
{%- if documents|length > 0 %}
{% for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor %}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found, please adjust the
filters or try a different question."
{% endif %}
Question: {{ question.text }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: meta_field_grouping_ranker.documents
receiver: qa_llm.documents
inputs:
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files: []
query:
- qa_llm.question
- ranker.query
- retriever.query
outputs:
documents: meta_field_grouping_ranker.documents
messages: qa_llm.messages
updated_query:
max_runs_per_component: 100
metadata: {}
```
Here is how to connect the components in Pipeline Builder. In the index, `OpenAIDocumentEmbedder` receives documents from `DocumentSplitter` and then passes the embedded documents to `DocumentWriter`, which writes them into the Document Store:
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack_integrations.components.embedders.voyage_embedders.voyage_document_embedder.VoyageDocumentEmbedder
init_parameters:
model: "voyage-2" # the model to use
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
```yaml
components:
# ...
query_embedder:
type: haystack_integrations.components.embedders.voyage_embedders.voyage_text_embedder.VoyageTextEmbedder
init_parameters:
model: "voyage-2" # the model to use
retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{question}}
Answer:
generator:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: "gpt-3.5-turbo" # the model to use
generation_kwargs: # additional parameters for the model
max_tokens: 400
temperature: 0.0
seed: 0
answer_builder:
init_parameters: {}
type: haystack.components.builders.answer_builder.AnswerBuilder
connections: # Defines how the components are connected
# ...
- sender: query_embedder.embedding
receiver: retriever.query_embedding
- sender: retriever.documents
receiver: prompt_builder.documents
- sender: prompt_builder.prompt
receiver: generator.prompt
- sender: generator.replies
receiver: answer_builder.replies
inputs:
query:
# ...
- "query_embedder.text" # TextEmbedder needs query as input and it's not getting it
- "retriever.query" # from any component it's connected to, so it needs to receive it from the pipeline.
- "prompt_builder.question"
- "answer_builder.query"
```
## Related Information
- [Add Custom Model Definitions](/docs/how-to-guides/managing-access/add-custom-model-definitions.mdx)
- [LLM](/docs/reference/pipeline-components/ai/LLM.mdx)
---
## Use Amazon Bedrock Models
You can use models hosted in your own Bedrock account.
***
You can use embedding models and LLMs hosted on Amazon Bedrock through Bedrock's API. You can connect to your Bedrock account using your Bedrock API key of IAM access key.
For a full list of supported models, see [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html).
## Bedrock Prompt Caching
Amazon Bedrock models support prompt caching for system prompts. You can set the `system_cachepoint_config_ttl` for models hosted on Amazon Bedrock to cache your system prompt for 5 minutes (`"5m"`) or 1 hour (`"1h"`), reducing latency and cost for repeated requests that share the same system prompt. The system prompt must stay static, with no parameters, for the cache to work.
## Prerequisites
- To connect using your Bedrock API key, you must have a valid API key.
- To connect using your IAM access key, you must have a valid access key ID and secret access key for your Amazon region.
For details, see [Amazon Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) and [Amazon Bedrock documentation](https://docs.aws.amazon.com/sagemaker/latest/dg/gs.html).
## Using Bedrock Models
First, connect
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack_integrations.components.embedders.amazon_bedrock.document_embedder.AmazonBedrockDocumentEmbedder
init_parameters:
model: "cohere.embed-english-v3"
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
```yaml
# haystack-pipeline
inputs:
query:
- AmazonBedrockTextEmbedder.text
filters: []
files: []
messages: []
components:
LLM:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: global.anthropic.claude-sonnet-4-6
type: haystack_integrations.components.generators.amazon_bedrock.chat.chat_generator.AmazonBedrockChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The
answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{ question }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
AmazonBedrockTextEmbedder:
type: haystack_integrations.components.embedders.amazon_bedrock.text_embedder.AmazonBedrockTextEmbedder
init_parameters:
model:
aws_access_key_id:
type: env_var
env_vars:
- AWS_ACCESS_KEY_ID
strict: false
aws_secret_access_key:
type: env_var
env_vars:
- AWS_SECRET_ACCESS_KEY
strict: false
aws_session_token:
type: env_var
env_vars:
- AWS_SESSION_TOKEN
strict: false
aws_region_name:
type: env_var
env_vars:
- AWS_DEFAULT_REGION
strict: false
aws_profile_name:
type: env_var
env_vars:
- AWS_PROFILE
strict: false
boto3_config:
OpenSearchEmbeddingRetriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
filters:
top_k: 10
filter_policy: replace
custom_query:
raise_on_failure: true
efficient_filtering: true
search_kwargs:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
index: ""
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
settings:
index.knn: true
create_index: true
outputs:
answers:
documents:
messages: LLM.messages
connections:
- sender: AmazonBedrockTextEmbedder.embedding
receiver: OpenSearchEmbeddingRetriever.query_embedding
- sender: OpenSearchEmbeddingRetriever.documents
receiver: LLM.documents
```
## Related Information
- [Add Custom Model Definitions](/docs/how-to-guides/managing-access/add-custom-model-definitions.mdx)
---
## Use Azure OpenAI Models
Use OpenAI models deployed through Azure services in your pipelines.
***
For a list of supported models, see [Azure documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?source=recommendations).
:::tip Anthropic on Azure
For information on using Anthropic models on Azure, see [Use Anthropic Models on Azure](/docs/how-to-guides/designing-your-pipeline/use-hosted-models-and-services/use-anthropic-models.mdx#use-anthropic-models-on-azure).
:::
## Prerequisites
You need an Azure OpenAI API key and Azure OpenAI endpoint. For details, see [Azure REST API reference](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).
## Use Azure OpenAI
First, connect
```yaml
components:
# ...
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
document_embedder:
type: haystack.components.embedders.azure_document_embedder.AzureOpenAIDocumentEmbedder
init_parameters:
azure_deployment: "text-embedding-ada-002" # this is the name of the model you want to use
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
similarity: cosine
policy: OVERWRITE
connections: # Defines how the components are connected
# ...
- sender: splitter.documents
receiver: document_embedder.documents
- sender: document_embedder.documents
receiver: writer.documents
```
```yaml Query Pipeline
components:
# ...
query_embedder:
type: haystack.components.embedders.azure_text_embedder.AzureOpenAITextEmbedder
init_parameters:
azure_endpoint: "https://your-company.azure.openai.com/"
azure_deployment: "text-embedding-ada-002" #this is the name of the model you want to use
retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
top_k: 20
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{question}}
Answer:
generator:
type: haystack.components.generators.azure.AzureOpenAIGenerator
init_parameters:
generation_kwargs:
temperature: 0.0
azure_deployment: gpt-35-turbo #this is the model you want to use
answer_builder:
init_parameters: {}
type: haystack.components.builders.answer_builder.AnswerBuilder
connections: # Defines how the components are connected
# ...
- sender: query_embedder.embedding
receiver: retriever.query_embedding
- sender: retriever.documents
receiver: prompt_builder.documents
- sender: prompt_builder.prompt
receiver: generator.prompt
- sender: generator.replies
receiver: answer_builder.replies
inputs:
query:
# ...
- "query_embedder.text" # TextEmbedder needs query as input and it's not getting it
- "retriever.query" # from any component it's connected to, so it needs to receive it from the pipeline.
- "prompt_builder.question"
- "answer_builder.query"
```
## Related Information
- [Add Custom Model Definitions](/docs/how-to-guides/managing-access/add-custom-model-definitions.mdx)
- [LLM](/docs/reference/pipeline-components/ai/LLM.mdx)
---
## Add Custom Code
# Adding Custom Code
Add custom Python code to enhance your pipelines.
***
## About This Task
You can add custom Python code to your pipelines in two ways:
- [With a `Code` component in Builder](./create-code-component.mdx) (recommended): Write your component code directly in Builder and test it right away. You can use it in a single pipeline or save it as a custom component to share with your workspace or organization.
- [With a GitHub template](./add-custom-component.mdx): Write your component in your IDE using a GitHub template and upload it to
Example
This is an example of a `Code` component that counts words in a text. The component takes a string as input and returns the number of words in the string and the original string.
```python
@component
class WordCounter:
"""
A component that counts words in a text.
"""
@component.output_types(count=int, original_text=str)
def run(self, text: str):
return {
"count": len(text.split()),
"original_text": text
}
```
5. If your class defines `__init__` parameters, click the **Advanced** tab in the configuration panel to set their values.
6. Run the component to test it:
1. On the component card, click **Run**.
2. Enter the component inputs and click **Run Component**. You should see the component's outputs in the Results panel.
7. Connect the component to the other components it needs to work with.
8. Save your pipeline.
## Save a Code Component as a Custom Component
To save a `Code` component as a custom component and reuse it in other pipelines:
1. On the component card, click **Save as Custom Component**.
/.py` file.
3. Update the component version in the `./dc-custom-component-template/src/dc_custom_component/__about__.py` file.
:::info Checking the current version
You can check the version of the component that's currently in /.py` file, treating them as separate components and giving each version a distinct name.
3. Update the component version in the `./dc-custom-component-template/src/dc_custom_component/__about__.py` file.
4. [Upload your components to
```shell Linux and macOS
zip -r ../custom_component.zip ./*
```
```shell Windows
Compress-Archive -Path .\* -DestinationPath ..\custom_component.zip -Force
```
2. Upload the ZIP file to
```curl
curl
--request POST \
--url https://api.cloud.deepset.ai/api/v2/custom_components \
--header 'accept: application/json' \
--header 'Authorization: Bearer api_XXX' \
--form 'file=@"/path/to/custom/component/custom_component.zip";type=application/zip'
```
```python
url = "https://api.cloud.deepset.ai/api/v2/custom_components"
files = { "file": ("custom_component.zip", open("path/to/custom_component.zip", "rb"), "application/x-zip-compressed") }
headers = {
"accept": "application/json",
"authorization": "Bearer deepset_cloud_API_key"
}
response = requests.post(url, files=files, headers=headers)
print(response.text)
```
### Upload with Commands
This method is currently available for Linux and macOS systems.
1. Set your
```
2. From within this project (custom component template),run the following command to upload your custom component:
```shell
hatch run dc:build-and-push
```
This command creates a ZIP file called `custom_component.zip` in the `dist` directory and uploads it to
```python
url = "https://api.cloud.deepset.ai/api/v2/custom_components"
headers = {
"accept": "application/json",
"authorization": "Bearer deepset_cloud_API_key"
}
response = requests.get(url, headers=headers)
print(response.text)
```
```curl
curl --request GET \
--url https://api.cloud.deepset.ai/api/v2/custom_components \
--header 'accept: application/json' \
--header 'authorization: Bearer deepset_cloud_API_key'
```
:::info
It takes a while for the custom component to be available in Pipeline Builder. Refresh the page and wait a couple of minutes.
:::
## What to Do Next
Once the component is successfully uploaded to
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/WORKSPACE_NAME/pipelines/PIPELINE_NAME/search-stream \
--header 'accept: application/json' \
--header 'authorization: Bearer DEEPSET_API_KEY' \
--header 'content-type: application/json' \
--data '
{
"debug": false,
"include_result": true,
"view_prompts": false,
"query": "who started all-girl bands?"
}
'
```
```python
url = "https://api.cloud.deepset.ai/api/v1/workspaces/WORKSPACE_NAME/pipelines/PIPELINE_NAME/search-stream"
payload = {
"debug": False,
"include_result": True,
"view_prompts": False,
"query": "who started all-girl bands?"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer DEEPSET_API_KEY"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
Replace:
- `WORKSPACE_NAME`: With the name of the workspace containing your pipeline.
- `PIPELINE_NAME`: With the name of the pipeline to use for search.
- `DEEPSET_API_KEY`: With your
Click to read the instructions
With this approach, you need two components connected together: `PromptBuilder` and a `Generator`. You pass the prompt in `PromptBuilder`'s `template` parameter. At search time, `PromptBuilder` renders the template, fills in the variables with real values, and sends the rendered prompt to the `Generator`.
The `Generator` is essentially the LLM. There's a `Generator` for each model provider, for example, `OpenAIGenerator`, `CohereGenerator`, and so on. When the pipeline runs, the `Generator` receives the prompt with all variables filled in and generates a response based on the instructions.
This is an example of using `PromptBuilder` in Pipeline Builder with a basic prompt template. It contains two variables: `question` and `documents`, which will be populated with the user query and retrieved documents and then sent to the Generator:
### ChatPromptBuilder and ChatGenerator
:::warning Legacy approach
This is a legacy approach and will be deprecated in future releases. We recommend using the `LLM` component instead. It works with any LLM provider and replaces both `ChatPromptBuilder` and `ChatGenerator` components. For details, see [LLM](/docs/reference/pipeline-components/ai/LLM.mdx).
:::
Click to read the instructions
ChatGenerators receive the prompt from `ChatPromptBuilder`. You can configure the prompt using `ChatPromptBuilder`'s `template` parameter. `ChatGenerators` require a list of `ChatMessage` objects as input, which means the format of the prompt must comply with the `ChatMessage` format:
## Adding Variables to Prompts
You can use Jinja2 syntax to insert variables into your prompts. Each variable is replaced with real values when the pipeline runs. The values come from the components that are connected upstream in your pipeline: whatever a component outputs (for example, `documents` from a Retriever, or `query` from the Input component) can be used as a variable in the prompt, as long as the components are connected so that the prompt receives the values at runtime. The prompt template is rendered with these values and then the final prompt is sent to the LLM.
For example, in this prompt, the variable `{{ question }}` is a placeholder for the user query:
```jinja2
You are a technical expert.
You answer questions truthfully based on your knowledge.
Ignore typing errors in the question.
Question: {{ question }}
Answer:
```
In this example, prompt needs the query. In Builder, you simply connect the `Input` component's `query` output to the prompt's `question` input:
.`. For attributes like meta, you can specify the key you want. For instance, to include the `date_created` metadata key, use: `document.meta.date_created`.
This Jinja2 expression adds the document's score, content, and date_created metadata key to the prompt:
```jinja2
You are a technical expert.
You answer questions truthfully based on provided documents.
If the answer exists in several documents, summarize them.
Ignore documents that don't contain the answer to the question.
Only answer based on the documents provided. Don't make things up.
If no information related to the question can be found in the document, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
Here are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
Date created: {{ document.meta.date_created }}
{{ document.content }}
{% endfor %}
Question: {{ question }}
Answer:
```
Rendered prompt
```
You are a technical expert.
You answer questions truthfully based on provided documents.
If the answer exists in several documents, summarize them.
Ignore documents that don't contain the answer to the question.
Only answer based on the documents provided. Don't make things up.
If no information related to the question can be found in the document, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
Here are the documents:
Document[1]:
Date created: 19-Aug-2004
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
More Than One Way To Do It
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Okay, the Zen doesn't say that there should be Only One Way To Do It.
But it does have a prohibition against allowing "more than one way to
do it".
''''''''Response
''''''''
There is no such prohibition. The "Zen of Python" merely expresses a
*preference* for "only one *obvious* way"::
There should be one-- and preferably only one --obvious way to do
it.
The emphasis here is that there should be an obvious way to do "it".
In the case of dict update operations, there are at least two
different operations that we might wish to do:
- *Update a dict in place*: The Obvious Way is to use the ``update()``
method. If this proposal is accepted, the ``|=`` augmented
assignment operator will also work, but that is a side-effect of how
augmented assignments are defined. Which you choose is a matter of
taste.
- *Merge two existing dicts into a third, new dict*: This PEP proposes
that the Obvious Way is to use the ``|`` merge operator.
In practice, this preference for "only one way" is frequently violated
in Python. For example, every ``for`` loop could be re-written as a
``while`` loop; every ``if`` block could be written as an ``if``/
``else`` block. List, set and dict comprehensions could all be
replaced by generator expressions.
Document[2]:
Date created: 19-Aug-2004
PEP: 20
Title: The Zen of Python
Author: Tim Peters
Status: Active
Type: Informational
Content-Type: text/x-rst
Post-History: 22-Aug-2004
Abstract
========
Long time Pythoneer Tim Peters succinctly channels the BDFL's guiding
principles for Python's design into 20 aphorisms, only 19 of which
have been written down.
The Zen of Python
=================
.. code-block:: text
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Easter Egg
==========
.. code-block:: pycon
>>> import this
References
==========
Originally posted to comp.lang.python/python-list@python.org under a
thread called `"The Way of Python"
`__
Copyright
=========
This document has been placed in the public domain.
Document[3]:
Date created: 19-Aug-2004
The trio is not expected to preach/advertise for
Python. They can if they want to, but not expected.
- Not an educator of Python. The trio is not expected to be the ones teaching/writing
about Python. They can if they want to, but not expected.
- The trio is not expected to be available 24/7, 365 days a year. They are free
to decide for themselves their availability for Python.
- Not a PEP editor.
Guidelines for the formation of the trio
========================================
The success of this governance model relies on the members of the trio, and the
ability of the trio members to collaborate and work well together.
The three people need to have similar vision to Python, and each can have
different skills that complement one another.
With such a team, disagreements and conflict should be rare, but can still happen.
We will need to trust the people we select that they are able to resolve this among
themselves.
When it comes to select the members of the trio, instead of nominating various
individuals and choosing the top three, core developers will nominate trios
and vote for groups of threes who they believe can form this united trio. There
is no restriction that an individual can only be nominated in one slate.
This PEP will not name or nominate anyone into the trio.
Only once this PEP is accepted, any active core developers (who are eligible to vote)
can submit nomination of groups of three.
Document[4]:
Date created: 19-Aug-2004
Typically only exceptions that
signal an error are desired to be caught. This means that exceptions
that are used to signify that the interpreter should exit should not
be caught in the common case.
With KeyboardInterrupt and SystemExit moved to inherit from
BaseException instead of Exception, changing bare ``except`` clauses
to act as ``except Exception`` becomes a much more reasonable
default. This change also will break very little code since these
semantics are what most people want for bare ``except`` clauses.
The complete removal of bare ``except`` clauses has been argued for.
The case has been made that they violate both Only One Way To Do It
(OOWTDI) and Explicit Is Better Than Implicit (EIBTI) as listed in the
:pep:`Zen of Python <20>`. But Practicality Beats Purity (PBP), also in
the Zen of Python, trumps both of these in this case. The BDFL has
stated that bare ``except`` clauses will work this way
[#python-dev8]_.
Implementation
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
The compiler will emit the bytecode for ``except Exception`` whenever
a bare ``except`` clause is reached.
Transition Plan
===============
Because of the complexity and clutter that would be required to add
all features planned in this PEP, the transition plan is very simple.
In Python |2.x| BaseException is added. In Python 3.0, all remaining
features (required superclass, change in inheritance, bare ``except``
clauses becoming the same as ``except Exception``) will go into
affect.
Document[5]:
Date created: 19-Aug-2004
* random_bytes - returns a random byte string.
* random_number - depending on the argument, returns either a random
integer in the range(0, n), or a random float between 0.0 and 1.0.
* urlsafe_base64 - returns a random URL-safe Base64 encoded string.
* uuid - return a version 4 random Universally Unique IDentifier.
What Should Be The Name Of The Module?
======================================
There was a proposal to add a "random.safe" submodule, quoting the Zen
of Python "Namespaces are one honking great idea" koan. However, the
author of the Zen, Tim Peters, has come out against this idea [#]_, and
recommends a top-level module.
In discussion on the python-ideas mailing list so far, the name "secrets"
has received some approval, and no strong opposition.
There is already an existing third-party module with the same name [#]_,
but it appears to be unused and abandoned.
Frequently Asked Questions
==========================
* Q: Is this a real problem? Surely MT is random enough that nobody can
predict its output.
A: The consensus among security professionals is that MT is not safe
in security contexts. It is not difficult to reconstruct the internal
state of MT [#]_ [#]_ and so predict all past and future values. There
are a number of known, practical attacks on systems using MT for
randomness [#]_.
* Q: Attacks on PHP are one thing, but are there any known attacks on
Python software?
A: Yes. There have been vulnerabilities in Zope and Plone at the very
least.
Document[6]:
Date created: 19-Aug-2004
If a
developer knows that her package will never be a portion of a
namespace package, then there is a performance advantage to it being a
regular package (with an ``__init__.py``). Creation and loading of a
regular package can take place immediately when it is located along
the path. With namespace packages, all entries in the path must be
scanned before the package is created.
Note that an ImportWarning will no longer be raised for a directory
lacking an ``__init__.py`` file. Such a directory will now be
imported as a namespace package, whereas in prior Python versions an
ImportWarning would be raised.
Alyssa (Nick) Coghlan presented a list of her objections to this proposal [4]_.
They are:
1. Implicit package directories go against the Zen of Python.
2. Implicit package directories pose awkward backwards compatibility
challenges.
3. Implicit package directories introduce ambiguity into file system
layouts.
4. Implicit package directories will permanently entrench current
newbie-hostile behavior in ``__main__``.
Alyssa later gave a detailed response to her own objections [5]_, which
is summarized here:
1. The practicality of this PEP wins over other proposals and the
status quo.
2. Minor backward compatibility issues are okay, as long as they are
properly documented.
3. This will be https://www.iana.org/assignments/media-types/application/vnd.openxmlformats-officedocument.wordprocessingml.documented in :pep:`395`.
4. This will also be https://www.iana.org/assignments/media-types/application/vnd.openxmlformats-officedocument.wordprocessingml.documented in :pep:`395`.
The inclusion of namespace packages in the standard library was
motivated by Martin v. Löwis, who wanted the ``encodings`` package to
become a namespace package [6]_.
Document[7]:
Date created:
* A nearly-identical syntax is already established for f-strings.
* Programmers will, as ever, adjust over time.
The feature is confusing
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
We argue that:
* Introducing new features typically has this impact temporarily.
* The syntax is very similar to the established ``f'{x=}'`` syntax.
* The feature and syntax are familiar from other popular modern languages.
* The expansion of ``x=`` to ``x=x`` is in fact a trivial feature and inherently
significantly less complex than ``*arg`` and ``**kwarg`` expansion.
* This particular syntactic form has been independently proposed on numerous
occasions, indicating that it is the most obvious [1]_ [2]_ [6]_.
The feature is not explicit
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
We recognize that, in an obvious sense, the argument value is 'implicit' in this
proposed syntax. However, we do not think that this is what the Zen of Python is
aiming to discourage.
In the sense that we take the Zen to be referring to, keyword arguments (for
example) are more explicit than positional arguments where the argument name is
omitted and impossible to tell from the local context. Conversely, the syntactic
sugar for integers ``x += 1`` is not more implicit than ``x = x + 1`` in this
sense, even though the variable is omitted from the right hand side, because it
is immediately obvious from the local context what it is.
Document[8]:
Date created: 19-Aug-2004
- Provide vision and leadership for Python, the programming language and the community.
- Understand their own limitation, and seek advice whenever necessary.
- Provide mentorship to the next generation of leaders.
- Be a Python core developer
- Be a voting member of The PSF (one of Contributing / Manager / Fellow / Supporter). [2]_
- Understand that Python is not just a language but also a community. They need
to be aware of issues in Python not just the technical aspects, but also
other issues in the community.
- Facilitate the formation of specialized working groups within Core Python.
See "formation of specialized working groups" section below.
- Set good example of behavior, culture, and tone to Python community.
Just as Python looks at and learn from other communities for inspiration, other
communities will look at Python and learn from us.
Authority of the trio
=====================
To be clear, in case any dispute arises: the trio has the final
authority to pronounce on PEPs (except for the governance PEP), to
decide whether a particular decision requires a PEP, and to resolve
technical disputes in general. The trio's authority does not include
changing the governance itself, or other non-technical disputes that
may arise; these should be handled through the process described in
:pep:`8001`.
What are NOT considered as the role responsibilities of the trio
================================================================
The following are not the expected out of the trio, however they can do these if they wish.
Question: what are the three zens of python?
Answer:
```
For a complete list of `document`'s attributes, see [Haystack documentation](https://docs.haystack.deepset.ai/docs/data-classes#document).
## Adding Dates to Prompts
You can use the Jinja2 time extension to insert dates in your prompts.
### Adding the Current Date
You can use the `{% now %}` tag to render the current date and time in your prompts. The syntax is: `{% now [timezone] %}`. Type `/` in the prompt editor and choose *Now (Current Time)* to insert the tag. You can then choose the timezone and format of the date.
For example: `The current time is: {% now 'CEST' %}`. This renders as: `The current time is 2025-05-06 17:03:12`.
### Storing the Date as a Variable
Use the following syntax to set a variable name for the date: `The current time is {% now 'Europe/Berlin' as current_time %}`. `current_time` becomes the name of the variable for the current time.
When using rich editor, simply type the variable name in the *As* field:
Rendered prompt
```Text Rendered prompt
You are a technical expert.
You answer questions truthfully based on provided documents.
If the answer exists in several documents, summarize them.
Ignore documents that don't contain the answer to the question.
Only answer based on the documents provided. Don't make things up.
If no information related to the question can be found in the document, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
These are the documents:
[Document(id=e307dd3c6f765aed116ad81d064dc8188d410481927309cd42b44ed8e22bb25e, content: '--------------------------
More Than One Way To Do It
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Okay, the Zen does...', meta: {'_split_overlap': [{'range': [1073, 1363], 'doc_id': '92d2764f063333fee7cf76d86254acb2752934ea07d2364c2b6eb209bb5cc739'}, {'range': [0, 223], 'doc_id': 'b44519a3df1ca77a0515c579ec00ad297dee50be90cb3eb3736e3716e80490c0'}], 'split_idx_start': 9309, 'file_name': 'pep-0584.txt', '_file_created_at': '2024-10-18T09:03:45.832385+00:00', 'split_id': 8, '_file_size': 30734, 'page_number': 1, 'file_id': '679bbf37-4cb9-4583-9f02-51289283bcd4', 'source_id': '982a93602209b5c2df80f37d9018d5a958aaf85e5f22a48e22d0f3970368d619'}, score: 0.158935546875), Document(id=a279b61737eef5529a0b27b2b97de0d4925c6509e8f00b1f37682a056371e50b, content: 'PEP: 20
Title: The Zen of Python
Author: Tim Peters
Status: Active
Type: Info...', meta: {'_split_overlap': [], 'split_idx_start': 0, 'file_name': 'pep-0020.txt', '_file_created_at': '2024-10-18T09:04:17.099685+00:00', 'split_id': 0, '_file_size': 1673, 'page_number': 1, 'file_id': '66633e10-67b1-4210-ab81-f22b162da69f', 'source_id': 'd4398d899e10248f3615dfc523283ebdd06cc9d4ba7349bc2dfc0dabc7310e9f'}, score: 0.132568359375), Document(id=92d2764f063333fee7cf76d86254acb2752934ea07d2364c2b6eb209bb5cc739, content: 'If one expects to be merging a large number of dicts where performance
is an issue, it may be better...', meta: {'_split_overlap': [{'range': [1172, 1531], 'doc_id': 'c6070df4a665dea988466251522ab286451f86e8d67e821484365fbe860dc522'}, {'range': [0, 290], 'doc_id': 'e307dd3c6f765aed116ad81d064dc8188d410481927309cd42b44ed8e22bb25e'}], 'split_idx_start': 8236, 'file_name': 'pep-0584.txt', '_file_created_at': '2024-10-18T09:03:45.832385+00:00', 'split_id': 7, '_file_size': 30734, 'page_number': 1, 'file_id': '679bbf37-4cb9-4583-9f02-51289283bcd4', 'source_id': '982a93602209b5c2df80f37d9018d5a958aaf85e5f22a48e22d0f3970368d619'}, score: 0.04217529296875), Document(id=de665889f31c7e28b722106a5fa445dea020cb5b1deadb5ff87a200dccbca64b, content: '* A nearly-identical syntax is already established for f-strings.
* Programmers will, as ever, adjus...', meta: {'_split_overlap': [{'range': [1300, 1547], 'doc_id': 'cbda35aa73c0e994987f1df6aa33996b3e6bfee5d37fe00b43c74a3389dcb78d'}, {'range': [0, 243], 'doc_id': '855465dc4e9941a1b50d267d7f23d61378288a60c87769ea2fe3a4e01d42fdb8'}], 'split_idx_start': 16006, 'file_name': 'pep-0736.txt', '_file_created_at': '2024-10-18T09:03:32.851485+00:00', 'split_id': 10, '_file_size': 25013, 'page_number': 1, 'file_id': 'a5a73fe5-14e4-43e0-8839-104d658a268d', 'source_id': '6acf4d46895d82a5b5f39ef3a4b8bb7b602ad6751d97fc5ea7ae5bb80a7ef869'}, score: 0.033599853515625), Document(id=dcbacf054847b57d03e5a03d8220d99451fa8ae0e7fbcc9c181d6c9a6daf6103, content: 'Type declarators after names that are only read, not assigned to, are not strictly
necessary but enf...', meta: {'_split_overlap': [{'range': [1335, 1565], 'doc_id': '8462f7bf34aa29a6abd2b0967902c5f8ff40845458c887616d9b271acf898cb3'}, {'range': [0, 375], 'doc_id': '8ca6c53419aaf4828c9c399dea7c87ef77b78ad770be79cdc7b1de7915f2ad7a'}], 'split_idx_start': 2713, 'file_name': 'pep-3117.txt', '_file_created_at': '2024-10-18T09:03:32.119394+00:00', 'split_id': 2, '_file_size': 8570, 'page_number': 1, 'file_id': '28215f42-588c-4a05-bb30-d38a979e54b9', 'source_id': '0098114fc233fd584f7b3dce6f20b38f8fee5671534fcadf52609771eb1872d9'}, score: 0.029205322265625), Document(id=266460ca840d425453afcbcb214b775de933f816972f4294c2992f911743ea3a, content: '* random_bytes - returns a random byte string.
* random_number - depending on the argument, retur...', meta: {'_split_overlap': [{'range': [1633, 1826], 'doc_id': 'cb505fb7b551acc17bc30be7e4698eca6ce01f2724326b7b8a38cfc1eaabba27'}, {'range': [0, 173], 'doc_id': '6754d08c1a7fb48d16d754bc556a76f6b049c977640b0bb130d723348134d74c'}], 'split_idx_start': 10795, 'file_name': 'pep-0506.txt', '_file_created_at': '2024-10-18T09:03:53.308697+00:00', 'split_id': 8, '_file_size': 18395, 'page_number': 1, 'file_id': '13775073-db35-4864-b7fc-a1d71202be3a', 'source_id': '375ba446b3fc8643ef846664ea0f644caba318a6d0fb7113475c3dbf7357e906'}, score: 0.028594970703125), Document(id=8462f7bf34aa29a6abd2b0967902c5f8ff40845458c887616d9b271acf898cb3, content: 'Therefore, this PEP combines the move to type declarations with another bold
move that will once aga...', meta: {'_split_overlap': [{'range': [1378, 1629], 'doc_id': '1f47efdb3224a877cf94bcbee759cf79b96f83768dc99bbc301b2a2f9cbd1417'}, {'range': [0, 230], 'doc_id': 'dcbacf054847b57d03e5a03d8220d99451fa8ae0e7fbcc9c181d6c9a6daf6103'}], 'split_idx_start': 1378, 'file_name': 'pep-3117.txt', '_file_created_at': '2024-10-18T09:03:32.119394+00:00', 'split_id': 1, '_file_size': 8570, 'page_number': 1, 'file_id': '28215f42-588c-4a05-bb30-d38a979e54b9', 'source_id': '0098114fc233fd584f7b3dce6f20b38f8fee5671534fcadf52609771eb1872d9'}, score: 0.0258636474609375), Document(id=0358e0dc28ffad1c66d8b51e8b52c87670bb10d3379df9ca215c94f00dcbf881, content: 'Typically only exceptions that
signal an error are desired to be caught. This means that exceptions...', meta: {'_split_overlap': [{'range': [1441, 1642], 'doc_id': '2b91fca3faf02123a3d14f6aa206cfec9848a40577a72561e43b9d45a42947da'}, {'range': [0, 384], 'doc_id': 'd8038333a8193db3f52139147c1dd0fc38b13099a86a14ff05c9ca28c7641cc8'}], 'split_idx_start': 9260, 'file_name': 'pep-0348.txt', '_file_created_at': '2024-10-18T09:04:05.356969+00:00', 'split_id': 7, '_file_size': 19534, 'page_number': 1, 'file_id': '96d69bd9-9727-4ad0-a06e-ddafb8d96c0d', 'source_id': 'e6bf6cb76eed041b0d80c64c9bf0898d7017757b0933dbed1e1a54a05f079a83'}, score: 0.010650634765625)]
```
### Changing How the Documents Are Presented
You can also use a Jinja loop to add documents to your prompts. The following loop structures documents in a numbered way:
```jinja2
These are the documents:
{% for document in documents %}
Document[{{ loop.index }}]:
{{ document.content }}
{% endfor %}
Question: {{ question }}
Answer:
```
This loop results in documents being rendered like this:
```
Document[1]:
Document[2]:
```
Such a format makes it easier for the LLM to understand document boundaries by creating a clear, predictable structure. It's also useful if you want the LLM to generate references in its answers. It can then reference the document by its number.
Rendered prompt example
```
You are a technical expert.
You answer questions truthfully based on provided documents.
If the answer exists in several documents, summarize them.
Ignore documents that don't contain the answer to the question.
Only answer based on the documents provided. Don't make things up.
If no information related to the question can be found in the document, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
These are the documents:
Document[1]:
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
More Than One Way To Do It
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Okay, the Zen doesn't say that there should be Only One Way To Do It.
But it does have a prohibition against allowing "more than one way to
do it".
''''''''Response
''''''''
There is no such prohibition. The "Zen of Python" merely expresses a
*preference* for "only one *obvious* way"::
There should be one-- and preferably only one --obvious way to do
it.
The emphasis here is that there should be an obvious way to do "it".
In the case of dict update operations, there are at least two
different operations that we might wish to do:
- *Update a dict in place*: The Obvious Way is to use the ``update()``
method. If this proposal is accepted, the ``|=`` augmented
assignment operator will also work, but that is a side-effect of how
augmented assignments are defined. Which you choose is a matter of
taste.
- *Merge two existing dicts into a third, new dict*: This PEP proposes
that the Obvious Way is to use the ``|`` merge operator.
In practice, this preference for "only one way" is frequently violated
in Python. For example, every ``for`` loop could be re-written as a
``while`` loop; every ``if`` block could be written as an ``if``/
``else`` block. List, set and dict comprehensions could all be
replaced by generator expressions.
Document[2]:
PEP: 20
Title: The Zen of Python
Author: Tim Peters
Status: Active
Type: Informational
Content-Type: text/x-rst
Created: 19-Aug-2004
Post-History: 22-Aug-2004
Abstract
========
Long time Pythoneer Tim Peters succinctly channels the BDFL's guiding
principles for Python's design into 20 aphorisms, only 19 of which
have been written down.
The Zen of Python
=================
.. code-block:: text
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Easter Egg
==========
.. code-block:: pycon
>>> import this
References
==========
Originally posted to comp.lang.python/python-list@python.org under a
thread called `"The Way of Python"
`__
Copyright
=========
This document has been placed in the public domain.
Document[3]:
If one expects to be merging a large number of dicts where performance
is an issue, it may be better to use an explicit loop and in-place
merging::
new = {}
for d in many_dicts:
new |= d
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Dict Union Is Lossy
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Dict union can lose data (values may disappear); no other form of
union is lossy.
''''''''Response
''''''''
It isn't clear why the first part of this argument is a problem.
``dict.update()`` may throw away values, but not keys; that is
expected behavior, and will remain expected behavior regardless of
whether it is spelled as ``update()`` or ``|``.
Other types of union are also lossy, in the sense of not being
reversible; you cannot get back the two operands given only the union.
``a | b == 365``... what are ``a`` and ``b``?
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Only One Way To Do It
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Dict union will violate the Only One Way koan from the Zen.
''''''''Response
''''''''
There is no such koan. "Only One Way" is a calumny about Python
originating long ago from the Perl community.
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
More Than One Way To Do It
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
Okay, the Zen doesn't say that there should be Only One Way To Do It.
But it does have a prohibition against allowing "more than one way to
do it".
''''''''Response
''''''''
There is no such prohibition.
Document[4]:
* A nearly-identical syntax is already established for f-strings.
* Programmers will, as ever, adjust over time.
The feature is confusing
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
We argue that:
* Introducing new features typically has this impact temporarily.
* The syntax is very similar to the established ``f'{x=}'`` syntax.
* The feature and syntax are familiar from other popular modern languages.
* The expansion of ``x=`` to ``x=x`` is in fact a trivial feature and inherently
significantly less complex than ``*arg`` and ``**kwarg`` expansion.
* This particular syntactic form has been independently proposed on numerous
occasions, indicating that it is the most obvious [1]_ [2]_ [6]_.
The feature is not explicit
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
We recognize that, in an obvious sense, the argument value is 'implicit' in this
proposed syntax. However, we do not think that this is what the Zen of Python is
aiming to discourage.
In the sense that we take the Zen to be referring to, keyword arguments (for
example) are more explicit than positional arguments where the argument name is
omitted and impossible to tell from the local context. Conversely, the syntactic
sugar for integers ``x += 1`` is not more implicit than ``x = x + 1`` in this
sense, even though the variable is omitted from the right hand side, because it
is immediately obvious from the local context what it is.
Document[5]:
Type declarators after names that are only read, not assigned to, are not strictly
necessary but enforced anyway (see the Python Zen: "Explicit is better than
implicit.").
The mapping between types and declarators is not static. It can be completely
customized by the programmer, but for convenience there are some predefined
mappings for some built-in types:
========================= ===================================================
Type Declarator
========================= ===================================================
``object`` � (REPLACEMENT CHARACTER)
``int`` ℕ (DOUBLE-STRUCK CAPITAL N)
``float`` ℮ (ESTIMATED SYMBOL)
``bool`` ✓ (CHECK MARK)
``complex`` ℂ (DOUBLE-STRUCK CAPITAL C)
``str`` ✎ (LOWER RIGHT PENCIL)
``unicode`` ✒ (BLACK NIB)
``tuple`` ⒯ (PARENTHESIZED LATIN SMALL LETTER T)
``list`` ♨ (HOT SPRINGS)
``dict`` ⧟ (DOUBLE-ENDED MULTIMAP)
``set`` ∅ (EMPTY SET) (*Note:* this is also for full sets)
``frozenset`` ☃ (SNOWMAN)
``datetime`` ⌚ (WATCH)
``function`` ƛ (LATIN SMALL LETTER LAMBDA WITH STROKE)
``generator`` ⚛ (ATOM SYMBOL)
``Exception`` ⌁ (ELECTRIC ARROW)
========================= ===================================================
The declarator for the ``None`` type is a zero-width space.
These characters should be obvious and easy to remember and type for every
programmer.
Unicode replacement units
=========================
Since even in our modern, globalized world there are still some old-fashioned
rebels who can't or don't want to use Unicode in their source code, and since
Python is a forgiving language, a fallback is provided for those:
Instead of the single Unicode character, they can type ``name${UNICODE NAME OF
THE DECLARATOR}$``.
Document[6]:
* random_bytes - returns a random byte string.
* random_number - depending on the argument, returns either a random
integer in the range(0, n), or a random float between 0.0 and 1.0.
* urlsafe_base64 - returns a random URL-safe Base64 encoded string.
* uuid - return a version 4 random Universally Unique IDentifier.
What Should Be The Name Of The Module?
======================================
There was a proposal to add a "random.safe" submodule, quoting the Zen
of Python "Namespaces are one honking great idea" koan. However, the
author of the Zen, Tim Peters, has come out against this idea [#]_, and
recommends a top-level module.
In discussion on the python-ideas mailing list so far, the name "secrets"
has received some approval, and no strong opposition.
There is already an existing third-party module with the same name [#]_,
but it appears to be unused and abandoned.
Frequently Asked Questions
==========================
* Q: Is this a real problem? Surely MT is random enough that nobody can
predict its output.
A: The consensus among security professionals is that MT is not safe
in security contexts. It is not difficult to reconstruct the internal
state of MT [#]_ [#]_ and so predict all past and future values. There
are a number of known, practical attacks on systems using MT for
randomness [#]_.
* Q: Attacks on PHP are one thing, but are there any known attacks on
Python software?
A: Yes. There have been vulnerabilities in Zope and Plone at the very
least.
Document[7]:
Therefore, this PEP combines the move to type declarations with another bold
move that will once again prove that Python is not only future-proof but
future-embracing: the introduction of Unicode characters as an integral
constituent of source code.
Unicode makes it possible to express much more with much less characters, which
is in accordance with the :pep:`Zen <20>` ("Readability counts."). Additionally, it
eliminates the need for a separate type declaration statement, and last but not
least, it makes Python measure up to Perl 6, which already uses Unicode for its
operators. [#]_
Specification
=============
When the type declaration mode is in operation, the grammar is changed so that
each ``NAME`` must consist of two parts: a name and a type declarator, which is
exactly one Unicode character.
The declarator uniquely specifies the type of the name, and if it occurs on the
left hand side of an expression, this type is enforced: an ``InquisitionError``
exception is raised if the returned type doesn't match the declared type. [#]_
Also, function call result types have to be specified. If the result of the call
does not have the declared type, an ``InquisitionError`` is raised. Caution: the
declarator for the result should not be confused with the declarator for the
function object (see the example below).
Type declarators after names that are only read, not assigned to, are not strictly
necessary but enforced anyway (see the Python Zen: "Explicit is better than
implicit.").
The mapping between types and declarators is not static.
Document[8]:
Typically only exceptions that
signal an error are desired to be caught. This means that exceptions
that are used to signify that the interpreter should exit should not
be caught in the common case.
With KeyboardInterrupt and SystemExit moved to inherit from
BaseException instead of Exception, changing bare ``except`` clauses
to act as ``except Exception`` becomes a much more reasonable
default. This change also will break very little code since these
semantics are what most people want for bare ``except`` clauses.
The complete removal of bare ``except`` clauses has been argued for.
The case has been made that they violate both Only One Way To Do It
(OOWTDI) and Explicit Is Better Than Implicit (EIBTI) as listed in the
:pep:`Zen of Python <20>`. But Practicality Beats Purity (PBP), also in
the Zen of Python, trumps both of these in this case. The BDFL has
stated that bare ``except`` clauses will work this way
[#python-dev8]_.
Implementation
deepset_platform_metadata:
group: how-tos
navigation: guides
section: working-with-llms
source: docusaurus-build
title: writing-prompts-in-deepsetq
type: how-to
---
The compiler will emit the bytecode for ``except Exception`` whenever
a bare ``except`` clause is reached.
Transition Plan
===============
Because of the complexity and clutter that would be required to add
all features planned in this PEP, the transition plan is very simple.
In Python |2.x| BaseException is added. In Python 3.0, all remaining
features (required superclass, change in inheritance, bare ``except``
clauses becoming the same as ``except Exception``) will go into
affect.
Question: what are the python zens?
Answer:
```
#### Adding Documents with Their Metadata
You can also enhance the documents passed to the LLM with their metadata by using this syntax: `document.meta.`. This example adds the date of publication and genre of each document in the prompt:
```jinja2
Here are the articles:
{% for document in documents %}
Document[{{ loop.index }}]:
Date of Publication: {{ document.meta.date }}
Genre: {{ document.meta.genre }}
{{ document.content }}
{% endfor %}
Question: {{ question }}
Answer:
```
In the rendered prompt, the documents would be displayed as follows:
```
Here are the articles:
Document[1]:
Date of Publication: 12.03.2024}
Genre: News
This is a news article.
Document[2]:
Date of Publication: 23.09.2024}
Genre: Interview
This is an interview.
Question: What happened in Austria yesterday?
Answer:
```
### Examples in Prompts
You can add examples to your prompt. This technique, called few-shot prompting, teaches the LLM how to perform the task by example. This prompt contains examples of questions and answers:
```jinja2
You are a helpful assistant that answers questions.
Answer the questions as shown in the examples.
Here are some question-answer examples:
{% set ns = namespace(example="") -%}
{% for e in examples -%}
{% set ns.example = ns.example + "\nQuery: " + e.query + "\nResponse: "+ e.response + "\n" -%}
{% endfor -%}
{{ ns.example }}
Now please answer the user query.
Query: {{query}}
Answer:
```
:::info
In this case, PromptBuilder would need `examples` and `query` as input to render the prompt.
:::
The rendered prompt would contain some query-response pairs:
```
You are a helpful assistant that answers questions
Answer the questions as shown in the examples.
Here are some question-answer examples:
Query: What is the capital of France?
Response: The capital of France is Paris.
Query: How tall is Mount Everest?
Response: Mount Everest is approximately 29,029 feet (8,848 meters) tall.
Now please answer the user query.
Query: What is the speed of light?
Answer:
```
### Variables in Prompts
#### Setting Required Variables
This `ChatPromptBuilder`'s prompt contains the `target_language` and `text` variables. Then, using the `required_variables` setting, it declares them as required. This means that if either of them is not provided at runtime, the component raises an error.
`ChatPromptBuilder` template:
```yaml
- content:
text: "Translate to {{ target_language }}: {{ text }}"
role: user
```
`ChatPromptBuilder` `required_variables` parameter setting to indicate both variables are required:
```yaml
- target_language
- text
```
#### Declaring All Variables
The following prompts declare all variables as valid inputs and set `location` and `day_count` as required.
This is the system prompt:
```text
You are a helpful assistant speaking {{ language }}
```
This is the user prompt:
```text
"What’s the weather in {{ location }} for the next {{ day_count }} days?"
```
Then, in Required Variables, you indicate which of the variables must be provided:
```yaml
- location
- day_count
```
---
## Collect User Feedback
Monitor users' feedback to give you an indication of how your AI system is doing. Collecting feedback is crucial throughout your app's lifecycle to evaluate quality and improve the pipeline, starting from development, through prototype testing, to production.
## About This Task
You or your users can rate each answer as accurate (thumbs up), fairly accurate (thumbs sideways), or inaccurate (thumbs down). When users select the rating, they can explain it by selecting predefined reasons called tags or by adding comments in the text field.
/pipelines//feedback \
--header 'accept: text/csv' \
--header 'authorization: Bearer '
```
---
## Guidelines for Onboarding Your Users
To demo your application to the users, it is important to explain how it works and to set the right expectations. Here are a couple of guidelines that can help you do it.
## Basic Search Functionality
Make sure the users know what to expect from your system. For example:
- For extractive question answering systems that highlight the answer in the text, make sure the users understand that the information they're looking for must exist in the text data the system runs on. The search system cannot make up answers by itself.
- For generative question answering pipelines that aren't chat, make sure the users realize it's not chat-based. The system generates novel answers, but they're unrelated to the previous question.
- What the system returns depends on the pipeline you defined. For example, for a Retriever-only pipeline, the system returns text passages that fit the query, while for a question answering pipeline, the system also highlights the answers within the text passages it returns. Make sure your users know this.
- Explain what queries work well (for example, natural language questions as opposed to simple keywords or copy-pasted error messages).
## Data
- Make your users aware of what data is indexed in their /mcp",
"headers": {
"Authorization": "Bearer your-api-key"
}
}
}
}
```
#### Claude Code (CLI)
```bash
claude mcp add-json haystack-enterprise '{
"type": "http",
"url": "https://api.cloud.deepset.ai/api/v2/workspaces/your-workspace-id/mcp",
"headers": {
"Authorization": "Bearer your-api-key"
}
}'
```
## Disable a Pipeline Tool or Delete the MCP Server
### Disable a Pipeline Tool
To stop use a specific pipeline as a tool without affecting the rest of the server:
1. Go to **Pipelines** and click the pipeline you want to remove.
2. Click **Settings**.
3. In the **MCP Tool** section, turn off **Use as MCP tool**.
The pipeline is immediately removed from the server. Other enabled pipelines continue to work.
### Delete the MCP Server
To stop using your workspace as an MCP server entirely:
1. Go to **Settings > Workspace > MCP**.
2. Switch off **Create MCP Server**.
The server and all its tools are immediately removed and can no longer be used by external clients.
## Troubleshooting
- **The MCP section is grayed out**: You need the `pipelines:write` permission for the workspace. Contact your workspace administrator to assign the appropriate role.
- **The MCP tool toggle is disabled**: The toggle can be disabled for several reasons. Hover over the toggle to see the reason. Common causes are: the pipeline is not deployed (deploy the pipeline first), you don't have write access to the MCP server (contact your workspace administrator), or the pipeline has no published versions.
- **A warning icon appears next to a pipeline in the MCP Tools list**: The pipeline is not in a deployed or standby state and cannot currently serve as an MCP tool. Click the pipeline to open its settings, check for configuration errors, and redeploy it.
- **AI client can't connect**: Verify your API key is correct and has the necessary permissions. Try copying the configuration snippet again from the server settings.
- **Changes aren't saving**: Settings are saved automatically with a short delay. Wait a few seconds after making changes before navigating away.
## Related Information
- [Model Context Protocol](/docs/concepts/model-context-protocol.mdx)
- [Generate API Keys](/docs/how-to-guides/managing-access/generate-api-key.mdx)
- [Model Context Protocol Official Website](https://modelcontextprotocol.io/)
- [Writing MCP Server Instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/)
---
## Implement CI/CD with Github Actions
Use our customizable template to manage deployments across development and production workspaces, following best practices for automation.
***
We provide a GitHub repository containing a fully functional CI/CD template with GitHub Actions. Check the repository at [GitHub](https://github.com/deepset-ai/deepset-cloud-github-action-template).
---
## Monitor Pipeline Performance
If you're wondering how many requests you can send from your search system to
YAML configuration
```yaml
# haystack-pipeline
components:
Agent:
type: haystack.components.agents.agent.Agent
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.5
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
tools:
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: search_internal_it
description: >-
Search Acme Corp's internal IT documentation. Use this tool for
questions about internal
IT policies, procedures, and processes—such as requesting software licenses, getting VPN
access, IT support escalation, new employee IT setup, or any company-specific IT how-tos.
input_mapping:
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files:
- multi_file_converter.sources
query:
- chat_summary_llm.question
output_mapping:
chat_summary_llm.last_message: updated_query
meta_field_grouping_ranker.documents: documents
qa_llm.messages: messages
pipeline:
pipeline_output_type: chat
components:
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: internal-it-docs
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
fuzziness: 0
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
tabular_joiner.documents: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_converter.documents
receiver: splitter.documents
- sender: pdf_converter.documents
receiver: splitter.documents
- sender: markdown_converter.documents
receiver: splitter.documents
- sender: html_converter.documents
receiver: splitter.documents
- sender: pptx_converter.documents
receiver: splitter.documents
- sender: docx_converter.documents
receiver: splitter.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
chat_summary_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are part of a chatbot.
You receive a question (Current Question) and a chat
history.
Use the context from the chat history and reformulate the
question so that it is suitable for retrieval augmented
generation.
If X is followed by Y, only ask for Y and do not repeat X
again.
If the question does not require any context from the chat
history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
{% endmessage %}
required_variables: "*"
streaming_callback:
qa_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the
question.
Only use documents that are related to the question to
answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make
things up.
Just output the structured, informative and precise answer
and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when
using information from a document, e.g. [3] for Document [3]
.
Never name the documents, only enter a number in square
brackets as a reference.
The reference must only refer to the number that comes in
square brackets after the document.
Otherwise, do not use brackets in your answer and reference
ONLY the number of the document without mentioning the word
document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found,
please adjust the filters or try a different question."
{% endif %}
Question: {{ question.text }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: multi_file_converter.documents
receiver: meta_field_grouping_ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: chat_summary_llm.last_message
receiver: retriever.query
- sender: chat_summary_llm.last_message
receiver: ranker.query
- sender: chat_summary_llm.last_message
receiver: qa_llm.question
- sender: meta_field_grouping_ranker.documents
receiver: qa_llm.documents
max_runs_per_component: 100
metadata: {}
is_pipeline_async: false
inputs_from_state: {}
outputs_to_string: {}
outputs_to_state: {}
_meta:
name: search_internal_it
description: >-
Search Acme Corp's internal IT documentation. Use this tool for
questions about internal
IT policies, procedures, and processes—such as requesting software licenses, getting VPN
access, IT support escalation, new employee IT setup, or any company-specific IT how-tos.
tool_id:
pipeline_version_id: 5916d707-f550-4b0a-a4d1-6be06a471f98
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: search_vendor_docs
description: >-
Search vendor software documentation. Use this tool for questions
about how to use
specific applications and products—such as Zoom features, Microsoft 365, setting up
email on mobile, or any other software how-to questions.
input_mapping:
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files:
- multi_file_converter.sources
query:
- chat_summary_llm.question
output_mapping:
chat_summary_llm.last_message: updated_query
meta_field_grouping_ranker.documents: documents
qa_llm.messages: messages
pipeline:
pipeline_output_type: chat
components:
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: vendor-documents
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
fuzziness: 0
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
tabular_joiner.documents: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_converter.documents
receiver: splitter.documents
- sender: pdf_converter.documents
receiver: splitter.documents
- sender: markdown_converter.documents
receiver: splitter.documents
- sender: html_converter.documents
receiver: splitter.documents
- sender: pptx_converter.documents
receiver: splitter.documents
- sender: docx_converter.documents
receiver: splitter.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
chat_summary_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are part of a chatbot.
You receive a question (Current Question) and a chat
history.
Use the context from the chat history and reformulate the
question so that it is suitable for retrieval augmented
generation.
If X is followed by Y, only ask for Y and do not repeat X
again.
If the question does not require any context from the chat
history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
{% endmessage %}
required_variables: "*"
streaming_callback:
qa_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the
question.
Only use documents that are related to the question to
answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make
things up.
Just output the structured, informative and precise answer
and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when
using information from a document, e.g. [3] for Document [3]
.
Never name the documents, only enter a number in square
brackets as a reference.
The reference must only refer to the number that comes in
square brackets after the document.
Otherwise, do not use brackets in your answer and reference
ONLY the number of the document without mentioning the word
document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found,
please adjust the filters or try a different question."
{% endif %}
Question: {{ question.text }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: multi_file_converter.documents
receiver: meta_field_grouping_ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: chat_summary_llm.last_message
receiver: retriever.query
- sender: chat_summary_llm.last_message
receiver: ranker.query
- sender: chat_summary_llm.last_message
receiver: qa_llm.question
- sender: meta_field_grouping_ranker.documents
receiver: qa_llm.documents
max_runs_per_component: 100
metadata: {}
is_pipeline_async: false
inputs_from_state: {}
outputs_to_string: {}
outputs_to_state: {}
_meta:
name: search_vendor_docs
description: >-
Search vendor software documentation. Use this tool for questions
about how to use
specific applications and products—such as Zoom features, Microsoft 365, setting up
email on mobile, or any other software how-to questions.
tool_id:
pipeline_version_id: c164dc6d-3b28-406e-8766-a47b19cbee65
system_prompt: >-
{% message role="system" %}
You are an IT helpdesk assistant for Corp. You help employees solve IT
problems and answer questions about IT processes and software.
You have two tools:
- search_internal_it: Use this for questions about Acme Corp's internal
IT policies and procedures—requesting software, getting VPN access, IT
support processes, internal how-tos.
- search_vendor_docs: Use this for questions about how to use software
products—Zoom, Microsoft 365, and other applications.
When a question involves both internal processes and software (for
example, "I can't connect to Teams because my VPN is blocking it"), use
both tools before answering.
Base your answer only on the information you find. Cite which documents
you used. If you can't find the answer in either knowledge base, say so
clearly and tell the employee to contact the IT helpdesk directly at
helpdesk@acmecorp.internal.
{% endmessage %}
user_prompt:
required_variables:
exit_conditions:
state_schema: {}
max_agent_steps: 100
streaming_callback:
raise_on_tool_invocation_failure: false
tool_invoker_kwargs:
confirmation_strategies:
LangfuseConnector:
type: haystack_integrations.components.connectors.langfuse.langfuse_connector.LangfuseConnector
init_parameters:
name: helpdesk-agent
public: false
public_key:
type: env_var
env_vars:
- LANGFUSE_PUBLIC_KEY
strict: false
secret_key:
type: env_var
env_vars:
- LANGFUSE_SECRET_KEY
strict: false
httpx_client:
span_handler:
host:
langfuse_client_kwargs:
max_runs_per_component: 100
metadata: {}
inputs:
messages:
- Agent.messages
filters: []
files: []
outputs:
answers:
documents:
messages: Agent.last_message
```
---
## Trace Your Pipelines
Understand, analyze, and troubleshoot your AI pipelines using logging features and integrated services.
***
## Tracing vs Debugging
Tracing and debugging both help you understand how your pipeline runs, but they serve different purposes.
Tracing captures the full journey of a query — from the user's input through each processing step to the final result. A trace usually includes timestamps, the original query and its transformations, generated embeddings, retrieved documents, scoring and ranking decisions, as well as any errors or latency issues. Tracing shows how data flows through the system and when each step occurs, giving you a clear picture of what happened end to end. Tools like Langfuse or Weave make this information easy to visualize and explore.
Debugging is about getting to the root of problems. It involves analyzing detailed logs to pinpoint errors, misconfigurations, or unexpected behavior. While tracing shows you the "what" and "when," debugging helps you uncover the "why."
AI-powered applications are often complex and opaque, making it hard to understand what’s happening under the hood. When something goes wrong, tracing and debugging let you lift the veil. They’re essential for fixing issues, improving performance, and gaining insight into how your models behave. Whether you're tracking down high latency, investigating odd query results, or exploring search patterns, these tools give you the visibility you need to take action.
## Tools for Debugging
- Pipeline logs: Capture operational details, such as the component that generated the log, log level, timestamp, and log message. They're available in the Builder on the Analytics tab, but also after running the pipeline in Builder or Playground.
- Pipeline debugger: Offers live component-level logs available from Builder.
- Remote debug with a VS Code tunnel.
## Tools for Tracing
Use integrated services to trace your
What Changed: Credits vs Production and Development Hours
Previously, we tracked deployment hours separately for production and development pipelines. This included indexing time, as indexes were tied to query pipelines.
Now, we've simplified things. We no longer distinguish between development and production hours. Instead, we measure all active deployment time and all indexing activity in credits:
- One credit per hour per active replica
- One credit per hour of indexing
#### Estimating Your Credit Usage
When planning your credit usage, it's helpful to understand how credits are consumed across different parts of the system.
##### Query Pipelines
Credits for query pipelines are based on how long your pipeline is actively deployed and how many replicas it uses.
- Development pipeline: 1 credit per hour (no replicas by default)
- Production pipeline: 1 replica by default = 1 credit per hour minimum
If your production pipeline scales due to high traffic, credit usage increases proportionally with the number of active replicas (up to a maximum of 10). You can configure the minimum and maximum number of replicas in the pipeline's **Settings** tab.
##### Indexing
Credits for indexes are only used when files are being processed. You don’t need to index the same data more than once. After indexing, you can reuse that data across different query pipelines without additional credit costs.
Several factors can affect how many credits indexing will use:
- Size and number of files: Larger and more files take longer to process.
- Index configuration: Preprocessing steps like OCR or generating metadata with a language model increase processing time.
- Upload pattern: Uploading files in a single batch or in several large batches is more efficient. Uploading files one-by-one with long gaps in between may add warm-up time.
- Embedding model: The dimensionality of the embedding model, the number of models used, and whether they're hosted locally or accessed via API can impact speed and credit usage.
##### Example Credit Usage
Here are some rough estimates for how many credits are used by our standard index templates. This scenario assumes:
- 100 files in a mix of formats (TXT, HTML, XLSX, PDF, DOCX, CSV)
- All files uploaded together in one batch
| Index Template | Approximate Credits Used |
| :----------------------- | :----------------------- |
| Standard Index (English) | 0.03 |
| AI-Generated Metadata | 0.06 |
These figures can vary depending on your specific setup, but they offer a starting point for estimating costs.
### 3. Document Storage Units
Document Storage Units (DSU) show how much vector storage you're using for your indexed documents. The DSU count on the Usage page reflect the current state. They can go up or down as you add or remove documents.
When you upload and index your files, we split them into smaller pieces called _documents_. These documents are stored and your DSU count depends on two key factors:
- How many documents your files are split into.
- The size (dimensionality) of the embedding model used to process them.
The more documents or the larger the model, the more storage units you use.
#### Calculating DSUs
To calculate DSUs, we multiply the number of stored documents by a multiplier that reflects the embedding model's dimensionality:
- A standard embedding model with 768 dimensions uses a multiplier of 1.
- A larger model with 1,536 dimensions uses a multiplier of 2, meaning it needs twice as much storage.
- If you use keyword-based search or don't use vector storage, the multiplier is just 0.2, so it uses much less storage.
##### Example
Say you upload 5,000 files which are split into 83,697 documents:
- With the standard embedding model (768 dimensions): `83,697 documents × 1 = 83,697 storage units`
- With a larger model (1,536 dimensions): `83,697 documents × 2 = 167,394 storage units`
- With keyword search only or no vector storage: `83,697 documents × 0.2 = 16,739.4 storage units`
#### Optimizing Storage Usage
As you near your storage capacity, you can reduce storage consumption by:
- Deleting duplicate files.
- Reducing irrelevant files, starting from the largest ones. Detecting irrelevant files is specific to your use case. You can use the [Search History](/docs/api/main/search-history-api-v-1-workspaces-workspace-name-search-history-get.api.mdx) endpoint to check user queries, files, and documents used.
- Adjusting settings in DocumentSplitter:
- If your `split_overlap` setting is high, consider decreasing it.
- If your `split_length` setting is low, try increasing it. Remember that it's important to avoid too large values to prevent Retriever and Generator components from cutting the documents.
### 4. Usage Per Pipeline or Index
At the bottom of the page, you can check the detailed usage per pipeline or index. You can check the number of credits used and the workspace it's in.
Indexes and pipelines that were deleted but contributed to usage in the current cycle are greyed out.
---
## Trace with Weights & Biases Weave
Use the Weights & Biases (W&B) Weave service for tracing and monitoring your LLM apps.
***
## About This Task
Add Weave Integration
2. Add the `WeaveConnector` component to your pipeline, but do not connect it to any other component.
3. Set the `pipeline_name` parameter in `WeaveConnector` to your pipeline's name. The value you provide for `pipeline_name` will be used as the name of your Weave tracing project in W&B.
The W&B tracing project is automatically created when you query the pipeline for the first time. You can view it on the [W&B dashboard](https://wandb.ai/) under _Projects_. Using a pipeline name helps you easily identify which pipeline the traces belong to, especially when managing multiple projects.
## Example
This is an example of an agent with `WeaveConnector`. The component is in the pipeline, but it's not connected to any other component. That's enough to send the pipeline traces to Weights & Biases:
```yaml
components:
Agent:
type: haystack.components.agents.agent.Agent
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.5
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
tools:
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: search_internal_it
description: >-
Search Acme Corp's internal IT documentation. Use this tool for
questions about internal
IT policies, procedures, and processes—such as requesting software licenses, getting VPN
access, IT support escalation, new employee IT setup, or any company-specific IT how-tos.
input_mapping:
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files:
- multi_file_converter.sources
query:
- chat_summary_llm.question
output_mapping:
chat_summary_llm.last_message: updated_query
meta_field_grouping_ranker.documents: documents
qa_llm.messages: messages
pipeline:
pipeline_output_type: chat
components:
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: internal-it-docs
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
fuzziness: 0
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
tabular_joiner.documents: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_converter.documents
receiver: splitter.documents
- sender: pdf_converter.documents
receiver: splitter.documents
- sender: markdown_converter.documents
receiver: splitter.documents
- sender: html_converter.documents
receiver: splitter.documents
- sender: pptx_converter.documents
receiver: splitter.documents
- sender: docx_converter.documents
receiver: splitter.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
chat_summary_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are part of a chatbot.
You receive a question (Current Question) and a chat
history.
Use the context from the chat history and reformulate the
question so that it is suitable for retrieval augmented
generation.
If X is followed by Y, only ask for Y and do not repeat X
again.
If the question does not require any context from the chat
history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
{% endmessage %}
required_variables: "*"
streaming_callback:
qa_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the
question.
Only use documents that are related to the question to
answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make
things up.
Just output the structured, informative and precise answer
and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when
using information from a document, e.g. [3] for Document [3]
.
Never name the documents, only enter a number in square
brackets as a reference.
The reference must only refer to the number that comes in
square brackets after the document.
Otherwise, do not use brackets in your answer and reference
ONLY the number of the document without mentioning the word
document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found,
please adjust the filters or try a different question."
{% endif %}
Question: {{ question.text }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: multi_file_converter.documents
receiver: meta_field_grouping_ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: chat_summary_llm.last_message
receiver: retriever.query
- sender: chat_summary_llm.last_message
receiver: ranker.query
- sender: chat_summary_llm.last_message
receiver: qa_llm.question
- sender: meta_field_grouping_ranker.documents
receiver: qa_llm.documents
max_runs_per_component: 100
metadata: {}
is_pipeline_async: false
inputs_from_state: {}
outputs_to_string: {}
outputs_to_state: {}
_meta:
name: search_internal_it
description: >-
Search Acme Corp's internal IT documentation. Use this tool for
questions about internal
IT policies, procedures, and processes—such as requesting software licenses, getting VPN
access, IT support escalation, new employee IT setup, or any company-specific IT how-tos.
tool_id:
pipeline_version_id: 5916d707-f550-4b0a-a4d1-6be06a471f98
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: search_vendor_docs
description: >-
Search vendor software documentation. Use this tool for questions
about how to use
specific applications and products—such as Zoom features, Microsoft 365, setting up
email on mobile, or any other software how-to questions.
input_mapping:
filters:
- retriever.filters_bm25
- retriever.filters_embedding
files:
- multi_file_converter.sources
query:
- chat_summary_llm.question
output_mapping:
chat_summary_llm.last_message: updated_query
meta_field_grouping_ranker.documents: documents
qa_llm.messages: messages
pipeline:
pipeline_output_type: chat
components:
retriever:
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
hosts:
index: vendor-documents
max_chunk_bytes: 104857600
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
fuzziness: 0
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
tabular_joiner.documents: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
extraction_kwargs:
output_format: markdown
target_language:
include_tables: true
include_links: true
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_converter.documents
receiver: splitter.documents
- sender: pdf_converter.documents
receiver: splitter.documents
- sender: markdown_converter.documents
receiver: splitter.documents
- sender: html_converter.documents
receiver: splitter.documents
- sender: pptx_converter.documents
receiver: splitter.documents
- sender: docx_converter.documents
receiver: splitter.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
chat_summary_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt:
user_prompt: >-
{% message role="user" %}
You are part of a chatbot.
You receive a question (Current Question) and a chat
history.
Use the context from the chat history and reformulate the
question so that it is suitable for retrieval augmented
generation.
If X is followed by Y, only ask for Y and do not repeat X
again.
If the question does not require any context from the chat
history, output it unedited.
Don't make questions too long, but short and precise.
Stay as close as possible to the current question.
Only output the new question, nothing else!
{{ question }}
New question:
{% endmessage %}
required_variables: "*"
streaming_callback:
qa_llm:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.4
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the
question.
Only use documents that are related to the question to
answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make
things up.
Just output the structured, informative and precise answer
and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when
using information from a document, e.g. [3] for Document [3]
.
Never name the documents, only enter a number in square
brackets as a reference.
The reference must only refer to the number that comes in
square brackets after the document.
Otherwise, do not use brackets in your answer and reference
ONLY the number of the document without mentioning the word
document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found,
please adjust the filters or try a different question."
{% endif %}
Question: {{ question.text }}
Answer:
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: multi_file_converter.documents
receiver: meta_field_grouping_ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: chat_summary_llm.last_message
receiver: retriever.query
- sender: chat_summary_llm.last_message
receiver: ranker.query
- sender: chat_summary_llm.last_message
receiver: qa_llm.question
- sender: meta_field_grouping_ranker.documents
receiver: qa_llm.documents
max_runs_per_component: 100
metadata: {}
is_pipeline_async: false
inputs_from_state: {}
outputs_to_string: {}
outputs_to_state: {}
_meta:
name: search_vendor_docs
description: >-
Search vendor software documentation. Use this tool for questions
about how to use
specific applications and products—such as Zoom features, Microsoft 365, setting up
email on mobile, or any other software how-to questions.
tool_id:
pipeline_version_id: c164dc6d-3b28-406e-8766-a47b19cbee65
system_prompt: >-
{% message role="system" %}
You are an IT helpdesk assistant for Corp. You help employees solve IT
problems and answer questions about IT processes and software.
You have two tools:
- search_internal_it: Use this for questions about Acme Corp's internal
IT policies and procedures—requesting software, getting VPN access, IT
support processes, internal how-tos.
- search_vendor_docs: Use this for questions about how to use software
products—Zoom, Microsoft 365, and other applications.
When a question involves both internal processes and software (for
example, "I can't connect to Teams because my VPN is blocking it"), use
both tools before answering.
Base your answer only on the information you find. Cite which documents
you used. If you can't find the answer in either knowledge base, say so
clearly and tell the employee to contact the IT helpdesk directly at
helpdesk@acmecorp.internal.
{% endmessage %}
user_prompt:
required_variables:
exit_conditions:
state_schema: {}
max_agent_steps: 100
streaming_callback:
raise_on_tool_invocation_failure: false
tool_invoker_kwargs:
confirmation_strategies:
WeaveConnector:
type: haystack_integrations.components.connectors.weave.weave_connector.WeaveConnector
init_parameters:
pipeline_name: helpdesk-agent
weave_init_kwargs:
max_runs_per_component: 100
metadata: {}
inputs:
messages:
- Agent.messages
filters: []
files: []
outputs:
answers:
documents:
messages: Agent.last_message
```
In Pipeline Builder, you simply drag the component from the Connectors group, drop it on the canvas, and pass the name of the pipeline you want to trace in the `pipeline_name` parameter. `WeaveConnector` is not connected to any component.
## Related Information
- [WeaveConnector](/docs/reference/pipeline-components/integrations/weave/WeaveConnector.mdx)
- [Trace Your Pipelines](/docs/how-to-guides/productionizing-your-pipeline/trace-your-pipelines.mdx)
---
## Test Your Pipeline in Playground
Time to test your pipeline!
***
## About This Task
You can run queries with your pipeline and check whether the responses match the quality you expect. You can also use the Playground to collect feedback from users; they can add feedback to each response. You can then check this feedback on the Pipeline details page. For more information, see [Collect User Feedback](/docs/how-to-guides/evaluating-your-pipeline/collect-feedback.mdx).
### Upload Files
You can upload files directly in Playground. If the workspace doesn't contain any files, the pipeline runs only on the files you upload. If the workspace already has files, the pipeline uses both the workspace files and the ones you uploaded.
To support file uploads in Playground, make sure the `Input` component is configured to receive files. We also recommend adding Converters and PreProcessors that can handle the types of files you plan to upload, just like you would in an index. Without them, the uploaded files won't be preprocessed.
:::info Pipeline Templates
If you're using a pipeline built with one of our templates, all the necessary components are already included.
:::
### Download Generated Files
If your pipeline generates files as output, for example processed documents, reports, or other file types, you can download them from the Playground. Open the sources section in the answer and download the file.
### Pipeline Output Type
You can indicate the output type of your pipeline in pipeline YAML to make sure Playground displays the results in the best possible way. Add `piepline_output_type` to the YAML and set it to one of these values:
- `chat`
- `generative`
- `extractive`
- `document`
For details, see [Set Pipeline Output Type](/docs/how-to-guides/designing-your-pipeline/set-additional-params/set-pipeline-output.mdx).
### Logs
Playground shows logs for each query you run. You can click the Debug icon to view output logs for each pipeline run. These include component parameters, queries, and answers.
## Prerequisites
- If you're asking your colleague to test your pipeline, have a look at [Guidelines for Onboarding Your Users](/docs/how-to-guides/evaluating-your-pipeline/guidelines-for-onboarding-your-users.mdx).
- You must have a deployed, active pipeline.
## Run Queries in the UI
1. Log in to ",
"value": "field_value"
},
"params": {
"param1": "value1",
"param2": "value2"
},
"queries": [
"my query"
]
}
'
```
See also [Use Your Pipeline in Your Target App](../productionizing-your-pipeline/embed-your-pipeline-in-your-target-app.mdx) and [Productionizing Your Pipeline](../productionizing-your-pipeline/productionizing-your-pipeline.mdx).
## What's Next
You can open or download each document containing the answer. To do that, hover over the More Actions icon next to the document name.
You can also copy or download the answer text using the copy and download icons next to the answer. Downloading saves the answer as a Markdown file.
You can also give feedback for each answer using the thumbs-up and thumbs-down icons. This will let the pipeline creator know how the pipeline is doing.
As the pipeline creator, you can then analyze the feedback on the Pipeline Details page. Click the pipeline name to open it.
---
## Set Default Pipeline(Searching-with-your-pipeline)
You can update your pipeline in production without any downtime. Use the `set default pipeline` endpoint to seamlessly direct all traffic to a new pipeline.
***
## About This Task
You can set a pipeline as the default for your search by using the [Set Default Pipeline](/docs/api/main/set-default-pipeline-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-default-post.api.mdx) endpoint. Once you do this, you can simply use `default` as the pipeline name in the [Search](/docs/api/main/search-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-post.api.mdx) endpoint. No additional work or app changes are required on your part.
This option gives you the flexibility to change the pipeline you use for search in production at any time without disrupting your service. For example, if you need to tweak the pipeline used in production, you can create and test a new one in the background. When it's ready, simply set it as the default pipeline to smoothly redirect traffic to it.
:::tip Setting a Default Pipeline Version with the UI
You can also set a pipeline version as the default one. For details on how to do this, see [Manage Pipeline Versions](/docs/how-to-guides/designing-your-pipeline/manage-pipeline-versions.mdx).
:::
## Change the Default Pipeline
1. [Create a pipeline](/docs/how-to-guides/designing-your-pipeline/create-a-pipeline/create-a-pipeline-in-studio.mdx) that will replace the pipeline currently running in production.
2. [Deploy the new pipeline](/docs/how-to-guides/designing-your-pipeline/deploy-a-pipeline.mdx).
We recommend verifying this pipeline's performance by sharing it with other users and collecting feedback.
3. Use the [set default pipeline](/docs/api/main/set-default-pipeline-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-default-post.api.mdx) API endpoint to indicate that you want to use the newly created pipeline in production. This simply routes all queries to the new pipeline without any interruptions.
4. When using the endpoints for search, such as [Search](/docs/api/main/search-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-post.api.mdx), [Search Stream](/docs/api/main/search-stream-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-stream-post.api.mdx), [Chat](/docs/api/main/chat-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-chat-post.api.mdx), or [Chat Stream](/docs/api/main/chat-stream-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-chat-stream-post.api.mdx), set the pipeline name to `default` in the URL, for example: `https://api.cloud.deepset.ai/api/v1/workspaces/my_workspace/pipelines/default/search`.
---
## Modify Pipeline Parameters at Query Time
You can override component parameters set in the pipeline configuration for a specific query. This helps you test different settings without changing the pipeline file.
***
## Parameters You Can Modify
At query time, you can modify the `run()` method parameters of the components in your pipeline. To check the parameters you can change for a specific component:
1. Go to the [component documentation](/docs/concepts/about-pipelines/pipeline-components.mdx).
2. Scroll down to the _Run Method Parameter_ section. These are the parameters you can modify at query time.
For example, for `DeepsetAnswerBuilder`, you can find the parameters in the [Run Method Parameters](/docs/reference/pipeline-components/data-processing/transform/DeepsetAnswerBuilder.mdx#run-method-parameters) section of the documentation.
:::info Component Connections
You can't modify component connections at query time.
:::
## Parameter Format
Pass parameters as a JSON dictionary using the following format:
```json
{
"component1_name":{ // this is the name you gave to your component in your pipeline
"parameter1_name":"parameter1_value",
"parameter2_name":"parameter2_value"
},
"component2_name":{
"parameter3_name":"parameter3_value"
}
}
```
For example, to change the Retriever's `top_k` parameter for a specific query, use this code:
```json
{
"retriever":{"top_k":5}
}
```
:::warning Important
The component names must match those defined in your pipeline. The parameters you set must be valid `run()` method parameters for the corresponding components.
:::
## Passing Parameters
You can modify parameter values at query time in three ways:
- Through the Search API endpoint
- Through the Chat Stream API endpoint
- In Playground
- In a query set for a job
- On a shared prototype page
- In Prompt Explorer
### Passing Parameters Through the Search API
When querying your pipeline with the [Search](/docs/api/main/search-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-post.api.mdx) API endpoint, include the `params` field in your request. Inside `params`, specify the component names and the parameters you want to modify.
This is an example request that changes the `embedding_retriever`'s `top_k` to `1` for the query "Who was in the first all-girl jazz bands?":
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/my_workspace/pipelines/my_pipeline/search \
--header 'accept: application/json' \
--header 'authorization: Bearer deepset_API_key' \
--header 'content-type: application/json' \
--data '
{
"debug": true,
"params": {
"embedding_retriever": { "top_k": 1 }
},
"view_prompts": false,
"queries": [
"who was in the first all-girl jazz bands?"
]
}
'
```
### Passing Parameters Through the Chat Stream API
When querying your pipeline with the [Chat Stream](/docs/api/main/chat-stream-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-chat-stream-post.api.mdx) API endpoint, include the `params` field in your request body. This works both for deployed pipelines and for pipelines running in serverless mode (without prior deployment).
This is an example request that limits the retriever to one result:
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/my_workspace/pipelines/my_pipeline/chat-stream \
--header 'accept: application/json' \
--header 'authorization: Bearer deepset_API_key' \
--header 'content-type: application/json' \
--data '
{
"query": "Who was in the first all-girl jazz bands?",
"params": {
"retriever": { "top_k": 1 }
},
"search_session_id": "your-session-id"
}
'
```
#### Routing Filters to Components in Serverless Mode
When running a pipeline in serverless mode via `chat-stream`, you can also pass Haystack [filters](/docs/how-to-guides/working-with-your-data/working-with-metadata/use-metadata-in-your-search-system.mdx) at query time. For filters to reach the right component, you must add an `inputs` section to your pipeline YAML that maps the `filters` key to the target component input using the format `component_name.input_name`:
```yaml
inputs:
filters:
- retriever.filters
```
You can map filters to multiple components at once:
```yaml
inputs:
filters:
- bm25_retriever.filters
- embedding_retriever.filters
```
With this mapping in place, filters you pass in the `chat-stream` request body are forwarded to all listed components:
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/my_workspace/pipelines/my_pipeline/chat-stream \
--header 'accept: application/json' \
--header 'authorization: Bearer deepset_API_key' \
--header 'content-type: application/json' \
--data '
{
"query": "What did Alice write?",
"filters": {
"field": "meta.category",
"operator": "==",
"value": "news"
},
"search_session_id": "your-session-id",
"serverless": true,
"pipeline_version_id": "your-pipeline-version-id"
}
'
```
:::warning Important
If the `inputs.filters` mapping in your pipeline YAML is malformed (for example, a list entry is missing the dot separator between component name and input name), the request returns a 400 error. Make sure each entry follows the `component_name.input_name` format.
:::
### Passing Parameters in Playground, Shared Prototype, and Prompt Explorer
When testing your pipeline in the
Using Builder
After you save an index, you must enable it to start indexing the files in your workspace. Files uploaded after an index was enabled, are automatically added to the enabled index. The query pipeline can access all files only after indexing is complete.
## Prerequisites
- Understanding indexes. To learn more, see [Indexes](/docs/concepts/indexes/indexes.mdx).
- Understanding pipelines and components. For details, see [Pipelines](/docs/concepts/about-pipelines/about-pipelines.mdx) and [Pipeline Components](/docs/concepts/about-pipelines/pipeline-components.mdx).
## Create an Index in Pipeline Builder
1. Log in to
```bash
deepset-cloud --help
```
```shell
python3 -m deepset_cloud_sdk.cli --help
```
---
## Download Files with Python
You can download files from a
```python
from deepset_cloud_sdk.workflows.sync_client.files import download
download(
api_key="",
workspace_name="",
file_dir=Path("./downloaded_files"),
)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import download
async def my_async_context() -> None:
await download(
api_key="",
workspace_name="",
file_dir=Path("./downloaded_files"),
)
```
---
## Get Upload Sessions Details
Files are uploaded in an upload session. You can list all upload sessions or get a single session to check its status, creation time, and files uploaded.
***
## About This Task
### Sessions
```python
from deepset_cloud_sdk.workflows.sync_client.files import list_upload_sessions
for session_batch in list_upload_sessions(
api_key="",
workspace_name="",
is_expired=False, # Set to True if you want to list expired sessions
batch_size=100, # Adjust the batch size as needed
):
for session in session_batch: # List of length 100
print(session.session_id)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import list_upload_sessions
async def my_async_context() -> None:
async for session_batch in list_upload_sessions(
api_key="",
workspace_name="",
is_expired=False, # Set to True if you want to list expired sessions
batch_size=100, # Adjust the batch size as needed
):
for session in session_batch: # List of length 100
print(session.session_id)
```
## Get Details of a Single Session Script Examples
Here's the code you can use to view a single upload session. (You can get session IDs from the `list_upload_sessions()` method.)
```python
from deepset_cloud_sdk.workflows.async_client.files import get_upload_session
from uuid import UUID
session_id = UUID(
"enter-your-session-id-here"
) # Replace with your actual upload session ID returned by `list_upload_sessions`
session_details = get_upload_session(
api_key="",
workspace_name="",
session_id=session_id,
)
print(session_details)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import get_upload_session
from uuid import UUID
session_id = UUID(
"enter-your-session-id-here"
) # Replace with your actual upload session ID returned by `list_upload_sessions`
async def my_async_context() -> None:
session_details = await get_upload_session(
api_key="",
workspace_name="",
session_id=session_id,
)
print(session_details)
```
## Close a Session
You may need to close a session manually, for example, because you reached the limit of 10 open sessions to trigger file ingestion. You can do so using the [Close Session](/docs/api/main/close-session-api-v-1-workspaces-workspace-name-upload-sessions-session-id-put.api.mdx) REST API endpoint. You'll need the upload session ID, /upload_sessions/ \
--header 'accept: application/json' \
--header 'authorization: Bearer
```python
from deepset_cloud_sdk.workflows.sync_client.files import list_files
for file_batch in list_files(
api_key="",
workspace_name="",
batch_size=10,
):
for file in file_batch: # Lists with length 10 of files
print(file.name)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import list_files
async def my_async_context() -> None:
async for file_batch in list_files(
api_key="",
workspace_name="",
batch_size=10,
):
for file in file_batch:
print(file.name)
```
### List Files by Name
Here's an example of how to use the `list_files()` method to list files in a workspace by their name:
```python
from deepset_cloud_sdk.workflows.sync_client.files import list_files
for file_batch in list_files(
api_key="",
workspace_name="",
name="specific_filename.txt" # Uses fuzzy search for file names
batch_size=10,
):
for file in file_batch:
print(file.name)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import list_files
async def my_async_context() -> None:
async for file_batch in list_files(
api_key="",
workspace_name="",
name="specific_filename.txt" # Uses fuzzy search for file names
):
for file in file_batch:
print(file.name)
```
### List Files by Filter
This example uses an OData filter to list files in a workspace:
```python
from deepset_cloud_sdk.workflows.sync_client.files import list_files
for file_batch in list_files(
api_key="",
workspace_name="",
odata_filter="modified gt 2023-01-01T00:00:00Z"
):
for file in file_batch:
print(file.name)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import list_files
async def my_async_context() -> None:
async for file_batch in list_files(
api_key="",
workspace_name="",
odata_filter="modified gt 2023-01-01T00:00:00Z"
):
for file in file_batch:
print(file.name)
```
---
## Upload Files with Python
Use this method if you have many files to upload or want to upload files with metadata.
***
## About This Task
Uploading files using the Python methods included in the SDK is asynchronous and uses sessions under the hood. It's best for uploading large numbers of files with metadata. To upload files using this method, create and run a Python script. You can find example scripts at the bottom of this page.
To learn more, see also [Upload Files](/docs/how-to-guides/working-with-your-data/upload-files.mdx) and [Working with Metadata](/docs/how-to-guides/working-with-your-data/working-with-metadata/use-metadata-in-your-search-system.mdx).
### Sessions
```python
from pathlib import Path
from deepset_cloud_sdk.workflows.sync_client.files import upload
# Uploads all files from a given path
upload(
paths=[Path("")],
api_key="",
workspace_name="",
blocking=True, # waits until the files are displayed in deepset,
# this may take a couple of minutes
timeout_s=300, # the timeout for the `blocking` parameter in number of seconds
show_progress=True, # shows the progress bar
recursive=True, # uploads files from all subfolders as well
)
```
```python
from pathlib import Path
from deepset_cloud_sdk.workflows.async_client.files import upload
# Uploads all files from a given path.
async def my_async_context() -> None:
await upload(
paths=[Path("")],
api_key="",
workspace_name="",
blocking=True, # waits until the files are displayed in deepset Cloud,
# this may take a couple of minutes
timeout_s=300, # the timeout for the `blocking` parameter in number of seconds
show_progress=True, # shows the progress bar
recursive=True, # uploads files from all subfolders as well
)
# Run the async function
if __name__ == "__main__":
asyncio.run(my_async_context())
```
### Upload Bytes
You can upload files as bytes to a
```python
from deepset_cloud_sdk.workflows.sync_client.files import upload_bytes, DeepsetCloudFileBytes
upload_bytes(
api_key="",
workspace_name="", # optional, by default the environment variable "DEFAULT_WORKSPACE_NAME" is used
files=[
DeepsetCloudFileBytes(
name="example.txt",
file_bytes=b"this is text",
meta={"key": "value"}, # optional
)
],
blocking=True, # optional, by default True
timeout_s=300, # optional, by default 300
)
```
```python
from deepset_cloud_sdk.workflows.async_client.files import upload_bytes, DeepsetCloudFileBytes
async def my_async_context() -> None:
await upload_bytes(
api_key="",
workspace_name="", # optional, by default the environment variable "DEFAULT_WORKSPACE_NAME" is used
files=[
DeepsetCloudFileBytes(
name="example.txt",
file_bytes=b"this is some byte text",
meta={"key": "value"}, # optional
)
],
blocking=True, # optional, by default True
timeout_s=300, # optional, by default 300
)
# Run the async function
if __name__ == "__main__":
asyncio.run(my_async_context())
```
### Synchronize GitHub Files with "
def _parse_filename(url: str) -> str:
"""Parses the filename from a URL.
:param url: URL to parse the filename from
:return: Filename
"""
path = urlparse(url).path
filename = path.split("/")[-1]
return filename
def fetch_and_prepare_files(urls: List[str]) -> List[DeepsetCloudFile]:
"""Fetches files from URLs and converts them to DeepsetCloudFile objects.
These Objects can be uploaded to the Haystack Enterprise Platform directly without
having to first copy them to disk.
:param urls: List of URLs to fetch files from
:return: List of DeepsetCloudFile objects
"""
files_to_upload: List[DeepsetCloudFile] = []
for url in urls:
response = httpx.get(url)
response.raise_for_status()
file = DeepsetCloudFile(
text=response.text,
name=_parse_filename(url),
meta={"url": url},
)
files_to_upload.append(file)
return files_to_upload
# URLs of files to download and upload
DOWNLOAD_URLS: List[str] = [
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example.txt",
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example2.txt",
"https://raw.githubusercontent.com/deepset-ai/haystack/main/README.md",
]
files = fetch_and_prepare_files(DOWNLOAD_URLS)
# Upload .txt and .md files to deepset Cloud
upload_texts(
workspace_name="upload-test-123", # optional, uses "DEFAULT_WORKSPACE_NAME" by default
files=files,
blocking=False, # Set to False for non-blocking uploads
timeout_s=300, # Optional, default is 300 seconds
show_progress=True, # Optional, default is True
api_key=API_KEY,
write_mode=WriteMode.OVERWRITE,
)
```
### Download Files from a URL and Upload to "
WORKSPACE: str = ""
def _parse_filename(url: str) -> str:
"""Parses the filename from a URL.
:param url: URL to parse the filename from
:return: Filename
"""
path = urlparse(url).path
filename = path.split("/")[-1]
return filename
def fetch_and_upload_file(url: str) -> None:
"""Fetches a file from the given URL and converts it to a DeepsetCloudFile object.
That Object can be uploaded to the Haystack Enterprise Platform directly without
having to first copy them to disk.
:param url: URL to fetch files from
"""
response = httpx.get(url)
response.raise_for_status()
file = DeepsetCloudFile(
text=response.text,
name=_parse_filename(url),
meta={"url": url},
)
upload_texts(
workspace_name=WORKSPACE, # optional, uses "DEFAULT_WORKSPACE_NAME" by default
files=[file],
blocking=False, # Set to False for non-blocking uploads
timeout_s=300, # Optional, default is 300 seconds
show_progress=True, # Optional, default is True
api_key=API_KEY,
write_mode=WriteMode.OVERWRITE,
)
# URLs of files to download and upload
DOWNLOAD_URLS: List[str] = [
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example.txt",
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example2.txt",
"https://raw.githubusercontent.com/deepset-ai/haystack/main/README.md",
]
if __name__ == '__main__':
# Upload .txt and .md files to deepset Cloud
# Start one thread per URL to download and upload the files
with multiprocessing.Pool(processes=3) as pool:
results = pool.map(fetch_and_upload_file, DOWNLOAD_URLS)
```
#### Async
This example downloads files from a URL you specify and then uploads them asynchronously to "
WORKSPACE: str = ""
def _parse_filename(url: str) -> str:
"""Parses the filename from a URL.
:param url: URL to parse the filename from
:return: Filename
"""
path = urlparse(url).path
filename = path.split("/")[-1]
return filename
async def fetch_and_upload_file(url: str) -> None:
"""Fetches a file from the given URL and converts it to a DeepsetCloudFile object.
That Object can be uploaded to the Haystack Enterprise Platform directly without
having to first copy them to disk.
:param url: URL to fetch file from
"""
async with httpx.AsyncClient() as client:
response = await client.get(url)
response.raise_for_status()
file = DeepsetCloudFile(
text=response.text,
name=_parse_filename(url),
meta={"url": url},
)
await upload_texts(
workspace_name=WORKSPACE, # optional, uses "DEFAULT_WORKSPACE_NAME" environment variable by default
files=[file],
blocking=False, # Set to False for non-blocking uploads
timeout_s=300, # Optional, default is 300 seconds
show_progress=True, # Optional, default is True
api_key=API_KEY,
write_mode=WriteMode.OVERWRITE,
)
async def main(urls: List[str]) -> None:
"""Main function to run the asynchronous fetching and uploading of files."""
tasks = [fetch_and_upload_file(url) for url in urls]
await asyncio.gather(*tasks)
# URLs of files to download and upload
DOWNLOAD_URLS: List[str] = [
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example.txt",
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example2.txt",
"https://raw.githubusercontent.com/deepset-ai/haystack/main/README.md",
]
# Run the main function
if __name__ == "__main__":
asyncio.run(main(DOWNLOAD_URLS))
```
#### From Memory in Byte Format
Here's an example of how to fetch a PDF file from a given URL, convert it to a byte format, and then upload it to "
WORKSPACE: str = ""
def _parse_filename(url: str) -> str:
"""Parses the filename from a URL.
:param url: URL to parse the filename from
:return: Filename
"""
path = urlparse(url).path
filename = path.split("/")[-1]
return filename
def fetch_and_upload_file(url: str) -> None:
"""Fetches a file from the given URL and converts it to a DeepsetCloudFile object.
That Object can be uploaded to the Haystack Enterprise Platform directly without
having to first copy them to disk.
:param url: URL to fetch files from
"""
response = httpx.get(url)
response.raise_for_status()
file = DeepsetCloudFileBytes(
file_bytes=response.content,
name=_parse_filename(url),
meta={"url": url},
)
upload_bytes(
workspace_name=WORKSPACE, # optional, by default the environment variable "DEFAULT_WORKSPACE_NAME" is used
files=[file],
# by default blocking=True - by setting to False it will mean that you can immediately
# continue uploading another batch of files
blocking=False,
timeout_s=300, # optional, by default 300
show_progress=True, # optional, by default True
api_key=API_KEY,
write_mode=WriteMode.OVERWRITE,
)
# URLs of files to download and upload
DOWNLOAD_URLS: List[str] = [
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example.txt",
"https://raw.githubusercontent.com/deepset-ai/deepset-cloud-sdk/main/test-upload/example2.txt",
"https://raw.githubusercontent.com/deepset-ai/haystack/main/README.md",
"https://sherlock-holm.es/stories/pdf/letter/1-sided/advs.pdf",
]
if __name__ == '__main__':
# Upload .txt and .pdf files to deepset Cloud
# Start one thread per URL to download and upload the files
with multiprocessing.Pool(processes=4) as pool:
results = pool.map(fetch_and_upload_file, DOWNLOAD_URLS)
```
### Google Colab Notebook
Here's a Colab notebook with different upload scenarios you can test: [Upload files with SDK in Google Colab](https://colab.research.google.com/drive/1y2KMB606h-57BafCkhuiaXFWo4gDKtG3).
---
## Using Python Methods
Make use of the Python methods included in the ",
workspace_name="",
api_url="",
batch_size=10,
):
for file in file_batch:
print(file.name)
# Run the async function
if __name__ == "__main__":
asyncio.run(my_async_context())
---
## List Existing Files with CLI
Print a list of files that exist in the --workspace-name hotels --name "hilton-hotel" --batch-size 20
```
---
## Download Files with CLI
Using the SDK command-line interface, you can download files from a
```
The files are downloaded to the folder you specified, including all metadata. Metadata are downloaded as separate JSON files with the `meta.json` suffix.
## Examples
- This command uses an odata filter to narrow down the files downloaded. In this case, it downloads files with the following metadata: `{"Hotel_Address": "Amsterdam Netherlands"}` to the `hotels` directory:
```shell
deepset-cloud download --file-dir "./hotels" --odata-filter "Hotel_Address eq 'Amsterdam Netherlands'"
```
- This command downloads files whose names contain the string `westcord_art_hotel_amsterdam_4_stars` from the "hotels" workspace. It also includes the API key to connect to --workspace-name hotels --name "westcord_art_hotel_amsterdam_4_stars"
```
- This command downloads files to the current directory without their metadata:
```shell
deepset-cloud download ---no-include-meta
```
---
## Set Up the SDK CLI
# Set Up the Command Line interface
```
While the upload is progressing, you can first see the upload status, which means the files were uploaded to the S3 bucket, and then the ingestion status, which means the files are being transferred to
Obtaining the ARN for your clusters
1. Log in to your AWS account and open **Amazon OpenSearch Service**.
2. Select the cluster whose ARN you want to check.
The cluster details page opens, and in the _General information_ section, you can see the domain ARN for the cluster.
## Connect Your Cluster to ",
"aws_domain_arn": "",
"username": "",
}
'
```
3. Wait until you get the response. This may take a couple of minutes, as AWS takes some time to create the connection. The response contains the cluster's credentials ID. You'll need them to create the workspace in the last step.
4. Repeat step 2 for the pipeline cluster. Again, wait for the response and make sure you save the credentials ID from it.
:::info Listing Credentials
You can also use the [List Available Opensearch Credentials ](/docs/api/main/list-available-opensearch-credentials-api-v-1-infrastructure-document-stores-get.api.mdx) endpoint to get a list of all the credentials created for your ",
"workspace_document_store_credentials_id": ""
},
"name": ""
}
'
```
## What To Do Next
Now, the pipelines you create and deploy in the newly created workspace will use the files stored in your OpenSearch cluster.
### Updating Credentials
If your credentials to any of the clusters connected to ",
"role_session_name": ""
},
"bucket_name": ""
}
'
```
`role_session_name` is any name you want to give to this session.
3. Wait for the response. The response contains the ID of the credentials for S3. You'll need it to create the workspace connected to S3.
4. Create the workspace that will use the files stored in S3. Use the [Create Workspace](/docs/api/main/create-workspace-api-v-1-workspaces-post.api.mdx) endpoint and specify the `file_store_credentials`. You can ignore the `document_store_credentials` (it's used for OpenSearch).
Here's the code you can use to start with:
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
"file_store_credentials": {
"file_store_credentials_id": ""
},
"name": ""
}
'
```
## What To Do Next
You connected your newly created workspace to your S3 bucket. All the files you upload to this workspace will be stored in your S3 bucket, and all the pipelines you create in this workspace will use the files from S3.
You can now upload files to your supports files encoded in UTF-8 format. For files with different encoding formats, you may experience issues with display or formatting.
- A single file cannot be larger than 200 MB. If a file exceeds this size, it won't be uploaded. You can use [
Preparing file metadata
To add metadata to your files at upload time, create one metadata file for each file you upload. The metadata file must be a JSON file with the same name as the file whose metadata it contains and the extension `meta.json`.
For example, if you're uploading a file called `example.txt`, the metadata file should be called `example.txt.meta.json`. If you're uploading a file called `example.pdf`, the metadata file should be `example.pdf.meta.json`.
Here's the format of metadata in your `*.meta.json` files: `{"meta_key1": "value1", "meta_key2": "value2"}`.
To learn more about adding metadata, see [Add Metadata to Your Files](/docs/how-to-guides/working-with-your-data/working-with-metadata/add-metadata.mdx).
To learn about how to use metadata in your search app, see [Working with Metadata](/docs/how-to-guides/working-with-your-data/working-with-metadata/use-metadata-in-your-search-system.mdx).
### Upload Sessions
The SDK and the [Create Upload Session](/docs/api/main/create-upload-session-api-v-1-workspaces-workspace-name-upload-sessions-post.api.mdx) REST API endpoint use upload _sessions_. To start uploading files, you must first create a session. Sessions help you track the files you're uploading. Each session has an ID and you can check the status of your uploaded files at any time. Files start uploading only after a session is closed. If you don't close a session explicitly, it's automatically closed after 24 hours.
We recommend using upload sessions for large file uploads as they are faster and more efficient. There's no limit on the number of files per session, but we recommend keeping it to a maximum of 50,000 files.
After you upload files to ` in the URL with the name of your workspace and enter your /upload_sessions \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json'
```
4. Send your files to the URL you received in the response using the authentication configuration from the response. You can send both your metadata and raw files to this URL.
5. After you send all your files, close the session to start the upload. Use this code as a starting point replacing `workspace_name` in the URL with the name of your workspace and `YOUR_API_KEY` in the `authorization` header with your ' \
--header 'content-type: application/json'
```
6. Wait a while until your files are listed in
An example script to upload files in a session
In this scenario, you save the files locally first:
```python
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Dict, List, Tuple, Optional
from uuid import UUID
from tqdm.asyncio import tqdm # to visualise progress of async task completion
DC_ENDPOINT = "https://api.cloud.deepset.ai/api/v1"
WORKSPACE_NAME=""
API_TOKEN=""
log = structlog.get_logger(__name__)
def create_session() -> Tuple[UUID, Dict[Any, Any]]:
response = httpx.post(
f"{DC_ENDPOINT}/workspaces/{WORKSPACE_NAME}/upload_sessions",
headers={"Authorization": f"Bearer {API_TOKEN}"},
json={},
timeout=120,
)
assert response.status_code == 201
return (
UUID(response.json()["session_id"]),
response.json()["aws_prefixed_request_config"],
)
def close_session(session_id: UUID) -> None:
response = httpx.put(
f"{DC_ENDPOINT}/workspaces/{WORKSPACE_NAME}/upload_sessions/{session_id}",
headers={"Authorization": f"Bearer {API_TOKEN}"},
json={"status": "CLOSED"},
timeout=120,
)
assert response.status_code == 204, f"status code should be '204', got '{response.status_code}' with content '{response.text}'"
@dataclass
class IngestionStatus:
finished_files: int
failed_files: int
def get_session_status(session_id: UUID) -> IngestionStatus:
response = httpx.get(
f"{DC_ENDPOINT}/workspaces/{WORKSPACE_NAME}/upload_sessions/{session_id}",
headers={"Authorization": f"Bearer {API_TOKEN}"},
timeout=120,
)
assert response.status_code == 200
response_body = response.json()
print(response_body)
return IngestionStatus(
finished_files=response_body["ingestion_status"]["finished_files"],
failed_files=response_body["ingestion_status"]["failed_files"],
)
@dataclass
class UploadFileResult:
file: str
exception: Optional[Exception] = None
async def upload_file_to_s3(
file_path: str,
aws_prefixed_request_config: Dict[Any, Any],
semaphore:asyncio.BoundedSemaphore,
concurrency=10
) -> List[UploadFileResult]:
client = httpx.AsyncClient()
# upload file asynchronously using prefixed request config
async with semaphore:
async with httpx.AsyncClient(
limits=httpx.Limits(
max_keepalive_connections=concurrency, max_connections=concurrency
)
) as client:
try:
async with aiofiles.open(file_path, "rb") as file:
file_name = os.path.basename(file_path)
content = await file.read()
response = await client.post(
aws_prefixed_request_config["url"],
data=aws_prefixed_request_config["fields"],
files={"file": (file_name, content)},
timeout=2000,
)
assert response.status_code == 204, f"status code should be '204', got '{response.status_code}'"
except Exception as exc:
return UploadFileResult(file=file_name, exception=exc)
return UploadFileResult(file=file_name)
def wait_for_files_to_be_ingested(file_paths, exceptions, session_id):
total_uploaded_files = len(file_paths) - len(exceptions)
total_processed_files = 0
while total_processed_files < total_uploaded_files:
session_status = get_session_status(session_id)
log.info(
"Polling status",
failed_files=session_status.failed_files,
finished_files=session_status.finished_files,
)
total_processed_files = (
session_status.failed_files + session_status.finished_files
)
time.sleep(3)
#### the main flow ####
async def main():
session_id, aws_prefixed_request_config = create_session()
# get a list of files as below, alternatively give a list of explicit paths
file_paths = [p for p in Path('./path/to/data/dir').glob('*')]
concurrency = 10
semaphore = asyncio.BoundedSemaphore(concurrency)
tasks = []
for file_path in file_paths:
# upload files
tasks.append(
upload_file_to_s3(file_path, aws_prefixed_request_config, semaphore=semaphore, concurrency=concurrency)
)
results:List[UploadFileResult] = await tqdm.gather(*tasks)
exceptions = [r for r in results if r.exception is not None]
log.info(
"files uploaded",
successful=len(results) - len(exceptions),
failed=len(exceptions),
)
if len(exceptions):
log.warning("upload exceptions", exceptions=exceptions)
# close session once you are done with uploading
# the ingestion will start once the session is closed
close_session(session_id)
# wait for files to be ingested into deepsetCloud
wait_for_files_to_be_ingested(file_paths, exceptions, session_id)
if __name__ == '__main__':
asyncio.run(main())
```
You can check the status of your session with the [Get Session Status](/docs/api/main/get-session-status-api-v-1-workspaces-workspace-name-upload-sessions-session-id-get.api.mdx) endpoint.
### Upload with the `Upload File` Endpoint
This method is not recommended for uploading more than a few hundred files at once. If you have large numbers of files, upload with the SDK instead.
Below are sample requests that you can send to upload your files. For more information, you can also see the [upload file](/docs/api/main/upload-file-api-v-1-workspaces-workspace-name-files-post.api.mdx) endpoint documentation. You need to [Generate an API Key](/docs/how-to-guides/managing-access/generate-api-key.mdx) first.
#### Upload an Existing File
To upload an existing file, use this code as a starting point for your request:
```curl
--request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces//files?write_mode=OVERWRITE' \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: multipart/form-data' \
--form 'meta={"key1":"value1", "key2":"value2"}, {"key2":"value2"}' \
--form file=@
```
Replace the following parameters:
- In the URL, replace `YOUR_WORKSPACE_NAME` with the name of your workspace.
- In the `authorization` header, replace `YOUR_API_KEY` with your /files?file_name=myFile.txt' \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: multipart/form-data' \
--form 'meta={"key1":"value1", "key2":"value2"}' \
--form 'text=This is the file text'
```
Replace the following parameters:
- In the URL, replace `YOUR_WORKSPACE_NAME` with the name of your /files \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: multipart/form-data' \
--form 'meta={"key1":"value1", "key2":"value2"}' \
--form file=@
# This is an example request if you're creating the file during upload:
curl --request POST \
--url 'https://api.cloud.deepset.ai/api/v1/workspaces//files?file_name=myFile.txt' \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: multipart/form-data' \
--form 'meta={"key1":"value1", "key2":"value2"}' \
--form 'text=This is the file text'
```
---
## Connect to Your Snowflake Database
Query data in your Snowflake database using "
account: ""
authenticator: "SNOWFLAKE" # Choose from: SNOWFLAKE, SNOWFLAKE_JWT, OAUTH
warehouse: ""
database: ""
db_schema: ""
replies_to_sql:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ replies[0] }}'
output_type: str
display_prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
You are an expert data analyst.
Your role is to answer the user's question {{ question }} using the information
in the table.
You will base your response solely on the information provided in the
table(s).
Do not rely on your knowledge base; only the data that is in the table.
Refrain from using the term "table" in your response, but instead, use
the word "data".
If the table is blank say:
"The specific answer can't be found in the database. Try rephrasing your
question."
Additionally, you will present the table in a tabular format and provide
the SQL query used to extract the relevant rows from the database in
Markdown.
If the table is larger than 10 rows, display the most important rows up
to 10 rows. Your answer must be detailed and provide insights based on
the question and the available data.
SQL query:
{{ sql_query }}
Table:
{{ table }}
Answer:
display_llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": false}
model: "gpt-4o"
generation_kwargs:
max_tokens: 2000
temperature: 0
seed: 0
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
connections:
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: sql_prompt_builder.documents
- sender: ranker.documents
receiver: answer_builder.documents
- sender: sql_prompt_builder.prompt
receiver: sql_llm.prompt
- sender: sql_llm.replies
receiver: replies_to_sql.replies
- sender: replies_to_sql.output
receiver: snowflake_retriever.query
- sender: snowflake_retriever.table
receiver: display_prompt_builder.table
- sender: replies_to_sql.output
receiver: display_prompt_builder.sql_query
- sender: display_prompt_builder.prompt
receiver: display_llm.prompt
- sender: display_prompt_builder.prompt
receiver: answer_builder.prompt
- sender: display_llm.replies
receiver: answer_builder.replies
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "retriever.query"
- "ranker.query"
- "sql_prompt_builder.question"
- "display_prompt_builder.question"
- "answer_builder.query"
filters: # These components will receive a potential query filter as input
- "retriever.filters_bm25"
- "retriever.filters_embedding"
outputs: # Defines the output of your pipeline
documents: "ranker.documents" # The output of the pipeline is the retrieved documents
answers: "answer_builder.answers" # The output of the pipeline is the generated answers
max_runs_per_component: 100
metadata: {}
```
---
## Add Metadata to Your Files
You can add metadata to your files. You can do this when you upload your files through REST API or
Example metadata file
This file contains reviews for the Hotel Park Royal Palace in Vienna. The file is called _austria_trend_hotel_park_royal_palace_vienna_0.txt_.
```Text austria_trend_hotel_park_royal_palace_vienna_0.txt
Positives:
location and how clean it is
Negatives:
lack of variety in food any thing you ask for will charge you 5 euro the WiFi is not covering all my room dogs are allowed
```
This is the accompanying metadata file. It's called _austria_trend_hotel_park_royal_palace_vienna_0.txt.meta.json_.
```json austria_trend_hotel_park_royal_palace_vienna_0.txt.meta.json
{"Hotel_Address": "Schlossallee 8 14 Penzing 1140 Vienna Austria", "Review_Date": "2016-02-22", "Average_Score": 8.8, "Hotel_Name": "Austria Trend Hotel Park Royal Palace Vienna", "Reviewer_Score": 9.6}
```
### Formatting Guidelines for Uploading with REST API
If you're uploading files through the API, pass metadata for each file in a separate dictionary formatted like this: `meta={"key1":"value1", "key2":"value2"}`. For each file you're uploading, provide a corresponding metadata dictionary. The order matters: the first dictionary you pass is linked to the first file, the second dictionary to the second file, and so on.
### Allowed Values
In your metadata dictionaries, you can pass the following:
- Numerical data
- Dates
- Keyword fields
- Lists
Metadata limitations:
- One level of nesting works best.
- The size limit for a single value in the _key:value_ pair is 32 766 bytes, which is roughly 32 766 characters.
- The total size of metadata (all keys and values) is 250 000 bytes maximum, roughly 250 000 characters.
### Example
Here are simple examples of metadata:
```python
metadata = [{"type": "article", "source": "New York Times", "title": "Leaders Look into the Future", "year published": "2020"}]
```
```curl
{
"type": "book",
"topic": "business",
"author": "Ben Horowitz",
"book_titles": [
"The Hard Thing About Hard Things",
"What You Do Is Who You Are"
]
}
```
## Add Metadata with the Python SDK
The easiest way is to upload metadata together with your files. For detailed instructions, see [Tutorial: Uploading Files with CLI](/docs/tutorials/learn-the-basics/tutorial-uploading-files-with-cli.mdx) or [Tutorials: Uploading Files with Python Methods](/docs/tutorials/learn-more-advanced-features/tutorial-uploading-files-with-python-methods.mdx).
## Add Metadata with REST API
Here's the code you can use to add metadata to files when [uploading them through REST API](/docs/api/main/upload-file-api-v-1-workspaces-workspace-name-files-post.api.mdx):
```curl
curl --request POST \
--url 'https://api.cloud.deepset.ai/api/v1/workspaces//files?write_mode=OVERWRITE' \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: multipart/form-data' \
--form file=@
// Here is where you define the metadata for your file:
--form 'meta={"year":"2009", "type":"financial report"}'
```
Make sure you update the following parameters:
- In the URL, update `` to your ` with your ` with the path to your file.
- Update the metadata.
You can also add or update metadata of files that are already uploaded to /files//meta \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
// Here is where you pass the metadata:
--data '
{
"year": "2009",
"type": "financial report"
}
'
```
## Add Metadata from the UI
This is an easy way to add, update, and remove metadata from files.
1. Log in to
```yaml
router:
type: haystack.components.routers.metadata_router.MetadataRouter
rules:
en: # Router's rules use filters:
field: meta.type
operator: ==
value: article
```
```python
filters = {"field": "type", "operator": "==", "value": "article"}
```
#### Comparison and Logic Filter
Here's a more complex filter combining both comparison and logic filters. For a document to be selected, all of the following conditions must be true, as they're combined using the `AND` operator:
1. The document's type must be "article".
2. The document's date must be on or after January 1, 2015.
3. The document's date must be before January 1, 2021.
4. The document's rating must be 3 or higher.
5. The document must either belong to the genres "economy" or "politics" or it must be published by "The New York Times".
```yaml
retriever:
type: haystack.components.retrievers.filter_retriever.FilterRetriever
init_parameters:
document_store:
init_parameters:
use_ssl: True
verify_certs: False
http_auth:
- "${OPENSEARCH_USER}"
- "${OPENSEARCH_PASSWORD}"
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
filters:
operator: "AND"
conditions:
- field: type
operator: ==
value: "article"
- field: date
operator: ==
value: 1420066800
- field: date
operator: <
value: 1609455600
- field: rating
operator: <
value: 3
- operator: "OR"
conditions:
- field: genre
operator: "IN"
value: ["economy", "politics"]
- field: publisher
operator: ==
value: "nytimes"
```
```python
filters = {
"operator": "AND",
"conditions": [
{"field": "type", "operator": "==", "value": "article"},
{"field": "date", "operator": ">=", "value": "2015-01-01"},
{"field": "date", "operator": "<", "value": "2021-01-01"},
{"field": "rating", "operator": ">=", "value": 3},
{
"operator": "OR",
"conditions": [
{"field": "genre", "operator": "in", "value": ["economy", "politics"]},
{"field": "publisher", "operator": "==", "value": "nytimes"},
],
},
],
}
```
## Components Using Filters
- [`MetadataRouter`](https://docs.haystack.deepset.ai/docs/metadatarouter): You can use filters in the `rules` parameter.
- [`Retrievers`](/docs/concepts/about-pipelines/pipeline-components.mdx)
For details and usage examples, see the component's documentation page.
## Legacy Filters
The syntax of filters in ' \
--header 'content-type: application/json' \
--data '
{
"debug": false,
"filters": {
"category": "news",
"published_date": "2024"
},
"view_prompts": false,
"queries": [
"What did Alice write?"
]
}
'
```
See also [Filter Syntax](./filtering-logic.mdx).
## Embedding Metadata with DocumentEmbedders
`DocumentEmbedders` can vectorize not only the document text but also the metadata you indicate in the `meta_fields_to_embed` parameter. In this example, `SentenceTransformersDocumentEmbedder` embeds the title and subtitle of documents:
```yaml
components:
document_embedder:
type: haystack.components.embedders.sentence_transformers_document_embedder.SentenceTransformersDocumentEmbedder
init_parameters:
model: "intfloat/e5-base-v2"
meta_fields_to_embed: ["title", "subtitle"]
```
This means that the title and subtitle would be prepended to the document content.
## Metadata for Ranking
When using `TransformersSimilarityRanker` or `CohereRanker`, you can assign a higher rank to documents with certain metadata values. To learn more about rankers, see `Rankers`.
All three rankers mentioned above take the `meta_fields_to_embed` parameter, where you can pass the metadata fields you want to prioritize. Like with DocumentEmbedders, the values of these fields are then prepended to the document content and embedded there. This means that the content of the metadata fields you indicate is taken into consideration during the ranking. In this example, the Ranker prioritizes documents with fields `category` and `authors`:
```yaml
components:
ranker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: "intfloat/simlm-msmarco-reranker"
top_k: 8
meta_fields_to_embed: ["category", "authors"]
```
There's also `MetaFieldRanker`, which sorts documents based on the value of a specific metadata field. It also lets you choose how important the metadata field is in the ranking process. For example, to prioritize documents with the highest rating (assuming the rating is part of the document's metadata), you could use `MetaFieldRanker`:
```yaml
components:
ranker:
type: haystack.components.rankers.meta_field.MetaFieldRanker
init_parameters:
meta_field: "rating"
weight: 1.0
```
Setting weight to `1.0` means `MetaFieldRanker` only ranks by the metadata field, ignoring any previous rankings or document content.
## Metadata in Prompts
You can pass documents' metadata in prompts for additional context and then instruct the LLM to use them. To pass the metadata, you can use the Jinja2 `for` loop that iterates over the documents displaying its number (`loop.index`), title (`doc.meta['title']`), and content (`doc.content`):
```text
You are a helpful assistant. Please answer the question based on the following documents:
{% for doc in documents %}
Document {{ loop.index }}:
Title: {{ doc.meta['title'] }}
Content: {{ doc.content }}
{% endfor %}
Question: {{ query }}
Answer:
"""
```
The syntax for accessing a document's metadata is: `document.meta['metadata_key']`.
## Example
Here's an example pipeline that uses metadata during the retrieval, ranking, and answer generation stages. During retrieval, it focuses on documents from the "news" category and embeds the title and subtitle into the document's text. Then, when ranking the documents, it considers the document's title and subtitle. Finally, when generating the answer, it passes the document's published date in the prompt, instructing the LLM to prefer the most recent documents.
```yaml
components:
bm25_retriever:
type: >-
haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: >-
haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
use_ssl: true
verify_certs: false
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
embedding_dim: 768
similarity: cosine
top_k: 20
custom_query: >
query:
bool:
must:
- multi_match:
query: $query
type: most_fields
fields:
- content
- title
- authors
operator: OR
filter:
term:
category: news
document_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
ranker:
type: >-
haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
model_kwargs:
torch_dtype: torch.float16
meta_fields_to_embed:
- title
- subtitle
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: >-
You are a media expert.
You answer questions truthfully based on provided documents.
For each document, check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document. e.g. [3], for Document[3].
The reference must only refer to the number that comes in square brackets after passage.
Otherwise, do not use brackets in your answer and reference ONLY the number of the passage without mentioning the word passage.
If the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.
For contradictory information, prefer recent documents.
These are the documents:
{% for doc in documents %}
Document {{ loop.index }}:
Title: {{ doc.meta['title'] }}
Subtitle: {{ doc.meta['subtitle'] }}
Published Date: {{ doc.meta['published_date'] }}
Content: {{ doc.content }}
{% endfor %}
Question: {{ question }}
Answer:
llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- OPENAI_API_KEY
strict: false
model: gpt-4o
generation_kwargs:
max_tokens: 650
temperature: 0
seed: 0
answer_builder:
type: >-
deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
FilterRetriever:
type: haystack.components.retrievers.filter_retriever.FilterRetriever
init_parameters:
document_store:
type: >-
haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
use_ssl: true
verify_certs: false
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
embedding_dim: 768
similarity: cosine
filters:
category: news
connections:
- sender: bm25_retriever.documents
receiver: document_joiner.documents
- sender: document_joiner.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: prompt_builder.documents
- sender: ranker.documents
receiver: answer_builder.documents
- sender: prompt_builder.prompt
receiver: llm.prompt
- sender: prompt_builder.prompt
receiver: answer_builder.prompt
- sender: llm.replies
receiver: answer_builder.replies
- sender: FilterRetriever.documents
receiver: document_joiner.documents
max_loops_allowed: 100
metadata: {}
inputs:
query:
- bm25_retriever.query
- ranker.query
- prompt_builder.question
- answer_builder.query
filters:
- bm25_retriever.filters
- FilterRetriever.filters
outputs:
documents: ranker.documents
answers: answer_builder.answers
```
## Related Information
- [Filter Syntax](./filtering-logic.mdx)
- [Add Metadata to Your Files](./add-metadata.mdx)
---
## Haystack Enterprise Platform Documentation Knowledge Graph
This knowledge graph represents the structure and relationships between documentation topics in the dc-docs repository (Haystack Enterprise Platform documentation).
## Main Documentation Areas
```mermaid
graph TB
Root[Haystack Enterprise Platform Documentation]
Root --> GettingStarted[Getting Started]
Root --> Learn[Learn]
Root --> Concepts[Concepts]
Root --> HowTo[How-To Guides]
Root --> Tutorials[Tutorials]
Root --> API[API Reference]
Root --> Builder[Builder]
style Root fill:#2563eb,stroke:#1e40af,color:#fff
style GettingStarted fill:#059669,stroke:#047857,color:#fff
style Learn fill:#dc2626,stroke:#b91c1c,color:#fff
style Concepts fill:#7c3aed,stroke:#6d28d9,color:#fff
style HowTo fill:#ea580c,stroke:#c2410c,color:#fff
style Tutorials fill:#0891b2,stroke:#0e7490,color:#fff
style API fill:#4b5563,stroke:#374151,color:#fff
style Builder fill:#65a30d,stroke:#4d7c0f,color:#fff
```
## Core Concepts Relationships
```mermaid
graph LR
subgraph Core["Core Concepts"]
Pipelines[Pipelines]
Components[Pipeline Components]
Indexes[Indexes]
DocStores[Document Stores]
Data[Data Flow]
LLMs[Language Models]
Jobs[Jobs]
Agents[AI Agents]
end
Pipelines -->|contain| Components
Pipelines -->|use| Indexes
Pipelines -->|connect to| DocStores
Pipelines -->|use| LLMs
Pipelines -->|run as| Jobs
Pipelines -->|can include| Agents
Indexes -->|write to| DocStores
Indexes -->|process| Data
Components -->|read from| DocStores
Components -->|use| LLMs
Agents -->|use| Components
Agents -->|call| Tools[Agent Tools]
Agents -->|maintain| Memory[Agent Memory]
style Pipelines fill:#2563eb,stroke:#1e40af,color:#fff
style Components fill:#7c3aed,stroke:#6d28d9,color:#fff
style Indexes fill:#059669,stroke:#047857,color:#fff
style DocStores fill:#dc2626,stroke:#b91c1c,color:#fff
style Agents fill:#ea580c,stroke:#c2410c,color:#fff
```
## Pipeline Components Ecosystem
```mermaid
graph TB
subgraph ComponentTypes["Component Types"]
Embedders[Embedders]
Generators[Generators]
Retrievers[Retrievers]
Rankers[Rankers]
Builders[Builders]
Converters[Converters]
Preprocessors[Preprocessors]
Joiners[Joiners]
Routers[Routers]
Writers[Writers]
end
subgraph Providers["Model Providers"]
OpenAI[OpenAI]
Anthropic[Anthropic]
Cohere[Cohere]
AmazonBedrock[Amazon Bedrock]
GoogleVertex[Google Vertex]
HuggingFace[Hugging Face]
Nvidia[Nvidia]
Ollama[Ollama]
end
Embedders -->|powered by| Providers
Generators -->|powered by| Providers
Rankers -->|powered by| Providers
Converters --> Preprocessors
Preprocessors --> Embedders
Embedders --> Retrievers
Retrievers --> Rankers
Rankers --> Builders
Builders --> Generators
Generators --> Writers
style ComponentTypes fill:#f3f4f6,stroke:#9ca3af
style Providers fill:#fef3c7,stroke:#fbbf24
```
## Document Stores Relationships
```mermaid
graph TB
subgraph DocStores["Document Stores"]
OpenSearch[OpenSearchCore Store]
Elasticsearch[Elasticsearch]
Pinecone[Pinecone]
Weaviate[Weaviate]
Qdrant[Qdrant]
MongoDB[MongoDB Atlas]
PgVector[PgVector]
Snowflake[Snowflake]
end
subgraph Components["Components That Use Stores"]
DocWriter[DocumentWriter]
BM25[BM25 Retriever]
Embedding[Embedding Retriever]
Hybrid[Hybrid Retriever]
end
OpenSearch -->|core managed| DocWriter
OpenSearch -->|retrieve from| BM25
OpenSearch -->|retrieve from| Embedding
Elasticsearch --> DocWriter
Pinecone --> DocWriter
Weaviate --> DocWriter
Qdrant --> DocWriter
MongoDB --> DocWriter
PgVector --> DocWriter
style OpenSearch fill:#2563eb,stroke:#1e40af,color:#fff
style DocWriter fill:#059669,stroke:#047857,color:#fff
```
## Data Flow
```mermaid
graph LR
subgraph Upload["Data Upload"]
Files[Files]
S3[AWS S3]
VPC[Private VPC]
end
subgraph Indexing["Indexing Process"]
Index[Index]
Preprocess[Preprocessing]
Documents[Documents]
end
subgraph Storage["Storage Layer"]
DocStore[Document Store]
Database[SQL Database]
end
subgraph Query["Query Pipeline"]
UserQuery[User Query]
Retriever[Retriever]
GenOrLLM[Generator or LLM]
AnswerBuilder[Answer builder]
Answer[Answer]
end
Files --> S3
Files --> VPC
S3 --> Index
VPC --> Index
Index --> Preprocess
Preprocess --> Documents
Documents --> DocStore
Files -->|metadata| Database
UserQuery --> Retriever
DocStore --> Retriever
Retriever --> GenOrLLM
GenOrLLM --> AnswerBuilder
AnswerBuilder --> Answer
Answer -->|results| Database
style Upload fill:#dbeafe,stroke:#3b82f6
style Indexing fill:#dcfce7,stroke:#22c55e
style Storage fill:#fce7f3,stroke:#ec4899
style Query fill:#fef3c7,stroke:#f59e0b
```
## AI Agents Architecture
```mermaid
graph TB
subgraph Agent["AI Agent System"]
AgentComp[Agent Component]
LLM[Language Model]
Memory[Agent Memory]
Tools[Agent Tools]
end
subgraph ToolTypes["Tool Types"]
Pipelines[Pipelines]
CustomFunc[Custom Functions]
MCP[MCP Servers]
WebSearch[Web Search]
end
UserInput[User Input] --> AgentComp
AgentComp --> LLM
LLM -->|decides| Tools
Tools -->|execute| ToolTypes
ToolTypes -->|results| LLM
LLM -->|output| Memory
Memory -->|context| LLM
LLM --> Answer[Answer]
style AgentComp fill:#ea580c,stroke:#c2410c,color:#fff
style Tools fill:#7c3aed,stroke:#6d28d9,color:#fff
style Memory fill:#059669,stroke:#047857,color:#fff
```
## How-To Guides Organization
```mermaid
graph TB
HowTo[How-To Guides]
HowTo --> BuildingAgents[Building Agents]
HowTo --> DesigningPipelines[Designing Pipelines]
HowTo --> WorkingWithIndexes[Working with Indexes]
HowTo --> WorkingWithData[Working with Data]
HowTo --> Searching[Searching]
HowTo --> Evaluating[Evaluating]
HowTo --> Optimizing[Optimizing]
HowTo --> Productionizing[Productionizing]
HowTo --> ManagingAccess[Managing Access]
HowTo --> WorkingWithJobs[Working with Jobs]
HowTo --> UsingSDK[Using SDK]
DesigningPipelines --> CreatePipeline[Create Pipeline]
DesigningPipelines --> DeployPipeline[Deploy Pipeline]
DesigningPipelines --> EditPipeline[Edit Pipeline]
DesigningPipelines --> WorkWithLLMs[Work with LLMs]
DesigningPipelines --> CustomComponents[Custom Components]
DesigningPipelines --> HostedModels[Hosted Models]
BuildingAgents --> ConfigureAgent[Configure Agent]
BuildingAgents --> AdvancedConfig[Advanced Config]
BuildingAgents --> MinimalAgent[Minimal Agent]
BuildingAgents --> Troubleshooting[Troubleshooting]
style HowTo fill:#ea580c,stroke:#c2410c,color:#fff
```
## Learning Path
```mermaid
graph LR
subgraph Learn["Learn Section"]
Basics[5-Step Guide]
AppComponents[App Components]
DocRetrieval[Document Retrieval]
Extractive[Extractive QA]
RAG[RAG QA]
LLMOverview[LLM Overview]
PromptEng[Prompt Engineering]
MCP[Model Context Protocol]
end
Basics --> AppComponents
AppComponents --> DocRetrieval
DocRetrieval --> Extractive
Extractive --> RAG
RAG --> LLMOverview
LLMOverview --> PromptEng
style Basics fill:#059669,stroke:#047857,color:#fff
style RAG fill:#dc2626,stroke:#b91c1c,color:#fff
```
## Tutorials Journey
```mermaid
graph TB
Tutorials[Tutorials]
subgraph Basics["Learn the Basics"]
FirstSearch[First Document Search]
FirstQA[First QA App]
RobustRAG[Robust RAG System]
DataCleaning[Data Cleaning Agent]
PII[PII Masking]
MongoDB[MongoDB RAG]
AutoTagging[Auto-tagging with LLM]
ConnectUI[Connect to UI]
UploadCLI[Upload with CLI]
end
subgraph Advanced["Learn Advanced Features"]
CustomComponent[Custom Component]
DemoApp[Demo Your App]
PythonUpload[Upload with Python]
end
subgraph RESTAPI["REST API Tutorials"]
ChatApp[Chat App API]
FeedbackAPI[Feedback API]
end
Tutorials --> Basics
Tutorials --> Advanced
Tutorials --> RESTAPI
FirstSearch --> FirstQA
FirstQA --> RobustRAG
style Tutorials fill:#0891b2,stroke:#0e7490,color:#fff
```
## Cross-Cutting Concerns
```mermaid
graph TB
subgraph CrossCutting["Cross-Cutting Concerns"]
Security[Secrets & Integrations]
Roles[User Roles & Permissions]
Workspaces[Workspaces]
Organizations[Organizations]
Settings[Settings]
Status[Platform Status]
end
subgraph AllAreas["Affects All Areas"]
Pipelines2[Pipelines]
Indexes2[Indexes]
Data2[Data]
Agents2[Agents]
end
Security -.->|secures| AllAreas
Roles -.->|controls access| AllAreas
Workspaces -.->|contains| AllAreas
Organizations -.->|manages| Workspaces
style CrossCutting fill:#f3f4f6,stroke:#9ca3af
```
## Component Providers and Integrations
```mermaid
graph TB
subgraph Haystack["Haystack Components"]
HaystackCore[Core Components]
Embedders2[Embedders]
Generators2[Generators]
Retrievers2[Retrievers]
Preprocessors2[Preprocessors]
Builders2[Builders]
end
subgraph DeepsetCustom["deepset Custom Nodes"]
Augmenters[Augmenters]
Code[Code]
Crawler[Firecrawl]
DeepsetGen[deepset Generators]
DeepsetConv[deepset Converters]
end
subgraph ThirdParty["Third-Party Integrations"]
OpenAI2[OpenAI]
Anthropic2[Anthropic]
Cohere2[Cohere]
Bedrock2[Amazon Bedrock]
Vertex2[Google Vertex]
Nvidia2[Nvidia]
Jina2[Jina]
Voyage2[Voyage]
Mistral2[Mistral]
end
HaystackCore --> Embedders2
HaystackCore --> Generators2
HaystackCore --> Retrievers2
HaystackCore --> Preprocessors2
HaystackCore --> Builders2
ThirdParty -.->|powers| HaystackCore
ThirdParty -.->|powers| DeepsetCustom
style Haystack fill:#2563eb,stroke:#1e40af,color:#fff
style DeepsetCustom fill:#059669,stroke:#047857,color:#fff
style ThirdParty fill:#fef3c7,stroke:#fbbf24
```
## Documentation Structure Summary
### Top-Level Organization
File counts are MDX pages under `docs/` (approximate; rerun `find` when restructuring).
1. **Getting Started** (~37 files)
- Basic concepts
- Quick start guide
- What's new (releases)
- Platform status
- Settings management
- Working in Haystack Enterprise Platform
2. **Learn** (~9 files)
- 5-step guide to prototyping
- Document retrieval
- Extractive QA
- RAG QA
- LLM overview
- Prompt engineering
- Model Context Protocol
3. **Concepts** (~26 files under `docs/concepts/`)
- Pipelines (including examples and multimodal topics)
- AI Agents
- Document stores
- Indexes
- Data in the platform
- Language models
- Jobs
- Roles, secrets, and integrations (cross-cutting)
4. **Reference — Pipeline components** (~234 files under `docs/reference/pipeline-components/`)
- AI components (for example, `Agent`, `LLM`)
- Knowledge retrieval, data processing, logic and flow
- Third-party integrations (provider-specific components)
- Custom `Code` and workspace custom components
- Legacy and deprecated components
- Input, output, and overview pages
5. **How-To Guides** (~107 files)
- Building agents
- Designing pipelines (including smart connections and hosted models)
- Working with indexes and data
- Searching, evaluating, optimizing
- Productionizing, managing access, jobs
- Using the SDK and REST API workflows
6. **Tutorials** (~14 files)
- Learn the basics (9 tutorials)
- Learn advanced features (3 tutorials)
- REST API tutorials (2 tutorials)
7. **API Reference** (~227 files)
- Main REST API (OpenAPI-generated pages)
- Jobs API and related endpoints
8. **Builder** (1 file)
- Deploy with Hayhooks
## Key Relationships Summary
### Primary Dependencies
- **Pipelines** depend on Components, Indexes, Document Stores, and LLMs
- **Indexes** depend on Document Stores and process Data
- **Components** depend on Document Stores and LLMs
- **AI Agents** depend on Components, Tools, and maintain Memory
- **Query pipelines** depend on enabled Indexes
- **Document Stores** are used by both Indexes (write) and Retrievers (read)
### Data Flow Path
1. Files → Upload to S3/VPC
2. Files → Index (preprocessing)
3. Index → Documents → Document Store
4. User Query → Retriever → Document Store
5. Retriever → Documents → Generator or LLM
6. Generator or LLM → Answer builder (`DeepsetAnswerBuilder` or Haystack `AnswerBuilder`) → Answer
### Agent Workflow
1. User Input → Agent Component
2. Agent → LLM (with tools list)
3. LLM → Tool Call OR Direct Answer
4. Tool → Execution → Result
5. Result → Check Exit Condition
6. Continue loop or return answer
### Component Pipeline
Files → Converters → Preprocessors → Embedders → (Storage) → Retrievers → Rankers → Prompt builders → Generators or LLM → Answer builders → Output
Smart connections can merge compatible lists (for example, multiple retrievers into one `documents` input) and convert between some types (for example, `string` and `ChatMessage`), which reduces the need for joiners and adapters in many pipelines.
## Cross-References and Integration Points
- **Security & Access**: Applies to all pipelines, indexes, and data
- **Workspaces**: Contain pipelines, indexes, and files
- **Organizations**: Contain multiple workspaces
- **Jobs**: Can run any pipeline type
- **LLMs**: Used by Generators, ChatGenerators, the `LLM` component, and Agents
- **Document Stores**: Central to both indexing and querying
- **Embedders**: Must use same model in indexing and query pipelines
- **Agents**: Can use pipelines as tools
## Special Component Combinations
Common patterns documented:
- Retriever + Ranker
- PromptBuilder + Generator
- ChatPromptBuilder + ChatGenerator
- Embedder + Retriever
- Joiner + Ranker (often replaceable with smart connections)
- Generator or LLM + `DeepsetAnswerBuilder` (RAG answers with references in the UI) or Haystack `AnswerBuilder`
- `Input` (`messages`) + `Agent` (minimal agent pipelines)
- Router + Multiple paths
- Validator + Loop
---
## 5-Step Guide to Building a Successful Prototype
Creating a successful AI-based application requires careful planning and execution. This guide outlines five essential steps to help you navigate the process, from identifying your use case to testing your prototype.
***
## Step 1: Identify Your Use Case
### Brainstorm and Prioritize
Gather your business and technical teams to brainstorm potential use cases for your LLM app. It’s crucial the team consists of business and technical people. Business teams know and understand business problems, while technical experts can spot what’s doable.
Make sure everyone understands the business value of each use case. For each idea, ask:
1. How much value would solving this problem bring?
2. How much effort would it take to solve this problem?
Choose use cases that offer high impact without draining your resources. Aim for a working system that delivers value and functionality, even if it’s not polished yet.
As your first choice, look for use cases that don’t require spending time on data preparation. Make sure you can easily access the data, it’s in a format you can consume, and you have permissions to use it.
When estimating the effort needed to build your solution, remember that it’s often the best choice to start small. AI doesn’t need to replace your whole workflow. Improving one small part of it can already be a big win.
## Step 2: Assemble Your Team
To build a successful prototype, you need these key players:
### Must-Have Team Members
These are the team members you must have on your team. Otherwise, you’ll miss valuable expertise.
- **Product Leader**: Sets the vision, works with stakeholders, and keeps delivery on track.
- **AI Engineer**: Knows AI, vector databases, and prompting. Has a product-focused mindset and understands the current LLM and AI landscape. Choose someone who shipped great products before.
- **Domain Expert**: Gives advice and tests the app. This will be the subject matter expert who looks at the app from the content perspective.
### Additional Team Members
Depending on your app, you might also want:
- **Backend Engineer**: Handles the server side of your app and ensures that it's scalable, performant, and secure, among other things.
- **Frontend Engineer**: Creates a user-friendly interface and ensures your app is responsive, accessible, and performant.
- **UI/UX Designer**: Ensures your app provides a positive and meaningful experience for its users. Conducts user research, designs how users interact with your app, and creates designs for the frontend engineer.
- **DevOps Engineer**: Manages and provisions infrastructure, implements systems for monitoring and logging, sets up CI/CD pipelines, ensures efficient allocation of computing resources, and more.
- **Data Engineer**: Ensures data quality and consistency.
Ensure that your team has a balanced mix of skills to handle all aspects of development.
:::tip Team structure when using
Available Dependencies
## Usage Examples
### Basic Configuration
```yaml
Code:
type: deepset_cloud_custom_nodes.code.code_component.Code
init_parameters:
code: |
from haystack import component
@component
class Code:
@component.output_types(result=str)
def run(self, text: str) -> dict:
return {"result": text.upper()}
```
### Masking Sensitive Information
This is a query pipeline that masks sensitive information, like emails or phone numbers, before sending the data to an LLM. `pii_redactor` is a `Code` component with custom Python code that masks the sensitive information.
```yaml
# haystack-pipeline
components:
pii_redactor:
type: deepset_cloud_custom_nodes.code.code_component.Code
init_parameters:
code: |
from haystack import component
@component
class Code:
"""Masks personally identifiable information before LLM processing."""
@component.output_types(redacted_text=str, pii_found=bool)
def run(self, text: str) -> dict:
redacted = text
pii_found = False
# Email addresses
email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
if re.search(email_pattern, redacted):
pii_found = True
redacted = re.sub(email_pattern, '[EMAIL]', redacted)
# Phone numbers (various formats)
phone_pattern = r'\b(\+?1?[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b'
if re.search(phone_pattern, redacted):
pii_found = True
redacted = re.sub(phone_pattern, '[PHONE]', redacted)
return {"redacted_text": redacted, "pii_found": pii_found}
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |
Help the user with their request: {{ query }}
llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
model: gpt-4o-mini
api_key:
type: env_var
env_vars:
- OPENAI_API_KEY
strict: false
answer_builder:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters: {}
connections:
- sender: pii_redactor.redacted_text
receiver: prompt_builder.query
- sender: prompt_builder.prompt
receiver: llm.prompt
- sender: llm.replies
receiver: answer_builder.replies
inputs:
query:
- answer_builder.query
- pii_redactor.text
outputs:
answers: answer_builder.answers
max_runs_per_component: 100
metadata: {}
```
This is what the component looks like in the Builder:
/.py`: This is where your component code is stored. The base path `./dc-custom-component-template/src/dc_custom_component/` must remain unchanged, but you can create additional subfolders to organize your custom components within the `dc_custom_component` folder.
You can create a separate folder for each component, with its own `.py` file, or group multiple components in a single folder and manage them through one `.py` file. Whatever works best for you.
The folder name appears as the group's name in the components library in Pipeline Builder, where you can find your custom component. For example, if you place your custom component under `./dc-custom-component-template/src/dc_custom_component/components/rankers/custom_ranker.py`, it will show up in Pipeline Builder in the Rankers group.
- `./dc-custom-component-template/src/dc_custom_component/__about__.py`: This is the component version. Make sure to update it here every time you upload a new version. The version is set for all components in the package.
- `./dc-custom-component-template/pyproject.toml`: If your component has any dependencies, you can add them in this file in the `dependencies` section.
### Versioning
Here's how pipelines use your custom component versions:
- New pipelines can only use the latest version of your components.
- Running pipelines use the component version that was the latest at the time when then were deployed. To use a new version of a custom component, undeploy the pipelines using the component and deploy them again.
To compare different versions of a component, upload a package with both versions included in the `.py` file, similar to how you would upload two components at once. Ensure each version has a unique name. After that, create multiple pipelines, each using a different component version, and compare their performance.
### Handling Non-JSON Serializable Types
If your component uses an input type that's not JSON-serializable, you must implement its serialization methods: `to_dict()` and `from_dict()`. These methods define how to convert the type into a dictionary, which is needed for storage or transmission.
One example is the `Secret` type. This type enhances security by preventing you from directly passing sensitive information, like API keys, into initialization parameters. Since it's not a JSON-serializable type, you must implement the `to_dict()` and `from_dict()` methods to convert it into a JSON-serializable string for proper handling.
For an example of a component that uses the `Secret` type, see the Examples section below.
### Using Components In a Pipeline
Once your component is in
{{ doc.content|truncate(25000) }}
{% endif %}
{% endfor %}
variables:
type: haystack.components.builders.prompt_builder.PromptBuilder
converter:
init_parameters:
extraction_kwargs: {}
store_full_path: false
type: haystack.components.converters.html.HTMLToDocument
fetcher:
init_parameters:
raise_on_failure: false
retry_attempts: 2
timeout: 3
user_agents:
- haystack/LinkContentFetcher/2.11.1
type: haystack.components.fetchers.link_content.LinkContentFetcher
search:
init_parameters:
api_key:
env_vars:
- SERPERDEV_API_KEY
strict: false
type: env_var
search_params: {}
top_k: 10
type: haystack.components.websearch.serper_dev.SerperDevWebSearch
AnthropicGenerator:
type: haystack_integrations.components.generators.anthropic.generator.AnthropicGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- ANTHROPIC_API_KEY
strict: false
model: claude-sonnet-4-20250514
streaming_callback:
system_prompt:
generation_kwargs:
timeout:
max_retries:
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters:
pattern:
reference_pattern:
last_message_only: false
return_only_referenced_documents: true
connections:
- receiver: fetcher.urls
sender: search.links
- receiver: converter.sources
sender: fetcher.streams
- receiver: builder.docs
sender: converter.documents
- sender: builder.prompt
receiver: AnthropicGenerator.prompt
- sender: AnthropicGenerator.replies
receiver: AnswerBuilder.replies
max_runs_per_component: 100
metadata: {}
inputs:
query:
- search.query
- AnswerBuilder.query
outputs:
answers: AnswerBuilder.answers
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `urls` | List[str] | A list of URLs to fetch content from. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `streams` | List[ByteStream] | `ByteStream` objects representing the extracted content. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `raise_on_failure` | bool | True | 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` | Optional[List[str]] | None | [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` | int | 2 | The number of times to retry fetching the URL's content. |
| `timeout` | int | 3 | Timeout in seconds for the request. |
| `http2` | bool | False | Whether to enable HTTP/2 support for requests. Requires the `h2` package to be installed (via `pip install httpx[http2]`). |
| `client_kwargs` | Optional[Dict] | None | Additional keyword arguments to pass to the httpx client. If `None`, default values are used. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `urls` | List[str] | A list of URLs to fetch content from. |
---
## MSGToDocument
Convert Microsoft Outlook MSG files into documents your pipelines can query. The component extracts email metadata and body content, and returns file attachments as separate ByteStream objects.
`MSGToDocument` extracts email metadata (such as sender, recipients, CC, BCC, subject) and body content from MSG files and converts them into structured documents. It also extracts file attachments as `ByteStream` objects.
## Key Features
- Extracts email metadata (sender, recipients, CC, BCC, subject) and body content.
- Outputs attachments as separate `ByteStream` objects for further processing.
- Optional metadata attachment to resulting documents.
## Configuration
1. Drag the `MSGToDocument` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Set **Store Full Path** to control whether the full file path or just the file name is stored in document metadata.
## Connections
`MSGToDocument` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs converted `Document` objects and any file attachments as `ByteStream` objects.
It typically connects with:
- `FileTypeRouter`: receives MSG files routed by MIME type.
- `DocumentJoiner`: sends converted documents to join with output from other converters before further processing.
## Source Code
To check this component's source code, open [`msg.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/msg.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
MSGToDocument:
type: haystack.components.converters.msg.MSGToDocument
init_parameters:
store_full_path: false
```
### Using the Component in an Index
This index converts MSG files to documents and sends them to `DocumentJoiner` that combines them with documents coming from other converters. The joined documents are then sent to `DocumentSplitter`.
```yaml
# haystack-pipeline
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/text
- text/markdown
- application/vnd.ms-outlook
additional_mimetypes:
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
MarkdownToDocument:
type: haystack.components.converters.markdown.MarkdownToDocument
init_parameters:
table_to_single_line: false
progress_bar: true
store_full_path: false
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: aga-index
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
MSGToDocument:
type: haystack.components.converters.msg.MSGToDocument
init_parameters:
store_full_path: false
connections:
- sender: FileTypeRouter.text/text
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.text/markdown
receiver: MarkdownToDocument.sources
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: MarkdownToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DocumentWriter.documents
- sender: FileTypeRouter.application/vnd.ms-outlook
receiver: MSGToDocument.sources
- sender: MSGToDocument.documents
receiver: DocumentJoiner.documents
max_runs_per_component: 100
metadata: {}
inputs:
files:
- FileTypeRouter.sources
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | Converted documents. |
| `attachments` | List[ByteStream] | Created ByteStream objects from file attachments. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `store_full_path` | bool | False | If `True`, the full path of the file is stored in the metadata of the document. If False, only the file name is stored. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
---
## MarkdownToDocument
Convert Markdown files into text documents your pipeline can query. Use this component in indexes to write Markdown file contents into a document store.
## Key Features
- Converts Markdown files to plain-text documents for indexing and search.
- Optional table-to-single-line conversion to simplify table content.
- Optional metadata attachment to resulting documents.
## Configuration
1. Drag the `MarkdownToDocument` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Enable **Table to Single Line** if you want table contents converted to a single line.
- Set **Store Full Path** to control whether the full file path or just the file name is stored in document metadata.
- Toggle **Progress Bar** to show or hide a progress bar during conversion.
## Connections
`MarkdownToDocument` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of `Document` objects.
It typically connects with:
- `FileTypeRouter`: receives Markdown files routed by MIME type.
- `DocumentJoiner`: sends converted documents to join with output from other converters before further processing.
## Source Code
To check this component's source code, open [`markdown.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/markdown.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
MarkdownToDocument:
type: haystack.components.converters.markdown.MarkdownToDocument
init_parameters:
table_to_single_line: false
progress_bar: true
store_full_path: false
```
### Using the Component in an Index
In this index, `MarkdownToDocument` receives Markdown files from `FileTypeRouter` and sends them to `DocumentJoiner`.
```yaml
# haystack-pipeline
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/text
- text/markdown
- application/json
additional_mimetypes:
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
MarkdownToDocument:
type: haystack.components.converters.markdown.MarkdownToDocument
init_parameters:
table_to_single_line: false
progress_bar: true
store_full_path: false
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: aga-index
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
JSONConverter:
type: haystack.components.converters.json.JSONConverter
init_parameters:
jq_schema:
content_key:
extra_meta_fields:
store_full_path: false
connections:
- sender: FileTypeRouter.text/text
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.text/markdown
receiver: MarkdownToDocument.sources
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: MarkdownToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DocumentWriter.documents
- sender: FileTypeRouter.application/json
receiver: JSONConverter.sources
- sender: JSONConverter.documents
receiver: DocumentJoiner.documents
max_runs_per_component: 100
metadata: {}
inputs:
files:
- FileTypeRouter.sources
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | Converted documents. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `table_to_single_line` | bool | False | If `True` converts table contents into a single line. |
| `progress_bar` | bool | True | If `True` shows a progress bar when running. |
| `store_full_path` | bool | False | If `True`, the full path of the file is stored in the metadata of the document. If False, only the file name is stored. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
---
## MultiFileConverter
Convert multiple file types to documents in a single operation. The component automatically detects each file's type and applies the appropriate converter.
`MultiFileConverter` is a SuperComponent that combines `FileTypeRouter`, nine converters, and `DocumentJoiner` into a single component. It automatically detects file types and applies the appropriate converter for each file, so you don't need to manually connect individual converter components.
## Key Features
- Automatically detects file types and routes each file to the appropriate converter.
- Supports nine file types: CSV, DOCX, HTML, JSON, Markdown, plain text, PDF, PPTX, and XLSX.
- Returns a list of failed files separately so you can handle conversion errors.
- Simplifies pipeline design by replacing multiple converter components with one.
## Configuration
1. Drag the `MultiFileConverter` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Set the **Encoding** for text-based files. The default is UTF-8.
- Set the **JSON Content Key** to specify which key to use as document content when converting JSON files. The default is `content`.
## Connections
`MultiFileConverter` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of successfully converted `Document` objects and a list of file paths that failed to convert.
It typically connects with:
- `FilesInput`: receives files to convert.
- `DocumentSplitter` or document embedding components: sends converted documents for further processing.
## Source Code
To check this component's source code, open [`multi_file_converter.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/multi_file_converter.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
MultiFileConverter:
type: haystack.components.converters.multi_file_converter.MultiFileConverter
init_parameters:
encoding: utf-8
json_content_key: content
```
### Using the Component in an Index
In this index, `MultiFileConverter` receives files, converts them, and then sends them to `DocumentSplitter`.
```yaml
# haystack-pipeline
components:
MultiFileConverter:
type: haystack.components.converters.multi_file_converter.MultiFileConverter
init_parameters:
encoding: utf-8
json_content_key: content
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
skip_empty_documents: true
DeepsetNvidiaDocumentEmbedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
model: intfloat/multilingual-e5-base
prefix: ''
suffix: ''
batch_size: 32
meta_fields_to_embed:
embedding_separator: \n
truncate:
normalize_embeddings: true
timeout:
backend_kwargs:
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
connections:
- sender: MultiFileConverter.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DeepsetNvidiaDocumentEmbedder.documents
- sender: DeepsetNvidiaDocumentEmbedder.documents
receiver: DocumentWriter.documents
max_runs_per_component: 100
metadata: {}
inputs:
files:
- MultiFileConverter.sources
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | A list of file paths or byte streams to convert. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | A list of converted documents. Only included if at least one file is successfully converted. |
| `failed` | List[str] | A list of files that failed to convert. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `encoding` | str | utf-8 | The encoding to use when reading text files. |
| `json_content_key` | str | content | The key to extract content from JSON files. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | A list of file paths or byte streams to convert. |
---
## PDFMinerToDocument
Convert PDF files to documents using PDFMiner's extraction parameters. Use this component when you need fine-grained control over layout analysis and text extraction from PDFs.
`PDFMinerToDocument` uses `pdfminer`-compatible converters to extract text from PDF files. It exposes detailed layout analysis parameters for fine-tuned control over text extraction. For details, see the [PDFMiner documentation](https://pdfminersix.readthedocs.io/en/latest/).
## Key Features
- Fine-grained control over PDF text extraction with layout analysis parameters.
- Configurable margins for character, word, and line grouping.
- Optional vertical text detection.
- Optional metadata attachment to resulting documents.
## Configuration
1. Drag the `PDFMinerToDocument` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- This component works with default settings for most PDFs. Adjust the settings below if you need to tune extraction for specific PDF layouts.
- Set **Line Overlap** to adjust how characters are grouped onto the same line (default: 0.5).
- Set **Char Margin** to control the distance threshold for grouping characters on the same line (default: 2).
- Set **Word Margin** to control when an intermediate space is inserted between characters (default: 0.1).
- Set **Line Margin** to control the distance threshold for grouping lines into paragraphs (default: 0.5).
- Set **Boxes Flow** to control whether horizontal or vertical position takes precedence when ordering text boxes (default: 0.5, range: -1.0 to 1.0).
- Enable **Detect Vertical** to include vertical text in layout analysis.
- Enable **All Texts** to perform layout analysis on text in figures.
- Set **Store Full Path** to control whether the full file path or just the file name is stored in document metadata.
## Connections
`PDFMinerToDocument` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of `Document` objects.
It typically connects with:
- `FileTypeRouter`: receives PDF files routed by MIME type.
- `DocumentSplitter` or other preprocessors: sends converted documents for further processing.
## Source Code
To check this component's source code, open [`pdfminer.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pdfminer.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
PDFMinerToDocument:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
```
### Using the Component in an Index
This is a simple index you can use if you only have PDF files to index.
```yaml
# haystack-pipeline
components:
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
skip_empty_documents: true
DeepsetNvidiaDocumentEmbedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
model: intfloat/multilingual-e5-base
prefix: ''
suffix: ''
batch_size: 32
meta_fields_to_embed:
embedding_separator: \n
truncate:
normalize_embeddings: true
timeout:
backend_kwargs:
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
PDFMinerToDocument:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
connections:
- sender: DocumentSplitter.documents
receiver: DeepsetNvidiaDocumentEmbedder.documents
- sender: DeepsetNvidiaDocumentEmbedder.documents
receiver: DocumentWriter.documents
- sender: PDFMinerToDocument.documents
receiver: DocumentSplitter.documents
max_runs_per_component: 100
metadata: {}
inputs:
files:
- PDFMinerToDocument.sources
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of PDF file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | Converted documents. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `line_overlap` | float | 0.5 | 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` | float | 2 | 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` | float | 0.1 | 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` | float | 0.5 | 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` | Optional[float] | 0.5 | 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' disables advanced layout analysis, and text boxes are ordered based on the position of their bottom left corner. |
| `detect_vertical` | bool | True | Determines whether vertical text should be considered during layout analysis. |
| `all_texts` | bool | False | If layout analysis should be performed on text in figures. |
| `store_full_path` | bool | False | If `True`, the full path of the file is stored in the metadata of the document. If False, only the file name is stored. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of PDF file paths or ByteStream objects. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
---
## PDFToImageContent
Convert PDF files to `ImageContent` objects for multimodal AI processing. Each converted page becomes a separate `ImageContent` object containing base64-encoded image data and associated metadata.
`PDFToImageContent` reads PDF files and converts specified pages into images, creating `ImageContent` objects containing base64-encoded image data and metadata. Each converted page becomes a separate `ImageContent` object with metadata indicating the source file and page number.
## Key Features
- Converts PDF pages to base64-encoded `ImageContent` objects for multimodal AI models.
- Supports specific page selection and page ranges.
- Optional image resizing to reduce file size while maintaining aspect ratio.
- Configurable detail level for optimization with OpenAI vision models.
## Configuration
1. Drag the `PDFToImageContent` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Set the **Page Range** to specify which pages to convert. Accepts page numbers and ranges, for example `['1-3', '5', '8']`. If not set, all pages are converted.
- Set the **Detail** level for images (`auto`, `high`, or `low`). This is passed to the created `ImageContent` objects and is only supported by OpenAI.
- Set the **Size** to resize images to the specified dimensions (width, height) while maintaining aspect ratio. This reduces file size, memory usage, and processing time.
## Connections
`PDFToImageContent` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of `ImageContent` objects, one per converted page.
It typically connects with:
- `FilesInput` or `FileTypeRouter`: receives PDF files.
- `ChatPromptBuilder`: sends extracted page images to include in multimodal prompts.
## Source Code
To check this component's source code, open [`pdf_to_image.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/image/pdf_to_image.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
PDFToImageContent:
type: haystack.components.converters.image.PDFToImageContent
init_parameters:
detail: auto
page_range:
- 1-3
```
### Using the Component in a Pipeline
This example shows a query pipeline that uses `PDFToImageContent` to convert uploaded PDF pages to images for multimodal AI processing. The pipeline extracts specified pages from PDF documents, converts them to `ImageContent` objects, and sends them to a vision-enabled chat model for analysis.
```yaml
# haystack-pipeline
components:
PDFToImageContent:
type: haystack.components.converters.image.PDFToImageContent
init_parameters:
detail: auto
size:
page_range:
- "1-3"
ChatPromptBuilder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template:
- role: system
content: >-
You are an AI assistant that analyzes PDF documents. Examine the
provided PDF pages and answer questions about their content,
layout, text, images, and any other visible elements.
- role: user
content: "{{ question }}"
images: "{{ images }}"
required_variables:
- question
- images
OpenAIChatGenerator:
type: haystack.components.generators.chat.openai.OpenAIChatGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- OPENAI_API_KEY
strict: true
model: gpt-4o
generation_kwargs:
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: "{{ replies[0].text }}"
output_type: str
DeepsetAnswerBuilder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern:
connections:
- sender: PDFToImageContent.image_contents
receiver: ChatPromptBuilder.images
- sender: ChatPromptBuilder.prompt
receiver: OpenAIChatGenerator.messages
- sender: OpenAIChatGenerator.replies
receiver: OutputAdapter.replies
- sender: OutputAdapter.output
receiver: DeepsetAnswerBuilder.replies
inputs:
query:
- ChatPromptBuilder.question
files:
- PDFToImageContent.sources
outputs:
answers: DeepsetAnswerBuilder.answers
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of PDF file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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[Literal["auto", "high", "low"]] | None | Optional detail level of the image (only supported by OpenAI). This is passed to the created `ImageContent` objects. If not provided, the detail level is the one set in the constructor. |
| `size` | Optional[Tuple[int, int]] | None | If provided, resizes the image to fit within the specified dimensions (width, height) while maintaining aspect ratio. If not provided, the size value is the one set in the constructor. |
| `page_range` | Optional[List[Union[str, int]]] | None | List of page numbers and page ranges to convert to images. If not provided, the page range is the one set in the pipeline configuration. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `image_contents` | List[ImageContent] | A list of `ImageContent` objects created from the PDF pages. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `detail` | Optional[Literal["auto", "high", "low"]] | None | Optional detail level of the image (only supported by OpenAI). Possible values: "auto", "high", or "low". This is passed to the created `ImageContent` objects. |
| `size` | Optional[Tuple[int, int]] | None | 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. |
| `page_range` | Optional[List[Union[str, int]]] | None | List of page numbers and page ranges to convert to images. Page numbers start at 1. If `None`, all pages in the PDF are converted. Also accepts printable range strings, for example: ['1-3', '5', '8', '10-12']. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of PDF file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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[Literal["auto", "high", "low"]] | None | Optional detail level of the image (only supported by OpenAI). This is passed to the created `ImageContent` objects. If not provided, the detail level is the one set in the constructor. |
| `size` | Optional[Tuple[int, int]] | None | If provided, resizes the image to fit within the specified dimensions (width, height) while maintaining aspect ratio. If not provided, the size value is the one set in the constructor. |
| `page_range` | Optional[List[Union[str, int]]] | None | List of page numbers and page ranges to convert to images. Page numbers start at 1. If `None`, all pages in the PDF are converted. Pages outside the valid range are skipped with a warning. Also accepts printable range strings, for example: ['1-3', '5', '8', '10-12']. |
---
## PPTXToDocument
Convert PPTX files to documents your pipeline can query.
## Key Features
- Converts PowerPoint presentation files to text documents for indexing.
- Configurable link format output: plain text, Markdown, or no links.
- Optional metadata attachment to resulting documents.
## Configuration
1. Drag the `PPTXToDocument` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Set the **Link Format** to control how hyperlinks appear in the extracted text: `none` (default, text only), `markdown` (for `[text](url)`), or `plain` (for `text (url)`).
- Set **Store Full Path** to control whether the full file path or just the file name is stored in document metadata.
## Connections
`PPTXToDocument` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of `Document` objects.
It typically connects with:
- `FileTypeRouter`: receives PPTX files routed by MIME type.
- `DocumentJoiner`: sends converted documents to join with output from other converters before further processing.
## Source Code
To check this component's source code, open [`pptx.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pptx.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
PPTXToDocument:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters:
store_full_path: false
```
### Using the Component in an Index
In this index, `PPTXToDocument` receives PPTX files from `FileTypeRouter` and sends them to `DocumentJoiner`.
```yaml
# haystack-pipeline
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- application/vnd.openxmlformats-officedocument.presentationml.presentation
additional_mimetypes:
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
PyPDFToDocument:
type: haystack.components.converters.pypdf.PyPDFToDocument
init_parameters:
store_full_path: false
PPTXToDocument:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters:
store_full_path: false
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: presentation-index
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
connections:
- sender: FileTypeRouter.text/plain
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.application/pdf
receiver: PyPDFToDocument.sources
- sender: FileTypeRouter.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: PPTXToDocument.sources
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: PyPDFToDocument.documents
receiver: DocumentJoiner.documents
- sender: PPTXToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DocumentWriter.documents
max_runs_per_component: 100
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | Converted documents. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `store_full_path` | bool | False | If `True`, the full path of the file is stored in the metadata of the document. If `False`, only the file name is stored. |
| `link_format` | Literal['markdown', 'plain', 'none'] | none | The format for link output. Options: `"markdown"` for `[text](url)`, `"plain"` for `text (url)`, `"none"` to extract only the text and ignore link addresses. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
---
## PyPDFToDocument
Convert PDF files to documents your pipeline can query. This component uses the PyPDF library to extract text from PDFs and supports both plain and layout-aware extraction modes.
`PyPDFToDocument` uses the PyPDF library to extract text from PDF files. It supports two extraction modes: plain (default) and layout (experimental, adheres to the rendered layout of the PDF).
## Key Features
- Two extraction modes: plain text and layout-aware (experimental).
- Configurable orientation support for rotated pages in plain mode.
- Fine-grained layout mode parameters for vertical spacing and font handling.
- Optional metadata attachment to resulting documents.
## Configuration
1. Drag the `PyPDFToDocument` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. Configure the component settings:
- Set the **Extraction Mode** to choose between `plain` (default) or `layout` (experimental layout-aware extraction).
- **Plain mode**: set `plain_mode_orientations` to specify which page orientations to look for, and `plain_mode_space_width` to control default space width.
- **Layout mode**: set `layout_mode_space_vertically`, `layout_mode_scale_weight`, `layout_mode_strip_rotated`, and `layout_mode_font_height_weight` to tune layout extraction.
- Set **Store Full Path** to control whether the full file path or just the file name is stored in document metadata.
## Connections
`PyPDFToDocument` accepts a list of file paths or `ByteStream` objects through its `sources` input. It outputs a list of `Document` objects.
It typically connects with:
- `FileTypeRouter`: receives PDF files routed by MIME type.
- `DocumentJoiner`: sends converted documents to join with output from other converters before further processing.
## Source Code
To check this component's source code, open [`pypdf.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/pypdf.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
PyPDFToDocument:
type: haystack.components.converters.pypdf.PyPDFToDocument
init_parameters:
extraction_mode: PyPDFExtractionMode.PLAIN
plain_mode_orientations:
- 0
- 90
- 180
- 270
plain_mode_space_width: 200.0
layout_mode_space_vertically: true
layout_mode_scale_weight: 1.25
layout_mode_strip_rotated: true
layout_mode_font_height_weight: 1.0
store_full_path: false
```
### Using the Component in an Index
In this index, `PyPDFToDocument` receives PDF files from `FileTypeRouter` and sends them to `DocumentJoiner`.
```yaml
# haystack-pipeline
components:
FileTypeRouter:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
TextFileToDocument:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
PyPDFToDocument:
type: haystack.components.converters.pypdf.PyPDFToDocument
init_parameters:
extraction_mode: PyPDFExtractionMode.PLAIN
plain_mode_orientations:
- 0
- 90
- 180
- 270
plain_mode_space_width: 200.0
layout_mode_space_vertically: true
layout_mode_scale_weight: 1.25
layout_mode_strip_rotated: true
layout_mode_font_height_weight: 1.0
store_full_path: false
MarkdownToDocument:
type: haystack.components.converters.markdown.MarkdownToDocument
init_parameters:
table_to_single_line: false
progress_bar: true
store_full_path: false
DocumentJoiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: pdf-index
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
connections:
- sender: FileTypeRouter.text/plain
receiver: TextFileToDocument.sources
- sender: FileTypeRouter.application/pdf
receiver: PyPDFToDocument.sources
- sender: FileTypeRouter.text/markdown
receiver: MarkdownToDocument.sources
- sender: TextFileToDocument.documents
receiver: DocumentJoiner.documents
- sender: PyPDFToDocument.documents
receiver: DocumentJoiner.documents
- sender: MarkdownToDocument.documents
receiver: DocumentJoiner.documents
- sender: DocumentJoiner.documents
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DocumentWriter.documents
max_runs_per_component: 100
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `documents` | List[Document] | A list of converted documents. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `extraction_mode` | Union[str, PyPDFExtractionMode] | PyPDFExtractionMode.PLAIN | 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 | (0, 90, 180, 270) | 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` | float | 200.0 | Forces default space width if not extracted from font. Ignored if `extraction_mode` is `PyPDFExtractionMode.LAYOUT`. |
| `layout_mode_space_vertically` | bool | True | Whether to include blank lines inferred from y distance + font height. Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. |
| `layout_mode_scale_weight` | float | 1.25 | Multiplier for string length when calculating weighted average character width. Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. |
| `layout_mode_strip_rotated` | bool | True | 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` | float | 1.0 | Multiplier for font height when calculating blank line height. Ignored if `extraction_mode` is `PyPDFExtractionMode.PLAIN`. |
| `store_full_path` | bool | False | If True, the full path of the file is stored in the metadata of the document. If False, only the file name is stored. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `sources` | List[Union[str, Path, ByteStream]] | | List of file paths or ByteStream objects to convert. |
| `meta` | Optional[Union[Dict[str, Any], List[Dict[str, Any]]]] | None | 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. |
---
## RemoteWhisperTranscriber
Transcribe audio files using the OpenAI Whisper API.
`RemoteWhisperTranscriber` uses OpenAI's Whisper API to transcribe audio files and return them as documents for storage in a document store. It's typically used in indexes. For supported audio formats, languages, and other parameters, see the [Whisper API documentation](https://platform.openai.com/docs/guides/speech-to-text).
## Key Features
- Transcribes audio files to text documents using OpenAI's Whisper API.
- Supports multiple audio formats (see Whisper API documentation for the full list).
- Returns one document per audio file with the transcribed text as content.
## Configuration
You need an OpenAI API key to use this component. Connect deepset AI Platform to OpenAI first:
` captures the URL from the tag.
4. Go to the **Advanced** tab to configure additional settings:
- Set `return_empty_on_no_match` to control what happens when the pattern finds no match.
## Connections
`RegexTextExtractor` accepts either a string or a list of `ChatMessage` objects as input. Connect it to the `Input` component or to any component that produces `string` or `ChatMessage` output, such as `LLM`.
Connect its `captured_text` output to any component that consumes a text string.
## Source Code
To check this component's source code, open [`regex_text_extractor.py`](https://github.com/deepset-ai/haystack/blob/main/haystack/components/extractors/regex_text_extractor.py) in the [Haystack repository](https://github.com/deepset-ai/haystack).
## Usage Examples
### Basic Configuration
```yaml
RegexTextExtractor:
type: haystack.components.extractors.regex_text_extractor.RegexTextExtractor
init_parameters:
regex_pattern:
return_empty_on_no_match: true
```
### In a Pipeline
This query pipeline uses an `LLM` to analyze text and produce structured output, then uses `RegexTextExtractor` to extract a specific issue URL from the response:
```yaml
# haystack-pipeline
components:
RegexTextExtractor:
type: haystack.components.extractors.regex_text_extractor.RegexTextExtractor
init_parameters:
regex_pattern: ''
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters:
pattern:
reference_pattern:
LLM:
type: haystack.components.generators.chat.llm.LLM
init_parameters:
chat_generator:
init_parameters:
model: gpt-5.5
type: haystack.components.generators.chat.openai_responses.OpenAIResponsesChatGenerator
system_prompt: ""
user_prompt: >-
{% message role="user" %}
You are a helpful assistant that identifies issues in text.
When you find an issue, format your response as:
Description of
the issue
Analyze the following text and identify any issues:
{{ query }}
{% endmessage %}
required_variables: "*"
streaming_callback:
connections:
- sender: RegexTextExtractor.captured_text
receiver: AnswerBuilder.replies
- sender: LLM.last_message
receiver: RegexTextExtractor.text_or_messages
inputs:
query:
- AnswerBuilder.query
- LLM.query
outputs:
answers: AnswerBuilder.answers
max_runs_per_component: 100
metadata: {}
```
In this example:
1. `LLM` generates a response containing the structured output.
2. `RegexTextExtractor` uses the pattern `` to extract the URL from the response. The capture group `([^"]+)` matches any characters except quotes inside the `url` attribute.
3. `AnswerBuilder` formats the extracted URL as the final answer.
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `text_or_messages` | Union[str, List[ChatMessage]] | Either a string or a list of ChatMessage objects to search through. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `captured_text` | str | The matched text if a match is found. Empty string if no match is found and `return_empty_on_no_match=False`. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `regex_pattern` | str | | The regular expression pattern used to extract text. The pattern should include a capture group to extract the desired text. Example: `''` captures the URL from the tag. |
| `return_empty_on_no_match` | bool | True | If True, returns an empty dictionary when no match is found. If False, returns `{"captured_text": ""}`. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `text_or_messages` | Union[str, List[ChatMessage]] | Either a string or a list of ChatMessage objects to search through. |
---
## Extract Overview
# Extract Group
Use components in this group to pull structured information out of text. Use them when you want to enrich documents with metadata (for example language, entities, or custom fields) or extract specific content that you can store, filter on, or feed into downstream steps.
This subgroup is useful both during indexing and at query time. Extracted fields can improve retrieval and ranking, support metadata filters, and make your pipeline outputs easier to evaluate and debug.
## Available Components
{useCurrentSidebarCategory().items.map((item) => (
{'href' in item ?
token:
type: env_var
env_vars:
- HF_API_TOKEN
- HF_TOKEN
strict: false
generation_kwargs:
max_new_tokens: 500
temperature: 0.7
```
This query pipeline uses `HuggingFaceAPIGenerator` with a paid Inference Endpoint:
```yaml
# haystack-pipeline
components:
bm25_retriever:
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: 'default'
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 10
fuzziness: 0
PromptBuilder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |
Given the following information, answer the question.
Context:
{% for document in documents %}
{{ document.content }}
{% endfor %}
Question: {{ query }}
required_variables:
variables:
HuggingFaceAPIGenerator:
type: haystack.components.generators.hugging_face_api.HuggingFaceAPIGenerator
init_parameters:
api_type: inference_endpoints
api_params:
url:
token:
type: env_var
env_vars:
- HF_API_TOKEN
- HF_TOKEN
strict: false
generation_kwargs:
max_new_tokens: 500
temperature: 0.7
stop_words:
streaming_callback:
AnswerBuilder:
type: haystack.components.builders.answer_builder.AnswerBuilder
init_parameters:
pattern:
reference_pattern:
connections:
- sender: bm25_retriever.documents
receiver: PromptBuilder.documents
- sender: PromptBuilder.prompt
receiver: HuggingFaceAPIGenerator.prompt
- sender: HuggingFaceAPIGenerator.replies
receiver: AnswerBuilder.replies
- sender: bm25_retriever.documents
receiver: AnswerBuilder.documents
inputs:
query:
- bm25_retriever.query
- PromptBuilder.query
- AnswerBuilder.query
outputs:
answers: AnswerBuilder.answers
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :----------------- | :--------------------------- | :------ | :----------------------------------------------------------------------- |
| `prompt` | str | | A string representing the prompt. |
| `streaming_callback` | Optional[StreamingCallbackT] | None | A callback function that is called when a new token is received from the stream. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Additional keyword arguments for text generation. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--------------------- | :---------------------------------------------------------------------------------------- |
| `replies` | List[str] | A list of strings representing the generated replies. |
| `meta` | List[Dict[str, Any]] | A list of dictionaries with metadata associated with each reply, such as token count and finish reason. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :----------------- | :---------------------------- | :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_type` | Union[HFGenerationAPIType, str] | | The type of Hugging Face API to use. Options: `text_generation_inference` (self-hosted TGI), `inference_endpoints` (paid endpoints), `serverless_inference_api` (free API, may not work for generative models). |
| `api_params` | Dict[str, str] | | A dictionary with: `model` (required for `serverless_inference_api`), `url` (required for `inference_endpoints` or `text_generation_inference`), and other parameters like `timeout`, `headers`, `provider`. |
| `token` | Optional[Secret] | Secret.from_env_var(['HF_API_TOKEN', 'HF_TOKEN'], strict=False) | 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` | Optional[Dict[str, Any]] | None | A dictionary with keyword arguments to customize text generation: `max_new_tokens`, `temperature`, `top_k`, `top_p`. See [Hugging Face documentation](https://huggingface.co/docs/huggingface_hub/en/package_reference/inference_client#huggingface_hub.InferenceClient.text_generation). |
| `stop_words` | Optional[List[str]] | None | An optional list of strings representing the stop words. |
| `streaming_callback` | Optional[StreamingCallbackT] | None | An optional callable for handling streaming responses. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :----------------- | :--------------------------- | :------ | :----------------------------------------------------------------------- |
| `prompt` | str | | A string representing the prompt. |
| `streaming_callback` | Optional[StreamingCallbackT] | None | A callback function that is called when a new token is received from the stream. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Additional keyword arguments for text generation. |
## Related Information
- [Use Hugging Face Models](/docs/how-to-guides/designing-your-pipeline/use-hosted-models-and-services/use-hugging-face-models.mdx)
- [HuggingFaceAPIChatGenerator](/docs/reference/pipeline-components/integrations/hugging-face/HuggingFaceAPIChatGenerator.mdx)
---
## HuggingFaceAPITextEmbedder
Embed strings using Hugging Face APIs.
:::info
This component embeds plain text. To embed a list of documents, use `HuggingFaceAPIDocumentEmbedder`.
:::
## Key Features
- Embeds text strings using Hugging Face APIs: free Serverless Inference API, paid Inference Endpoints, and self-hosted Text Embeddings Inference (TEI)
- Use in query pipelines to embed user queries for semantic search
- Returns a vector embedding of the input text
## Configuration
1. Drag the `HuggingFaceAPITextEmbedder` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Select the API type: `serverless_inference_api`, `inference_endpoints`, or `text_embeddings_inference`.
2. Enter the API parameters: for `serverless_inference_api`, enter the model ID; for `inference_endpoints` or `text_embeddings_inference`, enter the endpoint URL.
3. Enter your Hugging Face API token. Connect ` | str | The input text, routed to the connection matching the detected language. |
| `unmatched` | str | The input text, if its language is not in the configured list. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `languages` | Optional[List[str]] | `["en"]` | A list of ISO 639-1 language codes to route text to. Each code creates a named output connection. Text that doesn't match any configured language is routed to the `unmatched` output. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `text` | str | | The text string to detect language for and route. |
## Related Information
- [DocumentLanguageClassifier](/docs/reference/pipeline-components/integrations/langdetect/DocumentLanguageClassifier.mdx)
- [Pipeline Components](/docs/reference/pipeline-components/pipeline-components.mdx)
---
## LangfuseConnector
Trace your pipelines with Langfuse.
## Key Features
- Integrates [Langfuse](https://langfuse.com) tracing into your pipelines without connecting to other components.
- Automatically traces all pipeline operations when added to a pipeline.
- Captures detailed information about pipeline runs, including API calls, context data, and prompts.
- Supports custom invocation context to tag traces with run IDs, user IDs, or other metadata.
- Configurable trace visibility: public or private.
## Configuration
1. Drag the `LangfuseConnector` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Create secrets with your Langfuse keys. Use `LANGFUSE_SECRET_KEY` for the secret key and `LANGFUSE_PUBLIC_KEY` for the public key. For instructions, see [Create Secrets](/docs/how-to-guides/managing-access/add-secrets.mdx). Get your API keys from [Langfuse](https://langfuse.com).
2. Enter a name for the trace. This name identifies the tracing run in the Langfuse dashboard.
3. Set `public` to control whether the tracing data is publicly accessible.
4. Go to the **Advanced** tab to configure `host`, `httpx_client`, `span_handler`, and `langfuse_client_kwargs`.
For more information about setting up tracing with Langfuse, see [Trace with Langfuse](/docs/how-to-guides/productionizing-your-pipeline/trace-with-langfuse.mdx).
## Connections
`LangfuseConnector` doesn't connect to any other components. Add it to your pipeline and it automatically traces all pipeline operations. It accepts an optional `invocation_context` input at runtime for adding per-run metadata to traces.
It outputs `name`, `trace_url`, and `trace_id` values you can use to access tracing data.
## Source Code
To check this component's source code, open [`langfuse_connector.py`](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/langfuse/src/haystack_integrations/components/connectors/langfuse/langfuse_connector.py) in the [Haystack Core Integrations repository](https://github.com/deepset-ai/haystack-core-integrations).
## Usage Examples
### Basic Configuration
```yaml
LangfuseConnector:
type: haystack_integrations.components.connectors.langfuse.langfuse_connector.LangfuseConnector
init_parameters:
name: rag-chat
public: false
public_key:
type: env_var
env_vars:
- LANGFUSE_PUBLIC_KEY
strict: false
secret_key:
type: env_var
env_vars:
- LANGFUSE_SECRET_KEY
strict: false
```
For more information about setting up tracing with Langfuse, see [Trace with Langfuse](/docs/how-to-guides/productionizing-your-pipeline/trace-with-langfuse.mdx).
## Connections
`LangfuseConnector` doesn't connect to any other components. Add it to your pipeline and it automatically traces all pipeline operations when tracing is enabled.
It accepts an optional `invocation_context` dictionary as input to attach additional metadata to each trace. It outputs the trace `name`, `trace_url`, and `trace_id`.
This example shows a RAG pipeline with Langfuse tracing enabled. The `LangfuseConnector` is added to the pipeline but does not connect to other components — it automatically traces all pipeline operations.
```yaml
# haystack-pipeline
components:
retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.open_search_hybrid_retriever.OpenSearchHybridRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
fuzziness: 0
embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
required_variables: "*"
template: |-
You are a technical expert.
You answer questions truthfully based on provided documents.
Ignore typing errors in the question.
For each document check whether it is related to the question.
Only use documents that are related to the question to answer it.
Ignore documents that are not related to the question.
If the answer exists in several documents, summarize them.
Only answer based on the documents provided. Don't make things up.
Just output the structured, informative and precise answer and nothing else.
If the documents can't answer the question, say so.
Always use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document [3] .
Never name the documents, only enter a number in square brackets as a reference.
The reference must only refer to the number that comes in square brackets after the document.
Otherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.
These are the documents:
{%- if documents|length > 0 %}
{%- for document in documents %}
Document [{{ loop.index }}] :
Name of Source File: {{ document.meta.file_name }}
{{ document.content }}
{% endfor -%}
{%- else %}
No relevant documents found.
Respond with "Sorry, no matching documents were found, please adjust the filters or try a different question."
{% endif %}
Question: {{ question }}
Answer:
llm:
type: haystack.components.generators.openai.OpenAIGenerator
init_parameters:
api_key: {"type": "env_var", "env_vars": ["OPENAI_API_KEY"], "strict": false}
model: "gpt-5"
generation_kwargs:
reasoning_effort: minimal
verbosity: low
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
attachments_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
weights:
top_k:
sort_by_score: true
multi_file_converter:
type: haystack.core.super_component.super_component.SuperComponent
init_parameters:
input_mapping:
sources:
- file_classifier.sources
is_pipeline_async: false
output_mapping:
score_adder.output: documents
pipeline:
components:
file_classifier:
type: haystack.components.routers.file_type_router.FileTypeRouter
init_parameters:
mime_types:
- text/plain
- application/pdf
- text/markdown
- text/html
- application/vnd.openxmlformats-officedocument.wordprocessingml.document
- application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- text/csv
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
pdf_converter:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
markdown_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
html_converter:
type: haystack.components.converters.html.HTMLToDocument
init_parameters:
# A dictionary of keyword arguments to customize how you want to extract content from your HTML files.
# For the full list of available arguments, see
# the [Trafilatura documentation](https://trafilatura.readthedocs.io/en/latest/corefunctions.html#extract).
extraction_kwargs:
output_format: markdown # Extract text from HTML. You can also also choose "txt"
target_language: # You can define a language (using the ISO 639-1 format) to discard documents that don't match that language.
include_tables: true # If true, includes tables in the output
include_links: true # If true, keeps links along with their targets
docx_converter:
type: haystack.components.converters.docx.DOCXToDocument
init_parameters:
link_format: markdown
pptx_converter:
type: haystack.components.converters.pptx.PPTXToDocument
init_parameters: {}
xlsx_converter:
type: haystack.components.converters.xlsx.XLSXToDocument
init_parameters: {}
csv_converter:
type: haystack.components.converters.csv.CSVToDocument
init_parameters:
encoding: utf-8
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
score_adder:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: |
{%- set scored_documents = [] -%}
{%- for document in documents -%}
{%- set doc_dict = document.to_dict() -%}
{%- set _ = doc_dict.update({'score': 100.0}) -%}
{%- set scored_doc = document.from_dict(doc_dict) -%}
{%- set _ = scored_documents.append(scored_doc) -%}
{%- endfor -%}
{{ scored_documents }}
output_type: List[haystack.Document]
custom_filters:
unsafe: true
text_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
tabular_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
sort_by_score: false
connections:
- sender: file_classifier.text/plain
receiver: text_converter.sources
- sender: file_classifier.application/pdf
receiver: pdf_converter.sources
- sender: file_classifier.text/markdown
receiver: markdown_converter.sources
- sender: file_classifier.text/html
receiver: html_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.wordprocessingml.document
receiver: docx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.presentationml.presentation
receiver: pptx_converter.sources
- sender: file_classifier.application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
receiver: xlsx_converter.sources
- sender: file_classifier.text/csv
receiver: csv_converter.sources
- sender: text_joiner.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: text_joiner.documents
- sender: pdf_converter.documents
receiver: text_joiner.documents
- sender: markdown_converter.documents
receiver: text_joiner.documents
- sender: html_converter.documents
receiver: text_joiner.documents
- sender: pptx_converter.documents
receiver: text_joiner.documents
- sender: docx_converter.documents
receiver: text_joiner.documents
- sender: xlsx_converter.documents
receiver: tabular_joiner.documents
- sender: csv_converter.documents
receiver: tabular_joiner.documents
- sender: splitter.documents
receiver: tabular_joiner.documents
- sender: tabular_joiner.documents
receiver: score_adder.documents
LangfuseConnector:
type: haystack_integrations.components.connectors.langfuse.langfuse_connector.LangfuseConnector
init_parameters:
name: rag-chat
public: false
public_key:
type: env_var
env_vars:
- LANGFUSE_PUBLIC_KEY
strict: false
secret_key:
type: env_var
env_vars:
- LANGFUSE_SECRET_KEY
strict: false
httpx_client:
span_handler:
host:
langfuse_client_kwargs:
connections: # Defines how the components are connected
- sender: retriever.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: prompt_builder.prompt
receiver: llm.prompt
- sender: prompt_builder.prompt
receiver: answer_builder.prompt
- sender: llm.replies
receiver: answer_builder.replies
- sender: multi_file_converter.documents
receiver: attachments_joiner.documents
- sender: meta_field_grouping_ranker.documents
receiver: attachments_joiner.documents
- sender: attachments_joiner.documents
receiver: answer_builder.documents
- sender: attachments_joiner.documents
receiver: prompt_builder.documents
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "retriever.query"
- "ranker.query"
- "prompt_builder.question"
- "answer_builder.query"
filters: # These components will receive a potential query filter as input
- "retriever.filters_bm25"
- "retriever.filters_embedding"
files:
- multi_file_converter.sources
outputs: # Defines the output of your pipeline
documents: "attachments_joiner.documents" # The output of the pipeline is the retrieved documents
answers: "answer_builder.answers" # The output of the pipeline is the generated answers
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `invocation_context` | Optional[Dict[str, Any]] | A dictionary with additional context for the invocation. Useful for tagging traces with a run ID, user ID, or other metadata. These key-value pairs are visible in the Langfuse traces. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `name` | str | The name of the tracing component. |
| `trace_url` | str | The URL to the tracing data. |
| `trace_id` | str | The ID of the trace. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|----------------------|------------------------|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|name |str | |The name for the trace. This name will be used to identify the tracing run in the Langfuse dashboard. |
|public |bool |False |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 |Optional[Secret] |Secret.from_env_var('LANGFUSE_PUBLIC_KEY')|The Langfuse public key. Defaults to reading from LANGFUSE_PUBLIC_KEY environment variable. |
|secret_key |Optional[Secret] |Secret.from_env_var('LANGFUSE_SECRET_KEY')|The Langfuse secret key. Defaults to reading from LANGFUSE_SECRET_KEY environment variable. |
|httpx_client |Optional[httpx.Client] |None |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[SpanHandler] |None |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[Dict[str, Any]]|None |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. |
|host |Optional[str] |None | |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type |Default| Description |
|------------------|------------------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|invocation_context|Optional[Dict[str, Any]]|None |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.|
## Related Information
- [Trace with Langfuse](/docs/how-to-guides/productionizing-your-pipeline/trace-with-langfuse.mdx)
---
## LiteLLMChatGenerator
Generate chat responses using any of 100+ LLM providers through [LiteLLM's](https://docs.litellm.ai/) unified interface.
## Key Features
- Single component for access to OpenAI, Anthropic, Google, AWS Bedrock, Azure, Cohere, Mistral, Groq, and many more providers.
- Uses LiteLLM's unified API format — no need to switch components when changing providers.
- Model names use the LiteLLM format `provider/model-name` (for example, `anthropic/claude-sonnet-4-20250514`).
- Accepts and returns messages in `ChatMessage` format.
- Supports streaming responses through a configurable callback.
- Supports tool calling for agentic workflows.
## Configuration
1. Drag the `LiteLLMChatGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Set the `model` using LiteLLM format: `provider/model-name` (for example, `openai/gpt-4o` or `anthropic/claude-opus-4-5`). For the full list of supported providers and model names, see the [LiteLLM documentation](https://docs.litellm.ai/docs/providers).
2. Create a secret with the appropriate API key for your provider (for example, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`). For instructions, see [Create Secrets](/docs/how-to-guides/managing-access/add-secrets.mdx).
4. Go to the **Advanced** tab to configure `generation_kwargs`, `api_base_url`, and `tools`.
## Connections
`LiteLLMChatGenerator` receives a list of `ChatMessage` objects, typically from `PromptBuilder` or `ChatPromptBuilder`. It outputs a list of reply `ChatMessage` objects you can connect to `AnswerBuilder` or other downstream components.
## Source Code
To check this component's source code, open [`chat_generator.py`](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/litellm/src/haystack_integrations/components/generators/litellm/chat/chat_generator.py) in the [Haystack Core Integrations repository](https://github.com/deepset-ai/haystack-core-integrations).
## Usage Examples
### Basic Configuration
```yaml
LiteLLMChatGenerator:
type: haystack_integrations.components.generators.litellm.chat.chat_generator.LiteLLMChatGenerator
init_parameters:
model: openai/gpt-4o
generation_kwargs:
temperature: 0.7
max_tokens: 1024
```
### Using the Component with Different Providers
```yaml
# Using Anthropic
LiteLLMChatGenerator:
type: haystack_integrations.components.generators.litellm.chat.chat_generator.LiteLLMChatGenerator
init_parameters:
model: anthropic/claude-opus-4-5
generation_kwargs:
max_tokens: 2048
```
```yaml
# Using AWS Bedrock
LiteLLMChatGenerator:
type: haystack_integrations.components.generators.litellm.chat.chat_generator.LiteLLMChatGenerator
init_parameters:
model: bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0
generation_kwargs:
max_tokens: 1024
```
### Using the Component in a Pipeline
```yaml
# haystack-pipeline
components:
prompt_builder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
required_variables: "*"
template:
- role: user
content: "Answer the following question: {{ question }}"
llm:
type: haystack_integrations.components.generators.litellm.chat.chat_generator.LiteLLMChatGenerator
init_parameters:
model: openai/gpt-4o-mini
generation_kwargs:
max_tokens: 1024
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
connections:
- sender: prompt_builder.prompt
receiver: llm.messages
- sender: llm.replies
receiver: answer_builder.replies
max_runs_per_component: 100
metadata: {}
inputs:
query:
- answer_builder.query
- prompt_builder.question
outputs:
answers: answer_builder.answers
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `messages` | List[ChatMessage] | A list of chat messages representing the conversation so far. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `replies` | List[ChatMessage] | A list of generated reply messages from the model. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `api_key` | Optional[Secret] | None | The API key for the provider. Set the appropriate environment variable (for example, `OPENAI_API_KEY`) and use `Secret.from_env_var()`. |
| `model` | str | `openai/gpt-4o` | The model to use in LiteLLM format: `provider/model-name`. See the [LiteLLM provider list](https://docs.litellm.ai/docs/providers). |
| `streaming_callback` | Optional[Callable] | None | A callback function for streaming responses. |
| `api_base_url` | Optional[str] | None | A custom API base URL for proxies or custom deployments. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Additional generation parameters, such as `temperature`, `max_tokens`, and `top_p`. |
| `tools` | Optional[List[Tool]] | None | A list of tools the model can use for tool calling. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `messages` | List[ChatMessage] | | A list of chat messages representing the conversation. |
| `streaming_callback` | Optional[Callable] | None | A callback function to override the init-time streaming callback. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Generation parameters to override init-time values. |
| `tools` | Optional[List[Tool]] | None | Tools to make available to the model. |
## Related Information
- [Pipeline Components](/docs/reference/pipeline-components/pipeline-components.mdx)
---
## LlamaCppChatGenerator
Generate chat responses using LLMs run locally via [llama.cpp](https://github.com/ggml-org/llama.cpp).
## Key Features
- Runs GGUF-format language models locally without requiring cloud API access.
- Works on standard hardware, including machines without dedicated GPUs.
- Accepts and returns messages in `ChatMessage` format.
- Supports streaming responses through a configurable callback.
- Supports tool calling for agentic workflows.
- Supports multimodal models (text and image) through the LLaVA family and similar models.
- Configurable context length and batch size.
## Configuration
1. Drag the `LlamaCppChatGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Set the `model` to the path or URL of the GGUF model file to load (for example, `/path/to/mistral-7b.gguf`).
4. Go to the **Advanced** tab to configure `n_ctx`, `n_batch`, `model_kwargs`, `generation_kwargs`, and `streaming_callback`.
## Connections
`LlamaCppChatGenerator` receives a list of `ChatMessage` objects, typically from `PromptBuilder` or `ChatPromptBuilder`. It outputs a list of reply `ChatMessage` objects you can connect to `AnswerBuilder` or other downstream components.
## Source Code
To check this component's source code, open [`chat_generator.py`](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/llama_cpp/src/haystack_integrations/components/generators/llama_cpp/chat_generator.py) in the [Haystack Core Integrations repository](https://github.com/deepset-ai/haystack-core-integrations).
## Usage Examples
### Basic Configuration
```yaml
LlamaCppChatGenerator:
type: haystack_integrations.components.generators.llama_cpp.LlamaCppChatGenerator
init_parameters:
model: /path/to/mistral-7b-instruct.gguf
n_ctx: 4096
generation_kwargs:
max_tokens: 1024
temperature: 0.7
```
### Using the Component in a Pipeline
```yaml
# haystack-pipeline
components:
prompt_builder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
required_variables: "*"
template:
- role: user
content: "Answer the following question: {{ question }}"
llm:
type: haystack_integrations.components.generators.llama_cpp.LlamaCppChatGenerator
init_parameters:
model: /path/to/mistral-7b-instruct.gguf
n_ctx: 4096
generation_kwargs:
max_tokens: 1024
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
connections:
- sender: prompt_builder.prompt
receiver: llm.messages
- sender: llm.replies
receiver: answer_builder.replies
max_runs_per_component: 100
metadata: {}
inputs:
query:
- answer_builder.query
- prompt_builder.question
outputs:
answers: answer_builder.answers
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `messages` | List[ChatMessage] | A list of chat messages representing the conversation so far. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `replies` | List[ChatMessage] | A list of generated reply messages from the model. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `model` | str | *(required)* | The path to the GGUF model file or a URL to download the model from. |
| `n_ctx` | Optional[int] | 0 | The maximum context window size. Set to `0` to use the model's default. |
| `n_batch` | Optional[int] | 512 | The number of tokens to process in parallel during evaluation. |
| `model_kwargs` | Optional[Dict[str, Any]] | None | Additional keyword arguments for the `llama_cpp.Llama` constructor. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Default generation parameters such as `max_tokens`, `temperature`, `top_p`, `top_k`, and `stop`. |
| `tools` | Optional[List[Tool]] | None | A list of tools the model can use for tool calling. |
| `streaming_callback` | Optional[Callable] | None | A callback function for streaming token-by-token responses. |
| `chat_handler_name` | Optional[str] | None | The name of a registered chat handler for multimodal models. |
| `model_clip_path` | Optional[str] | None | The path to the CLIP model for multimodal (image + text) support. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `messages` | List[ChatMessage] | | A list of chat messages representing the conversation. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Generation parameters to override init-time values. |
| `tools` | Optional[List[Tool]] | None | Tools to make available to the model. |
## Related Information
- [Pipeline Components](/docs/reference/pipeline-components/pipeline-components.mdx)
---
## MetaLlamaChatGenerator
Generates text using Meta's Llama models via the Llama API.
## Key Features
- Generates text using models available on [Meta's Llama API](https://llama.developer.meta.com/docs/).
- Supports streaming responses token by token.
- Supports tool calling for agentic use cases.
- Works seamlessly with `ChatPromptBuilder` for prompt construction.
- Accepts any text generation parameters valid for the Llama Chat Completion API via `generation_kwargs`.
:::note Response Format
`MetaLlamaChatGenerator` currently only supports `json_schema` response format.
:::
## Configuration
1. Drag the `MetaLlamaChatGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Create a secret with your Llama API key. Use `LLAMA_API_KEY` as the secret key. For instructions, see [Create Secrets](/docs/how-to-guides/managing-access/add-secrets.mdx).
2. Select the model. For supported models, see [Llama API Docs](https://llama.developer.meta.com/docs/).
4. Go to the **Advanced** tab to configure `generation_kwargs`, `streaming_callback`, `tools`, and `api_base_url`.
## Connections
`MetaLlamaChatGenerator` accepts a list of `ChatMessage` objects through its `messages` input. It outputs generated responses as a list of `ChatMessage` objects through its `replies` output.
Connect `ChatPromptBuilder`'s `prompt` output to `MetaLlamaChatGenerator`'s `messages` input. Connect its `replies` output to `OutputAdapter` and then to `DeepsetAnswerBuilder`.
## Source Code
To check this component's source code, open [`chat_generator.py`](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/meta_llama/src/haystack_integrations/components/generators/meta_llama/chat/chat_generator.py) in the [Haystack Core Integrations repository](https://github.com/deepset-ai/haystack-core-integrations).
## Usage Examples
### Basic Configuration
```yaml
MetaLlamaChatGenerator:
type: haystack_integrations.components.generators.meta_llama.chat.chat_generator.MetaLlamaChatGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- LLAMA_API_KEY
strict: false
model: Llama-4-Scout-17B-16E-Instruct-FP8
api_base_url: https://api.llama.com/compat/v1/
```
This is an example RAG pipeline with `MetaLlamaChatGenerator` and `DeepsetAnswerBuilder`:
```yaml
# haystack-pipeline
components:
bm25_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: 'Standard-Index-English'
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
fuzziness: 0
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: 'Standard-Index-English'
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
document_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
ChatPromptBuilder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template:
- _content:
- text: "You are a helpful assistant answering the user's questions based on the provided documents.\nIf the answer is not in the documents, rely on the web_search tool to find information.\nDo not use your own knowledge.\n"
_role: system
- _content:
- text: "Provided documents:\n{% for document in documents %}\nDocument [{{ loop.index }}] :\n{{ document.content }}\n{% endfor %}\n\nQuestion: {{ query }}\n"
_role: user
required_variables:
variables:
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ replies[0] }}'
output_type: List[str]
custom_filters:
unsafe: false
MetaLlamaChatGenerator:
type: haystack_integrations.components.generators.meta_llama.chat.chat_generator.MetaLlamaChatGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- LLAMA_API_KEY
strict: false
model: Llama-4-Scout-17B-16E-Instruct-FP8
api_base_url: https://api.llama.com/compat/v1/
generation_kwargs:
streaming_callback:
tools:
connections: # Defines how the components are connected
- sender: bm25_retriever.documents
receiver: document_joiner.documents
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: document_joiner.documents
- sender: document_joiner.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: meta_field_grouping_ranker.documents
receiver: answer_builder.documents
- sender: meta_field_grouping_ranker.documents
receiver: ChatPromptBuilder.documents
- sender: OutputAdapter.output
receiver: answer_builder.replies
- sender: ChatPromptBuilder.prompt
receiver: MetaLlamaChatGenerator.messages
- sender: MetaLlamaChatGenerator.replies
receiver: OutputAdapter.replies
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "bm25_retriever.query"
- "query_embedder.text"
- "ranker.query"
- "answer_builder.query"
- "ChatPromptBuilder.query"
filters: # These components will receive a potential query filter as input
- "bm25_retriever.filters"
- "embedding_retriever.filters"
outputs: # Defines the output of your pipeline
documents: "meta_field_grouping_ranker.documents" # The output of the pipeline is the retrieved documents
answers: "answer_builder.answers" # The output of the pipeline is the generated answers
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `messages` | List[ChatMessage] | A list of `ChatMessage` instances representing the input messages. |
| `streaming_callback` | Optional[StreamingCallbackT] | A callback function that is called when a new token is received from the stream. |
| `generation_kwargs` | Optional[Dict[str, Any]] | Additional keyword arguments for the model. For details, see model documentation. |
| `tools` | Optional[Union[List[Tool], Toolset]] | A list of Tool objects or a Toolset that the model can use. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `replies` | List[ChatMessage] | A list containing the generated ChatMessage responses. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|------------------|------------------------------------|------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|api_key |Secret |Secret.from_env_var('LLAMA_API_KEY')|The Llama API key. |
|model |str |Llama-4-Scout-17B-16E-Instruct-FP8 |The name of the Llama chat completion model to use. |
|streaming_callback|Optional[StreamingCallbackT] |None |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 |Optional[str] |https://api.llama.com/compat/v1/ |The Llama API Base url. For more details, see LlamaAPI [docs](https://llama.developer.meta.com/docs/features/compatibility/). |
|generation_kwargs |Optional[Dict[str, Any]] |None |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.|
|tools |Optional[Union[List[Tool], Toolset]]|None |A list of tools for which the model can prepare calls. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type |Default| Description |
|------------------|------------------------------------|-------|------------------------------------------------------------------------------------------------------------------------------|
|messages |List[ChatMessage] | |A list of ChatMessage instances representing the input messages. |
|streaming_callback|Optional[StreamingCallbackT] |None |A callback function that is called when a new token is received from the stream. |
|generation_kwargs |Optional[Dict[str, Any]] |None |Additional keyword arguments for the model. For details, see model documentation. |
|tools |Optional[Union[List[Tool], Toolset]]|None |A list of Tool objects or a Toolset that the model can use. |
---
## MistralChatGenerator
Generates text using Mistral's generative models through the Mistral API.
## Key Features
- Generates text using [Mistral AI](https://docs.mistral.ai/platform/endpoints/) models via the Mistral Chat Completion API.
- Supports streaming responses token by token.
- Supports tool calling for agentic use cases.
- Accepts any text generation parameters valid for the Mistral Chat Completion API via `generation_kwargs`.
- Configurable timeout, retry behavior, and custom HTTP client.
## Configuration
1. Drag the `MistralChatGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Create a secret with your Mistral API key. Use `MISTRAL_API_KEY` as the secret key. For instructions, see [Create Secrets](/docs/how-to-guides/managing-access/add-secrets.mdx).
2. Select the model. For supported models, see [Mistral AI docs](https://docs.mistral.ai/platform/endpoints/).
4. Go to the **Advanced** tab to configure `generation_kwargs`, `streaming_callback`, `tools`, `timeout`, `max_retries`, `http_client_kwargs`, and `api_base_url`.
## Connections
`MistralChatGenerator` accepts a list of `ChatMessage` objects through its `messages` input. It outputs generated responses as a list of `ChatMessage` objects through its `replies` output.
Connect `ChatPromptBuilder`'s `prompt` output to `MistralChatGenerator`'s `messages` input. Connect its `replies` output to `OutputAdapter` and then to `DeepsetAnswerBuilder`.
## Source Code
To check this component's source code, open [`chat_generator.py`](https://github.com/deepset-ai/haystack-core-integrations/blob/main/integrations/mistral/src/haystack_integrations/components/generators/mistral/chat/chat_generator.py) in the [Haystack Core Integrations repository](https://github.com/deepset-ai/haystack-core-integrations).
## Usage Examples
### Basic Configuration
```yaml
MistralChatGenerator:
type: haystack_integrations.components.generators.mistral.chat.chat_generator.MistralChatGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- MISTRAL_API_KEY
strict: false
model: mistral-small-latest
api_base_url: https://api.mistral.ai/v1
```
This is an example RAG pipeline with `MistralChatGenerator` and `DeepsetAnswerBuilder` connected through `OutputAdapter`:
```yaml
# haystack-pipeline
components:
bm25_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: 'Standard-Index-English'
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
fuzziness: 0
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever: # Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: 'Standard-Index-English'
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
top_k: 20 # The number of results to return
document_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: intfloat/simlm-msmarco-reranker
top_k: 8
meta_field_grouping_ranker:
type: haystack.components.rankers.meta_field_grouping_ranker.MetaFieldGroupingRanker
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
ChatPromptBuilder:
type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
init_parameters:
template:
- _content:
- text: "You are a helpful assistant answering the user's questions based on the provided documents.\nIf the answer is not in the documents, rely on the web_search tool to find information.\nDo not use your own knowledge.\n"
_role: system
- _content:
- text: "Provided documents:\n{% for document in documents %}\nDocument [{{ loop.index }}] :\n{{ document.content }}\n{% endfor %}\n\nQuestion: {{ query }}\n"
_role: user
required_variables:
variables:
OutputAdapter:
type: haystack.components.converters.output_adapter.OutputAdapter
init_parameters:
template: '{{ replies[0] }}'
output_type: List[str]
custom_filters:
unsafe: false
MistralChatGenerator:
type: haystack_integrations.components.generators.mistral.chat.chat_generator.MistralChatGenerator
init_parameters:
api_key:
type: env_var
env_vars:
- MISTRAL_API_KEY
strict: false
model: mistral-small-latest
streaming_callback:
api_base_url: https://api.mistral.ai/v1
generation_kwargs:
tools:
timeout:
max_retries:
http_client_kwargs:
connections: # Defines how the components are connected
- sender: bm25_retriever.documents
receiver: document_joiner.documents
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: document_joiner.documents
- sender: document_joiner.documents
receiver: ranker.documents
- sender: ranker.documents
receiver: meta_field_grouping_ranker.documents
- sender: meta_field_grouping_ranker.documents
receiver: answer_builder.documents
- sender: meta_field_grouping_ranker.documents
receiver: ChatPromptBuilder.documents
- sender: OutputAdapter.output
receiver: answer_builder.replies
- sender: ChatPromptBuilder.prompt
receiver: MistralChatGenerator.messages
- sender: MistralChatGenerator.replies
receiver: OutputAdapter.replies
inputs: # Define the inputs for your pipeline
query: # These components will receive the query as input
- "bm25_retriever.query"
- "query_embedder.text"
- "ranker.query"
- "answer_builder.query"
- "ChatPromptBuilder.query"
filters: # These components will receive a potential query filter as input
- "bm25_retriever.filters"
- "embedding_retriever.filters"
outputs: # Defines the output of your pipeline
documents: "meta_field_grouping_ranker.documents" # The output of the pipeline is the retrieved documents
answers: "answer_builder.answers" # The output of the pipeline is the generated answers
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
| :-------- | :--- | :------ | :---------- |
| `messages` | List[ChatMessage] | | A list of `ChatMessage` objects representing the input messages. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | A dictionary containing keyword arguments to customize text generation. For more information on the arguments you can use, see [Mistral API docs](https://docs.mistral.ai/api/). |
| `tools` | Optional[Union[List[Tool], Toolset]] | None | A list of tools or a Toolset for which the model can prepare calls. If set, it overrides the `tools` parameter set in pipeline configuration. |
| `streaming_callback` | Optional[StreamingCallbackT] | None | A callback function called when a new token is received from the stream. The callback function accepts `StreamingChunk` as an argument. |
| `tools_strict` | Optional[bool] | None | Whether to strictly enforce the tools provided in the `tools` parameter. If set to `True`, the model will only use the tools provided in the `tools` parameter. If set to `False`, the model can use other tools that are not provided in the `tools` parameter. |
### Outputs
| Parameter | Type | Description |
| :-------- | :--- | :---------- |
| `replies` | List[ChatMessage] | A list of `ChatMessage` objects representing the generated responses. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|------------------|------------------------------------|--------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|api_key |Secret |Secret.from_env_var('MISTRAL_API_KEY')|The Mistral API key. |
|model |str |mistral-small-latest |The name of the Mistral chat completion model to use. |
|streaming_callback|Optional[StreamingCallbackT] |None |A callback function called when a new token is received from the stream. The callback function accepts StreamingChunk as an argument. |
|api_base_url |Optional[str] |https://api.mistral.ai/v1 |The Mistral API Base url. For more details, see Mistral [docs](https://docs.mistral.ai/api/). |
|generation_kwargs |Optional[Dict[str, Any]] |None |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.|
|tools |Optional[Union[List[Tool], Toolset]]|None |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 |Optional[float] |None |The timeout for the Mistral API call. If not set, it defaults to either the `OPENAI_TIMEOUT` environment variable, or 30 seconds. |
|max_retries |Optional[int] |None |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|Optional[Dict[str, Any]] |None |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). |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
|Parameter|Type|Default|Description|
|---------|----|-------|-----------|
| messages | List[ChatMessage] | |A list of `ChatMessage` objects representing the input messages. |
| generation_kwargs | Optional[Dict[str, Any]] | None | A dictionary containing keyword arguments to customize text generation. For more information on the arguments you can use, see [Mistral API docs](https://docs.mistral.ai/api/).|
| tools | Optional[Union[List[Tool], Toolset]] | None | A list of tools or a Toolset for which the model can prepare calls. If set, it overrides the `tools` parameter set in pipeline configuration. |
| streaming_callback | Optional[StreamingCallbackT] | None | A callback function called when a new token is received from the stream. The callback function accepts `StreamingChunk` as an argument. |
|tools_strict | Optional[bool] | None | Whether to strictly enforce the tools provided in the `tools` parameter. If set to `True`, the model will only use the tools provided in the `tools` parameter. If set to `False`, the model can use other tools that are not provided in the `tools` parameter. |
---
## MistralDocumentEmbedder
Embed documents using Mistral embedding models.
## Key Features
- Embeds documents using [Mistral AI](https://mistral.ai/) embedding models.
- Stores the embedding in each document's `embedding` field, ready for semantic search.
- Use in indexing pipelines to embed documents before storing them in a document store.
- Use the same embedding model as in `MistralTextEmbedder` in your query pipeline.
- Configurable batch size and timeout for production use.
api_version: '2023-05-15'
azure_deployment: gpt-4o
generation_kwargs:
max_tokens: 650
temperature: 0
seed: 0
```
### Using the Component in a Pipeline
Here's an example of a query pipeline with `DeepsetAzureOpenAIVisionGenerator`. It's preceded by `DeepsetFileDownloader` (`image_downloader`), which downloads the documents returned by previous components, such as a Ranker or `DocumentJoiner`. It then sends the downloaded files to `DeepsetPDFDocumentToBase64Image` (`pdf_to_image`), which converts them into `Base64Image` objects that `DeepsetAzureOpenAIVisionGenerator` can take in. The Generator also receives the prompt from the `PromptBuilder`. It then sends the generated replies to `DeepsetAnswerBuilder`.
```yaml
# haystack-pipeline
components:
bm25_retriever:
type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
use_ssl: true
verify_certs: false
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
embedding_dim: 1024
similarity: cosine
top_k: 20
query_embedder:
type: haystack.components.embedders.sentence_transformers_text_embedder.SentenceTransformersTextEmbedder
init_parameters:
model: BAAI/bge-m3
tokenizer_kwargs:
model_max_length: 1024
embedding_retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
use_ssl: true
verify_certs: false
hosts:
- ${OPENSEARCH_HOST}
http_auth:
- ${OPENSEARCH_USER}
- ${OPENSEARCH_PASSWORD}
embedding_dim: 1024
similarity: cosine
top_k: 20
document_joiner:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
join_mode: concatenate
ranker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: BAAI/bge-reranker-v2-m3
top_k: 8
model_kwargs:
torch_dtype: torch.float16
tokenizer_kwargs:
model_max_length: 1024
meta_fields_to_embed:
- file_name
image_downloader:
type: deepset_cloud_custom_nodes.augmenters.deepset_file_downloader.DeepsetFileDownloader
init_parameters:
file_extensions:
- .pdf
pdf_to_image:
type: deepset_cloud_custom_nodes.converters.pdf_to_image.DeepsetPDFDocumentToBase64Image
init_parameters:
detail: high
prompt_builder:
type: haystack.components.builders.prompt_builder.PromptBuilder
init_parameters:
template: |-
Answer the questions briefly and precisely using the images and text passages provided.
Only use images and text passages that are related to the question to answer it.
In your answer, only refer to images and text passages that are relevant in answering the query.
Only use references in the form [NUMBER OF IMAGE] if you are using information from an image.
Or [NUMBER OF DOCUMENT] if you are using information from a document.
These are the documents:
{% for document in documents %}
Document[ {{ loop.index }} ]:
File Name: {{ document.meta['file_name'] }}
Text only version of image number {{ loop.index }} that is also provided.
{{ document.content }}
{% endfor %}
Question: {{ question }}
Answer:
answer_builder:
type: deepset_cloud_custom_nodes.augmenters.deepset_answer_builder.DeepsetAnswerBuilder
init_parameters:
reference_pattern: acm
TopKDocuments:
type: haystack.components.joiners.document_joiner.DocumentJoiner
init_parameters:
top_k: 8
DeepsetAzureOpenAIVisionGenerator:
type: deepset_cloud_custom_nodes.generators.azure_openai_vision.DeepsetAzureOpenAIVisionGenerator
init_parameters:
azure_endpoint:
api_version: '2023-05-15'
azure_deployment: gpt-4o
generation_kwargs:
max_tokens: 650
temperature: 0
seed: 0
connections:
- sender: bm25_retriever.documents
receiver: document_joiner.documents
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: document_joiner.documents
- sender: document_joiner.documents
receiver: ranker.documents
- sender: image_downloader.documents
receiver: pdf_to_image.documents
- sender: prompt_builder.prompt
receiver: answer_builder.prompt
- sender: ranker.documents
receiver: prompt_builder.documents
- sender: ranker.documents
receiver: TopKDocuments.documents
- sender: TopKDocuments.documents
receiver: image_downloader.documents
- sender: ranker.documents
receiver: answer_builder.documents
- sender: prompt_builder.prompt
receiver: DeepsetAzureOpenAIVisionGenerator.prompt
- sender: pdf_to_image.base64_images
receiver: DeepsetAzureOpenAIVisionGenerator.images
- sender: DeepsetAzureOpenAIVisionGenerator.replies
receiver: answer_builder.replies
max_loops_allowed: 100
metadata: {}
inputs:
query:
- bm25_retriever.query
- query_embedder.text
- ranker.query
- prompt_builder.question
- answer_builder.query
filters:
- embedding_retriever.filters
- bm25_retriever.filters
outputs:
answers: answer_builder.answers
documents: ranker.documents
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `prompt` | str | The prompt with instructions for the model. |
| `images` | List[Base64Image] | A list of Base64Images that represent the image content of the message. The base64 encoded images are passed to OpenAI for text generation. |
| `generation_kwargs` | Optional[Dict[str, Any]] | Additional keyword arguments for text generation. These parameters potentially override the parameters in pipeline configuration. |
### Outputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `replies` | List[str] | A list of strings containing the generated responses. |
| `meta` | List[Dict[str, Any]] | A list of dictionaries containing the metadata for each response. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `azure_endpoint` | Optional[str] | None | The endpoint of the deployed model, for example `https://example-resource.azure.openai.com/`. |
| `api_version` | Optional[str] | 2023-05-15 | The version of the API to use. |
| `azure_deployment` | Optional[str] | gpt-4o | The deployment of the model, usually the model name. |
| `api_key` | Optional[Secret] | Secret.from_env_var('AZURE_OPENAI_API_KEY', strict=False) | The API key to use for authentication. |
| `azure_ad_token` | Optional[Secret] | Secret.from_env_var('AZURE_OPENAI_AD_TOKEN', strict=False) | [Azure Active Directory token](https://www.microsoft.com/en-us/security/business/identity-access/microsoft-entra-id). |
| `organization` | Optional[str] | None | Your organization ID. For help, see [Setting up your organization](https://platform.openai.com/docs/guides/production-best-practices/setting-up-your-organization). |
| `streaming_callback` | Optional[Callable[[StreamingChunk], None]] | None | A callback function called when a new token is received from the stream. |
| `system_prompt` | Optional[str] | None | The system prompt to use for text generation. If not provided, the Generator omits the system prompt and uses the default system prompt. |
| `timeout` | Optional[float] | None | Timeout for AzureOpenAI client. If not set, it is inferred from the `OPENAI_TIMEOUT` environment variable or set to 30. |
| `max_retries` | Optional[int] | None | 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. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Other parameters to use for the model, sent directly to the OpenAI endpoint. For details, see [OpenAI documentation](https://platform.openai.com/docs/api-reference/chat). |
| `default_headers` | Optional[Dict[str, str]] | None | Default headers to use for the AzureOpenAI client. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `prompt` | str | | The prompt with instructions for the model. |
| `images` | List[Base64Image] | | A list of `Base64Image`'s that represent the image content of the message. |
| `generation_kwargs` | Optional[Dict[str, Any]] | None | Additional keyword arguments for text generation. For more details, refer to the OpenAI [documentation](https://platform.openai.com/docs/api-reference/chat/create). |
## Related Information
- [Add Integrations](/docs/how-to-guides/managing-access/add-integrations.mdx)
---
## DeepsetChatHistoryParser
Parse a string containing chat history and a current question into a list of `ChatMessage` objects.
`DeepsetChatHistoryParser` is primarily used with an `Agent` to supply both the chat history and the current query. It expects input in the following format:
`"Chat History: [{...array of messages...}] Current Question: {question text}"`. Each message in the chat history should be a dictionary containing two keys: `role` and `content`. If the input doesn't match this structure, `DeepsetChatHistoryParser` returns it as a single message from the user.
## Key Features
- Parses a combined chat history and current query string into a list of `ChatMessage` objects.
- Compatible with the `Agent` component for multi-turn conversational pipelines.
- Handles malformed input gracefully by returning it as a single user message.
- Requires no initialization parameters.
## Configuration
1. Drag the `DeepsetChatHistoryParser` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. This component has no required configuration. It takes no initialization parameters.
## Connections
`DeepsetChatHistoryParser` receives a combined string of chat history and the current query through its `history_and_query` input — typically from the pipeline's `query` input. It outputs a list of `ChatMessage` objects through its `messages` output, which you connect to the `Agent`'s `messages` input.
## Usage Examples
### Basic Configuration
```yaml
history_parser:
type: deepset_cloud_custom_nodes.parsers.chat_history_parser.DeepsetChatHistoryParser
init_parameters: {}
```
This is an example of an agentic pipeline with `DeepsetChatHistoryParser` used to provide the current query and chat history to the Agent:
```yaml
# haystack-pipeline
components:
adapter:
init_parameters:
custom_filters: {}
output_type: typing.List[str]
template: '{{ [(messages|last).text] }}'
unsafe: false
type: haystack.components.converters.output_adapter.OutputAdapter
agent:
init_parameters:
chat_generator:
init_parameters:
api_base_url:
api_key:
env_vars:
- OPENAI_API_KEY
strict: false
type: env_var
generation_kwargs: {}
max_retries:
model: gpt-4o
organization:
streaming_callback:
timeout:
tools:
tools_strict: false
type: haystack.components.generators.chat.openai.OpenAIChatGenerator
exit_conditions:
- text
max_agent_steps: 100
raise_on_tool_invocation_failure: false
state_schema: {}
streaming_callback:
system_prompt: |-
You are a deep research assistant.
You create comprehensive research reports to answer the user's questions.
You use the 'search'-tool to answer any questions.
You perform multiple searches until you have the information you need to answer the question.
Make sure you research different aspects of the question.
Use markdown to format your response.
When you use information from the websearch results, cite your sources using markdown links.
It is important that you cite accurately.
tools:
- data:
component:
init_parameters:
input_mapping:
query:
- search.query
output_mapping:
builder.prompt: result
pipeline:
components:
builder:
init_parameters:
required_variables:
template: |-
{% for doc in docs %}
{% if doc.content and doc.meta.url|length > 0 %}
{{ doc.content|truncate(25000) }}
{% endif %}
{% endfor %}
variables:
type: haystack.components.builders.prompt_builder.PromptBuilder
converter:
init_parameters:
extraction_kwargs: {}
store_full_path: false
type: haystack.components.converters.html.HTMLToDocument
fetcher:
init_parameters:
raise_on_failure: false
retry_attempts: 2
timeout: 3
user_agents:
- haystack/LinkContentFetcher/2.11.1
type: haystack.components.fetchers.link_content.LinkContentFetcher
search:
init_parameters:
api_key:
env_vars:
- SERPERDEV_API_KEY
strict: false
type: env_var
search_params: {}
top_k: 10
type: haystack.components.websearch.serper_dev.SerperDevWebSearch
connection_type_validation: true
connections:
- receiver: fetcher.urls
sender: search.links
- receiver: converter.sources
sender: fetcher.streams
- receiver: builder.docs
sender: converter.documents
max_runs_per_component: 100
metadata: {}
type: haystack.core.super_component.super_component.SuperComponent
description: Use this tool to search for information on the internet.
inputs_from_state:
name: search
parameters:
type: haystack.tools.component_tool.ComponentTool
type: haystack.components.agents.agent.Agent
answer_builder:
init_parameters:
pattern:
reference_pattern:
type: haystack.components.builders.answer_builder.AnswerBuilder
history_parser:
init_parameters: {}
type: deepset_cloud_custom_nodes.parsers.chat_history_parser.DeepsetChatHistoryParser
connections:
- receiver: agent.messages
sender: history_parser.messages
- receiver: adapter.messages
sender: agent.messages
- receiver: answer_builder.replies
sender: adapter.output
inputs:
query:
- answer_builder.query
- history_parser.history_and_query
outputs:
answers: answer_builder.answers
pipeline_output_type: chat
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `history_and_query` | str | Chat history and the current question to convert into a list of `ChatMessage` objects. |
### Outputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `messages` | List[ChatMessage] | A list of `ChatMessage` objects. Each message has a role (either user or assistant) and content. |
### Init Parameters
This component doesn't take any initialization parameters.
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `history_and_query` | str | | Chat history and the current query to be parsed into ChatMessages. |
---
## DeepsetFileDownloader
Download files referenced by documents to the local filesystem. Use this component in visual question answering pipelines to fetch PDFs and images before conversion.
:::warning Deprecation Notice
This component is deprecated. Use `S3Downloader` from the Haystack AWS integration instead. Existing pipelines that use this component continue to work for now.
:::
## Key Features
- Downloads files associated with documents from platform storage to local disk.
- Filters downloads by file extension.
- Caches downloaded files locally with a configurable cache size.
- Returns updated documents with `file_path` set in metadata.
- Supports concurrent downloads for multiple files.
## Configuration
1. Drag the `DeepsetFileDownloader` component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Set `file_extensions` to limit which file types are downloaded.
4. Configure `sources_target_type` and `max_cache_size` as needed.
:::info Warm-up required
This component requires a warm-up step before it can download files. The platform handles this automatically when the pipeline runs.
:::
## Connections
`DeepsetFileDownloader` accepts `documents` or `sources` as input. It outputs `documents` with `file_path` metadata and `sources` in the configured target type.
Connect a Ranker or retriever that returns documents with `file_id` metadata to the input. Connect the `documents` or `sources` output to `DeepsetPDFDocumentToBase64Image`, `DeepsetFileToBase64Image`, or a visual Generator.
## Usage Examples
### Basic Configuration
```yaml
DeepsetFileDownloader:
type: deepset_cloud_custom_nodes.augmenters.deepset_file_downloader.DeepsetFileDownloader
init_parameters:
file_extensions:
- .pdf
sources_target_type: str
max_cache_size: 100
```
### Using the Component in a Pipeline
This example downloads PDF files before converting them to images:
```yaml
# haystack-pipeline
components:
image_downloader:
type: deepset_cloud_custom_nodes.augmenters.deepset_file_downloader.DeepsetFileDownloader
init_parameters:
file_extensions:
- .pdf
sources_target_type: str
max_cache_size: 100
pdf_to_image:
type: deepset_cloud_custom_nodes.converters.pdf_to_image.DeepsetPDFDocumentToBase64Image
init_parameters:
detail: auto
connections:
- sender: image_downloader.documents
receiver: pdf_to_image.documents
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | Optional[List[Document]] | None | Documents with `file_id` in metadata to download. |
| sources | Optional[List[Union[ByteStream, UUID, str]]] | None | File IDs or byte streams to download. |
### Outputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | List[Document] | | Documents with `file_path` set in metadata. |
| sources | List[Union[str, Path, ByteStream]] | | Downloaded file paths or byte streams in the configured target type. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| file_extensions | Optional[List[str]] | None | File extensions to download, such as `[".pdf", ".png"]`. If `None`, all file types are downloaded. |
| sources_target_type | Literal["str", "pathlib.Path", "haystack.dataclasses.ByteStream"] | str | Type of the sources returned in the output. |
| max_cache_size | int | 100 | Maximum number of files to keep in the local cache. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | Optional[List[Document]] | None | Documents with `file_id` in metadata to download. |
| sources | Optional[List[Union[ByteStream, UUID, str]]] | None | File IDs or byte streams to download. |
---
## DeepsetFileToBase64Image
Convert image files from disk into base64-encoded images for use in visual question answering pipelines.
:::warning Deprecation Notice
This component is deprecated. Use `ImageFileToImageContent` from Haystack instead. Existing pipelines that use this component continue to work for now.
:::
## Key Features
- Reads image files from local disk and converts them to `Base64Image` objects.
- Supports PNG, JPG, JPEG, and GIF file formats.
- Accepts documents with `file_path` metadata or direct file sources.
- Configurable image detail level for vision model input sizing.
## Configuration
1. Drag the `DeepsetFileToBase64Image` component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Set `detail` to control how the image is resized before encoding.
## Connections
`DeepsetFileToBase64Image` accepts `documents` with `file_path` metadata or direct `sources` as input. It outputs `documents` and `base64_images`.
Connect `DeepsetFileDownloader` to provide documents with local file paths. Connect the `base64_images` output to a visual Generator such as `DeepsetOpenAIVisionGenerator` or `Base64ImageJoiner`.
## Usage Examples
### Basic Configuration
```yaml
DeepsetFileToBase64Image:
type: deepset_cloud_custom_nodes.converters.file_to_image.DeepsetFileToBase64Image
init_parameters:
detail: auto
```
### Using the Component in a Pipeline
This example converts downloaded image files to base64 for a vision Generator:
```yaml
# haystack-pipeline
components:
image_downloader:
type: deepset_cloud_custom_nodes.augmenters.deepset_file_downloader.DeepsetFileDownloader
init_parameters:
file_extensions:
- .png
- .jpg
- .jpeg
sources_target_type: str
max_cache_size: 100
file_to_image:
type: deepset_cloud_custom_nodes.converters.file_to_image.DeepsetFileToBase64Image
init_parameters:
detail: auto
connections:
- sender: image_downloader.documents
receiver: file_to_image.documents
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | Optional[List[Document]] | None | Documents with `file_path` in metadata pointing to image files. |
| sources | Optional[List[Union[str, Path, ByteStream]]] | None | Direct file paths or byte streams to convert. |
### Outputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | List[Document] | | Documents that had convertible image files. |
| base64_images | List[Base64Image] | | Base64-encoded images ready for vision Generators. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| detail | Literal["auto", "low", "high"] | auto | Controls how the image is resized before encoding. See the [OpenAI vision documentation](https://platform.openai.com/docs/guides/vision) for details. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | Optional[List[Document]] | None | Documents with `file_path` in metadata. |
| sources | Optional[List[Union[str, Path, ByteStream]]] | None | Direct file paths or byte streams to convert. |
---
## DeepsetMetadataGrouper
Reorder documents by grouping them on metadata fields. Use this component to keep related document chunks together before sending them to an LLM.
:::warning Deprecation Notice
This component is deprecated. Use `MetaFieldGroupingRanker` from Haystack instead. Existing pipelines that use this component continue to work for now.
:::
## Key Features
- Groups documents by a metadata field such as `file_id`.
- Creates subgroups within each group using a second metadata field.
- Sorts documents within groups by a numeric metadata value.
- Helps LLMs process related chunks in a logical order.
## Configuration
1. Drag the `DeepsetMetadataGrouper` component onto the canvas from the Component Library.
2. Click the component to open the configuration panel.
3. Set `group_by` to the primary metadata field for grouping.
4. Optionally set `subgroup_by` and `sort_docs_by`.
## Connections
`DeepsetMetadataGrouper` accepts a list of `documents` as input. It outputs `documents` — the same documents reordered by group and subgroup.
Connect a `Ranker` or retriever to the input. Connect the output to a `PromptBuilder` or pipeline output.
## Usage Examples
### Basic Configuration
```yaml
DeepsetMetadataGrouper:
type: deepset_cloud_custom_nodes.rankers.deepset_metadata_grouper.DeepsetMetadataGrouper
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
```
### Using the Component in a Pipeline
This example groups ranked documents by `file_id` and sorts them by `split_id`:
```yaml
# haystack-pipeline
components:
ranker:
type: haystack.components.rankers.transformers_similarity.TransformersSimilarityRanker
init_parameters:
model: cross-encoder/ms-marco-MiniLM-L-6-v2
top_k: 15
metadata_grouper:
type: deepset_cloud_custom_nodes.rankers.deepset_metadata_grouper.DeepsetMetadataGrouper
init_parameters:
group_by: file_id
subgroup_by:
sort_docs_by: split_id
connections:
- sender: ranker.documents
receiver: metadata_grouper.documents
outputs:
documents: metadata_grouper.documents
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | List[Document] | | Documents to group and reorder. |
### Outputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | List[Document] | | Documents reordered by group and subgroup. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| group_by | str | | Metadata key used to group documents. |
| subgroup_by | Optional[str] | None | Metadata key used to create subgroups within each group. |
| sort_docs_by | Optional[str] | None | Metadata key used to sort documents within each group or subgroup. Documents without this key are placed at the end. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| documents | List[Document] | | Documents to group and reorder. |
---
## DeepsetOpenAIVisionGenerator
Generate text using text and image capabilities of OpenAI's LLMs.
:::warning Deprecation Notice
This component is deprecated. It will continue to work in your existing pipelines for now. You can replace it with the `OpenAIChatGenerator` component.
:::
`DeepsetOpenAIVisionGenerator` works with the GPT families of models hosted on Azure. These models can understand images, making it possible to describe them, analyze details, and answer questions based on images. For details and limitations, check [OpenAI's Vision](https://platform.openai.com/docs/guides/vision) documentation.
## Key Features
- Accepts both text prompts and images (as `Base64Image` objects) for multimodal generation.
- Works with GPT-4 and other vision-capable OpenAI models.
- Supports streaming responses token by token.
- Customizable generation via `generation_kwargs`, including `max_tokens`, `temperature`, `top_p`, and more.
## Configuration
1. Drag the `DeepsetOpenAIVisionGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Enter the model name in the **Model** field (for example, `gpt-4o`).
2. Make sure '
consider_all_messages: false
return_empty_on_no_match: false
return_all_matches: false
```
### Using the Component in a Pipeline
This example extracts a URL from a chat message:
```yaml
# haystack-pipeline
components:
regex_parser:
type: deepset_cloud_custom_nodes.parsers.regex_parser.DeepsetRegexParser
init_parameters:
regex_pattern: ''
consider_all_messages: false
return_empty_on_no_match: false
return_all_matches: false
inputs:
text_or_messages:
- regex_parser.text_or_messages
outputs:
captured_text: regex_parser.captured_text
```
## Parameters
### Inputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| text_or_messages | str or List[ChatMessage] | | Text or chat messages to search. |
### Outputs
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| captured_text | str | | First captured text when `return_all_matches` is `False`. |
| captured_texts | List[str] | | All captured texts when `return_all_matches` is `True`. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| regex_pattern | str | | Regular expression pattern with a capture group to extract text. |
| consider_all_messages | bool | False | If `True`, applies the regex to all chat messages. If `False`, only the last message is searched. |
| return_empty_on_no_match | bool | False | If `True`, returns an empty dictionary when no match is found. |
| return_all_matches | bool | False | If `True`, returns all matches as `captured_texts`. If `False`, returns only the first match as `captured_text`. |
### Run Method Parameters
These are the parameters you can configure for the component's `run()` method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| text_or_messages | str or List[ChatMessage] | | Text or chat messages to search. |
---
## DeepsetSourceToBase64Image
Convert file sources directly to base64-encoded images.
:::warning Deprecation Notice
This component is deprecated. It will continue to work in your existing pipelines for now.
:::
## Key Features
- Converts file sources (such as image files) directly to base64-encoded `Base64Image` objects.
- Configurable detail level (`auto`, `low`, or `high`) for image processing.
- Used in visual question answering pipelines to prepare images for vision-capable generators.
## Configuration
1. Drag the `DeepsetSourceToBase64Image` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab, configure the **Detail** level: `auto` (default), `low`, or `high`.
4. Go to the **Advanced** tab to configure additional settings.
## Connections
`DeepsetSourceToBase64Image` receives file sources through its input and outputs a list of `Base64Image` objects. You typically connect its output to a vision-capable Generator or to `Base64ImageJoiner` when combining images from multiple sources.
## Usage Examples
### Basic Configuration
```yaml
DeepsetSourceToBase64Image:
type: deepset_cloud_custom_nodes.converters.file_to_image.DeepsetSourceToBase64Image
init_parameters: {}
```
### Using the Component in a Pipeline
This example converts uploaded image files to base64 for a vision pipeline:
```yaml
# haystack-pipeline
components:
source_to_image:
type: deepset_cloud_custom_nodes.converters.file_to_image.DeepsetSourceToBase64Image
init_parameters:
detail: auto
inputs:
sources:
- source_to_image.sources
outputs:
base64_images: source_to_image.base64_images
max_runs_per_component: 100
metadata: {}
```
## Parameters
### Inputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `sources` | List[Union[str, Path, ByteStream]] | A list of file sources to convert to base64-encoded images. |
### Outputs
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `base64_images` | List[Base64Image] | A list of base64-encoded images. |
### Init Parameters
These are the parameters you can configure in Pipeline Builder:
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `detail` | Literal['auto', 'low', 'high'] | auto | Controls how the model processes the image and generates its textual understanding. Choose `high` for best results and `low` for lowest inference costs. |
### Run Method Parameters
These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see [Modify Pipeline Parameters at Query Time](/docs/how-to-guides/searching-with-your-pipeline/set-runtime-parameters-to-override-pipeline-configuration.mdx).
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `sources` | List[Union[str, Path, ByteStream]] | | A list of file sources to convert to base64-encoded images. |
---
## DeepsetTogetherAIGenerator
Generate text using large language models hosted on Together AI.
:::warning Deprecation Notice
This component is deprecated. It will continue to work in your existing pipelines for now. You can replace it with the `TogetherAIChatGenerator` component.
:::
`DeepsetTogetherAIGenerator` generates answers to queries using models hosted on Together AI. For a complete list of models you can use, check [Together AI documentation](https://docs.together.ai/docs/serverless-models).
## Key Features
- Supports a wide range of open-source models hosted on Together AI.
- String-based input and output interface, compatible with `PromptBuilder`.
- Supports streaming responses token by token.
- Supports system prompts at both initialization time and run time.
- Customizable generation via `generation_kwargs`, including `max_tokens`, `temperature`, and more.
## Configuration
1. Drag the `DeepsetTogetherAIGenerator` component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the **General** tab:
1. Enter the model name in the **Model** field (for example, `deepseek-ai/DeepSeek-R1`).
2. Make sure
Pipeline YAML
This is the YAML configuration for the document search pipeline:
```yaml
components:
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever:
# Selects the most similar documents from the document store
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
index: Standard-Index-English
top_k: 20 # The number of results to return
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 20
connections:
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: ranker.documents
inputs:
query:
- query_embedder.text
- ranker.query
filters:
- embedding_retriever.filters
outputs:
documents: ranker.documents
```
**Result**: You have a document search pipeline that returns relevant policy snippets and is ready to be used as a tool.
## Add the Deal Policy Search Tool to the Agent
Attach the search pipeline as a tool on your agent:
1. Leave Builder and on the Pipelines page click the *deal-desk-agent* pipeline to open it.
2. Click the `Agent` component to open its configuration.
3. In the *Tools* section, click **Add Tool**.
4. Choose *Pipeline* as the tool type.
5. On the Create Pipeline Tool window, choose *Existing pipeline* and select *deal-policy-search*.
6. Leave *Current draft* as the pipeline version.
7. Enter `search_deal_policy` as the tool name.
8. Copy the following text and paste it as the tool description:
```text
Search Atlas Analytics deal desk policies for discount authority, pricing tiers,
vertical rules, and approval escalation. Use when you need policy language to
cite in a discount approval answer.
```
9. Click **Add Pipeline Tool**.
**Result**: The agent has a pipeline tool that can search deal desk policies.
:::info
When you add an existing pipeline as a tool, the platform handles input and output mapping for you. For details, see [Add a Pipeline as a Tool](/docs/how-to-guides/building-agents/configuring-agent.mdx#add-a-pipeline-as-a-tool).
:::
## Add the Discount Approval Code Tool
The second tool encodes the company's discount approval rules in Python. The code uses a class with `__init__` parameters for the fixed thresholds and a `@tool` function the agent calls with per-deal facts from the conversation.
:::tip Init parameters vs tool parameters
`__init__` parameters are configured once in the tool card UI — they're the business rules that rarely change (discount caps, ACV thresholds). `@tool` function arguments are what the agent passes at runtime from the sales rep's message (contract value, discount percent, term, vertical). To create a second pipeline with different thresholds for a different market, you clone it and change only the init parameters.
:::
1. On the `Agent` componentconfiguration, in the *Tools* section, click **Add Tool**.
2. Choose **Code** as the tool type.
3. Type `check_discount_approval` as the tool name.
4. Copy the following text and paste it as the tool description:
```text
Check whether a requested discount needs rep, manager, or VP approval given ACV, discount percent, contract term, and vertical.
```
:::note
Keep the description on a single line. Some LLM providers, including Anthropic, reject tool descriptions that contain line breaks.
:::
5. Click **Create Tool**.
6. In the code editor, paste the following code replacing the example code:
```python
from typing import Annotated
from haystack.tools import tool
class DiscountApprovalEngine:
"""Discount rules configured at deploy time through init parameters."""
def __init__(
self,
max_rep_discount_percent: float = 15,
manager_max_discount_percent: float = 25,
vp_approval_acv_threshold_usd: float = 75000,
healthcare_max_without_vp: float = 20,
multi_year_bonus_percent: float = 3,
):
self.max_rep_discount_percent = max_rep_discount_percent
self.manager_max_discount_percent = manager_max_discount_percent
self.vp_approval_acv_threshold_usd = vp_approval_acv_threshold_usd
self.healthcare_max_without_vp = healthcare_max_without_vp
self.multi_year_bonus_percent = multi_year_bonus_percent
def check(
self,
annual_contract_value_usd: float,
requested_discount_percent: float,
contract_term_years: int,
industry_vertical: str,
) -> dict:
vertical = industry_vertical.strip().lower()
healthcare_verticals = {"healthcare", "life_sciences", "life sciences", "pharma"}
rep_limit = self.max_rep_discount_percent
if contract_term_years >= 2:
rep_limit += self.multi_year_bonus_percent
if vertical in healthcare_verticals and requested_discount_percent > self.healthcare_max_without_vp:
return {
"rep_can_approve": False,
"approval_required": "vp_sales",
"rep_discount_limit_percent": rep_limit,
"reason": (
f"Healthcare vertical discounts above {self.healthcare_max_without_vp}% "
"require VP Sales approval."
),
}
if (
annual_contract_value_usd > self.vp_approval_acv_threshold_usd
and requested_discount_percent > self.max_rep_discount_percent
):
return {
"rep_can_approve": False,
"approval_required": "vp_sales",
"rep_discount_limit_percent": rep_limit,
"reason": (
f"Deals over ${self.vp_approval_acv_threshold_usd:,.0f} with a discount "
f"above {self.max_rep_discount_percent}% require VP Sales approval."
),
}
if requested_discount_percent <= rep_limit:
return {
"rep_can_approve": True,
"approval_required": "none",
"rep_discount_limit_percent": rep_limit,
"reason": (
f"Requested discount is within the rep limit of {rep_limit}% "
f"({'includes multi-year bonus' if contract_term_years >= 2 else 'standard authority'})."
),
}
if requested_discount_percent <= self.manager_max_discount_percent:
return {
"rep_can_approve": False,
"approval_required": "sales_manager",
"rep_discount_limit_percent": rep_limit,
"reason": (
f"Discount exceeds rep limit of {rep_limit}% but is within the "
f"{self.manager_max_discount_percent}% manager threshold."
),
}
return {
"rep_can_approve": False,
"approval_required": "vp_sales",
"rep_discount_limit_percent": rep_limit,
"reason": (
f"Discount above {self.manager_max_discount_percent}% requires VP Sales approval."
),
}
_engine = DiscountApprovalEngine()
@tool
def check_discount_approval(
annual_contract_value_usd: Annotated[float, "Annual contract value in USD"],
requested_discount_percent: Annotated[float, "Requested discount as a percentage, for example 28 for 28%"],
contract_term_years: Annotated[int, "Contract length in years"],
industry_vertical: Annotated[
str,
"Industry vertical, for example healthcare, financial_services, or standard",
],
):
"""Check discount approval level using Atlas Analytics deal desk rules."""
acv = float(str(annual_contract_value_usd).replace(",", ""))
discount = float(str(requested_discount_percent).replace("%", "").strip())
term = int(str(contract_term_years).strip())
return _engine.check(
annual_contract_value_usd=acv,
requested_discount_percent=discount,
contract_term_years=term,
industry_vertical=industry_vertical,
)
```
7. Close the code editor.
**Result**: The agent has a code tool that returns a structured approval result for any deal the sales rep describes.
## Set the System Prompt
Give the agent instructions so it knows when to use each tool.
1. Click the **Agent** component to open its configuration.
2. Copy the following text and paste it as the system prompt:
```text
You are an Atlas Analytics deal desk assistant helping sales reps evaluate discount requests.
You have access to two tools:
1. search_deal_policy: Search deal desk policies for discount authority, pricing tiers, vertical rules, and approval escalation.
2. check_discount_approval: Check whether a discount can be approved at rep level or needs escalation. Pass annual_contract_value_usd, requested_discount_percent, contract_term_years, and industry_vertical.
Workflow:
- Extract deal facts from the user's message (ACV, discount, contract term, vertical).
- If any fact is missing, ask one short follow-up question.
- Call check_discount_approval with the extracted facts.
- Call search_deal_policy to find policy excerpts that support your answer.
- Combine the approval result with policy citations in your reply.
Response format:
- Can the rep approve: yes or no
- Approval required: none, sales_manager, or vp_sales
- Rep discount limit
- Policy references from search_deal_policy
- Next steps for the sales rep
```
Full AgentYAML Configuration
This is the YAML configuration for the agent with tools:
```yaml
inputs:
query: []
filters: []
files: []
messages:
- Agent.messages
components:
Agent:
type: haystack.components.agents.agent.Agent
init_parameters:
chat_generator:
type: haystack_integrations.components.generators.anthropic.chat.chat_generator.AnthropicChatGenerator
init_parameters:
model: claude-sonnet-4-6
ignore_tools_thinking_messages: true
api_key:
type: env_var
strict: true
env_vars:
- ANTHROPIC_API_KEY
tools:
- type: haystack.tools.pipeline_tool.PipelineTool
data:
name: search_deal_policy
description: >-
Search Atlas Analytics deal desk policies for discount authority,
pricing tiers,
vertical rules, and approval escalation. Use when you need policy language to
cite in a discount approval answer.
input_mapping:
query:
- query_embedder.text
- ranker.query
filters:
- embedding_retriever.filters
output_mapping:
ranker.documents: documents
pipeline:
components:
query_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
init_parameters:
normalize_embeddings: true
model: intfloat/e5-base-v2
embedding_retriever:
type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
embedding_dim: 768
index: Standard-Index-English
top_k: 20
ranker:
type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
init_parameters:
model: tomaarsen/Qwen3-Reranker-0.6B-seq-cls
top_k: 20
connections:
- sender: query_embedder.embedding
receiver: embedding_retriever.query_embedding
- sender: embedding_retriever.documents
receiver: ranker.documents
is_pipeline_async: false
inputs_from_state: {}
outputs_to_string: {}
outputs_to_state: {}
_meta:
name: search_deal_policy
description: >-
Search Atlas Analytics deal desk policies for discount authority,
pricing tiers,
vertical rules, and approval escalation. Use when you need policy language to
cite in a discount approval answer.
tool_id:
pipeline_version_id: c9bdb695-fa2e-47c7-a25a-3bccc9701817
- type: deepset_cloud_custom_nodes.tools.code_tool.CodeTool
data:
name: check_discount_approval
description: Check whether a requested discount needs rep, manager, or VP
approval given ACV, discount percent, contract term, and vertical.
code: "from typing import Annotated\r
\r
from haystack.tools import tool\r
\r
\r
class DiscountApprovalEngine:\r
\ \"\"\"Discount rules configured at deploy time through init
parameters.\"\"\"\r
\r
\ def __init__(\r
\ self,\r
\ max_rep_discount_percent: float = 15,\r
\ manager_max_discount_percent: float = 25,\r
\ vp_approval_acv_threshold_usd: float = 75000,\r
\ healthcare_max_without_vp: float = 20,\r
\ multi_year_bonus_percent: float = 3,\r
\ ):\r
\ self.max_rep_discount_percent = max_rep_discount_percent\r
\ self.manager_max_discount_percent =
manager_max_discount_percent\r
\ self.vp_approval_acv_threshold_usd =
vp_approval_acv_threshold_usd\r
\ self.healthcare_max_without_vp =
healthcare_max_without_vp\r
\ self.multi_year_bonus_percent = multi_year_bonus_percent\r
\r
\ def check(\r
\ self,\r
\ annual_contract_value_usd: float,\r
\ requested_discount_percent: float,\r
\ contract_term_years: int,\r
\ industry_vertical: str,\r
\ ) -> dict:\r
\ vertical = industry_vertical.strip().lower()\r
\ healthcare_verticals = {\"healthcare\", \"life_sciences\",
\"life sciences\", \"pharma\"}\r
\r
\ rep_limit = self.max_rep_discount_percent\r
\ if contract_term_years >= 2:\r
\ rep_limit += self.multi_year_bonus_percent\r
\r
\ if vertical in healthcare_verticals and
requested_discount_percent > self.healthcare_max_without_vp:\r
\ return {\r
\ \"rep_can_approve\": False,\r
\ \"approval_required\": \"vp_sales\",\r
\ \"rep_discount_limit_percent\": rep_limit,\r
\ \"reason\": (\r
\ f\"Healthcare vertical discounts above
{self.healthcare_max_without_vp}% \"\r
\ \"require VP Sales approval.\"\r
\ ),\r
\ }\r
\r
\ if (\r
\ annual_contract_value_usd >
self.vp_approval_acv_threshold_usd\r
\ and requested_discount_percent >
self.max_rep_discount_percent\r
\ ):\r
\ return {\r
\ \"rep_can_approve\": False,\r
\ \"approval_required\": \"vp_sales\",\r
\ \"rep_discount_limit_percent\": rep_limit,\r
\ \"reason\": (\r
\ f\"Deals over
${self.vp_approval_acv_threshold_usd:,.0f} with a discount \"\r
\ f\"above {self.max_rep_discount_percent}%
require VP Sales approval.\"\r
\ ),\r
\ }\r
\r
\ if requested_discount_percent <= rep_limit:\r
\ return {\r
\ \"rep_can_approve\": True,\r
\ \"approval_required\": \"none\",\r
\ \"rep_discount_limit_percent\": rep_limit,\r
\ \"reason\": (\r
\ f\"Requested discount is within the rep limit
of {rep_limit}% \"\r
\ f\"({'includes multi-year bonus' if
contract_term_years >= 2 else 'standard authority'}).\"\r
\ ),\r
\ }\r
\r
\ if requested_discount_percent <=
self.manager_max_discount_percent:\r
\ return {\r
\ \"rep_can_approve\": False,\r
\ \"approval_required\": \"sales_manager\",\r
\ \"rep_discount_limit_percent\": rep_limit,\r
\ \"reason\": (\r
\ f\"Discount exceeds rep limit of {rep_limit}%
but is within the \"\r
\ f\"{self.manager_max_discount_percent}% manager
threshold.\"\r
\ ),\r
\ }\r
\r
\ return {\r
\ \"rep_can_approve\": False,\r
\ \"approval_required\": \"vp_sales\",\r
\ \"rep_discount_limit_percent\": rep_limit,\r
\ \"reason\": (\r
\ f\"Discount above
{self.manager_max_discount_percent}% requires VP Sales approval.\"\r
\ ),\r
\ }\r
\r
\r
_engine = DiscountApprovalEngine()\r
\r
\r
@tool\r
def check_discount_approval(\r
\ annual_contract_value_usd: Annotated[float, \"Annual contract
value in USD\"],\r
\ requested_discount_percent: Annotated[float, \"Requested
discount as a percentage, for example 28 for 28%\"],\r
\ contract_term_years: Annotated[int, \"Contract length in
years\"],\r
\ industry_vertical: Annotated[\r
\ str,\r
\ \"Industry vertical, for example healthcare,
financial_services, or standard\",\r
\ ],\r
):\r
\ \"\"\"Check discount approval level using Atlas Analytics deal
desk rules.\"\"\"\r
\ acv = float(str(annual_contract_value_usd).replace(\",\",
\"\"))\r
\ discount = float(str(requested_discount_percent).replace(\"%\",
\"\").strip())\r
\ term = int(str(contract_term_years).strip())\r
\ return _engine.check(\r
\ annual_contract_value_usd=acv,\r
\ requested_discount_percent=discount,\r
\ contract_term_years=term,\r
\ industry_vertical=industry_vertical,\r
\ )"
_meta:
name: check_discount_approval
description:
tool_id:
system_prompt: >-
{% message role="system" %}
You are an Atlas Analytics deal desk assistant helping sales reps
evaluate discount requests.
You have access to two tools:
1. search_deal_policy: Search deal desk policies for discount authority,
pricing tiers, vertical rules, and approval escalation.
2. check_discount_approval: Check whether a discount can be approved at
rep level or needs escalation. Pass annual_contract_value_usd,
requested_discount_percent, contract_term_years, and industry_vertical.
Workflow:
- Extract deal facts from the user's message (ACV, discount, contract
term, vertical).
- If any fact is missing, ask one short follow-up question.
- Call check_discount_approval with the extracted facts.
- Call search_deal_policy to find policy excerpts that support your
answer.
- Combine the approval result with policy citations in your reply.
Response format:
- Can the rep approve: yes or no
- Approval required: none, sales_manager, or vp_sales
- Rep discount limit
- Policy references from search_deal_policy
- Next steps for the sales rep
{% endmessage %}
user_prompt:
required_variables:
exit_conditions:
state_schema: {}
max_agent_steps: 100
streaming_callback:
raise_on_tool_invocation_failure: false
tool_invoker_kwargs:
confirmation_strategies:
outputs:
answers:
documents:
messages: Agent.messages
```
**Result**: The agent has a clear policy for when and how to use each tool.
## Test the Agent
1. In Builder, with the deal-desk-agent pipeline open, click **Run Pipeline** next to the **Input** component.
2. Paste a message like this:
```text
A healthcare prospect wants 28% off a $95,000 annual contract on a 1-year deal.
Can the rep approve this discount?
```
The code tool should report *VP Sales approval required* (healthcare cap is 20%). The agent should cite the healthcare vertical rules and escalation matrix from `search_deal_policy`.
3. Try a deal the rep can approve:
```text
A standard SaaS prospect wants 12% off a $40,000 annual contract on a 1-year deal.
Can the rep approve this?
```
The code tool should report *rep can approve* (12% is within the 15% rep limit).
**Result**: Congratulations!You have created an agent that can answer discount approval questions with a mix of policy citations and deterministic business rules. The agent uses two tools: `search_deal_policy` for citations and `check_discount_approval` for the definitive call.
***
## What's Next
- Add more vertical rules or regional pricing tiers to the code tool init parameters.
- Connect the agent to your CRM through an MCP server tool. For details, see [Use Your Pipeline as an MCP Tool](/docs/how-to-guides/productionizing-your-pipeline/expose-pipeline-as-mcp-tool.mdx).
- Use [Prompt Explorer](/docs/how-to-guides/designing-your-pipeline/work-with-llms/using-prompt-studio.mdx) to refine the system prompt.
- For more on agents and tools, see [Agent Tools](/docs/concepts/ai-agents/agent-tools.mdx).
---
## Tutorial: Building an IT Helpdesk Agent with Multiple Knowledge Bases
Build an AI agent that answers employee IT questions by automatically deciding which knowledge base to search: an internal IT procedures database or a vendor software documentation database. The agent reads the question, picks the right tool, and synthesizes an answer from the relevant documents.
The agent uses two search pipelines as tools. One pipeline searches the internal IT documentation, the other searches the vendor software documentation. The agent decides which tool to use based on the question.
***
- **Level**: Intermediate
- **Time to complete**: 25 minutes
- **Prerequisites**:
- A basic understanding of pipelines and indexes in ")], # provide a path to the folder on your computer where you saved the hotel_reviews folder
api_key="", # the API key to connect to deepset
workspace_name="", # the workspace where you want to upload files
blocking=True, # waits until the files are displayed in deepset,
# this may take a couple of minutes
timeout_s=300, # the timeout for the `blocking` parameter in number of seconds
show_progress=True, # shows the progress bar
recursive=True, # uploads files from all subfolders as well
)
```
2. Save the script and run it:
```python
python hotel_reviews_upload.py
```
3. Wait until the upload finishes successfully. You should see this message:
```python
deepset-cloud list-files
```
```python
python -m deepset_cloud_sdk.cli list-files
```
You should see a list of files with file ID, URL, name, size, metadata, and the date when it was created.
Index YAML
```yaml
components:
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
document_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
model: intfloat/e5-base-v2
normalize_embeddings: true
meta_fields_to_embed:
- context
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
search_fields:
- content
- context
policy: OVERWRITE
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
LLMMetadataExtractor:
type: haystack.components.extractors.llm_metadata_extractor.LLMMetadataExtractor
init_parameters:
prompt: |
Please extract the following metadata for the provided document:
- "title": A short title describing the content
- "summary": A 2 sentence summary of the content
document:
{{ document.content | truncate(25000) }}
Answer exclusively with the JSON object as plain text. Use NO code blocks, NO markdown formatting, NO prefixes like "json" or similar. Begin your response directly with { and end with }.
Required structure:
{
"title": "",
"summary": ""
}
chat_generator:
type: haystack_integrations.components.generators.amazon_bedrock.chat.chat_generator.AmazonBedrockChatGenerator
init_parameters:
model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
boto3_config:
region_name: us-west-2
read_timeout: 120
retries:
total_max_attempts: 3
mode: standard
generation_kwargs:
max_tokens: 650
expected_keys:
- summary
- title
connections: # Defines how the components are connected
- sender: document_embedder.documents
receiver: writer.documents
- sender: splitter.documents
receiver: document_embedder.documents
- sender: LLMMetadataExtractor.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: LLMMetadataExtractor.documents
inputs: # Define the inputs for your pipeline
files: # This component will receive the files to index as input
- text_converter.sources
max_runs_per_component: 100
metadata: {}
```
### Update the Prompt
Now, let's update the prompt to tag the emails with specific attributes.
1. Find the `LLMMetadataExtractor` and click it. This opens the configuration panel where you can update the prompt.
2. Delete the current prompt and replace it with the following text:
```text
You are an email annotation assistant. For each email, analyze it and return a JSON object with the following fields:
- "urgency": one of "high", "medium", or "low".
- "type": one of "meeting request", "status update", "question", "announcement", or "other".
- "action required": either "yes" or "no".
Your answer must only be the JSON object, starting with { and ending with }, with no extra text, explanations, or formatting.
---
Guidelines for annotation
Urgency
- "high":
- Mentions a near-term deadline (e.g., today, tomorrow, this week).
- Explicitly marked urgent or requires immediate attention.
- Requests blocking input or decisions.
- "medium":
- Requests action but not immediate (within a few days).
- Important updates with some implied timeliness.
- "low":
- Informational only, no clear deadline.
- General announcements or FYI.
Type
- "meeting request": Asks to schedule, confirm, or prepare for a meeting.
- "status update": Provides progress reports, updates on work, results.
- "question": Primarily asks for information or clarification.
- "announcement": Broadcasts general info, policy changes, or news.
- "other": Anything that doesn’t fit the above categories.
Action required
- "yes": Recipient is asked to reply, decide, confirm, attend, or do something.
- "no": Purely informational, no expectation of response or action.
---
Tie-breaking rules
1. Meeting request > Question > Status update > Announcement > Other
- Example: If an email both asks a question and proposes a meeting → classify as "meeting request".
2. If urgency is ambiguous, default to "medium".
3. If action required is unclear, default to "no".
---
Example Input:
"Hi team, could you please confirm your availability for tomorrow’s sync?"
Example Output:
{ "urgency": "high", "type": "meeting request", "action required": "yes" }
Email: {{ document.content }}
```
3. Optionally, configure the expected metadata keys:
1. In the `LLMMetadataExtractor` configuration panel, click **Advanced**.
2. Under `Expected keys`, type:
```text
- urgency
- type
- action
```
Index YAML
```yaml
components:
text_converter:
type: haystack.components.converters.txt.TextFileToDocument
init_parameters:
encoding: utf-8
store_full_path: false
document_embedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
model: intfloat/e5-base-v2
normalize_embeddings: true
meta_fields_to_embed:
- context
writer:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
search_fields:
- content
- context
policy: OVERWRITE
splitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 250
split_overlap: 30
respect_sentence_boundary: true
language: en
LLMMetadataExtractor:
type: haystack.components.extractors.llm_metadata_extractor.LLMMetadataExtractor
init_parameters:
prompt: |
You are an email annotation assistant. For each email, analyze it and return a JSON object with the following fields:
- "urgency": one of "high", "medium", or "low".
- "type": one of "meeting request", "status update", "question", "announcement", or "other".
- "action required": either "yes" or "no".
Your answer must only be the JSON object, starting with { and ending with }, with no extra text, explanations, or formatting.
---
Guidelines for annotation
Urgency
- "high":
- Mentions a near-term deadline (e.g., today, tomorrow, this week).
- Explicitly marked urgent or requires immediate attention.
- Requests blocking input or decisions.
- "medium":
- Requests action but not immediate (within a few days).
- Important updates with some implied timeliness.
- "low":
- Informational only, no clear deadline.
- General announcements or FYI.
Type
- "meeting request": Asks to schedule, confirm, or prepare for a meeting.
- "status update": Provides progress reports, updates on work, results.
- "question": Primarily asks for information or clarification.
- "announcement": Broadcasts general info, policy changes, or news.
- "other": Anything that doesn’t fit the above categories.
Action required
- "yes": Recipient is asked to reply, decide, confirm, attend, or do something.
- "no": Purely informational, no expectation of response or action.
---
Tie-breaking rules
1. Meeting request > Question > Status update > Announcement > Other
- Example: If an email both asks a question and proposes a meeting → classify as "meeting request".
2. If urgency is ambiguous, default to "medium".
3. If action required is unclear, default to "no".
Example Input:
"Hi team, could you please confirm your availability for tomorrow’s sync?"
Example Output:
{ "urgency": "high", "type": "meeting request", "action required": "yes" }
Email:
{{ document.content }}
chat_generator:
type: haystack_integrations.components.generators.amazon_bedrock.chat.chat_generator.AmazonBedrockChatGenerator
init_parameters:
model: "us.anthropic.claude-sonnet-4-20250514-v1:0"
boto3_config:
region_name: us-west-2
read_timeout: 120
retries:
total_max_attempts: 3
mode: standard
generation_kwargs:
max_tokens: 650
expected_keys:
- urgency
- type
- action
page_range: ''
connections: # Defines how the components are connected
- sender: document_embedder.documents
receiver: writer.documents
- sender: splitter.documents
receiver: document_embedder.documents
- sender: LLMMetadataExtractor.documents
receiver: splitter.documents
- sender: text_converter.documents
receiver: LLMMetadataExtractor.documents
inputs: # Define the inputs for your pipeline
files: # This component will receive the files to index as input
- text_converter.sources
max_runs_per_component: 100
metadata: {}
```
## Index Your Files
Let's preprocess the files, add metadata, and write the resulting documents into the document store:
1. In Builder, click **Enable** to start indexing.
Click to view the complete index configuration
```yaml
components:
Code:
type: deepset_cloud_custom_nodes.code.code_component.Code
init_parameters:
code: "from haystack import component, Document\nimport re\nfrom typing import List\n\n@component\nclass Code:\n \"\"\"\n Masks personally identifiable information in CV text before LLM processing.\n \"\"\"\n @component.output_types(cleaned_docs=List[Document])\n def run(self, documents: List[Document]) -> dict:\n cleaned_docs = []\n \n for doc in documents:\n redacted = doc.content\n\n # Email addresses\n email_pattern = r'\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b'\n redacted = re.sub(email_pattern, '[EMAIL]', redacted)\n\n # LinkedIn URLs\n linkedin_pattern = r'linkedin\\.com/in/[A-Za-z0-9_-]+'\n redacted = re.sub(linkedin_pattern, '[LINKEDIN]', redacted, flags=re.IGNORECASE)\n\n # GitHub URLs\n github_pattern = r'github\\.com/[A-Za-z0-9_-]+'\n redacted = re.sub(github_pattern, '[GITHUB]', redacted, flags=re.IGNORECASE)\n\n # Phone numbers: +44 7700 112233, 07700 112233, 798072811, etc.\n phone_pattern = r'(\\+\\d{1,3}[\\s.-]?)?\\(?\\d{2,4}\\)?[\\s.-]?\\d{3,4}[\\s.-]?\\d{3,4}|\\b\\d{9,11}\\b'\n redacted = re.sub(phone_pattern, '[PHONE]', redacted)\n\n # UK postcodes: BS8 1AF, M1 4HE, EC1A 1BB\n postcode_pattern = r'\\b[A-Z]{1,2}\\d[A-Z\\d]?\\s?\\d[A-Z]{2}\\b'\n redacted = re.sub(postcode_pattern, '[POSTCODE]', redacted, flags=re.IGNORECASE)\n\n # Street addresses (line containing number + street type)\n street_pattern = r'\\d+\\s+[\\w\\s]+(?:Street|St|Road|Rd|Avenue|Ave|Lane|Ln|Drive|Dr|Way|Court|Ct|Place|Pl|Square|Sq|Close|Crescent|Terrace|Grove|Park|Gardens|Row|Mews|Hill|Green|Wood|Gate|Walk|Fields|Rise|View|Valley|Meadow|Heights)\\b[^,\\n]*'\n redacted = re.sub(street_pattern, '[ADDRESS]', redacted, flags=re.IGNORECASE)\n\n # Date of birth patterns: DOB: 15/03/1988, Date of Birth: 15 March 1988\n dob_pattern = r'(DOB|Date of Birth|Born|Birthday|D\\.O\\.B\\.?)[\\s:]*\\d{1,2}[\\s./-](\\d{1,2}|Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|Jun(?:e)?|Jul(?:y)?|Aug(?:ust)?|Sep(?:tember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)[\\s./-]\\d{2,4}'\n redacted = re.sub(dob_pattern, '[DATE_OF_BIRTH]', redacted, flags=re.IGNORECASE)\n\n # National Insurance Number (UK): AB 12 34 56 C\n nino_pattern = r'\\b[A-Z]{2}\\s?\\d{2}\\s?\\d{2}\\s?\\d{2}\\s?[A-Z]\\b'\n redacted = re.sub(nino_pattern, '[NATIONAL_ID]', redacted, flags=re.IGNORECASE)\n\n cleaned_docs.append(Document(content=redacted, meta=doc.meta))\n\n return {\"cleaned_docs\": cleaned_docs}"
PDFMinerToDocument:
type: haystack.components.converters.pdfminer.PDFMinerToDocument
init_parameters:
line_overlap: 0.5
char_margin: 2
line_margin: 0.5
word_margin: 0.1
boxes_flow: 0.5
detect_vertical: true
all_texts: false
store_full_path: false
DocumentSplitter:
type: haystack.components.preprocessors.document_splitter.DocumentSplitter
init_parameters:
split_by: word
split_length: 200
split_overlap: 0
split_threshold: 0
splitting_function:
respect_sentence_boundary: false
language: en
use_split_rules: true
extend_abbreviations: true
skip_empty_documents: true
DeepsetNvidiaDocumentEmbedder:
type: deepset_cloud_custom_nodes.embedders.nvidia.document_embedder.DeepsetNvidiaDocumentEmbedder
init_parameters:
model: intfloat/multilingual-e5-base
prefix: ''
suffix: ''
batch_size: 32
meta_fields_to_embed:
embedding_separator: \n
truncate:
normalize_embeddings: true
timeout:
backend_kwargs:
DocumentWriter:
type: haystack.components.writers.document_writer.DocumentWriter
init_parameters:
policy: NONE
document_store:
type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
init_parameters:
hosts:
index: ''
max_chunk_bytes: 104857600
embedding_dim: 768
return_embedding: false
method:
mappings:
settings:
create_index: true
http_auth:
use_ssl:
verify_certs:
timeout:
connections: # Defines how the components are connected
- sender: PDFMinerToDocument.documents
receiver: Code.documents
- sender: Code.cleaned_docs
receiver: DocumentSplitter.documents
- sender: DocumentSplitter.documents
receiver: DeepsetNvidiaDocumentEmbedder.documents
- sender: DeepsetNvidiaDocumentEmbedder.documents
receiver: DocumentWriter.documents
inputs: # Define the inputs for your pipeline
files: # This component will receive the files to index as input
- PDFMinerToDocument.sources
max_runs_per_component: 100
metadata: {}
```
**Result**: You have created an index that can process PDF files and masks sensitive personal information using custom code. The index is enabled and ready to process files.
## Index Files
Now, let's upload sample files to the workspace and index them.
1. Download the sample files from the sample-cvs folder in Google Drive and unzip it to a location on your computer. You should have five PDF files.
2. In --recursive --write-mode OVERWRITE
```
```python Windows
python -m deepset_cloud_sdk.cli upload --recursive --write-mode OVERWRITE
```
:::info Uploading other file types
To upload other file types, use `--desired_file_types` with a list of file types, for example: `--desired_file_types ['.csv', '.html']\`.
:::
5. Wait until the upload finishes successfully. You should see this message:
```python
url = "https://api.cloud.deepset.ai/api/v1/workspaces//pipelines//search"
payload = {
"debug": False,
"view_prompts": False,
"queries": ["what are the symptomps of milk allegry?"]
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer "
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces//pipelines//search \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--data '
{
"debug": false,
"view_prompts": false,
"queries": [
"what are the symptomps of milk allegry?"
]
}
'
```
The response contains the query and the result ID, which you'll need to add, update, or delete feedback entries.
:::info Finding the Correct Result and Query IDs
To add a feedback entry, you’ll need the result ID associated with the answer. In the example response below, the result ID is `7e07bd73-c099-44fe-9d65-ec0ba5e83c41`.
Keep in mind that each document also has its own result ID. Make sure to use the result ID from the answer itself when adding your feedback.
For the query ID, make sure to use the query ID located in the `results` object. In the example below, it's `37547edb-48ec-49c0-96e8-1fcb5f37bd0c`.
:::
Sample response
```json
{
"query_id": "37547edb-48ec-49c0-96e8-1fcb5f37bd0c",
"results": [
{
"query_id": "37547edb-48ec-49c0-96e8-1fcb5f37bd0c",
"query": "What are milk allergy symptomps?",
"answers": [
{
"answer": "Milk allergy symptoms can be immediate or take more time to develop. Immediate signs and symptoms of milk allergy might include:\n\n* Hives\n* Wheezing\n* Itching or tingling feeling around the lips or mouth\n* Swelling of the lips, tongue or throat\n* Coughing or shortness of breath\n* Vomiting\n\nSigns and symptoms that may take more time to develop include:\n\n* Loose stools or diarrhea, which may contain blood\n* Abdominal cramps\n* Runny nose\n* Watery eyes\n* Colic, in babies\n\nAdditionally, mentions some general allergy symptoms that may also apply to milk allergy, including:\n\n* Itchy, irritated skin\n* Nasal stuffiness (congestion)\n* Belly (abdominal) pain\n* Dizziness, lightheadedness or fainting\n\nNote that is not specifically about milk allergy, but about allergies in general. However, the symptoms listed may still be relevant to milk allergy.",
"type": "generative",
"score": null,
"context": null,
"offsets_in_document": [],
"offsets_in_context": [],
"document_id": null,
"document_ids": [
"e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902",
"01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293",
"cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31",
"0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525",
"e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba",
"488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7"
],
"meta": {
"_references": [
{
"answer_end_idx": 13,
"answer_start_idx": 13,
"document_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"document_position": 1,
"label": "grounded",
"score": 0,
"doc_end_idx": 1559,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 18,
"answer_start_idx": 18,
"document_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"document_position": 2,
"label": "grounded",
"score": 0,
"doc_end_idx": 1402,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 507,
"answer_start_idx": 507,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"document_position": 8,
"label": "grounded",
"score": 0,
"doc_end_idx": 1576,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 729,
"answer_start_idx": 729,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"document_position": 8,
"label": "grounded",
"score": 0,
"doc_end_idx": 1576,
"doc_start_idx": 0,
"origin": "llm"
}
]
},
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"files": [
{
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
{
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
}
],
"result_id": "7e07bd73-c099-44fe-9d65-ec0ba5e83c41", /* the result ID you'll need */
"prompt": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>\n\nYou answer questions truthfully based on provided documents.\nFor each document check whether it is related to the question.\nOnly use documents that are related to the question to answer it.\nIgnore documents that are not related to the question.\nIf the answer exists in several documents, summarize them.\nOnly answer based on the documents provided. Don't make things up.\nIf the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.\nAlways use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].\nNever name the documents, only enter a number in square brackets as a reference.\nThe reference must only refer to the number that comes in square brackets after the document.\nOtherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.\nThese are the documents:\n\nDocument[1]:\nOverview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n\n\nDocument[2]:\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. \n\nDocument[3]:\nTests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n\n\nDocument[4]:\nThe next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. \n\nDocument[5]:\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. \n\nDocument[6]:\nSoy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.\n\nDocument[7]:\nDoes your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. \n\nDocument[8]:\nThey may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. \n\nQuestion: What are milk allergy symptomps? <|eot_id|><|start_header_id|>assistant<|end_header_id|>"
}
],
"documents": [
{
"id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"content": "Overview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
0,
633
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
}
],
"split_idx_start": 0,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 0,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.76318359375,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "bc8173bd-0164-4668-999d-ab579681077a"
},
{
"id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"content": "Immediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
926,
1559
],
"doc_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6"
},
{
"range": [
0,
254
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
}
],
"split_idx_start": 926,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 1,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.6025390625,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "8c702ffb-9170-4b8d-a5f4-6a35a6b2ff36"
},
{
"id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902",
"content": "Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1148,
1402
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
},
{
"range": [
0,
224
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
}
],
"split_idx_start": 2074,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 2,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.1593017578125,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "b4e68189-dfb3-4fa3-a987-28529dfbba05"
},
{
"id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293",
"content": "The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1060,
1284
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
},
{
"range": [
0,
230
],
"doc_id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31"
}
],
"split_idx_start": 3134,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 3,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.1376953125,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "774c03b5-87ee-453d-9ca4-7688a8f70335"
},
{
"id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31",
"content": "Risk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1198,
1428
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
},
{
"range": [
0,
236
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
}
],
"split_idx_start": 4332,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 4,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.05224609375,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "b304143d-5c83-40be-b9f3-422fee1e9952"
},
{
"id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525",
"content": "Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1297,
1585
],
"doc_id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba"
}
],
"split_idx_start": 8221,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 7,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.051666259765625,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "9c033d90-a592-46aa-976f-d884047a1a6e"
},
{
"id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba",
"content": "Does your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1324,
1561
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
},
{
"range": [
0,
288
],
"doc_id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525"
}
],
"split_idx_start": 6924,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 6,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.0341796875,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "1b5869e2-0233-4255-a875-65748b4151b9"
},
{
"id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"content": "They may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
977,
1585
],
"doc_id": "9b92616ee62b77dd44659f9b3589516d24587eea08bddc375bc2dc7fc6deb84a"
},
{
"range": [
0,
676
],
"doc_id": "c894391a5e0feafe8251959fc0aa0942cf95bc085998374c9936ad693e00e979"
}
],
"split_idx_start": 977,
"file_name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 1,
"dataset_name": "Healthcare",
"_file_size": 9017,
"page_number": 1,
"source_id": "35308e27d89136421775a7c1d7e7c709e7b938ebff990548bcdd383940031f4c"
},
"score": 0.026763916015625,
"embedding": null,
"file": {
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
},
"result_id": "bfc1a187-4654-48d6-9339-2b81dbe4f5b2"
}
],
"_debug": null,
"prompts": null
}
]
}
```
## Add, Update, and Delete Feedback
### Add a Feedback Entry
Add feedback to an answer your pipeline returned. Use the [Create Feedback](/docs/api/main/create-feedback-api-v-2-workspaces-workspace-id-pipelines-pipeline-id-feedback-post) endpoint. You can assign one of the feedback scores:
- `ACCURATE` (corresponds to the thumbs up icon in the UI)
- `INACCURATE` (corresponds to the thumbs down icon in the UI)
- `FAIRLY_ACCURATE` (corresponds to the mixed/neutral icon in the UI)
You need the following IDs to make the request:
```python
url = "https://api.cloud.deepset.ai/api/v2/workspaces//pipelines//feedback"
payload = {
"query_id": "",
"result_id": "",
"score": ""
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer "
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v2/workspaces//pipelines//feedback \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--data '
{
"query_id": "",
"result_id": "",
"score": ""
}
'
```
The response includes the feedback ID, which you will need to update or delete the feedback entry.
Sample response
```json
{
"score": "ACCURATE",
"comment": null,
"bookmarked": false,
"tags": [],
"result_id": "7e07bd73-c099-44fe-9d65-ec0ba5e83c41",
"feedback_id": "2fcba96d-8ae3-4572-af4c-47a9aed536a7", /*this is the feedback ID*/
"organization_id": "4f26a3b2-03fc-4742-a4b1-8c3dae2b2d2a",
"workspace_id": "b7f048eb-7b48-4ad8-b7b0-443cdddb81c5",
"pipeline_id": "07b04f1a-e053-4bd1-b3d5-e740b0dd6f2d",
"created_by": {
"user_id": "f6398740-5555-445d-8ae3-ef980ea4191d",
"given_name": "Jane",
"family_name": "Smith"
},
"created_at": "2024-12-10T11:56:13.884352Z",
"search_history": {
"search_history_result_id": "7e07bd73-c099-44fe-9d65-ec0ba5e83c41",
"query_id": "37547edb-48ec-49c0-96e8-1fcb5f37bd0c",
"documents": [
{
"id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"content": "Overview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
0,
633
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
}
],
"split_idx_start": 0,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 0,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.76318359375,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "bc8173bd-0164-4668-999d-ab579681077a"
},
{
"id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"content": "Immediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
926,
1559
],
"doc_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6"
},
{
"range": [
0,
254
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
}
],
"split_idx_start": 926,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 1,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.6025390625,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "8c702ffb-9170-4b8d-a5f4-6a35a6b2ff36"
},
{
"id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902",
"content": "Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1148,
1402
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
},
{
"range": [
0,
224
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
}
],
"split_idx_start": 2074,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 2,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.1593017578125,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "b4e68189-dfb3-4fa3-a987-28529dfbba05"
},
{
"id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293",
"content": "The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1060,
1284
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
},
{
"range": [
0,
230
],
"doc_id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31"
}
],
"split_idx_start": 3134,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 3,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.1376953125,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "774c03b5-87ee-453d-9ca4-7688a8f70335"
},
{
"id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31",
"content": "Risk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1198,
1428
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
},
{
"range": [
0,
236
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
}
],
"split_idx_start": 4332,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 4,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.05224609375,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "b304143d-5c83-40be-b9f3-422fee1e9952"
},
{
"id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525",
"content": "Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1297,
1585
],
"doc_id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba"
}
],
"split_idx_start": 8221,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 7,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.051666259765625,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "9c033d90-a592-46aa-976f-d884047a1a6e"
},
{
"id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba",
"content": "Does your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1324,
1561
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
},
{
"range": [
0,
288
],
"doc_id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525"
}
],
"split_idx_start": 6924,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 6,
"dataset_name": "Healthcare",
"_file_size": 4962,
"page_number": 1,
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e"
},
"score": 0.0341796875,
"embedding": null,
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"result_id": "1b5869e2-0233-4255-a875-65748b4151b9"
},
{
"id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"content": "They may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
977,
1585
],
"doc_id": "9b92616ee62b77dd44659f9b3589516d24587eea08bddc375bc2dc7fc6deb84a"
},
{
"range": [
0,
676
],
"doc_id": "c894391a5e0feafe8251959fc0aa0942cf95bc085998374c9936ad693e00e979"
}
],
"split_idx_start": 977,
"file_name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt",
"_file_created_at": "2024-12-09T11:08:47.728733+00:00",
"split_id": 1,
"dataset_name": "Healthcare",
"_file_size": 9017,
"page_number": 1,
"source_id": "35308e27d89136421775a7c1d7e7c709e7b938ebff990548bcdd383940031f4c"
},
"score": 0.026763916015625,
"embedding": null,
"file": {
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
},
"result_id": "bfc1a187-4654-48d6-9339-2b81dbe4f5b2"
}
],
"type": "generative",
"rank": 1,
"score": null,
"files": [
{
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
{
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
}
],
"context": null,
"answer": "According to and , milk allergy symptoms can be immediate or take more time to develop. Immediate signs and symptoms of milk allergy might include:\n\n* Hives\n* Wheezing\n* Itching or tingling feeling around the lips or mouth\n* Swelling of the lips, tongue or throat\n* Coughing or shortness of breath\n* Vomiting\n\nSigns and symptoms that may take more time to develop include:\n\n* Loose stools or diarrhea, which may contain blood\n* Abdominal cramps\n* Runny nose\n* Watery eyes\n* Colic, in babies\n\nAdditionally, mentions some general allergy symptoms that may also apply to milk allergy, including:\n\n* Itchy, irritated skin\n* Nasal stuffiness (congestion)\n* Belly (abdominal) pain\n* Dizziness, lightheadedness or fainting\n\nNote that is not specifically about milk allergy, but about allergies in general. However, the symptoms listed may still be relevant to milk allergy.",
"meta": {
"_references": [
{
"answer_end_idx": 13,
"answer_start_idx": 13,
"document_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"document_position": 1,
"label": "grounded",
"score": 0,
"doc_end_idx": 1559,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 18,
"answer_start_idx": 18,
"document_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"document_position": 2,
"label": "grounded",
"score": 0,
"doc_end_idx": 1402,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 507,
"answer_start_idx": 507,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"document_position": 8,
"label": "grounded",
"score": 0,
"doc_end_idx": 1576,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 729,
"answer_start_idx": 729,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"document_position": 8,
"label": "grounded",
"score": 0,
"doc_end_idx": 1576,
"doc_start_idx": 0,
"origin": "llm"
}
]
},
"offsets_in_context": [],
"prompt": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>\n\nYou answer questions truthfully based on provided documents.\nFor each document check whether it is related to the question.\nOnly use documents that are related to the question to answer it.\nIgnore documents that are not related to the question.\nIf the answer exists in several documents, summarize them.\nOnly answer based on the documents provided. Don't make things up.\nIf the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.\nAlways use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].\nNever name the documents, only enter a number in square brackets as a reference.\nThe reference must only refer to the number that comes in square brackets after the document.\nOtherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.\nThese are the documents:\n\nDocument[1]:\nOverview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n\n\nDocument[2]:\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. \n\nDocument[3]:\nTests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n\n\nDocument[4]:\nThe next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. \n\nDocument[5]:\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. \n\nDocument[6]:\nSoy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.\n\nDocument[7]:\nDoes your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. \n\nDocument[8]:\nThey may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. \n\nQuestion: What are milk allergy symptomps? <|eot_id|><|start_header_id|>assistant<|end_header_id|>",
"search": {
"created_at": "2024-12-09T12:33:30.371439Z",
"duration": 19.983364582061768,
"query": "What are milk allergy symptomps?",
"filters": {}
}
}
}
```
### Update Feedback
You can always update the feedback you gave earlier using the [Update Feedback](/docs/api/main/update-feedback-api-v-2-workspaces-workspace-id-pipelines-pipeline-id-feedback-feedback-id-patch) endpoint. You need the following IDs for this:
- Workspace ID (you can check it in
```python
url = "https://api.cloud.deepset.ai/api/v2/workspaces//pipelines//feedback/"
payload = { "score": "ACCURATE" }
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer "
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)
```
```curl
curl --request PATCH \
--url https://api.cloud.deepset.ai/api/v2/workspaces/WORKSPACE_ID/pipelines/PIPELINE_ID/feedback/FEEDBACK_ID \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--data '{"score":"ACCURATE"}'
```
Sample response
```json
{
"score": "FAIRLY_ACCURATE", /*the updated score*/
"comment": null,
"bookmarked": false,
"tags": [],
"result_id": "7e07bd73-c099-44fe-9d65-ec0ba5e83c41",
"feedback_id": "2fcba96d-8ae3-4572-af4c-47a9aed536a7",
"organization_id": "4f26a3b2-03fc-4742-a4b1-8c3dae2b2d2a",
"workspace_id": "b7f048eb-7b48-4ad8-b7b0-443cdddb81c5",
"pipeline_id": "07b04f1a-e053-4bd1-b3d5-e740b0dd6f2d",
"created_by": {
"user_id": "f6398740-5555-445d-8ae3-ef980ea4191d",
"given_name": "Agnieszka",
"family_name": "Marzec"
},
"created_at": "2024-12-10T11:56:13.884352Z",
"search_history": {
"search_history_result_id": "7e07bd73-c099-44fe-9d65-ec0ba5e83c41",
"query_id": "37547edb-48ec-49c0-96e8-1fcb5f37bd0c",
"documents": [
{
"id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 0,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
0,
633
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
}
],
"split_idx_start": 0,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.76318359375,
"content": "Overview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n",
"embedding": null,
"result_id": "bc8173bd-0164-4668-999d-ab579681077a",
"content_type": "text"
},
{
"id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 1,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
926,
1559
],
"doc_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6"
},
{
"range": [
0,
254
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
}
],
"split_idx_start": 926,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.6025390625,
"content": "Immediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. ",
"embedding": null,
"result_id": "8c702ffb-9170-4b8d-a5f4-6a35a6b2ff36",
"content_type": "text"
},
{
"id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 2,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
1148,
1402
],
"doc_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61"
},
{
"range": [
0,
224
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
}
],
"split_idx_start": 2074,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.1593017578125,
"content": "Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n",
"embedding": null,
"result_id": "b4e68189-dfb3-4fa3-a987-28529dfbba05",
"content_type": "text"
},
{
"id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 3,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
1060,
1284
],
"doc_id": "13a4046915e3b7f1ddce5cb4a69494da53972863c2a93470a9bd579787a76902"
},
{
"range": [
0,
230
],
"doc_id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31"
}
],
"split_idx_start": 3134,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.1376953125,
"content": "The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. ",
"embedding": null,
"result_id": "774c03b5-87ee-453d-9ca4-7688a8f70335",
"content_type": "text"
},
{
"id": "cf0faa27a97156c1fcd25b1970bf77c407267a8110cb5143482e980ba6438e31",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 4,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
1198,
1428
],
"doc_id": "01374947009de69505ab48ce77aff8579c75986101ed3e2b16c9a637b576e293"
},
{
"range": [
0,
236
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
}
],
"split_idx_start": 4332,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.05224609375,
"content": "Risk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. ",
"embedding": null,
"result_id": "b304143d-5c83-40be-b9f3-422fee1e9952",
"content_type": "text"
},
{
"id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 7,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
1297,
1585
],
"doc_id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba"
}
],
"split_idx_start": 8221,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.051666259765625,
"content": "Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.",
"embedding": null,
"result_id": "9c033d90-a592-46aa-976f-d884047a1a6e",
"content_type": "text"
},
{
"id": "e81e29ab84fd3d190876a323afb80cffa291c18a54b19e735ae96056346432ba",
"file": {
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
"meta": {
"split_id": 6,
"file_name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt",
"source_id": "95731bef674bd1f778c2b8ffa3de3eddf9eaf1d0b3dd33567287780041ab517e",
"_file_size": 4962,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
1324,
1561
],
"doc_id": "f7571820008fb10ef49414199539bbdffc6dc28cbdaf775a63cd05ae00a6d155"
},
{
"range": [
0,
288
],
"doc_id": "0813ca29e002b219399bdbbf8ec1ad4a82f206e67e29126d5cdd7639b9894525"
}
],
"split_idx_start": 6924,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.0341796875,
"content": "Does your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. ",
"embedding": null,
"result_id": "1b5869e2-0233-4255-a875-65748b4151b9",
"content_type": "text"
},
{
"id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"file": {
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
},
"meta": {
"split_id": 1,
"file_name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt",
"source_id": "35308e27d89136421775a7c1d7e7c709e7b938ebff990548bcdd383940031f4c",
"_file_size": 9017,
"page_number": 1,
"dataset_name": "Healthcare",
"_split_overlap": [
{
"range": [
977,
1585
],
"doc_id": "9b92616ee62b77dd44659f9b3589516d24587eea08bddc375bc2dc7fc6deb84a"
},
{
"range": [
0,
676
],
"doc_id": "c894391a5e0feafe8251959fc0aa0942cf95bc085998374c9936ad693e00e979"
}
],
"split_idx_start": 977,
"_file_created_at": "2024-12-09T11:08:47.728733+00:00"
},
"score": 0.026763916015625,
"content": "They may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. ",
"embedding": null,
"result_id": "bfc1a187-4654-48d6-9339-2b81dbe4f5b2",
"content_type": "text"
}
],
"type": "generative",
"rank": 1,
"score": null,
"files": [
{
"id": "c83a91f9-6206-478d-8838-938431ccd410",
"name": "https___www.mayoclinic.org_diseases-conditions_milk-allergy_symptoms-causes_syc-20375101_3d1d6c.txt"
},
{
"id": "04d06fa7-c3ef-4a7d-9244-55c83924e230",
"name": "https___www.mayoclinic.org_diseases-conditions_shellfish-allergy_symptoms-causes_syc-20377503_63c3a1.txt"
}
],
"context": null,
"answer": "According to and , milk allergy symptoms can be immediate or take more time to develop. Immediate signs and symptoms of milk allergy might include:\n\n* Hives\n* Wheezing\n* Itching or tingling feeling around the lips or mouth\n* Swelling of the lips, tongue or throat\n* Coughing or shortness of breath\n* Vomiting\n\nSigns and symptoms that may take more time to develop include:\n\n* Loose stools or diarrhea, which may contain blood\n* Abdominal cramps\n* Runny nose\n* Watery eyes\n* Colic, in babies\n\nAdditionally, mentions some general allergy symptoms that may also apply to milk allergy, including:\n\n* Itchy, irritated skin\n* Nasal stuffiness (congestion)\n* Belly (abdominal) pain\n* Dizziness, lightheadedness or fainting\n\nNote that is not specifically about milk allergy, but about allergies in general. However, the symptoms listed may still be relevant to milk allergy.",
"meta": {
"_references": [
{
"label": "grounded",
"score": 0,
"origin": "llm",
"doc_end_idx": 1559,
"document_id": "e7d2cc416005d62d2732e33b0c73c8a29b19e5689dd31c3635eca3d13a4d28d6",
"doc_start_idx": 0,
"answer_end_idx": 13,
"answer_start_idx": 13,
"document_position": 1
},
{
"label": "grounded",
"score": 0,
"origin": "llm",
"doc_end_idx": 1402,
"document_id": "6ce80daeb86e789ebf57837a5bd539c60835bb3ad6c4fc8405f3365b382fbb61",
"doc_start_idx": 0,
"answer_end_idx": 18,
"answer_start_idx": 18,
"document_position": 2
},
{
"label": "grounded",
"score": 0,
"origin": "llm",
"doc_end_idx": 1576,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"doc_start_idx": 0,
"answer_end_idx": 507,
"answer_start_idx": 507,
"document_position": 8
},
{
"label": "grounded",
"score": 0,
"origin": "llm",
"doc_end_idx": 1576,
"document_id": "488b2156989f3b1745a7a9bbc8382833e7a94fa228b7d849c03a7b46832bb8e7",
"doc_start_idx": 0,
"answer_end_idx": 729,
"answer_start_idx": 729,
"document_position": 8
}
]
},
"offsets_in_context": [],
"prompt": "<|begin_of_text|><|start_header_id|>user<|end_header_id|>\n\nYou answer questions truthfully based on provided documents.\nFor each document check whether it is related to the question.\nOnly use documents that are related to the question to answer it.\nIgnore documents that are not related to the question.\nIf the answer exists in several documents, summarize them.\nOnly answer based on the documents provided. Don't make things up.\nIf the documents can't answer the question or you are unsure say: 'The answer can't be found in the text'.\nAlways use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].\nNever name the documents, only enter a number in square brackets as a reference.\nThe reference must only refer to the number that comes in square brackets after the document.\nOtherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.\nThese are the documents:\n\nDocument[1]:\nOverview\nMilk allergy is an atypical immune system response to milk and products containing milk. It's one of the most common food allergies in children. Cow's milk is the usual cause of milk allergy, but milk from sheep, goats, buffalo and other mammals also can cause a reaction.\nAn allergic reaction usually occurs soon after you or your child consumes milk. Signs and symptoms of milk allergy range from mild to severe and can include wheezing, vomiting, hives and digestive problems. Milk allergy can also cause anaphylaxis — a severe, life-threatening reaction.\nAvoiding milk and milk products is the primary treatment for milk allergy. Fortunately, most children outgrow milk allergy. Those who don't outgrow it may need to continue to avoid milk products.\nSymptoms\nMilk allergy symptoms, which differ from person to person, occur a few minutes to a few hours after you or your child drinks milk or eats milk products.\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\n\n\nDocument[2]:\nImmediate signs and symptoms of milk allergy might include:\nHives\nWheezing\nItching or tingling feeling around the lips or mouth\nSwelling of the lips, tongue or throat\nCoughing or shortness of breath\nVomiting\nSigns and symptoms that may take more time to develop include:\nLoose stools or diarrhea, which may contain blood\nAbdominal cramps\nRunny nose\nWatery eyes\nColic, in babies\nMilk allergy or milk intolerance?\nA true milk allergy differs from milk protein intolerance and lactose intolerance. Unlike milk allergy, intolerance doesn't involve the immune system. Milk intolerance requires different treatment from true milk allergy.\nCommon signs and symptoms of milk protein intolerance or lactose intolerance include digestive problems, such as bloating, gas or diarrhea, after consuming milk or products containing milk.\nAnaphylaxis\nMilk allergy can cause anaphylaxis, a life-threatening reaction that narrows the airways and can block breathing. Milk is the third most common food — after peanuts and tree nuts — to cause anaphylaxis.\nIf you or your child has a reaction to milk, tell your health care provider, no matter how mild the reaction. Tests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. \n\nDocument[3]:\nTests can help confirm milk allergy, so you can avoid future and potentially worse reactions.\nAnaphylaxis is a medical emergency and requires treatment with an epinephrine (adrenaline) shot (EpiPen, Adrenaclick, others) and a trip to the emergency room. Signs and symptoms start soon after milk consumption and can include:\nConstriction of airways, including a swollen throat that makes it difficult to breathe\nFacial flushing\nItching\nShock, with a marked drop in blood pressure\nWhen to see a doctor\nSee your provider or an allergist if you or your child experiences milk allergy symptoms shortly after consuming milk. If possible, see your provider during the allergic reaction to help make a diagnosis. Seek emergency treatment if you or your child develops signs or symptoms of anaphylaxis.\nCauses\nAll true food allergies are caused by an immune system malfunction. If you have milk allergy, your immune system identifies certain milk proteins as harmful, triggering the production of immunoglobulin E (IgE) antibodies to neutralize the protein (allergen). The next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\n\n\nDocument[4]:\nThe next time you come in contact with these proteins, immunoglobulin E (IgE) antibodies recognize them and signal your immune system to release histamine and other chemicals, causing a range of allergic signs and symptoms.\nThere are two main proteins in cow's milk that can cause an allergic reaction:\nCasein, found in the solid part (curd) of milk that curdles\nWhey, found in the liquid part of milk that remains after milk curdles\nYou or your child may be allergic to only one milk protein or to both. These proteins may be hard to avoid because they're also in some processed foods. And most people who react to cow's milk will react to sheep, goat and buffalo milk.\nFood protein-induced enterocolitis syndrome (FPIES)\nA food allergen can also cause what's sometimes called a delayed food allergy. Although any food can be a trigger, milk is one of the most common. The reaction, commonly vomiting and diarrhea, usually occurs within hours after eating the trigger rather than within minutes.\nUnlike some food allergies, food protein-induced enterocolitis syndrome (FPIES) usually resolves over time. As with milk allergy, preventing an FPIES reaction involves avoiding milk and milk products.\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. \n\nDocument[5]:\nRisk factors\nCertain factors may increase the risk of developing milk allergy:\nOther allergies. Many children who are allergic to milk also have other allergies. Milk allergy may develop before other allergies.\nAtopic dermatitis. Children who have atopic dermatitis — a common, chronic inflammation of the skin — are much more likely to develop a food allergy.\nFamily history. A person's risk of a food allergy increases if one or both parents have a food allergy or another type of allergy or allergic disease — such as hay fever, asthma, hives or eczema.\nAge. Milk allergy is more common in children. As they age, their digestive systems mature, and their bodies are less likely to react to milk.\nComplications\nChildren who are allergic to milk are more likely to develop certain other health problems, including:\nNutritional deficiencies. Because of dietary restrictions and feeding challenges, children with milk allergy may have slowed growth as well as vitamin and mineral deficiencies.\nReduced quality of life. Many common, and sometimes unexpected, foods contain milk, including some salad dressings or even hot dogs. If you or your child is severely allergic, avoiding milk exposure may increase stress or anxiety levels when it comes to making food choices.\nPrevention\nThere's no sure way to prevent a food allergy, but you can prevent reactions by avoiding the food that causes them. If you know you or your child is allergic to milk, avoid milk and milk products.\nRead food labels carefully. \n\nDocument[6]:\nSoy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. You may need to exclude from your diet all products that contain milk. Talk to your health care provider if you know — or suspect — that your child has milk allergy and develops allergy signs and symptoms after breastfeeding.\nIf you or your child is on a milk-free diet, your health care provider or dietitian can help you plan nutritionally balanced meals. You or your child may need to take supplements to replace calcium and nutrients found in milk, such as vitamin D and riboflavin.\n\nDocument[7]:\nDoes your steak have melted butter on it? Was your seafood dipped in milk before cooking?\nIf you're at risk of a serious allergic reaction, talk with your health care provider about carrying and using emergency epinephrine (adrenaline). If you have already had a severe reaction, wear a medical alert bracelet or necklace that lets others know you have a food allergy.\nMilk alternatives for infants\nIn children who are allergic to milk, breastfeeding and the use of hypoallergenic formula can prevent allergic reactions.\nBreastfeeding is the best source of nutrition for your infant. Breastfeeding for as long as possible is recommended, especially if your infant is at high risk of developing milk allergy.\nHypoallergenic formulas are produced by using enzymes to break down (hydrolyze) milk proteins, such as casein or whey. Further processing can include heat and filtering. Depending on their level of processing, products are classified as either partially or extensively hydrolyzed. Or they may also be called elemental formulas.\nSome hypoallergenic formulas aren't milk based, but instead contain amino acids. Besides extensively hydrolyzed products, amino-acid-based formulas are the least likely to cause an allergic reaction.\nSoy-based formulas are based on soy protein instead of milk. Soy formulas are fortified to be nutritionally complete — but, unfortunately, some children with a milk allergy also develop an allergy to soy.\nIf you're breastfeeding and your child is allergic to milk, cow's milk proteins passed through your breast milk may cause an allergic reaction. \n\nDocument[8]:\nThey may include:\nHives\nItchy, irritated skin\nNasal stuffiness (congestion)\nSwelling of the lips, face, tongue and throat, or other parts of the body\nWheezing or trouble breathing\nCoughing and choking or a tight feeling in the throat\nBelly (abdominal) pain, diarrhea, nausea or vomiting\nDizziness, lightheadedness or fainting\nAnaphylaxis\nAllergies can cause a severe, potentially life-threatening allergic reaction known as anaphylaxis. It can occur within seconds to minutes after exposure to something you're allergic to — and worsens quickly.\nAn anaphylactic reaction to shellfish is a medical emergency. Anaphylaxis requires immediate treatment with an epinephrine (adrenaline) injection and a follow-up trip to the emergency room. If anaphylaxis isn't treated right away, it can be fatal.\nAnaphylaxis causes the immune system to release a flood of chemicals that can cause you to go into shock. Signs and symptoms of anaphylaxis include:\nA swollen throat or tongue or a tightness in the throat (airway constriction) that makes it difficult for you to breathe\nCoughing, choking or wheezing with trouble breathing\nShock, with a severe drop in your blood pressure and a rapid or weak pulse\nSevere skin rash, hives, itching or swelling\nNausea, vomiting or diarrhea\nDizziness, lightheadedness or fainting\nWhen to see a doctor\nSeek emergency treatment if you develop signs or symptoms of anaphylaxis.\nSee a health care provider or allergy specialist if you have food allergy symptoms shortly after eating.\nCauses\nAll food allergies are caused by an immune system overreaction. \n\nQuestion: What are milk allergy symptomps? <|eot_id|><|start_header_id|>assistant<|end_header_id|>",
"search": {
"created_at": "2024-12-09T12:33:30.371439Z",
"duration": 19.983364582061768,
"query": "What are milk allergy symptomps?",
"filters": {}
}
}
}
```
### Delete Feedback
You can delete feedback entries using the [Delete Feedback](/docs/api/main/delete-feedback-api-v-2-workspaces-workspace-id-pipelines-pipeline-id-feedback-feedback-id-delete) endpoint. You need the following IDs to do this:
- Workspace ID (check the workspace settings in
```python
url = "https://api.cloud.deepset.ai/api/v2/workspaces//pipelines//feedback/"
headers = {
"accept": "application/json",
"authorization": "Bearer "
}
response = requests.delete(url, headers=headers)
print(response)
```
```curl
curl --request DELETE \
--url https://api.cloud.deepset.ai/api/v2/workspaces//pipelines//feedback/ \
--header 'accept: application/json' \
--header 'authorization: Bearer '
```
# Example Colab Notebook
Use this Colab Notebook [](https://colab.research.google.com/drive/130ACcEGY0fEAuaAshZY0REclmkC2Zmmn#scrollTo=c84070bb-8a2e-47a2-a916-7c0a53ccf63e) to see how working with feedback through REST API works in practice. In the notebook, you:
- run a search on a pipeline.
- obtain all the necessary IDs.
- add, update, and delete feedback entries.
---
## Tutorial: Creating a Chat App Through REST API
# Tutorial: Creating a Chat App With REST API
Create a chat app that can answer questions about Python Enhancement Proposals (PEPs) using REST API endpoints.
***
- **Level**: Basic
- **Time to complete**: 15 minutes
- **Prerequisites**:
- You must have a basic understanding of REST API: HTTP methods, response and request structure, and basic concepts.
- Basic programming knowledge is a plus.
- You must have a
```python
url = "https://api.cloud.deepset.ai/api/v1/workspaces/peps/search_sessions" #legal-chat is the workspace name
payload = { "pipeline_id": "" } #insert the pipeline ID you got in the Get Pipeline response
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer " #insert your deepset API key
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/peps/search_sessions \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--data '
{
"pipeline_id": ""
}
'
```
As a response, you get the search session ID, which you'll need to start the chat:
```json
{
"search_session_id": "52bda5ec-23d9-4240-9d12-e7c48513158b"
}
```
### Start a Chat
Send your queries to the [Chat](/docs/api/main/chat-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-chat-post) endpoint to start chatting with your pipeline. You'll need to provide:
- your pipeline and workspace name (in the URL).
- your
```python
url = "https://api.cloud.deepset.ai/api/v1/workspaces/peps/pipelines/rag-chat/chat" #peps is the workspace name, rag-chat is the pipeline name
payload = {
"chat_history_limit": 3, # the number of chat history items to show in the chat
"debug": False,
"view_prompts": False,
"queries": ["How do you present datetime objects in human readable format?"], # the queries to ask
"search_session_id": "52bda5ec-23d9-4240-9d12-e7c48513158b" # ID of the search session
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"authorization": "Bearer " # your deepset API key
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
```curl
curl --request POST \
--url https://api.cloud.deepset.ai/api/v1/workspaces/peps/pipelines/rag-chat/chat \
--header 'accept: application/json' \
--header 'authorization: Bearer ' \
--header 'content-type: application/json' \
--data '
{
"chat_history_limit": 3,
"debug": false,
"view_prompts": false,
"queries": [
"How do you present datetime objects in human readable format?"
],
"search_session_id": "52bda5ec-23d9-4240-9d12-e7c48513158b"
}
'
```
Sample response
```json
{
"query_id": "036b2866-2703-4d59-823d-9d8e683c7fa1",
"results": [
{
"query_id": "036b2866-2703-4d59-823d-9d8e683c7fa1",
"query": "How do you present datetime objects in human readable format?",
"answers": [
{
"answer": "To present datetime objects in a human-readable format, you can use the `strftime()` method provided by the `datetime` class. This method allows you to specify the format of the output string using format specifiers that correspond to various components of the date and time. For example, you can format a datetime object to display the date and time in a readable format like \"Today is: {0:%a %b %d %H:%M:%S %Y}\". This would output a string such as \"Today is: Mon Sep 16 10:34:54 2023\" . Additionally, the `isoformat()` and `ctime()` methods on datetime objects return string representations of the time in ISO 8601 format and a more traditional format similar to the C function `asctime()`, respectively .",
"type": "generative",
"score": null,
"context": null,
"offsets_in_document": [],
"offsets_in_context": [],
"document_id": null,
"document_ids": [
"7001548c9e254ad0d2a35c1fea7a93ebaca5edc7f7e58ccbdf9bb2c665960040",
"b4f79b5862793f5fa1c3f9b669a1c27e1a9aa9cff9b6481fa0de2513b3c3264d",
"edbc2088c4f9922d1e38554a6e1919508f3d739682abb07769ff14bcfd53c132",
"a83b9c8fdf043d00e92fe0247e5913ea5de8234b6c5a793efbafd410f01e418b",
"bdf4d62f2f52e9a3d1e87e6e41b9679ada4a930c321d33d3e77544c137cb88fb",
"d707bfed2ede5435c51068efc5690033457d7e3106572b2221ee30097e16c20e",
"66722fd08f8adab75357847e2d8ab324d6175816435c99063e2c2d8a96171d74",
"d9878e926481ac189a88db4f7ed36cb64cd9e28bd58c450ee11c2731dba935d6"
],
"meta": {
"_references": [
{
"answer_end_idx": 487,
"answer_start_idx": 487,
"document_id": "edbc2088c4f9922d1e38554a6e1919508f3d739682abb07769ff14bcfd53c132",
"document_position": 3,
"label": "grounded",
"score": 0,
"doc_end_idx": 1607,
"doc_start_idx": 0,
"origin": "llm"
},
{
"answer_end_idx": 706,
"answer_start_idx": 706,
"document_id": "7001548c9e254ad0d2a35c1fea7a93ebaca5edc7f7e58ccbdf9bb2c665960040",
"document_position": 1,
"label": "grounded",
"score": 0,
"doc_end_idx": 1738,
"doc_start_idx": 0,
"origin": "llm"
}
]
},
"file": {
"id": "3ee143f6-47b8-4ceb-bd69-0b0eede32aac",
"name": "pep-0321.txt"
},
"files": [
{
"id": "3ee143f6-47b8-4ceb-bd69-0b0eede32aac",
"name": "pep-0321.txt"
},
{
"id": "c549dad4-9306-417e-9e31-72eff4db300c",
"name": "pep-0498.txt"
},
{
"id": "d6987234-60e7-4651-864d-017631ca53b3",
"name": "pep-3101.txt"
},
{
"id": "25a9a573-222b-4fc4-b284-a776903ed1ea",
"name": "pep-0495.txt"
},
{
"id": "5eda3f1a-74b9-4887-9772-35ca44be1e99",
"name": "pep-0410.txt"
},
{
"id": "cf52312b-26b9-4ded-ac2b-cb6faf344a86",
"name": "pep-0500.txt"
},
{
"id": "a8a8d83e-6696-46c7-9ebf-3a953da41132",
"name": "pep-0519.txt"
}
],
"result_id": "7ec72d79-639a-4291-8258-86a173ec02ae",
"prompt": "You are a technical expert.\nYou answer questions truthfully based on provided documents.\nIf the answer exists in several documents, summarize them.\nIgnore documents that don't contain the answer to the question.\nOnly answer based on the documents provided. Don't make things up.\nIf no information related to the question can be found in the document, say so.\nAlways use references in the form [NUMBER OF DOCUMENT] when using information from a document, e.g. [3] for Document[3].\nNever name the documents, only enter a number in square brackets as a reference.\nThe reference must only refer to the number that comes in square brackets after the document.\nOtherwise, do not use brackets in your answer and reference ONLY the number of the document without mentioning the word document.\nThese are the documents:\n\nDocument[1]:\nPEP: 321\nTitle: Date/Time Parsing and Formatting\nVersion: $Revision$\nLast-Modified: $Date$\nAuthor: A.M. Kuchling \nStatus: Withdrawn\nType: Standards Track\nContent-Type: text/x-rst\nCreated: 16-Sep-2003\nPython-Version: 2.4\nPost-History:\n\n\nAbstract\n========\n\nPython 2.3 added a number of simple date and time types in the\n``datetime`` module. There's no support for parsing strings in various\nformats and returning a corresponding instance of one of the types.\nThis PEP proposes adding a family of predefined parsing function for\nseveral commonly used date and time formats, and a facility for generic\nparsing.\n\nThe types provided by the ``datetime`` module all have\n``.isoformat()`` and ``.ctime()`` methods that return string\nrepresentations of a time, and the ``.strftime()`` method can be used\nto construct new formats. There are a number of additional\ncommonly-used formats that would be useful to have as part of the\nstandard library; this PEP also suggests how to add them.\n\n\nInput Formats\n=======================\n\nUseful formats to support include:\n\n* `ISO8601`_\n* ARPA/:rfc:`2822`\n* `ctime`_\n* Formats commonly written by humans such as the American\n \"MM/DD/YYYY\", the European \"YYYY/MM/DD\", and variants such as\n \"DD-Month-YYYY\".\n* CVS-style or tar-style dates (\"tomorrow\", \"12 hours ago\", etc.)\n\nXXX The Perl `ParseDate.pm`_ module supports many different input formats,\nboth absolute and relative. Should we try to support them all?\n\nOptions:\n\n1) Add functions to the ``datetime`` module::\n\n import datetime\n d = datetime.parse_iso8601(\"2003-09-15T10:34:54\")\n\n2) Add class methods to the various types. There are already various\n class methods such as ``.now()``, so this would be pretty natural.\n\nDocument[2]:\nHowever, ``str.format()`` is not without its issues. Chief among them\nis its verbosity. For example, the text ``value`` is repeated here::\n\n >>> value = 4 * 20\n >>> 'The value is {value}.'.format(value=value)\n 'The value is 80.'Even in its simplest form there is a bit of boilerplate, and the value\nthat's inserted into the placeholder is sometimes far removed from\nwhere the placeholder is situated::\n\n >>> 'The value is {}.'.format(value)\n 'The value is 80.'With an f-string, this becomes::\n\n >>> f'The value is {value}.''The value is 80.'F-strings provide a concise, readable way to include the value of\nPython expressions inside strings.\n\nIn this sense, ``string.Template`` and %-formatting have similar\nshortcomings to ``str.format()``, but also support fewer formatting\noptions. In particular, they do not support the ``__format__``\nprotocol, so that there is no way to control how a specific object is\nconverted to a string, nor can it be extended to additional types that\nwant to control how they are converted to strings (such as ``Decimal``\nand ``datetime``). This example is not possible with\n``string.Template``::\n\n >>> value = 1234\n >>> f'input={value:#06x}'\n 'input=0x04d2'\n\nAnd neither %-formatting nor ``string.Template`` can control\nformatting such as::\n\n >>> date = datetime.date(1991, 10, 12)\n >>> f'{date} was on a {date:%A}'\n '1991-10-12 was on a Saturday'\n\nNo use of globals() or locals()\n-------------------------------\n\nIn the discussions on python-dev [#]_, a number of solutions where\npresented that used locals() and globals() or their equivalents. All\nof these have various problems. \n\nDocument[3]:\nSame as 'g' except switches to 'E'\n if the number gets to large.\n 'n' - Number. This is the same as 'g', except that it uses the\n current locale setting to insert the appropriate\n number separator characters.\n '%' - Percentage. Multiplies the number by 100 and displays\n in fixed ('f') format, followed by a percent sign.\n '' (None) - similar to 'g', except that it prints at least one\n digit after the decimal point.\n\nObjects are able to define their own format specifiers to\nreplace the standard ones. An example is the 'datetime' class,\nwhose format specifiers might look something like the\narguments to the ``strftime()`` function::\n\n \"Today is: {0:%a %b %d %H:%M:%S %Y}\".format(datetime.now())\n\nFor all built-in types, an empty format specification will produce\nthe equivalent of ``str(value)``. It is recommended that objects\ndefining their own format specifiers follow this convention as\nwell.\n\n\nExplicit Conversion Flag\n------------------------\n\nThe explicit conversion flag is used to transform the format field value\nbefore it is formatted. This can be used to override the type-specific\nformatting behavior, and format the value as if it were a more\ngeneric type. Currently, two explicit conversion flags are\nrecognized::\n\n !r - convert the value to a string using repr().\n !s - convert the value to a string using str().\n\nThese flags are placed before the format specifier::\n\n \"{0!r:20}\".format(\"Hello\")\n\nIn the preceding example, the string \"Hello\" will be printed, with quotes,\nin a field of at least 20 characters width.\n\n\n\nDocument[4]:\nOnly complicated formats need to be supported; :rfc:`2822`\nis currently the only one I can think of.\n\nOptions:\n\n1) Provide predefined format strings, so you could write this::\n\n import datetime\n d = datetime.datetime(...)\n print d.strftime(d.RFC2822_FORMAT) # or datetime.RFC2822_FORMAT?\n\n2) Provide new methods on all the objects::\n\n d = datetime.datetime(...)\n print d.rfc822_time()\n\n\nRelevant functionality in other languages includes the `PHP date`_\nfunction (Python implementation by Simon Willison at\nhttp://simon.incutio.com/archive/2003/10/07/dateInPython)\n\n\nReferences\n==========\n\n.. _ISO8601: http://www.cl.cam.ac.uk/~mgk25/iso-time.html\n\n.. _ParseDate.pm: http://search.cpan.org/author/MUIR/Time-modules-2003.0211/lib/Time/ParseDate.pm\n\n.. _ctime: http://www.opengroup.org/onlinepubs/007908799/xsh/asctime.html\n\n.. _PHP date: http://www.php.net/date\n\nOther useful links:\n\nhttp://www.egenix.com/files/python/mxDateTime.html\nhttp://ringmaster.arc.nasa.gov/tools/time_formats.html\nhttp://www.thinkage.ca/english/gcos/expl/b/lib/0tosec.html\nhttps://moin.conectiva.com.br/DateUtil\n\n\nCopyright\n=========\n\nThis document has been placed in the public domain.\n\n\n\f\n..\n Local Variables:\n mode: indented-text\n indent-tabs-mode: nil\n sentence-end-double-space: t\n fill-column: 70\n End:\n\nDocument[5]:\nOnly datetime/time instances with ``fold=1`` pickled\nin the new versions will become unreadable by the older Python\nversions. Pickles of instances with ``fold=0`` (which is the\ndefault) will remain unchanged.\n\n\nQuestions and Answers\n=====================\n\nWhy not call the new flag \"isdst\"?\n----------------------------------\n\nA non-technical answer\n......................\n\n* Alice: Bob - let's have a stargazing party at 01:30 AM tomorrow!\n* Bob: Should I presume initially that Daylight Saving Time is or is\n not in effect for the specified time?\n* Alice: Huh?\n\n-------\n\n* Bob: Alice - let's have a stargazing party at 01:30 AM tomorrow!\n* Alice: You know, Bob, 01:30 AM will happen twice tomorrow. Which time do you have in mind?\n* Bob: I did not think about it, but let's pick the first.\n\n-------\n\n(same characters, an hour later)\n\n-------\n\n* Bob: Alice - this Py-O-Clock gadget of mine asks me to choose\n between fold=0 and fold=1 when I set it for tomorrow 01:30 AM.\n What should I do?\n* Alice: I've never hear of a Py-O-Clock, but I guess fold=0 is\n the first 01:30 AM and fold=1 is the second.\n\n\nA technical reason\n..................\n\nWhile the ``tm_isdst`` field of the ``time.struct_time`` object can be\nused to disambiguate local times in the fold, the semantics of such\ndisambiguation are completely different from the proposal in this PEP.\n\n\n\nDocument[6]:\nThere is also an ordering issues with daylight saving time (DST) in\nthe duplicate hour of switching from DST to normal time.\n\ndatetime.datetime has been rejected because it cannot be used for functions\nusing an unspecified starting point like os.times() or time.clock().\n\nFor time.time() and time.clock_gettime(time.CLOCK_GETTIME): it is already\npossible to get the current time as a datetime.datetime object using::\n\n datetime.datetime.now(datetime.timezone.utc)\n\nFor os.stat(), it is simple to create a datetime.datetime object from a\ndecimal.Decimal timestamp in the UTC timezone::\n\n datetime.datetime.fromtimestamp(value, datetime.timezone.utc)\n\n.. note::\n datetime.datetime only supports microsecond resolution, but can be enhanced\n to support nanosecond.\n\ndatetime.timedelta\n------------------\n\ndatetime.timedelta is the natural choice for a relative timestamp because it is\nclear that this type contains a timestamp, whereas int, float and Decimal are\nraw numbers. It can be used with datetime.datetime to get an absolute timestamp\nwhen the starting point is known.\n\ndatetime.timedelta has been rejected because it cannot be coerced to float and\nhas a fixed resolution. One new standard timestamp type is enough, Decimal is\npreferred over datetime.timedelta. Converting a datetime.timedelta to float\nrequires an explicit call to the datetime.timedelta.total_seconds() method.\n\n.. note::\n datetime.timedelta only supports microsecond resolution, but can be enhanced\n to support nanosecond.\n\n\n.. _tuple:\n\nTuple of integers\n-----------------\n\nTo expose C functions in Python, a tuple of integers is the natural choice to\nstore a timestamp because the C language uses structures with integers fields\n(e.g. timeval and timespec structures). Using only integers avoids the loss of\nprecision (Python supports integers of arbitrary length). \n\nDocument[7]:\nPEP: 500\nTitle: A protocol for delegating datetime methods to their tzinfo implementations\nVersion: $Revision$\nLast-Modified: $Date$\nAuthor: Alexander Belopolsky , Tim Peters \nDiscussions-To: datetime-sig@python.org\nStatus: Rejected\nType: Standards Track\nContent-Type: text/x-rst\nRequires: 495\nCreated: 08-Aug-2015\nResolution: https://mail.python.org/pipermail/datetime-sig/2015-August/000354.html\n\nAbstract\n========\n\nThis PEP specifies a new protocol (PDDM - \"A Protocol for Delegating\nDatetime Methods\") that can be used by concrete implementations of the\n``datetime.tzinfo`` interface to override aware datetime arithmetics,\nformatting and parsing. We describe changes to the\n``datetime.datetime`` class to support the new protocol and propose a\nnew abstract class ``datetime.tzstrict`` that implements parts of this\nprotocol necessary to make aware datetime instances to follow \"strict\"\narithmetic rules.\n\n\nRationale\n=========\n\nAs of Python 3.5, aware datetime instances that share a ``tzinfo``\nobject follow the rules of arithmetics that are induced by a simple\nbijection between (year, month, day, hour, minute, second,\nmicrosecond) 7-tuples and large integers. In this arithmetics, the\ndifference between YEAR-11-02T12:00 and YEAR-11-01T12:00 is always 24\nhours, even though in the US/Eastern timezone, for example, there are\n25 hours between 2014-11-01T12:00 and 2014-11-02T12:00 because the\nlocal clocks were rolled back one hour at 2014-11-02T02:00,\nintroducing an extra hour in the night between 2014-11-01 and\n2014-11-02.\n\nMany business applications require the use of Python's simplified view\nof local dates. No self-respecting car rental company will charge its\ncustomers more for a week that straddles the end of DST than for any\nother week or require that they return the car an hour early.\n\n\nDocument[8]:\nOne part is the proposal of a\nprotocol for objects to declare and provide support for exposing a\nfile system path representation. The other part deals with changes to\nPython's standard library to support the new protocol. These changes\nwill also lead to the pathlib module dropping its provisional status.\n\nProtocol\n--------\n\nThe following abstract base class defines the protocol for an object\nto be considered a path object::\n\n import abc\n import typing as t\n\n\n class PathLike(abc.ABC):\n\n \"\"\"Abstract base class for implementing the file system path protocol.\"\"\"@abc.abstractmethod\n def __fspath__(self) -> t.Union[str, bytes]:\n \"\"\"Return the file system path representation of the object.\"\"\"raise NotImplementedError\n\n\nObjects representing file system paths will implement the\n``__fspath__()`` method which will return the ``str`` or ``bytes``\nrepresentation of the path. The ``str`` representation is the\npreferred low-level path representation as it is human-readable and\nwhat people historically represent paths as.\n\n\nStandard library changes\n------------------------\n\nIt is expected that most APIs in Python's standard library that\ncurrently accept a file system path will be updated appropriately to\naccept path objects (whether that requires code or simply an update\nto documentation will vary). The modules mentioned below, though,\ndeserve specific details as they have either fundamental changes that\nempower the ability to use path objects, or entail additions/removal\nof APIs.\n\n\nbuiltins\n''''''''\n\n``open()`` [#builtins-open]_ will be updated to accept path objects as\nwell as continue to accept ``str`` and ``bytes``.\n\n\n\n\nQuestion: How do you present datetime objects in human readable format?\nAnswer:"
}
],
"documents": [
{
"id": "7001548c9e254ad0d2a35c1fea7a93ebaca5edc7f7e58ccbdf9bb2c665960040",
"content": "PEP: 321\nTitle: Date/Time Parsing and Formatting\nVersion: $Revision$\nLast-Modified: $Date$\nAuthor: A.M. Kuchling \nStatus: Withdrawn\nType: Standards Track\nContent-Type: text/x-rst\nCreated: 16-Sep-2003\nPython-Version: 2.4\nPost-History:\n\n\nAbstract\n========\n\nPython 2.3 added a number of simple date and time types in the\n``datetime`` module. There's no support for parsing strings in various\nformats and returning a corresponding instance of one of the types.\nThis PEP proposes adding a family of predefined parsing function for\nseveral commonly used date and time formats, and a facility for generic\nparsing.\n\nThe types provided by the ``datetime`` module all have\n``.isoformat()`` and ``.ctime()`` methods that return string\nrepresentations of a time, and the ``.strftime()`` method can be used\nto construct new formats. There are a number of additional\ncommonly-used formats that would be useful to have as part of the\nstandard library; this PEP also suggests how to add them.\n\n\nInput Formats\n=======================\n\nUseful formats to support include:\n\n* `ISO8601`_\n* ARPA/:rfc:`2822`\n* `ctime`_\n* Formats commonly written by humans such as the American\n \"MM/DD/YYYY\", the European \"YYYY/MM/DD\", and variants such as\n \"DD-Month-YYYY\".\n* CVS-style or tar-style dates (\"tomorrow\", \"12 hours ago\", etc.)\n\nXXX The Perl `ParseDate.pm`_ module supports many different input formats,\nboth absolute and relative. Should we try to support them all?\n\nOptions:\n\n1) Add functions to the ``datetime`` module::\n\n import datetime\n d = datetime.parse_iso8601(\"2003-09-15T10:34:54\")\n\n2) Add class methods to the various types. There are already various\n class methods such as ``.now()``, so this would be pretty natural.",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
0,
279
],
"doc_id": "850d4b3a9055c249407bc6c2577ffd340ffb1e297f532513274d584b899f42c0"
}
],
"split_idx_start": 0,
"file_name": "pep-0321.txt",
"_file_created_at": "2024-10-18T09:04:08.908838+00:00",
"split_id": 0,
"_file_size": 4372,
"page_number": 1,
"source_id": "0f5123e030c45b644e8c5db6c65c4beadbf11c82bf30e48a99f7b9ed02c696e9"
},
"score": 0.09124755859375,
"embedding": null,
"file": {
"id": "3ee143f6-47b8-4ceb-bd69-0b0eede32aac",
"name": "pep-0321.txt"
},
"result_id": "f93ab9cc-76ec-4120-9cfe-e6ac374b6684"
},
{
"id": "b4f79b5862793f5fa1c3f9b669a1c27e1a9aa9cff9b6481fa0de2513b3c3264d",
"content": "However, ``str.format()`` is not without its issues. Chief among them\nis its verbosity. For example, the text ``value`` is repeated here::\n\n >>> value = 4 * 20\n >>> 'The value is {value}.'.format(value=value)\n 'The value is 80.'Even in its simplest form there is a bit of boilerplate, and the value\nthat's inserted into the placeholder is sometimes far removed from\nwhere the placeholder is situated::\n\n >>> 'The value is {}.'.format(value)\n 'The value is 80.'With an f-string, this becomes::\n\n >>> f'The value is {value}.''The value is 80.'F-strings provide a concise, readable way to include the value of\nPython expressions inside strings.\n\nIn this sense, ``string.Template`` and %-formatting have similar\nshortcomings to ``str.format()``, but also support fewer formatting\noptions. In particular, they do not support the ``__format__``\nprotocol, so that there is no way to control how a specific object is\nconverted to a string, nor can it be extended to additional types that\nwant to control how they are converted to strings (such as ``Decimal``\nand ``datetime``). This example is not possible with\n``string.Template``::\n\n >>> value = 1234\n >>> f'input={value:#06x}'\n 'input=0x04d2'\n\nAnd neither %-formatting nor ``string.Template`` can control\nformatting such as::\n\n >>> date = datetime.date(1991, 10, 12)\n >>> f'{date} was on a {date:%A}'\n '1991-10-12 was on a Saturday'\n\nNo use of globals() or locals()\n-------------------------------\n\nIn the discussions on python-dev [#]_, a number of solutions where\npresented that used locals() and globals() or their equivalents. All\nof these have various problems. ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1194,
1425
],
"doc_id": "d873a90f56222b0c02ef2987a6ef2390aa5f7400bb6f8fe5c1cfafebaba3a9d4"
},
{
"range": [
0,
548
],
"doc_id": "76db0307a81ca4d9012184b0066414935f4342f14219f177170a61737d6bfd2c"
}
],
"split_idx_start": 3396,
"file_name": "pep-0498.txt",
"_file_created_at": "2024-10-18T09:03:54.839485+00:00",
"split_id": 3,
"_file_size": 25320,
"page_number": 1,
"source_id": "51927b0152d7c0504de7a4e0a4f5265617143fce6a5f763d17118f6afdc92298"
},
"score": 0.06280517578125,
"embedding": null,
"file": {
"id": "c549dad4-9306-417e-9e31-72eff4db300c",
"name": "pep-0498.txt"
},
"result_id": "0c46d7af-4542-4b1e-ac23-95d5d2bdbc7c"
},
{
"id": "edbc2088c4f9922d1e38554a6e1919508f3d739682abb07769ff14bcfd53c132",
"content": "Same as 'g' except switches to 'E'\n if the number gets to large.\n 'n' - Number. This is the same as 'g', except that it uses the\n current locale setting to insert the appropriate\n number separator characters.\n '%' - Percentage. Multiplies the number by 100 and displays\n in fixed ('f') format, followed by a percent sign.\n '' (None) - similar to 'g', except that it prints at least one\n digit after the decimal point.\n\nObjects are able to define their own format specifiers to\nreplace the standard ones. An example is the 'datetime' class,\nwhose format specifiers might look something like the\narguments to the ``strftime()`` function::\n\n \"Today is: {0:%a %b %d %H:%M:%S %Y}\".format(datetime.now())\n\nFor all built-in types, an empty format specification will produce\nthe equivalent of ``str(value)``. It is recommended that objects\ndefining their own format specifiers follow this convention as\nwell.\n\n\nExplicit Conversion Flag\n------------------------\n\nThe explicit conversion flag is used to transform the format field value\nbefore it is formatted. This can be used to override the type-specific\nformatting behavior, and format the value as if it were a more\ngeneric type. Currently, two explicit conversion flags are\nrecognized::\n\n !r - convert the value to a string using repr().\n !s - convert the value to a string using str().\n\nThese flags are placed before the format specifier::\n\n \"{0!r:20}\".format(\"Hello\")\n\nIn the preceding example, the string \"Hello\" will be printed, with quotes,\nin a field of at least 20 characters width.\n\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1386,
1647
],
"doc_id": "0080ddf63825baab764048b3e068878bd23701f44610365cd5808be57d4fe36d"
},
{
"range": [
0,
255
],
"doc_id": "2629b8672811bd4a8a6da1adaa55dc166d2fc0e3ba1b8336690e7599c77cc5f2"
}
],
"split_idx_start": 12752,
"file_name": "pep-3101.txt",
"_file_created_at": "2024-10-18T09:03:29.826858+00:00",
"split_id": 11,
"_file_size": 33149,
"page_number": 1,
"source_id": "b42e3a8de46bd3686eb4e0ec3015b34e916f424f29e9398acb58d062e89c15bf"
},
"score": 0.05792236328125,
"embedding": null,
"file": {
"id": "d6987234-60e7-4651-864d-017631ca53b3",
"name": "pep-3101.txt"
},
"result_id": "e497e02b-3aa9-498c-b687-fc850ed4398f"
},
{
"id": "a83b9c8fdf043d00e92fe0247e5913ea5de8234b6c5a793efbafd410f01e418b",
"content": "Only complicated formats need to be supported; :rfc:`2822`\nis currently the only one I can think of.\n\nOptions:\n\n1) Provide predefined format strings, so you could write this::\n\n import datetime\n d = datetime.datetime(...)\n print d.strftime(d.RFC2822_FORMAT) # or datetime.RFC2822_FORMAT?\n\n2) Provide new methods on all the objects::\n\n d = datetime.datetime(...)\n print d.rfc822_time()\n\n\nRelevant functionality in other languages includes the `PHP date`_\nfunction (Python implementation by Simon Willison at\nhttp://simon.incutio.com/archive/2003/10/07/dateInPython)\n\n\nReferences\n==========\n\n.. _ISO8601: http://www.cl.cam.ac.uk/~mgk25/iso-time.html\n\n.. _ParseDate.pm: http://search.cpan.org/author/MUIR/Time-modules-2003.0211/lib/Time/ParseDate.pm\n\n.. _ctime: http://www.opengroup.org/onlinepubs/007908799/xsh/asctime.html\n\n.. _PHP date: http://www.php.net/date\n\nOther useful links:\n\nhttp://www.egenix.com/files/python/mxDateTime.html\nhttp://ringmaster.arc.nasa.gov/tools/time_formats.html\nhttp://www.thinkage.ca/english/gcos/expl/b/lib/0tosec.html\nhttps://moin.conectiva.com.br/DateUtil\n\n\nCopyright\n=========\n\nThis document has been placed in the public domain.\n\n\n\f\n..\n Local Variables:\n mode: indented-text\n indent-tabs-mode: nil\n sentence-end-double-space: t\n fill-column: 70\n End:",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1582,
1892
],
"doc_id": "850d4b3a9055c249407bc6c2577ffd340ffb1e297f532513274d584b899f42c0"
}
],
"split_idx_start": 3041,
"file_name": "pep-0321.txt",
"_file_created_at": "2024-10-18T09:04:08.908838+00:00",
"split_id": 2,
"_file_size": 4372,
"page_number": 1,
"source_id": "0f5123e030c45b644e8c5db6c65c4beadbf11c82bf30e48a99f7b9ed02c696e9"
},
"score": 0.02606201171875,
"embedding": null,
"file": {
"id": "3ee143f6-47b8-4ceb-bd69-0b0eede32aac",
"name": "pep-0321.txt"
},
"result_id": "0956c775-a701-40e9-b914-5fdf82c42f19"
},
{
"id": "bdf4d62f2f52e9a3d1e87e6e41b9679ada4a930c321d33d3e77544c137cb88fb",
"content": "Only datetime/time instances with ``fold=1`` pickled\nin the new versions will become unreadable by the older Python\nversions. Pickles of instances with ``fold=0`` (which is the\ndefault) will remain unchanged.\n\n\nQuestions and Answers\n=====================\n\nWhy not call the new flag \"isdst\"?\n----------------------------------\n\nA non-technical answer\n......................\n\n* Alice: Bob - let's have a stargazing party at 01:30 AM tomorrow!\n* Bob: Should I presume initially that Daylight Saving Time is or is\n not in effect for the specified time?\n* Alice: Huh?\n\n-------\n\n* Bob: Alice - let's have a stargazing party at 01:30 AM tomorrow!\n* Alice: You know, Bob, 01:30 AM will happen twice tomorrow. Which time do you have in mind?\n* Bob: I did not think about it, but let's pick the first.\n\n-------\n\n(same characters, an hour later)\n\n-------\n\n* Bob: Alice - this Py-O-Clock gadget of mine asks me to choose\n between fold=0 and fold=1 when I set it for tomorrow 01:30 AM.\n What should I do?\n* Alice: I've never hear of a Py-O-Clock, but I guess fold=0 is\n the first 01:30 AM and fold=1 is the second.\n\n\nA technical reason\n..................\n\nWhile the ``tm_isdst`` field of the ``time.struct_time`` object can be\nused to disambiguate local times in the fold, the semantics of such\ndisambiguation are completely different from the proposal in this PEP.\n\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1389,
1681
],
"doc_id": "a1270e82b4dbf104c429342bb71fb0a7fc80db41719f0d2a79ffa88215e9ced6"
},
{
"range": [
0,
211
],
"doc_id": "ea7d03dac129035cacbb28d07304048f31e99487736aecb2df16b8903874ccca"
}
],
"split_idx_start": 23551,
"file_name": "pep-0495.txt",
"_file_created_at": "2024-10-18T09:03:54.819307+00:00",
"split_id": 18,
"_file_size": 34899,
"page_number": 1,
"source_id": "04ae5810b522e53d51d5bb1f7e708f045a1e09977cde5b7e18a54646ffa0575f"
},
"score": 0.020294189453125,
"embedding": null,
"file": {
"id": "25a9a573-222b-4fc4-b284-a776903ed1ea",
"name": "pep-0495.txt"
},
"result_id": "77aed3e6-8840-4edf-a532-e9b66375b1e2"
},
{
"id": "d707bfed2ede5435c51068efc5690033457d7e3106572b2221ee30097e16c20e",
"content": "There is also an ordering issues with daylight saving time (DST) in\nthe duplicate hour of switching from DST to normal time.\n\ndatetime.datetime has been rejected because it cannot be used for functions\nusing an unspecified starting point like os.times() or time.clock().\n\nFor time.time() and time.clock_gettime(time.CLOCK_GETTIME): it is already\npossible to get the current time as a datetime.datetime object using::\n\n datetime.datetime.now(datetime.timezone.utc)\n\nFor os.stat(), it is simple to create a datetime.datetime object from a\ndecimal.Decimal timestamp in the UTC timezone::\n\n datetime.datetime.fromtimestamp(value, datetime.timezone.utc)\n\n.. note::\n datetime.datetime only supports microsecond resolution, but can be enhanced\n to support nanosecond.\n\ndatetime.timedelta\n------------------\n\ndatetime.timedelta is the natural choice for a relative timestamp because it is\nclear that this type contains a timestamp, whereas int, float and Decimal are\nraw numbers. It can be used with datetime.datetime to get an absolute timestamp\nwhen the starting point is known.\n\ndatetime.timedelta has been rejected because it cannot be coerced to float and\nhas a fixed resolution. One new standard timestamp type is enough, Decimal is\npreferred over datetime.timedelta. Converting a datetime.timedelta to float\nrequires an explicit call to the datetime.timedelta.total_seconds() method.\n\n.. note::\n datetime.timedelta only supports microsecond resolution, but can be enhanced\n to support nanosecond.\n\n\n.. _tuple:\n\nTuple of integers\n-----------------\n\nTo expose C functions in Python, a tuple of integers is the natural choice to\nstore a timestamp because the C language uses structures with integers fields\n(e.g. timeval and timespec structures). Using only integers avoids the loss of\nprecision (Python supports integers of arbitrary length). ",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1272,
1544
],
"doc_id": "2f29a4a6323783368c1160597feb0d31e710bffb8f3df64f28bc205d88de1698"
},
{
"range": [
0,
342
],
"doc_id": "c7a17a8edafad008f36b5244fcd85b81d3cb50261f11ba6159fe1297112fb956"
}
],
"split_idx_start": 8032,
"file_name": "pep-0410.txt",
"_file_created_at": "2024-10-18T09:04:01.074298+00:00",
"split_id": 6,
"_file_size": 20703,
"page_number": 1,
"source_id": "0a5ffe8e2eae3b854132370ba3ee43c31cba6d88fb72c635690acb723fcadeae"
},
"score": 0.019683837890625,
"embedding": null,
"file": {
"id": "5eda3f1a-74b9-4887-9772-35ca44be1e99",
"name": "pep-0410.txt"
},
"result_id": "fd0e6f52-d944-4642-bc66-61b852960cc8"
},
{
"id": "66722fd08f8adab75357847e2d8ab324d6175816435c99063e2c2d8a96171d74",
"content": "PEP: 500\nTitle: A protocol for delegating datetime methods to their tzinfo implementations\nVersion: $Revision$\nLast-Modified: $Date$\nAuthor: Alexander Belopolsky , Tim Peters \nDiscussions-To: datetime-sig@python.org\nStatus: Rejected\nType: Standards Track\nContent-Type: text/x-rst\nRequires: 495\nCreated: 08-Aug-2015\nResolution: https://mail.python.org/pipermail/datetime-sig/2015-August/000354.html\n\nAbstract\n========\n\nThis PEP specifies a new protocol (PDDM - \"A Protocol for Delegating\nDatetime Methods\") that can be used by concrete implementations of the\n``datetime.tzinfo`` interface to override aware datetime arithmetics,\nformatting and parsing. We describe changes to the\n``datetime.datetime`` class to support the new protocol and propose a\nnew abstract class ``datetime.tzstrict`` that implements parts of this\nprotocol necessary to make aware datetime instances to follow \"strict\"\narithmetic rules.\n\n\nRationale\n=========\n\nAs of Python 3.5, aware datetime instances that share a ``tzinfo``\nobject follow the rules of arithmetics that are induced by a simple\nbijection between (year, month, day, hour, minute, second,\nmicrosecond) 7-tuples and large integers. In this arithmetics, the\ndifference between YEAR-11-02T12:00 and YEAR-11-01T12:00 is always 24\nhours, even though in the US/Eastern timezone, for example, there are\n25 hours between 2014-11-01T12:00 and 2014-11-02T12:00 because the\nlocal clocks were rolled back one hour at 2014-11-02T02:00,\nintroducing an extra hour in the night between 2014-11-01 and\n2014-11-02.\n\nMany business applications require the use of Python's simplified view\nof local dates. No self-respecting car rental company will charge its\ncustomers more for a week that straddles the end of DST than for any\nother week or require that they return the car an hour early.\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
0,
185
],
"doc_id": "2491a8b58f7bb1979fdf5061006dfc72c54b6e9e287f06f9b8a5dd669967c874"
}
],
"split_idx_start": 0,
"file_name": "pep-0500.txt",
"_file_created_at": "2024-10-18T09:03:51.944443+00:00",
"split_id": 0,
"_file_size": 7045,
"page_number": 1,
"source_id": "5180621105b359308fb5b39c5455b227c26cb8533a69672335202ed14e8d568d"
},
"score": 0.018798828125,
"embedding": null,
"file": {
"id": "cf52312b-26b9-4ded-ac2b-cb6faf344a86",
"name": "pep-0500.txt"
},
"result_id": "623d6f02-476c-4110-83e9-92186bc055b9"
},
{
"id": "d9878e926481ac189a88db4f7ed36cb64cd9e28bd58c450ee11c2731dba935d6",
"content": "One part is the proposal of a\nprotocol for objects to declare and provide support for exposing a\nfile system path representation. The other part deals with changes to\nPython's standard library to support the new protocol. These changes\nwill also lead to the pathlib module dropping its provisional status.\n\nProtocol\n--------\n\nThe following abstract base class defines the protocol for an object\nto be considered a path object::\n\n import abc\n import typing as t\n\n\n class PathLike(abc.ABC):\n\n \"\"\"Abstract base class for implementing the file system path protocol.\"\"\"@abc.abstractmethod\n def __fspath__(self) -> t.Union[str, bytes]:\n \"\"\"Return the file system path representation of the object.\"\"\"raise NotImplementedError\n\n\nObjects representing file system paths will implement the\n``__fspath__()`` method which will return the ``str`` or ``bytes``\nrepresentation of the path. The ``str`` representation is the\npreferred low-level path representation as it is human-readable and\nwhat people historically represent paths as.\n\n\nStandard library changes\n------------------------\n\nIt is expected that most APIs in Python's standard library that\ncurrently accept a file system path will be updated appropriately to\naccept path objects (whether that requires code or simply an update\nto documentation will vary). The modules mentioned below, though,\ndeserve specific details as they have either fundamental changes that\nempower the ability to use path objects, or entail additions/removal\nof APIs.\n\n\nbuiltins\n''''''''\n\n``open()`` [#builtins-open]_ will be updated to accept path objects as\nwell as continue to accept ``str`` and ``bytes``.\n\n\n",
"content_type": "text",
"meta": {
"_split_overlap": [
{
"range": [
1308,
1615
],
"doc_id": "73e62bf9eacb2631fd3da8a9f98313919f5e6851cbc7fcd72f71b8e2ffb578d9"
},
{
"range": [
0,
329
],
"doc_id": "e3149c5c7a835f78b529358fafabe007d0d109d48517de4314d5f6ad45534d7a"
}
],
"split_idx_start": 3824,
"file_name": "pep-0519.txt",
"_file_created_at": "2024-10-18T09:03:49.692777+00:00",
"split_id": 3,
"_file_size": 22105,
"page_number": 1,
"source_id": "cf21ac8366c79d9b83f9fc8a0efd4982b0d4d4e0ae7c2716a5eea2fca6bf00a9"
},
"score": 0.0169219970703125,
"embedding": null,
"file": {
"id": "a8a8d83e-6696-46c7-9ebf-3a953da41132",
"name": "pep-0519.txt"
},
"result_id": "85c4399f-38d4-439d-94b6-ffcfa7c52e67"
}
],
"_debug": null,
"prompts": null
}
]
}
```
### Chain the Requests
Here is a sample code that:
1. Calls the `Get Pipeline` endpoint.
2. Extracts the pipeline ID from the response and calls the `Create Search Session` endpoint to create a search session.
3. Uses the session ID from the response to start the chat using the `Chat` endpoint.
```python
# Replace your API key and base URL
API_KEY = ""
BASE_URL = "https://api.cloud.deepset.ai/api/v1"
WORKSPACE = "legal-chat"
PIPELINE = "rag-chat"
headers = {
"accept": "application/json",
"authorization": f"Bearer {API_KEY}",
"content-type": "application/json"
}
def get_pipeline_id():
url = f"{BASE_URL}/workspaces/{WORKSPACE}/pipelines/{PIPELINE}"
response = requests.get(url, headers=headers)
if response.status_code == 200:
return response.json()["pipeline_id"]
else:
raise Exception(f"Failed to get pipeline ID: {response.status_code}")
def create_search_session(pipeline_id):
url = f"{BASE_URL}/workspaces/{WORKSPACE}/search_sessions"
data = {
"pipeline_id": pipeline_id
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
return response.json()["search_session_id"]
else:
raise Exception(f"Failed to create search session: {response.status_code}")
def start_chat(search_session_id, query):
url = f"{BASE_URL}/workspaces/{WORKSPACE}/pipelines/{PIPELINE}/chat"
data = {
"chat_history_limit": 3,
"debug": False,
"view_prompts": False,
"queries": [query],
"search_session_id": search_session_id
}
response = requests.post(url, headers=headers, json=data)
return response.status_code, response.json()
def main():
try:
# Get the pipeline ID
pipeline_id = get_pipeline_id()
print(f"Pipeline ID: {pipeline_id}")
# Create a search session
search_session_id = create_search_session(pipeline_id)
print(f"Search Session ID: {search_session_id}")
# Start the chat
query = 'How do you present datetime objects in human readable format?"?'
status_code, response_data = start_chat(search_session_id, query)
print(f"Chat Status Code: {status_code}")
print("Chat Response:")
print(json.dumps(response_data, indent=2))
except Exception as e:
print(f"An error occurred: {str(e)}")
if __name__ == "__main__":
main()
```
```curl
#!/bin/bash
API_KEY=""
BASE_URL="https://api.cloud.deepset.ai/api/v1"
WORKSPACE="peps"
PIPELINE="rag-chat"
# Get pipeline ID
PIPELINE_ID=$(curl --silent --request GET \
--url "${BASE_URL}/workspaces/${WORKSPACE}/pipelines/${PIPELINE}" \
--header "accept: application/json" \
--header "authorization: Bearer ${API_KEY}" | jq -r .pipeline_id)
echo "Pipeline ID: $PIPELINE_ID"
# Create search session
SEARCH_SESSION_ID=$(curl --silent --request POST \
--url "${BASE_URL}/workspaces/${WORKSPACE}/search_sessions" \
--header "accept: application/json" \
--header "authorization: Bearer ${API_KEY}" \
--header "content-type: application/json" \
--data "{\"pipeline_id\": \"$PIPELINE_ID\"}" | jq -r .search_session_id)
echo "Search Session ID: $SEARCH_SESSION_ID"
# Start chat
curl --request POST \
--url "${BASE_URL}/workspaces/${WORKSPACE}/pipelines/${PIPELINE}/chat" \
--header "accept: application/json" \
--header "authorization: Bearer ${API_KEY}" \
--header "content-type: application/json" \
--data "{
\"chat_history_limit\": 3,
\"debug\": false,
\"view_prompts\": false,
\"queries\": [
\"How do you present datetime objects in human readable format?\"
],
\"search_session_id\": \"$SEARCH_SESSION_ID\"
}"
```
## Start a New Chat
To start a new chat, you must first create a new search session and then start a chat using the ID of the newly created session.
1. Call the [Create Search Session](/docs/api/main/create-search-session-api-v-1-workspaces-workspace-name-search-sessions-post) endpoint.
2. Call the [Chat](/docs/api/main/chat-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-chat-post) endpoint providing the search session ID.
## Show Previous Chats
Use the [Pipeline Search History](/docs/api/main/pipeline-search-history-api-v-1-workspaces-workspace-name-pipelines-pipeline-name-search-history-get) endpoint to display previous chats. Use this code snippet as a starting point for the request. Fill in:
- the pipeline and workspace name (in the URL).
-
```python
url = "https://api.cloud.deepset.ai/api/v1/workspaces/peps/pipelines/rag-chat/search_history" #peps is the workspace name, rag-chat is the pipeline name
headers = {
"accept": "application/json",
"authorization": "Bearer "
}
response = requests.get(url, headers=headers)
print(response.text)
```
```curl
curl --request GET \
--url https://api.cloud.deepset.ai/api/v1/workspaces/legal-chat/pipelines/rag-chat/search_history \
--header 'accept: application/json' \
--header 'authorization: Bearer '
```
## Example
This is an example Python script that:
1. Gets the pipeline ID and starts a new chat in the search session.
2. Resets the newly created chat.
3. Retrieves and displays a list of previous chats.
The script is available as Google Colab: [![Chat app in