SDK Overview - Ragrails

The Ragrails SDK has two main workflows. rag.ingest() builds a searchable knowledge base from your sources. rag.query() searches that knowledge base. rag.chat() builds on retrieval by sending retrieved context to your configured LLM and returning a grounded answer. Start with the workflows when you want the shortest path. Use the pipeline stage pages when you need to inspect output, tune behavior, or run one part directly.

Configure Once

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"},
    reranker={"provider": "voyage", "model": "rerank-2-lite"},
)

Constructor defaults are SDK-only. They do not write .ragrails.toml and they do not affect CLI or REST defaults.

The constructor uses vector_store={"provider": ...} plus top-level collection=. Per-call stage methods use vector_db=, collection=, url=, and options= when overriding one call.

Workflows

Ingest

Extract sources, chunk them, embed them, and store them in a vector database.

Query

Retrieve matching chunks or generate grounded answers from the indexed knowledge base.

# Ingest builds the index.
rag.ingest(docs=["files/refund-policy.pdf"])

# Query returns matching chunks.
matches = rag.query("How long do refunds take?", retrieval={"top_k": 5})

# Chat returns a grounded answer.
answer = rag.chat("How long do refunds take?", history=[])

Pipeline

The pipeline stages are the lower-level building blocks behind the workflows.

Overview

See how extraction, chunking, embedding, storing, retrieval, chat, and maintenance fit together.

Extraction

Load documents, websites, APIs, or direct Markdown before indexing.

Chunking

Split normalized Markdown into searchable passages.

Embedding

Convert chunks into vectors with your embedding model.

Storing

Write embedded chunks to the configured vector database.

Retrieval

Find the chunks most relevant to a user query.

Chat

Use retrieved context to answer with an LLM.

Knowledge Base Maintenance

Update or remove stored chunks so answers stay current.

Stage Flow

# Extraction
sources = rag.parse(files=["files/refund-policy.pdf"])

# Chunking
chunks = rag.chunk(markdown=sources.outputs)

# Embedding
embedded = rag.embed(chunks=chunks.items)

# Storing
rag.store(embedded_chunks=embedded.items)

# Retrieval
matches = rag.retrieve("How long do refunds take?", top_k=5)

# Chat
answer = rag.chat("How long do refunds take?", history=[])

Result Objects

Ragrails returns dataclass result objects. The data flowing between stages is plain dictionaries so you can inspect, persist, or transform it.

Stage	SDK method	Result object
Extraction	`scrape`, `parse`, `fetch`	`ScrapeResult`, `ParseResult`, `ApiIngestResult`
Chunking	`chunk`	`ChunkResult`
Embedding	`embed`	`EmbedResult`
Storing	`store`, `edit`, `delete`	`StoreResult`, `EditResult`, `DeleteResult`
Retrieval	`retrieve`, `query`	`RetrieveResult`
Chat	`chat`	`ChatResult`
Ingest workflow	`ingest`	`IngestPipelineResult`

Install

pip install "ragrails[store-qdrant]"
export VOYAGE_API_KEY="..."
export OPENAI_API_KEY="..."
docker run -p 6333:6333 qdrant/qdrant

For website extraction:

pip install "ragrails[url,store-qdrant]"
ragrails setup-url --browser chromium

Use SDK Quickstart for a copy-paste run, then use Pipeline Overview to choose the right SDK entry point.

​Configure Once

​Workflows

Ingest

Query

​Pipeline

Overview

Extraction

Chunking

Embedding

Storing

Retrieval

Chat

Knowledge Base Maintenance

​Stage Flow

​Result Objects

​Install

Configure Once

Workflows

Pipeline

Stage Flow

Result Objects

Install