Haystack Cookbook: What the Notebook Collection Actually Contains

The Gap the Cookbook Fills Between Docs and Tutorials

Haystack's own documentation explains how the framework is structured, and the official tutorials walk through complete applications. Between those two sits a third need: seeing a single integration work end to end. That is the space the cookbook occupies. The README describes the notebooks as guidelines for using different model providers, vector databases, retrieval techniques and new experimental features, and notes that most of them showcase a specific, small demo. The scope is deliberately narrow. A notebook is not trying to teach you retrieval-augmented generation from first principles. It is trying to show you the exact wiring for one provider or one database. This matters because Haystack's component model means the same pipeline shape gets reused with different backends, and the differences between backends live in constructor arguments and configuration rather than in the pipeline logic. The audience is therefore an engineer who has already read the docs and now wants a concrete reference for one piece of the stack. If you have not yet installed Haystack or read its documentation, the cookbook is the wrong entry point.

How index.toml Turns a Folder of Notebooks into a Catalogue

The repository has one structural mechanism worth understanding, and it is not in the notebooks themselves. Contributions go into the /notebooks folder, and every notebook must also be registered in index.toml with its title and topics. That file is what drives the browsable cookbook at haystack.deepset.ai/cookbook. The data flow is straightforward: a notebook file lives in the repository, an entry in index.toml describes it, and the website renders that entry. This has a practical consequence for anyone browsing. The website is a view over the index file, so a notebook that exists in the repository but is missing from index.toml will not appear in the catalogue. It also means the topics field is the only structured metadata you get. There is no schema for difficulty, Haystack version, or dependency pinning described in the README. If you are searching for a notebook about a specific vector database, the topics list is what you filter on, and its usefulness depends entirely on how the contributor filled it in. The README also specifies that experimental features get an extra field: the discussion link plus experimental = true. That flag is the one machine-readable signal in the whole index about stability.

Contributing a Notebook, Including the Colab Route

The contribution path is documented and short. Fork the repository, add your notebook to /notebooks, give it a descriptive filename, and add its title and topics to index.toml. The README is explicit about naming: include the model providers, databases, technologies and the task the example completes. That convention is what makes the catalogue searchable, so a file named after a vague concept defeats the purpose. There is a second route the README describes for people working in Colab: create a fork, select Save a Copy to GitHub from Colab, and open a pull request from the fork. For notebooks that demonstrate an experimental Haystack feature, the same pull request should add the discussion link and set experimental = true in the index entry. There is no described review checklist, no test harness mentioned, and no CI requirement stated in the material. The practical effect is that quality varies by contributor, and the index entry is the only place where a maintainer's signal about stability gets recorded.

No Licence File Means You Have to Check Before Reuse

The repository metadata supplied here lists the licence as unknown, and the README does not state one. That is a real constraint, not a formality. Without a licence, the default position under most copyright regimes is that others have no granted permission to copy, modify or redistribute the work, even when the repository is publicly visible on a hosting platform. The notebooks also depend on Haystack, which is a separate project with its own licence, and on whatever model providers and vector databases each notebook targets, each with its own terms. None of that is resolved by the cookbook itself. This is not legal advice; the point is narrower. If you intend to copy notebook code into a commercial pipeline, the absence of a stated licence is a question you have to answer before you do it, and the repository as described here does not answer it. Treat the notebooks as reading material until that is settled.

What the Cookbook Does Not Give You

The README is candid in a way that is worth taking literally: these are examples, and most showcase a specific, small demo. A small demo is not a production pipeline. There is no mention of dependency pinning per notebook, no stated compatibility matrix against Haystack releases, and no release history for the repository itself. The supplied metadata shows no releases retrieved, which fits a collection of notebooks rather than a versioned package. The failure mode follows from that. You copy a notebook, run it months later, and the provider SDK or the Haystack component signature has moved on. Nothing in the repository structure described here would tell you which Haystack version a given notebook was written against. There is also no test suite mentioned, so a broken notebook may sit in the catalogue until someone notices. The experimental flag in index.toml is the one place where the project warns you that an underlying feature is not settled, and it is worth reading that field before you invest time in a notebook.

Cookbook Versus the Haystack Repository Itself

The closest alternative is the main Haystack repository, which the README links to directly. The difference in approach is structural. Haystack is the framework: it ships the components, the pipeline abstractions and the test suite, and it is what you install and depend on. The cookbook depends on Haystack and contains no framework code of its own. If you want to know whether a component exists, what its parameters are, or whether a bug has been fixed, the framework repository and its documentation are the source. If you want to see one provider wired into a working pipeline with realistic inputs, the cookbook is faster than assembling that from the API reference. The two are not substitutes. A second comparison point is the official tutorials, also linked from the README. Tutorials build a complete application and explain the reasoning; cookbook notebooks are shorter and narrower, focused on the integration rather than the application. Choosing between them is a question of whether you need to understand a design or just need to see a specific connection made.

Who Should Read the Cookbook and What to Check First

The cookbook suits an engineer who has Haystack installed, has read the docs, and is now evaluating a specific model provider or vector database against their own data. Reading one notebook is a reasonable way to spend twenty minutes before committing to an integration. It does not suit anyone who needs a supported library with a version contract, and it does not suit anyone who cannot resolve the licence question. Before you build on a notebook, verify three things in the repository: that the notebook appears in index.toml with topics matching your use case, that it does not carry experimental = true if you need stability, and what Haystack version the code targets, since the index does not record that. The project's own contribution guidance is the best description of its intent: examples that serve as guidelines. Guidelines are worth reading and worth checking, and they are not a dependency.

Editorial conclusion

Adopt the cookbook as a reading list, not as a dependency. It fits engineers who already have Haystack installed and need to see how a particular model provider, vector database or retrieval technique is wired up in a working notebook. It does not fit anyone looking for a maintained library, a versioned API, or code they can import into a production pipeline without rewriting it. Before relying on any notebook, check two things in the repository itself: whether the notebook is listed in index.toml with the topics you expect, and whether it carries the experimental = true field, which signals that the feature it demonstrates is not stable. Also confirm the licence, because none is stated in the material supplied here.

Official sources

1. deepset-ai/haystack-cookbook on GitHub
2. Issues
3. Project website
4. README