Skip to content

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.