Skip to content

Concepts

Components

A pipeline is made of small, swappable components. Each one is a typing.Protocol in ragpick.interfaces, so any object with the right methods works. No base class is needed.

Kind Protocol Built-in types
loader load(path) -> Iterable[Document] directory, text, pdf, csv, multimodal, langchain, llamaindex
chunker split(docs) -> list[Chunk] recursive, fixed, parent_child, none
embedder embed(texts), dimension (optional embed_query) fake, openai, sentence_transformers, langchain, llamaindex
store add, search, delete, persist, load memory, qdrant, pgvector, chroma, lancedb
keyword_index add, search, persist, load bm25
retriever retrieve(query, k, filters) vector, keyword, hybrid, parent_child, corrective, graph, agentic, hierarchical, long_context, sql, langchain, llamaindex
reranker rerank(query, chunks, top_n) none, cross_encoder, cohere, jina
generator generate(query, contexts) -> Answer (optional stream) fake, openai, ollama, langchain, llamaindex

Data flows through these models: Document → Chunk → RetrievedChunk → Answer (text, citations as chunk ids, contexts, usage).

Ingest: loader → chunker → embedder → store (+ keyword index) → persisted to index_dir.

Query: retriever (with ACL filters) → reranker → generator → Answer.

Components receive embedder, store, keyword_index, generator and index_dir by constructor parameter name. The generator is built first, so loaders can use it too (the multimodal loader describes images with it). A component that implements index_documents(docs) also receives the raw documents at ingest (the SQL retriever builds its database this way), and one that implements index_chunks(chunks) receives the chunks (the graph retriever builds its knowledge graph this way).

Streaming: pipeline.stream(question) yields StreamEvents: contexts, then delta text pieces, then the final answer with citations.

Blueprints

A blueprint is a named, tested architecture: a YAML file with metadata (description, best_for, tradeoffs, status) and default components. Your rag.yaml names a blueprint and overrides only what differs:

blueprint: hybrid
components:
  embedder:  {type: openai, params: {model: text-embedding-3-small}}
  generator: {type: openai, params: {model: gpt-4o-mini}}

See Blueprints for the catalogue and roadmap.

Architecture as code

rag.yaml is validated by Pydantic. Mistakes are reported with their YAML key path:

Invalid configuration in rag.yaml:
  - query.topk: unknown key (check for typos)
  - components.retriever: required key is missing (set it, or choose a `blueprint` that provides it)

Layers merge as blueprint defaults → rag.yaml → --set flags. Secrets come from the environment with ${OPENAI_API_KEY} and are never written back to disk. Check the merged result with ragpick validate.

The selector

ragpick recommend runs a table of explainable rules over your requirements:

Situation Effect
summary_questions (overviews and details) hierarchical
long_context_model with a small corpus long_context
multi_hop (facts spread across documents) graph
complex_questions (multi-part, comparisons) agentic
conversational (follow-up questions) conversational (chat works with every blueprint)
multi_tenant reason: enable tenancy (see Multi-tenancy)
long, structured documents parent_child
small corpus, not keyword-heavy naive
keyword-heavy, or medium/large corpus hybrid
images (diagrams, screenshots, scanned, …) multimodal (warns that vision needs a capable LLM)
structured data (csv, sql, sqlite, …) sql (warns about row-level ACL; mixed data → use a router)
strict_grounding (wrong answers are costly) corrective (over parent_child for long documents)
latency: low reranker disabled, with a reason
access_control with a store that cannot filter warning
large corpus on the in-memory store warning, suggests Qdrant
pdf data without ragpick[pdf] warning

To settle it with data instead of rules, ragpick bench runs every stable blueprint on your documents and questions; see Evaluation.

Every recommendation lists reasons, alternatives and warnings. The rules live in ragpick.selector.rules.RULES and are easy to extend.

Vector stores

Store Use it for Notes
memory prototypes, up to a few hundred thousand chunks exact search, persisted to index_dir
qdrant large corpora, a dedicated vector DB pip install "ragpick[qdrant]"
pgvector teams already running PostgreSQL pip install "psycopg[binary]", the vector extension
chroma local development, Chroma servers pip install chromadb; path, or host/port
lancedb embedded, file- or object-storage-based (S3) pip install lancedb; defaults to <index_dir>/lancedb
components:
  store:
    type: pgvector
    params: {dsn: "${DATABASE_URL}", table: support_chunks, index: hnsw}

pgvector creates the table (and an HNSW cosine index) on first insert and evaluates ragpick filters, including allowed_groups, in SQL over a JSONB metadata column, so access control happens inside PostgreSQL before ranking. Metadata values are compared as text.

Access control

Document-level access control is built in. Attach groups to a document with Markdown front matter (or any loader's metadata):

---
allowed_groups: [support]
---
# Internal escalation guide

Then query as a member of some groups:

p.query("How do I escalate?", groups=["support"])
ragpick query "How do I escalate?" --groups support

Rules:

  • Chunks without allowed_groups are public.
  • Chunks with it are returned only if the caller's groups intersect it.
  • groups=None (or no --groups) means public chunks only. This is secure by default.
  • Filtering happens inside every store and the BM25 index before ranking, so restricted text never reaches fusion, reranking, or the LLM.

Other metadata filters use the same mechanism: p.query(q, filters={"lang": ["en", "de"]}).