← Back to all projects

haystack

Document-grounded answers and agents, assembled from components you wire yourself — a Python library, not a server.

OfficialApache-2.0
Stars
26.9k
Forks
3.4k
Open issues
197
Last commit
30 Oct 2026

What is haystack?

Haystack builds document-grounded answering and agents out of components — file converters, splitters, embedders, retrievers, chat generators, tools — that you register in a Pipeline and connect output-name to input-name, with a mismatch raising an error at connection time rather than partway through a run. Branches and capped loops live in the same graph, and an Agent is itself a component, so a whole tool-calling loop drops into a pipeline or becomes a tool for another agent. The cost is that the wiring is yours: there is no one-call path from a folder of PDFs to a working assistant, and the library runs inside your own process — serving a pipeline over HTTP or as an MCP server means adding Hayhooks, a separate deepset project, or writing that wrapper yourself.

What can you do with haystack?

  • Wire components by name, and hear about a mismatch at once — You register each step in a Pipeline and join one component's named output to another's named input; if the declared types cannot meet, the connection itself raises there and then. The same graph branches — PDFs down one path, spreadsheets down another — and loops back, with a per-component run cap that stops a check-and-rewrite cycle spinning forever.
  • Build the retrieval side out of parts you can replace — Going in, file converters and splitters feed an embedder that writes into a document store; coming out, a retriever fetches candidates by keyword, by vector or both, and a joiner merges the two rankings, with reciprocal rank fusion among the options. Retrievers come paired with their store, so moving off the in-memory one to Qdrant, Elasticsearch or pgvector changes those two pieces and leaves the rest of the graph alone.
  • An agent is itself a component, so agents nest — The Agent runs the whole loop — call the chat model, run the tools it asks for, update a typed state the tools share, stop on an exit condition or a step budget — streaming tokens and running several tool calls at once. Being an ordinary component, it drops into a pipeline, and a wrapper hands one agent to another as a tool.
  • Turn a function, a component or an entire pipeline into a tool — A decorator makes a tool out of a Python function and its type hints; wrappers expose an existing component, or a whole pipeline, as one. When the catalogue grows past a threshold, a searchable toolset shows the model a single search call and loads the rest on demand, and a skill toolset does the same for folders of written instructions.
  • Step into the agent's loop at six named points — Hooks fire before the run, before the model call, before and after a tool, on exit and after the run. Two are shipped ready-made: a confirmation step that asks a person before a tool executes — always, once per tool and arguments, or never — and one that writes a bulky tool result out to a file instead, leaving a short preview and a pointer in its place, for tools you nominate or once a result passes a size you set.
  • Score retrieval and answers before you trust them — Evaluators grade the retrieval half — whether the right documents came back and how near the top — and the answer half, including whether an answer stays faithful to those documents, plus a model-as-judge whose criteria you write. Ragas and DeepEval plug in the same way if you already use them.

Before you choose haystack

  • Version 3.0 dropped the legacy generators and moved thirty components into separately installed integration packages; deepset states 2.31 gets only security patches and critical bug fixes until the end of October 2026.
  • Pipeline templates, a Helm chart and deployment guides, direct support and early access to security work such as prompt-injection defence are sold as Haystack Enterprise rather than shipped in the open framework.

Star history

17 Aug to 30 Oct · +652

26.2k26.9k

Frequently asked questions

Is haystack free for commercial use?

haystack is released under the Apache-2.0 licence — OSI-approved open source, which permits commercial use.

How can haystack be deployed?

haystack is available as Self-hosted / Runs locally.