Configuration

Ragrails has three interfaces, and each one gets defaults from a different place. Keeping those scopes separate prevents most configuration surprises.

Interface	Where defaults live	How to override
SDK	The `RagRails(...)` object you create in Python	Pass arguments to a method call
CLI	`.ragrails.toml` in the current working directory	Pass command flags
REST API	Each JSON request body	Send different request fields

See vector databases for supported provider / vector_db values.

SDK constructor defaults do not automatically become CLI defaults. CLI .ragrails.toml values do not automatically become REST defaults.

One Stack, Three Config Forms

This is the same local setup in each interface: Qdrant at http://localhost:6333, Voyage embeddings, and OpenAI chat.

from ragrails import RagRails

rag = RagRails(
    collection="support",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
    llm={"provider": "openai", "model": "gpt-4o-mini"},
)

# .ragrails.toml
[vector_store]
provider = "qdrant"
collection = "support"
url = "http://localhost:6333"

[embedding]
provider = "voyage"
model = "voyage-3"

[llm]
provider = "openai"
model = "gpt-4o-mini"
max_tokens = 1024

{
  "embedding": {"provider": "voyage", "model": "voyage-3"},
  "storage": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"},
  "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"},
  "llm_provider": "openai",
  "llm_model": "gpt-4o-mini"
}

SDK Defaults

Use constructor defaults when you are writing Python. Every call on that rag object can inherit the configured vector store, embedding model, LLM, and reranker.

from ragrails import RagRails

rag = RagRails(
    collection="support",
    vector_store={"provider": "qdrant", "url": "http://localhost:6333"},
    embedding={"provider": "voyage", "model": "voyage-3"},
    llm={"provider": "openai", "model": "gpt-4o-mini"},
)

rag.ingest(markdown="# Refund policy\n\nRefunds are available within 30 days.")
rag.chat("How long do I have to request a refund?", history=[])

Override one call by passing method arguments:

rag.query("refund window", retrieval={"top_k": 5})
rag.chat("Summarize it", llm=rag.llm(model="gpt-4o"), history=[])

rag.llm() requires a model unless one was configured in RagRails(llm={...}).

CLI Defaults

Use .ragrails.toml when you run terminal commands. The CLI looks for .ragrails.toml in the current working directory. Run ragrails with no subcommand to open the setup wizard:

ragrails

The wizard writes .ragrails.toml. After that, commands can be shorter:

ragrails ingest --markdown "# Refund policy\n\nRefunds are available within 30 days."
ragrails query "How long do I have to request a refund?"
ragrails chat "How long do I have to request a refund?"

Without .ragrails.toml, pass explicit flags:

ragrails query "How long do I have to request a refund?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --provider voyage --model voyage-3 --top-k 5

Flags always win for that run. For example, this queries a different collection without editing .ragrails.toml:

ragrails query "refund policy" --collection legal

REST API Defaults

REST requests can be self-contained, or they can omit provider fields and use server environment defaults. Put provider and vector-store settings in the request body when one request needs to override the server defaults.

curl -X POST http://127.0.0.1:8000/v1/pipelines/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How long do I have to request a refund?",
    "embedding": {"provider": "voyage", "model": "voyage-3"},
    "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "top_k": 5}
  }'

The REST API also exposes /docs and /v1/openapi.json, so generated clients can type these request bodies. Server-level limits live in the process environment:

export EMBEDDING_PROVIDER=voyage
export EMBEDDING_MODEL=voyage-3
export VECTOR_DB_PROVIDER=qdrant
export VECTOR_DB_URL=http://qdrant:6333
export VECTOR_DB_COLLECTION=rag_chunks
export RAGRAILS_MAX_UPLOAD_FILES=20
export RAGRAILS_MAX_UPLOAD_BYTES=52428800

EMBEDDING_PROVIDER, EMBEDDING_MODEL, VECTOR_DB_PROVIDER, VECTOR_DB_URL, and VECTOR_DB_COLLECTION are REST server defaults used when request bodies omit those fields. RAGRAILS_MAX_UPLOAD_FILES controls how many files /v1/ingest/docs/upload and /v1/pipelines/ingest/mixed accept in one multipart request. RAGRAILS_MAX_UPLOAD_BYTES controls the maximum size of each uploaded file in bytes. Uploads above either limit return HTTP 413.

Secrets

Do not put API keys in .ragrails.toml. Store non-secret defaults in config and keep credentials in environment variables.

export VOYAGE_API_KEY="..."
export OPENAI_API_KEY="..."
export QDRANT_API_KEY="..."  # Qdrant Cloud only

See environment variables for every provider key.

Complete `.ragrails.toml`

Keep only the sections you need.

[vector_store]
provider = "qdrant"          # qdrant, qdrant_cloud, pinecone, weaviate
collection = "support"
url = "http://localhost:6333"

[embedding]
provider = "voyage"
model = "voyage-3"
batch_size = 64

[llm]
provider = "openai"          # openai, anthropic, google
model = "gpt-4o-mini"
max_tokens = 1024

[reranker]
enabled = false
provider = "voyage"
model = "rerank-2-lite"

[chunking]
chunk_size = 2000
chunk_overlap = 200
min_chunk_length = 100

[storage]
batch_size = 64

[retrieval]
top_k = 10
rerank_top_k = 5

[chat]
query_rewrite = false
intent_routing = true
history_compaction = true

Validate CLI Config

Run doctor from the same directory as .ragrails.toml:

ragrails doctor

Use --config to inspect a file somewhere else:

ragrails doctor --config path/to/.ragrails.toml

URL Ingestion Setup

Scrape Website needs the URL extra and a browser install. This is environment setup, not provider configuration.

rag.setup_url()

pip install "ragrails[url]"
ragrails setup-url

# Install the URL extra in the server environment before starting ragrails-api.
pip install "ragrails[url,server-qdrant]"

Get Started

Features

Capabilities

Use Cases

Walkthroughs

One Stack, Three Config Forms

SDK Defaults

CLI Defaults

REST API Defaults

Secrets

Complete `.ragrails.toml`

Validate CLI Config

URL Ingestion Setup

One Stack, Three Config Forms

SDK Defaults

CLI Defaults

REST API Defaults

Secrets

Complete .ragrails.toml

Validate CLI Config

URL Ingestion Setup

Complete `.ragrails.toml`