# https://github.com/KruxAI/ragbuilder Project Manual

Generated at: 2026-07-05 19:14:40 UTC

## Table of Contents

- [Overview and Installation](#page-1)
- [Core SDK API and Configuration Schema](#page-2)
- [RAG Templates and Component Modules](#page-3)
- [Optimization, Evaluation, Deployment, and Troubleshooting](#page-4)

<a id='page-1'></a>

## Overview and Installation

### Related Pages

Related topics: [Core SDK API and Configuration Schema](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/KruxAI/ragbuilder/blob/main/README.md)
- [install.sh](https://github.com/KruxAI/ragbuilder/blob/main/install.sh)
- [install.bat](https://github.com/KruxAI/ragbuilder/blob/main/install.bat)
- [docker-compose.yml](https://github.com/KruxAI/ragbuilder/blob/main/docker-compose.yml)
- [Dockerfile](https://github.com/KruxAI/ragbuilder/blob/main/Dockerfile)
- [pyproject.toml](https://github.com/KruxAI/ragbuilder/blob/main/pyproject.toml)
- [requirements.txt](https://github.com/KruxAI/ragbuilder/blob/main/requirements.txt)
- [.env.example](https://github.com/KruxAI/ragbuilder/blob/main/.env.example)
</details>

# Overview and Installation

RAGBuilder is an open-source toolkit for automatically configuring and optimizing Retrieval-Augmented Generation (RAG) pipelines. It explores combinations of LLMs, embeddings, vector stores, retrievers, and re-rankers against an evaluation dataset, then surfaces the configuration that produces the best answer quality. The toolkit exposes both a no-code web interface and a programmatic Python SDK, letting users move from experimentation to integration in the same codebase. Source: [README.md:1-40]()

## Project Scope and Core Capabilities

The repository delivers three primary modes of operation, declared in the top-level documentation:

- **Auto-optimization**: a "Best RAG for your data" run that sweeps module options and reports the winning configuration. Source: [README.md:42-60]()
- **Custom configuration**: a constrained search where the user pins specific modules (LLM, embeddings, retriever, vector DB) and lets RAGBuilder explore only the remaining dimensions. Source: [README.md:62-80]()
- **GraphRAG templates**: pre-built graph and hybrid pipelines that augment vector retrieval with knowledge-graph traversal. Source: [README.md:82-100]()

The SDK entry point introduced in release `v0.1.4` exposes these flows as Python objects. The minimal pattern is:

```python
from ragbuilder import RAGBuilder

builder = RAGBuilder.from_source_with_defaults(input_source='data.pdf')
results = builder.optimize()
response = results.invoke("What is HNSW?")
```

Source: [README.md:55-72](), release notes: [v0.1.4](https://github.com/KruxAI/ragbuilder/releases/tag/v0.1.4).

## System Requirements

The native installer expects a Python environment together with several system libraries required by the document-loaders and graph backends. On macOS the shell script explicitly upgrades CA certificates and installs `cairo`, `pkg-config`, and related graphics libraries that LangChain's `unstructured` and `graphrag` packages depend on. Source: [install.sh:1-40]()

On Windows the equivalent batch script sets up a virtual environment and installs Python wheels, but assumes a working Python 3.10+ interpreter is already on `PATH`. Source: [install.bat:1-30]()

A `.env.example` file shipped at the repository root enumerates the API keys and service URLs the application expects, including `OPENAI_API_KEY`, `SINGLESTOREDB_URL`, and `PINECONE_API_KEY`. Source: [.env.example:1-40]()

## Installation Paths

RAGBuilder ships three official installation routes, each with a different trade-off between convenience and control.

| Method | Entry point | Best for |
| --- | --- | --- |
| macOS / Linux shell | `install.sh` | Local development on Unix |
| Windows batch | `install.bat` | Local development on Windows |
| Docker Compose | `docker-compose.yml` | Reproducible, OS-independent runs |

The Docker image installs Python dependencies inside a container and exposes the Streamlit UI on a configurable port. The compose file wires the `ragbuilder` service, mounts the working directory as a volume, and pulls environment variables from a local `.env` file, which is how secrets such as `OPENAI_API_KEY` reach the application at runtime. Source: [docker-compose.yml:1-25]()

Inside the image, the `Dockerfile` copies the project, installs requirements from `pyproject.toml`, and sets the default command to launch the web UI. Source: [Dockerfile:1-40]()

## Configuration and First Run

After installation, configuration proceeds in three steps:

1. Copy `.env.example` to `.env` and populate the credentials for the providers you intend to use. Source: [.env.example:1-40]()
2. Provide an input source — a local file, a directory, or a URL — that the data processor will classify and chunk. Source: [README.md:95-110]()
3. Run the optimizer. Depending on the mode, RAGBuilder either sweeps the full configuration space or searches within the constraints you provided. Source: [README.md:60-88]()

The data ingestion layer is implemented in `src/ragbuilder/data_processor.py`, which classifies the input path, reads files or fetches URLs, and produces the document chunks fed into the evaluation pipeline. Source: [data_processor.py:1-50]()

```mermaid
flowchart LR
    A[Input Source] --> B[Data Processor]
    B --> C[Chunked Documents]
    C --> D[RAGBuilder.optimize]
    D --> E[Module Sweep]
    E --> F[Best Config]
    F --> G[results.invoke]
```

## Known Installation Issues and Workarounds

Several installation and first-run problems have been reported by the community and are worth handling before starting:

- **macOS installer stalls after `cairo` install.** A user reported the script hanging silently after the homebrew step. The workaround is to run the `cairo`, `pkg-config`, and `cairo-py3` installs in a fresh terminal to confirm success, then re-run `install.sh`. Source: [issue #55](https://github.com/KruxAI/ragbuilder/issues/55)
- **`install.sh` 404 on `Brewfile`.** The script references a `Brewfile` at `raw.githubusercontent.com/KruxAI/ragbuilder/main/Brewfile` which has been removed, producing `curl: (56) The requested URL returned error: 404`. Users can comment out the `brew bundle` line or install the listed formulae manually. Source: [issue #89](https://github.com/KruxAI/ragbuilder/issues/89)
- **Docker compose git setup failure on Mac.** Running `docker compose up` triggers a `gitpython` refresh error because `git` is not present in the image. Setting `GIT_PYTHON_REFRESH=quiet` in `.env` suppresses the prompt and lets the container boot. Source: [issue #58](https://github.com/KruxAI/ragbuilder/issues/58)
- **OpenAI rate-limit (HTTP 429).** RAGBuilder makes many parallel calls during optimization, which can exceed free-tier OpenAI quotas. Reducing the number of combinations or supplying a higher-tier key resolves the failure. Source: [issue #28](https://github.com/KruxAI/ragbuilder/issues/28)
- **Exposed API key in repository history.** A `GOOGLE_API_KEY` was found committed in source; rotate the key in Google Cloud Console and scrub it from git history before continuing. Source: [issue #90](https://github.com/KruxAI/ragbuilder/issues/90)

## Verifying the Install

A successful installation prints the Streamlit URL (default `http://localhost:8501`) once the container or script reaches the `optimize` stage. From the web UI you can upload a source document and trigger the optimization run; from the SDK the equivalent check is that `RAGBuilder.from_source_with_defaults(input_source=...).optimize()` returns a non-`None` `results` object. Source: [README.md:110-130]()

Once the basics are working, the next pages in this wiki cover module-wise configuration, custom RAG constraints, and GraphRAG templates.

---

<a id='page-2'></a>

## Core SDK API and Configuration Schema

### Related Pages

Related topics: [Overview and Installation](#page-1), [RAG Templates and Component Modules](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/ragbuilder/ragbuilder.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/ragbuilder.py)
- [src/ragbuilder/__init__.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/__init__.py)
- [src/ragbuilder/config/base.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/config/base.py)
- [src/ragbuilder/config/components.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/config/components.py)
- [src/ragbuilder/config/data_ingest.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/config/data_ingest.py)
- [src/ragbuilder/config/retriever.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/config/retriever.py)
</details>

# Core SDK API and Configuration Schema

## Purpose and Scope

The Core SDK API and Configuration Schema form the public entry point and the typed configuration backbone of ragbuilder. Together they expose a single, programmatic way for users to ingest source material, search a space of retrieval-augmented generation (RAG) configurations, optimize the best pipeline, and invoke it for queries. The SDK was introduced to replace the previous CLI/UI flow and to make module-wise configuration tractable from Python code.

The SDK is published as the top-level `ragbuilder` package, and `RAGBuilder` is the primary class users interact with. The accompanying `config` subpackage defines the strongly-typed schemas that describe every component a pipeline can contain — data ingestion, document splitting, embeddings, vector stores, retrievers, generators, and evaluators. Centralizing these schemas ensures that the optimizer, the runtime, and the evaluation harness all speak the same vocabulary.

Source: [src/ragbuilder/__init__.py:1-1]()
Source: [src/ragbuilder/ragbuilder.py:1-1]()
Source: [src/ragbuilder/config/base.py:1-1]()

## SDK Entry Point: `RAGBuilder`

The `RAGBuilder` class is the orchestrator. It accepts an `input_source` (a file path, a directory, or a URL) and a configuration object, then drives optimization and inference. The most concise usage, as documented in the v0.1.4 release notes, is:

```python
from ragbuilder import RAGBuilder

builder = RAGBuilder.from_source_with_defaults(input_source='data.pdf')
results = builder.optimize()
response = results.invoke("What is HNSW?")
```

The class separates two concerns:

- **Construction time** — handled by `from_source_with_defaults` and related class methods, which build a default configuration tree from the input. The defaults are derived from the schemas in `config/`, so any field a user omits is filled with a type-checked default.
- **Run time** — handled by `optimize()` (which selects the best pipeline by evaluating candidates against an optional test set) and the returned object, which exposes `invoke()` to run a query through the materialized pipeline.

The split between construction and run time is deliberate: it lets users mutate the configuration object (for example, to restrict retrievers or change models) before `optimize()` is called, and it lets `optimize()` run many candidate configurations through the same runtime.

Source: [src/ragbuilder/ragbuilder.py:1-1]()

## Configuration Schema Architecture

The `config` subpackage is organized so that each stage of a RAG pipeline has its own schema module, all rooted in a common base. The relationship between the schemas is summarized below.

| Module | Responsibility |
|---|---|
| `config/base.py` | Defines `ConfigBase`, the shared base class for all typed configs (validation, default factory, serialization). |
| `config/data_ingest.py` | Schemas for source loading, file classification, and document splitting. |
| `config/components.py` | Schemas for embedding models, LLMs, vector databases, and generators. |
| `config/retriever.py` | Schemas for retrievers (similarity, MMR, BM25, graph, hybrid). |

`ConfigBase` provides the conventions every child schema inherits — field validation, optional vs. required fields, default factories, and a uniform way to express "this field is auto-determined from context." This is why a single `ConfigBase` instance can be threaded through the optimizer and the runtime without each module re-parsing its arguments.

Source: [src/ragbuilder/config/base.py:1-1]()
Source: [src/ragbuilder/config/components.py:1-1]()
Source: [src/ragbuilder/config/data_ingest.py:1-1]()
Source: [src/ragbuilder/config/retriever.py:1-1]()

## Module-Wise Configuration

Because each pipeline stage has its own schema file, users can configure the SDK module-by-module rather than passing one monolithic dictionary. The v0.1.4 release notes describe this as "module-wise optimization," and it is the intended way to address two recurring community pain points:

- **Restricting the search space.** Issue [#69](https://github.com/KruxAI/ragbuilder/issues/69) reports that custom retriever selection was being overridden — the optimizer picked MMR or BM25 even when the user asked for similarity search only. The retriever schema in `config/retriever.py` is the place where the allow-list of retrievers is declared so the optimizer respects it.
- **Swapping providers via environment.** Issue [#80](https://github.com/KruxAI/ragbuilder/issues/80) requests OpenAI-compatible `base_url` configuration for local runtimes such as Ollama, vLLM, and XInference. `config/components.py` is the natural location for these fields, and the typed schema lets a user set them once and have them propagate to every LLM and embedding call.

The data ingestion schema in `config/data_ingest.py` mirrors the responsibility of `DataProcessor`, which was hardened in release 0.0.22 for error handling, efficiency, and logging. Keeping the schema next to the processor means the same field names (loader type, chunk size, overlap) are used at config time and at run time.

Source: [src/ragbuilder/config/retriever.py:1-1]()
Source: [src/ragbuilder/config/components.py:1-1]()
Source: [src/ragbuilder/config/data_ingest.py:1-1]()

## Runtime Invocation and Evaluation

After `optimize()` returns, the resulting object is a fully materialized pipeline. Calling `invoke(question)` routes the question through the chosen retriever(s) and generator and returns the answer. The same pipeline is what evaluation (for example, RAGAS, as raised in issue [#70](https://github.com/KruxAI/ragbuilder/issues/70)) exercises under the hood, so the configuration schema also defines what evaluators are allowed to score.

When `invoke()` or the evaluator needs an LLM or embedding model, the configuration is read from `config/components.py`; retriever behavior comes from `config/retriever.py`; and how source documents were originally loaded and split is recorded in `config/data_ingest.py`. This round trip — config in, materialized pipeline out, runtime reads config — is the contract that makes the SDK reproducible.

Source: [src/ragbuilder/ragbuilder.py:1-1]()
Source: [src/ragbuilder/config/base.py:1-1]()

## Community Considerations

Several open issues intersect directly with the schema and SDK layer and are worth knowing when designing around them:

- Issue [#58](https://github.com/KruxAI/ragbuilder/issues/58) (Docker Compose + macOS + git) suggests that the runtime inside the SDK reaches out to Git; any schema field that affects code generation should default to safe values when the network is constrained.
- Issue [#90](https://github.com/KruxAI/ragbuilder/issues/90) flags an exposed Google API key committed to the repo; the schema is the right place to enforce secret-via-environment-variable only.
- Issues [#57](https://github.com/KruxAI/ragbuilder/issues/57) and [#83](https://github.com/KruxAI/ragbuilder/issues/83) (GraphRAG retrieval and graph-loading errors) imply that `config/retriever.py` for the graph and hybrid templates still has edge cases to harden.

Together, the SDK class in `ragbuilder.py` and the typed schemas under `config/` define the stable contract that the optimizer, runtime, and evaluation harness all share, and the issues above describe where that contract is still being refined.

---

<a id='page-3'></a>

## RAG Templates and Component Modules

### Related Pages

Related topics: [Core SDK API and Configuration Schema](#page-2), [Optimization, Evaluation, Deployment, and Troubleshooting](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/ragbuilder/rag_templates/sota/graph_rag.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/graph_rag.py)
- [src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py)
- [src/ragbuilder/rag_templates/sota/hybrid_rag.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/hybrid_rag.py)
- [src/ragbuilder/rag_templates/sota/hyde.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/hyde.py)
- [src/ragbuilder/rag_templates/sota/query_rewrite.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/query_rewrite.py)
- [src/ragbuilder/rag_templates/sota/simple_rag.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/rag_templates/sota/simple_rag.py)
</details>

# RAG Templates and Component Modules

## Overview

The RAG Templates and Component Modules form the core abstraction layer of `ragbuilder`, located under `src/ragbuilder/rag_templates/sota/`. Each template is a self-contained, pre-built Retrieval-Augmented Generation (RAG) pipeline that can be selected, evaluated, and deployed without requiring the user to assemble retrieval, indexing, and generation components from scratch.

The SOTA (State-Of-The-Art) catalog packages well-known RAG patterns into composable modules so that the optimizer can mix and match strategies during automated search. Source: [src/ragbuilder/rag_templates/sota/simple_rag.py:1-30]()

The v0.1.4 SDK exposes this composition through `RAGBuilder.from_source_with_defaults(...)` followed by `optimize()`, allowing users to constrain which modules vary and which remain fixed per pipeline slot. Source: [src/ragbuilder/rag_templates/sota/simple_rag.py:1-30]() (cross-ref release v0.1.4)

## Template Catalog

The following table summarizes the six built-in templates shipped under `src/ragbuilder/rag_templates/sota/`:

| Template | File | Strategy | Primary Use Case |
|---|---|---|---|
| Simple RAG | `simple_rag.py` | Direct vector similarity retrieval → LLM answer | Baseline pipeline, low-latency QA |
| Hybrid RAG | `hybrid_rag.py` | Vector store + BM25 keyword search fusion | Improved recall on keyword-heavy queries |
| HyDE | `hyde.py` | Generates hypothetical document, embeds it, then retrieves | Bridges query–document semantic gap |
| Query Rewrite | `query_rewrite.py` | Rewrites user query via LLM before retrieval | Handles ambiguous or multi-intent questions |
| GraphRAG | `graph_rag.py` | Retrieves from a knowledge graph built over the corpus | Multi-hop reasoning and entity-centric QA |
| GraphRAG Hybrid | `graph_rag_hybrid.py` | Combines graph traversal with vector retrieval | Hybrid symbolic + dense retrieval |

Source: [src/ragbuilder/rag_templates/sota/hybrid_rag.py:1-20](), [src/ragbuilder/rag_templates/sota/hyde.py:1-20](), [src/ragbuilder/rag_templates/sota/query_rewrite.py:1-20](), [src/ragbuilder/rag_templates/sota/graph_rag.py:1-20](), [src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py:1-20]()

## Component Modules

Each template is composed of interchangeable module slots that the optimizer can vary:

### Retrievers

The retriever module abstracts over the data-source access strategy. The simple template uses a single vector-store retriever, while `hybrid_rag.py` introduces a BM25 retriever and fuses results with the dense vector hits to balance lexical and semantic matching. Source: [src/ragbuilder/rag_templates/sota/hybrid_rag.py:30-80](), [src/ragbuilder/rag_templates/sota/simple_rag.py:40-90]()

A known limitation surfaced by users is that when a custom configuration requests only "Vector DB – Similarity Search", runs sometimes still substitute "MMR search" or "BM25 Search" retrievers (community issue #69), indicating that retriever selection does not always honor the explicit user constraint. Source: [src/ragbuilder/rag_templates/sota/simple_rag.py:1-50]() (cross-ref community issue #69)

### Query Transformations

`query_rewrite.py` and `hyde.py` implement pre-retrieval query transformations. Query rewriting normalizes the user question into a form better suited for retrieval, while HyDE (Hypothetical Document Embeddings) prompts the LLM to imagine an answer first and embeds that generated text to search the index — closing the gap between short queries and long document embeddings. Source: [src/ragbuilder/rag_templates/sota/query_rewrite.py:1-60](), [src/ragbuilder/rag_templates/sota/hyde.py:1-60]()

### Graph Components

The graph-based templates introduce an additional module that builds and queries a knowledge graph over the corpus. `graph_rag.py` exposes a `full_retriever` function that calls `graph_retriever` to obtain graph data and additionally fetches vector-store data — although community review (issue #57) notes the vector-store branch is currently fetched but not used in the return value, making it a candidate for cleanup. Source: [src/ragbuilder/rag_templates/sota/graph_rag.py:1-80]() (cross-ref community issue #57)

The hybrid variant in `graph_rag_hybrid.py` pairs graph traversal with vector retrieval, aiming to combine the precision of symbolic lookups with the recall of dense embeddings for hybrid reasoning workloads. Source: [src/ragbuilder/rag_templates/sota/graph_rag_hybrid.py:1-80]()

## Known Issues and Community Notes

Several template-level limitations have been raised by users and are relevant when selecting or extending modules:

- **Graph loading instability**: GraphRAG templates (graph-only and hybrid) intermittently fail during graph load with errors logged from `loader.py` (community issue #83). The timing of failure varies per execution, suggesting non-deterministic resource contention during graph construction. Source: [src/ragbuilder/rag_templates/sota/graph_rag.py:1-120]() (cross-ref community issue #83)
- **Outdated graph builder**: The graph builder uses a slightly older LangChain integration; users (issue #59) have requested migration to `llm graph transformer` from langchain and an `ignore_tools_use` option for finer control. Source: [src/ragbuilder/rag_templates/sota/graph_rag.py:1-120]() (cross-ref community issue #59)
- **Local model support**: Users (issue #80) have requested adding an `OPENAI_BASE_URL` environment variable and broader model selection so that Ollama, VLLM, and XInference (OpenAI-schema-compatible hosts) can drive the templates without code changes. Source: [src/ragbuilder/rag_templates/sota/simple_rag.py:1-50]() (cross-ref community issue #80)
- **Source data ingestion confusion**: Users (issue #84) have asked how to point the templates at custom source data when only third-party vector DB credentials (Pinecone, SingleStore) are configured. This relates to the DataProcessor module that feeds every retriever slot in this template catalog. Source: [src/ragbuilder/rag_templates/sota/simple_rag.py:1-50]() (cross-ref community issue #84)

---

<a id='page-4'></a>

## Optimization, Evaluation, Deployment, and Troubleshooting

### Related Pages

Related topics: [Core SDK API and Configuration Schema](#page-2), [RAG Templates and Component Modules](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/ragbuilder/data_ingest/optimization.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/data_ingest/optimization.py)
- [src/ragbuilder/data_ingest/evaluation.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/data_ingest/evaluation.py)
- [src/ragbuilder/data_ingest/pipeline.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/data_ingest/pipeline.py)
- [src/ragbuilder/retriever/optimization.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/retriever/optimization.py)
- [src/ragbuilder/retriever/evaluation.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/retriever/evaluation.py)
- [src/ragbuilder/retriever/pipeline.py](https://github.com/KruxAI/ragbuilder/blob/main/src/ragbuilder/retriever/pipeline.py)
</details>

# Optimization, Evaluation, Deployment, and Troubleshooting

This page documents the post-ingestion phases of the ragbuilder SDK: how each pipeline module is tuned against a dataset, how candidate configurations are scored, how optimized pipelines are packaged for downstream use, and how to recover from the failures most commonly reported by users.

## Pipeline Architecture and Module Boundaries

ragbuilder models the RAG pipeline as a sequence of independently optimizable stages. The ingestion half covers loading, chunking, and embedding, while the retrieval half covers the vector store, retrievers, re-rankers, and the LLM used for generation. Each stage exposes its own optimizer and evaluator so that a search over one module does not re-run the others.

```
ingest_source ──▶ DataIngestPipeline ──▶ RetrieverPipeline ──▶ invoke()
        │                   │                      │
        ▼                   ▼                      ▼
    data_ingest/      retriever/           retriever/generation.py
```

The split is deliberate: chunking strategy and embedding model selection are evaluated on retrieval-quality proxies (recall@k), whereas the retrieval side is evaluated on end-to-end answer quality (faithfulness, answer relevance). Source: [src/ragbuilder/data_ingest/pipeline.py:1-40](), Source: [src/ragbuilder/retriever/pipeline.py:1-40]().

## Optimization

Optimization is performed per module. The ingest-side optimizer in `data_ingest/optimization.py` searches over chunk size, chunk overlap, and embedding model, while the retriever-side optimizer in `retriever/optimization.py` searches over vector store choice, retriever type (similarity, MMR, BM25, hybrid), re-ranker presence, and LLM parameters.

The public entry point introduced in v0.1.4 is `RAGBuilder.optimize()`:

```python
from ragbuilder import RAGBuilder

builder = RAGBuilder.from_source_with_defaults(input_source='data.pdf')
results = builder.optimize()        # module-wise search
response = results.invoke("What is HNSW?")
```

Each optimizer returns a ranked list of candidate configurations along with their evaluation scores, so the caller can inspect why a particular combination was selected. Source: [src/ragbuilder/data_ingest/optimization.py:1-60](), Source: [src/ragbuilder/retriever/optimization.py:1-60]().

## Evaluation

Evaluation is delegated to RAGAS-style metrics and is implemented separately for the two halves of the pipeline. The data-ingest evaluator focuses on retrieval proxies such as context recall and context precision, while the retriever evaluator adds answer-level metrics such as faithfulness and answer relevance.

| Stage | Evaluator | Primary Metrics | Source File |
|-------|-----------|-----------------|-------------|
| Ingest | `data_ingest/evaluation.py` | context_recall, context_precision | data_ingest/evaluation.py |
| Retrieval | `retriever/evaluation.py` | faithfulness, answer_relevancy | retriever/evaluation.py |

A known limitation reported by users is that explicitly restricting the search to a single retriever (e.g., "Vector DB - Similarity Search") does not always prevent the optimizer from selecting MMR or BM25 variants (see issue #69). This is caused by the optimizer falling back to its default candidate set when the user-supplied configuration cannot be evaluated against the test set. Source: [src/ragbuilder/data_ingest/evaluation.py:1-50](), Source: [src/ragbuilder/retriever/evaluation.py:1-50]().

## Deployment and Troubleshooting

Deployment uses the same pipeline objects produced by `optimize()`. The pipeline is exported as a runnable LangChain chain that can be invoked directly, serialized with `pickle`, or wrapped in a FastAPI/Streamlit service. The Streamlit UI in the repository calls the optimized chain directly via `results.invoke()`.

The following troubleshooting guidance is derived from the most-engaged community issues:

- **OpenAI rate-limit errors (issue #28):** Reduce the candidate set or switch to a smaller model such as `gpt-4o-mini`; evaluation calls are the dominant source of 429 responses. Source: [src/ragbuilder/retriever/evaluation.py:1-80]().
- **Docker / git setup on macOS (issue #58):** Set `GIT_PYTHON_REFRESH=quiet` in the compose `.env` file when running via `docker compose up`. Source: [src/ragbuilder/data_ingest/pipeline.py:1-40]().
- **GraphRAG graph-loading failures (issue #83):** The error is intermittent and originates in the graph construction step; rerunning with a smaller corpus or with `ignore_tools_use=False` (issue #59) is the recommended workaround. Source: [src/ragbuilder/retriever/pipeline.py:1-60]().
- **RAGAS evaluation crashes (issue #70):** Frequently caused by missing embeddings for the test set; ensure the test questions are embedded with the same model selected by the optimizer. Source: [src/ragbuilder/data_ingest/evaluation.py:1-50]().
- **Installer 404 on `Brewfile` (issue #89) and macOS install hang (issue #55):** The Brewfile URL is no longer reachable; users should install system dependencies manually before running `/install.sh`. Source: [src/ragbuilder/data_ingest/pipeline.py:1-40]().

For all error paths, the data processor has been hardened in v0.0.22 to wrap file reads, URL fetches, and directory walks in `try-except` blocks and to log recoverable failures instead of aborting the pipeline (PR #72). Source: [src/ragbuilder/data_ingest/pipeline.py:1-120]().

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: KruxAI/ragbuilder

Summary: Found 16 structured pitfall item(s), including 5 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

## 1. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/69

## 2. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/57

## 3. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/55

## 4. Installation risk - Installation risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/70

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/28

## 6. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/89

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/83

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/71

## 9. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/KruxAI/ragbuilder

## 10. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/KruxAI/ragbuilder

## 11. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/KruxAI/ragbuilder

## 12. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/KruxAI/ragbuilder

## 13. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/84

## 14. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/KruxAI/ragbuilder/issues/90

## 15. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/KruxAI/ragbuilder

## 16. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/KruxAI/ragbuilder

<!-- canonical_name: KruxAI/ragbuilder; human_manual_source: deepwiki_human_wiki -->