Config reference¶
Layers merge in this order: blueprint defaults → your rag.yaml → CLI --set.
Within components, changing a component's type replaces it entirely; keeping
the type merges params. Strings may use ${ENV_VAR} or ${ENV_VAR:-default}.
Relative paths (data, index_dir) resolve against the config file's directory.
Top level (rag.yaml)¶
Top-level schema of rag.yaml.
| Key | Type | Default | Description |
|---|---|---|---|
version |
1 |
1 |
Config schema version. |
name |
str | 'ragpick-app' |
Application name. |
blueprint |
str | null | None |
Blueprint supplying default components. |
data |
str | null | None |
Default source path for ragpick ingest / ragpick eval. |
requirements |
Requirements | see section | Inputs for ragpick recommend. |
components |
ComponentsConfig | required | Pipeline components (usually partly supplied by the blueprint). |
query |
QueryConfig | see section | Query-time settings. |
eval |
EvalConfig | see section | Evaluation settings. |
tracing |
TracingConfig | see section | Query tracing. |
cache |
CacheConfig | see section | Caching. |
serve |
ServeConfig | see section | HTTP API settings. |
tenancy |
TenancyConfig | see section | Multi-tenancy. |
conversation |
ConversationConfig | see section | Chat sessions. |
feedback |
FeedbackConfig | see section | Answer feedback. |
index_dir |
str | '.ragpick/index' |
Where indexes are persisted. |
requirements¶
What the application needs. Used by the selector (ragpick recommend).
| Key | Type | Default | Description |
|---|---|---|---|
data_types |
list[str] | ['markdown'] |
Kinds of source data, e.g. markdown, pdf, html, sql, csv. |
corpus_size |
small | medium | large |
'small' |
small (<1k chunks), medium, or large (>100k chunks). |
keyword_heavy |
bool | False |
Queries rely on exact terms: product codes, legal terms, IDs. |
long_documents |
bool | False |
Documents are long and structured (manuals, policies, contracts). |
complex_questions |
bool | False |
Questions need several lookups (comparisons, multi-part questions). |
multi_tenant |
bool | False |
Several customers' data must be kept in separate indexes. |
conversational |
bool | False |
Users ask follow-up questions in a chat. |
summary_questions |
bool | False |
Users ask for overviews and summaries as well as details. |
long_context_model |
bool | False |
The LLM reads 100k+ tokens (and the corpus is small). |
multi_hop |
bool | False |
Questions connect facts spread across several documents. |
strict_grounding |
bool | False |
Wrong answers are costly: prefer "I don't know" over guessing. |
latency |
low | normal |
'normal' |
low disables expensive stages. |
needs_citations |
bool | True |
Answers must cite their sources. |
access_control |
bool | False |
Documents are restricted to groups (allowed_groups metadata). |
components¶
The components that make up a pipeline.
| Key | Type | Default | Description |
|---|---|---|---|
loader |
ComponentSpec | required | Turns a path into documents. |
chunker |
ComponentSpec | required | Splits documents into chunks. |
embedder |
ComponentSpec | required | Embeds chunks and queries. |
store |
ComponentSpec | required | Vector store. |
keyword_index |
ComponentSpec | null | None |
Keyword index (required by the hybrid and keyword retrievers). |
retriever |
ComponentSpec | required | Retrieval strategy. |
reranker |
ComponentSpec | see section | Optional reranker. |
generator |
ComponentSpec | required | Answer generator (LLM). |
Component spec (each entry of components, and eval.judge)¶
A component reference: registry type plus constructor params.
| Key | Type | Default | Description |
|---|---|---|---|
type |
str | required | Registered component name, e.g. openai or bm25. |
params |
dict[str, Any] | {} |
Keyword arguments passed to the component. |
query¶
Query-time settings.
| Key | Type | Default | Description |
|---|---|---|---|
top_k |
int | 5 |
Number of contexts passed to the generator. |
eval¶
Evaluation settings.
| Key | Type | Default | Description |
|---|---|---|---|
judge |
ComponentSpec | null | None |
Generator used as LLM judge (must support complete). |
prices |
dict[str, PriceSpec] | {} |
Model name → price; merged over ragpick's built-in price table. |
fail_under |
dict[str, float] | {} |
Minimum metric values, e.g. {hit_rate@k: 0.8}; ragpick eval fails below. |
fail_over |
dict[str, float] | {} |
Maximum metric values, e.g. {latency_p95_ms: 1500}; eval fails above. |
Price spec (each entry of eval.prices)¶
Price of a model in USD per one million tokens.
| Key | Type | Default | Description |
|---|---|---|---|
prompt_per_1m |
float | 0.0 |
|
completion_per_1m |
float | 0.0 |
tracing¶
Query tracing (nested, timed spans per stage).
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | False |
Record a trace for every query. |
exporters |
list[ComponentSpec] | [] |
Where traces go: jsonl (params: path) and/or console. |
cache¶
Persistent cache for embeddings and LLM calls.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | False |
Turn caching on. |
dir |
str | '.ragpick/cache' |
Cache directory. |
embeddings |
bool | True |
Cache embeddings. |
generations |
bool | True |
Cache answers and LLM completions. |
ttl_seconds |
float | null | None |
Expire entries after this age. |
serve¶
HTTP API settings for ragpick serve.
| Key | Type | Default | Description |
|---|---|---|---|
host |
str | '127.0.0.1' |
Interface to bind. |
port |
int | 8000 |
Port to bind. |
api_keys |
list[ApiKeySpec] | [] |
If set, requests need Authorization: Bearer <key>. |
max_body_bytes |
int | 65536 |
Largest accepted request body. |
cors_origins |
list[str] | [] |
Origins allowed by CORS (* for any). |
allow_traces |
bool | False |
Let clients request traces in responses. |
tenancy¶
Per-tenant indexes within one pipeline.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | False |
Each tenant gets an isolated index under <index_dir>/tenants/<id>. |
max_loaded |
int | 32 |
Tenant indexes kept in memory (LRU). |
conversation¶
Chat sessions (chat(), ragpick chat, POST /chat).
| Key | Type | Default | Description |
|---|---|---|---|
rewrite |
auto | llm | heuristic | off |
'auto' |
How follow-ups become standalone questions (auto: LLM if real). |
max_turns |
int | 10 |
Turns kept per session. |
store |
memory | sqlite |
'memory' |
sqlite keeps sessions in <index_dir>/sessions.sqlite. |
max_sessions |
int | 1000 |
Sessions kept by the memory store (LRU). |
ttl_seconds |
float | null | None |
Forget idle sessions after this. |
feedback¶
Answer feedback (POST /feedback, record_feedback, ragpick feedback).
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
bool | False |
Accept POST /feedback on the HTTP server. |
answer_log_size |
int | 10000 |
Recent answers the server keeps so they can be rated. |
API key (each entry of serve.api_keys)¶
An API key for ragpick serve and the groups its holder may act as.
| Key | Type | Default | Description |
|---|---|---|---|
key |
str | required | The secret; use ${ENV_VAR} interpolation. |
name |
str | 'client' |
Label used in logs. |
groups |
list[str] | null | None |
Groups this key may query as (null = any groups the request names). |
tenant |
str | null | None |
Bind the key to one tenant (null = the request picks the tenant). |
Router config (top level of a router file)¶
A config that routes each question to one of several pipelines.
| Key | Type | Default | Description |
|---|---|---|---|
version |
1 |
1 |
Config schema version. |
name |
str | 'ragpick-router' |
Application name. |
router |
RouterSpec | required | |
eval |
EvalConfig | see section | Evaluation settings. |
tracing |
TracingConfig | see section | Query tracing. |
serve |
ServeConfig | see section | HTTP API settings. |
conversation |
ConversationConfig | see section | Chat sessions. |
feedback |
FeedbackConfig | see section | Answer feedback. |
sessions_dir |
str | '.ragpick/router' |
Where router sessions and feedback are stored. |
router¶
How questions are routed.
| Key | Type | Default | Description |
|---|---|---|---|
strategy |
auto | llm | keywords |
'auto' |
auto uses the LLM when one is available, else keywords. |
routes |
list[RouteSpec] | required | Possible destinations. |
default |
str | null | None |
Fallback route (default: the first). |
fallback |
bool | True |
Retry on the default route when the chosen one can't answer. |
llm |
ComponentSpec | null | None |
Generator used to classify questions (default: a route's LLM). |
Route (each entry of router.routes)¶
One destination of a router: another pipeline config.
| Key | Type | Default | Description |
|---|---|---|---|
name |
str | required | Route name. |
config |
str | required | Path to the route's rag.yaml (relative to this file). |
description |
str | '' |
What this route answers (shown to the LLM router). |
keywords |
list[str] | [] |
Words/phrases that point to this route. |
groups |
list[str] | null | None |
Only callers in these groups may be routed here. |