Ragrails

Ragrails is a modular RAG toolkit for turning URLs, local documents, and REST API responses into retrieval-ready vector indexes.

It is organized in layers:

core -> SDK -> CLI -> REST API

Most users should use the SDK, CLI, or REST API. The core modules are the shared foundation that the public interfaces build on.

Install

Ragrails requires Python 3.10 or newer.

pip install ragrails

The base install includes the SDK, CLI, REST API server, document ingestion, API ingestion, chunking, embedding orchestration, vector storage orchestration, retrieval, chat orchestration, and pipeline helpers.

Install extras for URL scraping, model providers, reranking, and vector database clients:

Provider extras are also available separately:

SDK Quick Start

from ragrails import RagRails

rag = RagRails()

Ingest and Store

Run ingestion, chunking, embedding, and vector storage in one call:

from ragrails import RagRails

rag = RagRails()

result = rag.ingest(
    markdown="# Guide\n\nRagrails builds modular RAG workflows.",
    embedding={
        "provider": "voyage",
        "model": "voyage-3",
    },
    storage={
        "vector_db": "qdrant",
        "collection": "docs",
        "url": "http://localhost:6333",
    },
)

print(result.stored)

You can also provide docs, urls, or api sources:

rag.ingest(
    docs=["files/guide.pdf"],
    ingestion={"docs": {"mode": "single"}},
    embedding={"provider": "voyage", "model": "voyage-3"},
    storage={"vector_db": "qdrant", "collection": "docs"},
)

URL ingestion uses Playwright through crawl4ai. Install the URL extra and run browser setup once in the target environment:

pip install "ragrails[url,voyage,qdrant]"

RagRails().setup_url()

Query

Run query embedding and retrieval in one call:

result = rag.query(
    "What does the guide cover?",
    embedding={
        "provider": "voyage",
        "model": "voyage-3",
    },
    retrieval={
        "vector_db": "qdrant",
        "collection": "docs",
        "url": "http://localhost:6333",
        "top_k": 5,
    },
)

for chunk in result.items:
    print(chunk.text)

Chat

Chat is stateless. Pass history explicitly and persist the returned result.history in your app session.

from ragrails import QueryRewriteConfig, RagRails

rag = RagRails()

llm = rag.llm(provider="openai", model="gpt-4.1-mini")
embedder = rag.embedder(provider="voyage", model="voyage-3", input_type="query")

history = []

result = rag.chat(
    "How do I authenticate?",
    llm=llm,
    embedder=embedder,
    vector_db="qdrant",
    collection="docs",
    url="http://localhost:6333",
    history=history,
    query_rewrite=QueryRewriteConfig(enabled=True),
)

print(result.answer)
history = result.history

Edit and Delete Stored Chunks

Edit and delete operations are vector database agnostic at the SDK layer.

edit_result = rag.edit(
    chunks=[
        {
            "id": "chunk-id",
            "text": "Updated chunk text",
            "source": "files/guide.pdf",
            "metadata": {"title": "Guide"},
        }
    ],
    embedder=rag.embedder(provider="voyage", model="voyage-3"),
    vector_db="qdrant",
    collection="docs",
    url="http://localhost:6333",
)

delete_result = rag.delete(
    ids=["chunk-id"],
    vector_db="qdrant",
    collection="docs",
    url="http://localhost:6333",
)

CLI

Ragrails ships with a CLI for local workflows and smoke tests.

ragrails --help

Examples:

ragrails ingest \
  --markdown "# Guide\n\nUse Ragrails for RAG workflows." \
  --vector-db qdrant \
  --collection docs

ragrails query "What does the guide cover?" \
  --vector-db qdrant \
  --collection docs

CLI docs live in ragrails/interfaces/cli/README.md.

REST API

Ragrails ships a FastAPI server on top of the SDK.

ragrails-api

Swagger UI is available at http://127.0.0.1:8000/docs when the server is running. The OpenAPI schema is available at /v1/openapi.json.

REST docs live in ragrails/interfaces/server/README.md.

Package Structure

ragrails/
  core/
    stg_01_ingestors/
    stg_02_chunker/
    stg_03_embedder/
    stg_04_storing/
    stg_05_retriever/
    stg_06_chat/
  interfaces/
    sdk/
    cli/
    server/

Interface Docs

Specialized SDK ingestion docs:

• URL ingestion
• Document ingestion
• API ingestion

Development Checks

Run local interface checks:

scripts/test-core.sh
scripts/test-sdk.sh
scripts/test-cli.sh
scripts/test-rest.sh

The repo uses .githooks/pre-push, so git push runs the same checks and blocks the push if any interface test fails.

Build and validate release artifacts:

uv build
uvx twine check dist/*

Publish only after the checks pass:

uv publish

Status

The public SDK currently covers ingestion, chunking, embedding, vector storage, retrieval, chat, vector edit/delete, and end-to-end ingestion/query pipeline helpers. CLI and REST API interfaces are built on top of the SDK.