Haystack

Haystack Expert Skill

Haystack (by deepset) is a production-oriented framework for building search and NLP pipelines. Its core abstraction is the Pipeline — a directed acyclic graph of typed components with explicit connections. Unlike LangChain's LCEL (pipe operator) or LlamaIndex's query engines, Haystack pipelines are declared upfront with add_component and connect, giving validated, debuggable DAGs.

Core Paradigm

from haystack import Pipeline
from haystack.components.embedders import SentenceTransformersTextEmbedder
from haystack.components.retrievers.in_memory import InMemoryEmbeddingRetriever
from haystack.components.builders import PromptBuilder
from haystack.components.generators import OpenAIGenerator
from haystack.document_stores.in_memory import InMemoryDocumentStore

# Build a pipeline
document_store = InMemoryDocumentStore()
pipeline = Pipeline()
pipeline.add_component("embedder", SentenceTransformersTextEmbedder())
pipeline.add_component("retriever", InMemoryEmbeddingRetriever(document_store=document_store))
pipeline.add_component("prompt_builder", PromptBuilder(template="Answer using: {{documents}}\n\nQuestion: {{question}}"))
pipeline.add_component("generator", OpenAIGenerator())

# Connect components
pipeline.connect("embedder.embedding", "retriever.query_embedding")
pipeline.connect("retriever.documents", "prompt_builder.documents")
pipeline.connect("prompt_builder", "generator")

# Run
result = pipeline.run({"embedder": {"text": "What is Haystack?"}, "prompt_builder": {"question": "What is Haystack?"}})

Core Principles

1. Pipelines are validated DAGs. add_component + connect. Pipeline validation catches errors BEFORE execution — leverage this during development.
2. Components are typed. Each component has input/output slots. Connections must match types. This prevents runtime errors.
3. PromptBuilder uses Jinja2. Templates are Jinja2 strings, not f-strings. {{documents}}, {{query}}, {{question}} are variable placeholders.
4. Indexing and query are separate pipelines. One pipeline loads/cleans/embeds/writes documents. Another retrieves/generates answers. They share the DocumentStore.
5. Evaluation is a pipeline too. Add evaluator components to measure faithfulness, relevancy, or custom metrics.

Where to Start

| You already have... | Start here | |---|---| | Nothing — exploring Haystack | Build a basic indexing + query pipeline | | Documents to index | Build an indexing pipeline (converters, splitter, embedder, writer) | | A search use case | Build a query pipeline (embedder, retriever, prompt, generator) | | A production deployment | Add Hayhooks + evaluation pipeline |

Quick Reference

| Task | Approach | Reference | |------|----------|-----------| | Build indexing pipeline | addcomponent -> connect -> run | references/pipeline-design.md | | Build query pipeline | retriever -> promptbuilder -> generator | references/pipeline-design.md | | Choose document store | InMemory (dev), Elasticsearch/Pinecone (prod) | references/document-stores.md | | Embedding retrieval | SentenceTransformersTextEmbedder + EmbeddingRetriever | references/retrievers.md | | Hybrid retrieval | BM25 + Embedding in parallel, DocumentJoiner | references/retrievers.md | | Prompt templates | Jinja2 in PromptBuilder | references/pipeline-design.md | | Evaluation | DeepEvalEvaluator, SASEvaluator | references/evaluation.md | | Deploy | Hayhooks REST API | references/deployment.md |

Framework Routing Guide

| Scenario | Reach for | Why | |----------|-----------|-----| | Search / NLP pipelines | Haystack | Pipeline DAG model is most mature for retrieval-heavy workloads | | Documents to query / RAG | LlamaIndex | Data ingestion is the primary primitive | | Chain/agent composition | LangChain | LCEL pipe operator for general chain building | | Compiled prompt programs | DSPy | Auto-optimizes prompts against a metric | | Role-based multi-agent | CrewAI | Higher-level agent abstraction |

Reference Files

| Reference | Load when | File | |-----------|-----------|------| | Pipeline Design | Building indexing and query pipelines | references/pipeline-design.md | | Document Stores | Store selection and configuration | references/document-stores.md | | Retrievers | Embedding, BM25, hybrid retrieval | references/retrievers.md | | Validation Audit | Research validation of all API claims | references/validation-audit.md | | File Converters | Multi-format indexing, YAML serialization, component types | references/file-converters.md | | Evaluation | Metrics, evaluators, pipeline evaluation | references/evaluation.md | | Deployment | Hayhooks, containerization, production | references/deployment.md | | FAQ & Troubleshooting | Common errors and fixes | references/faq-and-troubleshooting.md |

Templates

| Template | When to use | File | |----------|-------------|------| | Indexing Pipeline | Load, split, embed, write to store | templates/indexing-pipeline.py | | Query Pipeline | Retrieve, prompt, generate answer | templates/query-pipeline.py | | Hybrid RAG | BM25 + embedding in parallel | templates/hybrid-rag.py |

Troubleshooting

| Symptom | Likely cause | Fix | Reference | |---------|-------------|-----|-----------| | Pipeline run errors | Component connection mismatch | Check component input/output slot types | references/pipeline-design.md | | No documents retrieved | Empty document store | Run indexing pipeline first | references/pipeline-design.md | | Prompt not rendering | Wrong variable name in Jinja2 template | Check {{variables}} match pipeline input | references/pipeline-design.md | | Slow retrieval | Full scan instead of ANN | Configure approximate nearest neighbor index | references/retrievers.md | | Embedding mismatch | Different models for indexing vs query | Use same model in both pipelines | references/retrievers.md | | Hayhooks not starting | Port conflict or missing config | Check port, run with --help for options | references/deployment.md |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: magnus919
• Source: magnus919/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.