KruxAI/ragbuilder

What is RagBuilder?

RagBuilder is a Python library that helps you automatically build a production‑ready Retrieval‑Augmented Generation (RAG) pipeline for any collection of documents. It searches the space of RAG hyper‑parameters (chunk size, chunking strategy, retriever type, reranker, LLM, etc.) with Bayesian optimisation, evaluates each configuration on a test set, and returns the best‑performing setup.

Core capabilities

Capability	How it works (as described in the README)
Hyper‑parameter tuning	Uses Bayesian optimisation to try many combinations of chunking, vector store, retriever, reranker and LLM settings.
Pre‑defined templates	Ships with “state‑of‑the‑art” RAG templates (e.g., graph retriever, contextual chunker) that can be used out‑of‑box.
Test data	You can generate a synthetic test set or supply your own queries/answers for evaluation.
Component access	After optimisation you can directly retrieve the underlying vector store, retriever and generator objects.
API deployment	A single call to builder.serve() starts a local HTTP API (POST /query).
Project persistence	Pipelines can be saved to disk (builder.save()) and re‑loaded later (RAGBuilder.load()).

Typical workflow (quick‑start example)

from ragbuilder import RAGBuilder

# 1️⃣ Load data (URL, PDF, etc.) and use the default configuration
builder = RAGBuilder.from_source_with_defaults(
    input_source='https://lilianweng.github.io/posts/2023-06-23-agent/'
)

# 2️⃣ Run the optimisation (default number of trials)
results = builder.optimize()

# 3️⃣ Query the finished pipeline
answer = results.invoke("What is HNSW?")
print(answer)

# 4️⃣ See a short optimisation report
print(results.summary())

The same pattern works with custom models, custom chunkers, or a custom test dataset.

Customisation points

• Data ingestion – choose document loaders (pymupdf, unstructured, web, …), chunkers (character, semantic, token‑based, etc.) and embedding models.
• Retrieval – mix vector similarity, BM25, multi‑query, graph‑based retrieval, and assign weights.
• Reranking – plug in any of the listed rerankers (BGE, mxbai, Cohere, Jina, FlashRank, RankLLM, ColBERT, …).
• Generation – supply one or more LLM configs (OpenAI, Azure OpenAI, etc.) and optimisation settings such as number of trials.
• Evaluation – use built‑in Ragas evaluation or provide a custom evaluator class.

All of these are expressed through small Pydantic‑style config objects (DataIngestOptionsConfig, RetrievalOptionsConfig, GenerationOptionsConfig).

Installation & environment

• Requires Python 3.10+.
• Recommended to create an isolated virtual environment (uv venv ragbuilder).
• Install via uv pip install ragbuilder (or other methods linked in the docs).
• Set required API keys in a .env file – at minimum OPENAI_API_KEY. Optional keys for Mistral, Cohere, Azure OpenAI, and Neo4j are also supported.

Deployment & security notes

• The built‑in UI and API bind to 127.0.0.1 by default; remote access needs an API token (RAGBUILDER_API_TOKEN) and TLS termination.
• Docker Compose is provided for a containerised setup (includes Neo4j for graph‑based retrieval).
• Basic telemetry is sent to a Cloudflare collector; it can be disabled with ENABLE_ANALYTICS=false.

Project status

The repository is no longer actively maintained – it remains available for reference, but new issues or pull‑requests are not guaranteed to be addressed.

---

TL;DR – RagBuilder is a Python toolkit that automates the design, optimisation and deployment of RAG pipelines, letting you focus on data while it searches for the best combination of chunking, retrieval, reranking and LLM settings.