Overview

Ragrails has two workflows. ingest() builds the index from your sources. query() reads from that index. chat() builds on query by retrieving context and asking your configured LLM for a grounded answer. Start with the workflows when you want the shortest path. Open the pipeline stages when you need to inspect output, tune behavior, or run one part directly.

Workflows

Workflows are the high-level APIs most apps call directly. Use them when you want Ragrails to run the full path for indexing or answering without managing each stage yourself.

Ingest

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

Query

Search the index and generate grounded answers with retrieved context.

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

# Query returns matching chunks.
results = 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=[])

# Ingest builds the index.
ragrails ingest --docs files/refund-policy.pdf \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --provider voyage --model voyage-3

# Query returns matching chunks.
ragrails query "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --provider voyage --model voyage-3 --top-k 5

# Chat returns a grounded answer.
ragrails chat "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --embedder-provider voyage --embedder-model voyage-3 \
  --llm-provider openai --llm-model gpt-4o-mini

# Ingest builds the index.
curl -X POST http://127.0.0.1:8000/v1/pipelines/ingest \
  -H "Content-Type: application/json" \
  -d '{"docs": ["files/refund-policy.pdf"], "embedding": {"provider": "voyage", "model": "voyage-3"}, "storage": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"}}'

# Query returns matching chunks.
curl -X POST http://127.0.0.1:8000/v1/pipelines/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do refunds take?", "embedding": {"provider": "voyage", "model": "voyage-3"}, "retrieval": {"vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "top_k": 5}}'

# Chat returns a grounded answer.
curl -X POST http://127.0.0.1:8000/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do refunds take?", "llm_provider": "openai", "llm_model": "gpt-4o-mini", "embedder_provider": "voyage", "embedder_model": "voyage-3", "vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "history": []}'

{
  "ingest": {"sources": 1, "chunks": 3, "embedded": 3, "stored": 3, "failed": 0},
  "query": {"retrieved": 3, "items": [{"id": "policy#refunds", "score": 0.84}]},
  "chat": {"answer": "Refunds are returned within 5 business days.", "answer_confidence": {"level": "high", "reason": "retrieval_quality_pass"}}
}

Pipeline

Pipeline stages are the lower-level building blocks behind the workflows. Use them when you need to inspect intermediate output, tune a specific step, or run stages independently.

Extraction

Load documents, scraped 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.

# 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=[])

# Extraction
ragrails parse --files files/refund-policy.pdf --output-dir files/output/docs/

# Chunking
ragrails chunk --input-dir files/output/docs/ --output-dir files/output/chunks/

# Embedding
ragrails embed --input-dir files/output/chunks/ --output-dir files/output/embedded/ \
  --provider voyage --model voyage-3

# Storing
ragrails store --input-dir files/output/embedded/ \
  --vector-db qdrant --collection support --url http://localhost:6333

# Retrieval
ragrails retrieve "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --provider voyage --model voyage-3 --top-k 5

# Chat
ragrails chat "How long do refunds take?" \
  --vector-db qdrant --collection support --url http://localhost:6333 \
  --embedder-provider voyage --embedder-model voyage-3 \
  --llm-provider openai --llm-model gpt-4o-mini

# Extraction
curl -X POST http://127.0.0.1:8000/v1/ingest/docs \
  -H "Content-Type: application/json" \
  -d '{"files": ["files/refund-policy.pdf"]}'

# Chunking
curl -X POST http://127.0.0.1:8000/v1/chunk \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Refund policy\n\nRefunds are available within 30 days."}'

# Embedding
curl -X POST http://127.0.0.1:8000/v1/embed \
  -H "Content-Type: application/json" \
  -d '{"chunks": [{"id": "refunds", "text": "Refunds are available within 30 days.", "source": "policy.md", "metadata": {}}], "provider": "voyage", "model": "voyage-3"}'

# Storing
curl -X POST http://127.0.0.1:8000/v1/store \
  -H "Content-Type: application/json" \
  -d '{"embedded_chunks": [{"id": "refunds", "text": "Refunds are available within 30 days.", "embedding": [0.01, 0.02], "source": "policy.md", "metadata": {}}], "vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333"}'

# Retrieval
curl -X POST http://127.0.0.1:8000/v1/retrieve \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do refunds take?", "provider": "voyage", "model": "voyage-3", "vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "top_k": 5}'

# Chat
curl -X POST http://127.0.0.1:8000/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "How long do refunds take?", "llm_provider": "openai", "llm_model": "gpt-4o-mini", "embedder_provider": "voyage", "embedder_model": "voyage-3", "vector_db": "qdrant", "collection": "support", "url": "http://localhost:6333", "history": []}'

{
  "extraction": {"documents": 1, "failed": 0},
  "chunking": {"chunks": 3, "failed": 0},
  "embedding": {"embedded": 3, "failed": 0},
  "storing": {"stored": 3, "failed": 0},
  "retrieval": {"retrieved": 3, "items": [{"id": "policy#refunds", "score": 0.84}]},
  "chat": {"answer": "Refunds are returned within 5 business days.", "answer_confidence": {"level": "high", "reason": "retrieval_quality_pass"}}
}

New to RAG? Read How RAG works. Ready to run it? Start with the Quickstart.

How it fits together

Ingest path: Extraction -> Chunking -> Embedding -> Storing. Query path: Retrieval -> Chat. Stored data is not frozen. As sources change, keep your knowledge base current with edit() and delete() so answers stay accurate.

Get Started

Features

Capabilities

Use Cases

Walkthroughs

Workflows

Ingest

Query

Pipeline

Extraction

Chunking

Embedding

Storing

Retrieval

Chat

Knowledge Base Maintenance

How it fits together

​Workflows

Ingest

Query

​Pipeline

Extraction

Chunking

Embedding

Storing

Retrieval

Chat

Knowledge Base Maintenance

​How it fits together

Workflows

Pipeline

How it fits together