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_groupsare 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"]}).