Overview - Ragrails

Capabilities are the Ragrails advantages you turn on when basic RAG is not enough. They cover stronger retrieval, better multi-turn behavior, live progress, recoverable ingestion, provider extension, tool use, and lower operating cost.

Problem	Start here	Why
Vector search finds the topic but ranks weak chunks first	Reranking	Retrieve a wider candidate set, then reorder by query-specific relevance.
Follow-up questions like “what about the second one?” search poorly	Query Rewriting	Rewrite conversational turns into standalone search queries.
Long chats become costly, slow, or overconfident	Chat Tuning	Tune history compaction, intent routing, retrieval quality, and low-confidence behavior.
A crawl or API pull partly fails	Resilient Ingestion	Capture retryable failures and safely page through large APIs.
Users wait too long for crawls or answers	Streaming	Emit progress, token, error, and final result events over SDK or REST.
Interactive chat needs live lookup or side effects	Agentic Tools	Use the built-in CLI tool loop with `web_fetch` and `api_call`.
You want to build your own tool loop	Tool Calling	Use provider-neutral message and tool-call dataclasses.
You need an embedding or reranking provider Ragrails does not ship	Custom Providers	Register a provider factory at application startup.
Spend is too high	Cost Optimization	Reduce LLM calls, context size, re-embedding, and API reranking.

How capabilities attach

Area	SDK	CLI	REST API
Reranking	`retrieve(..., use_rerank=True)`, `query(retrieval={"rerank": ...})`, `chat(..., retrieval_config=...)`	`retrieve --rerank`, `query --rerank`, `chat --rerank`	`/v1/retrieve`, `/v1/pipelines/query`, `/v1/chat`
Query rewriting	`retrieve(..., use_query_rewrite=True)`, `query(retrieval={"query_rewrite": ...})`, `chat(query_rewrite=...)`	`chat --rewrite-query`	`/v1/retrieve`, `/v1/pipelines/query`, `/v1/chat`
Chat quality	`ChatRetrievalQualityConfig`	Not exposed as flags yet	`retrieval_quality` object on `/v1/chat`
History controls	`HistoryCompactionConfig`, `IntentRoutingConfig`	`--history-compaction`, `--intent-routing`	`history_compaction`, `intent_routing`
Streaming	`scrape_stream(...)`, `chat_stream(...)`	Interactive chat REPL streaming	`/v1/ingest/url/stream`, `/v1/chat/stream`
Resilient ingestion	`DLQ`, `fetch(..., pagination=...)`	Ingestion commands	Ingestion endpoints
Tool use	LLM `complete_with_tools()`	Interactive `ragrails chat`	Not exposed as a server route yet

Recommended order

Get extraction through chat working first.
Add reranking when retrieval order is the issue.
Add query rewriting when multi-turn queries are the issue.
Tune chat quality before exposing answers in production.
Add streaming when users need progress or token events.
Add maintenance and resilient ingestion for long-lived indexes.