Ragfold

Compare RAG and information-extraction engines behind one interface. Ragfold does for retrieval/extraction tools what docfold does for document parsers: standard adapters, clean fallbacks, built-in benchmarks, and a light default CI that needs no GPU, model downloads, API keys, or network.

pip install -e ".[dev]"
ragfold list-engines
ragfold compare examples/corpus.json examples/queries.json --engines text-rag,bm25 --top-k 3

Engine Comparison

Research-based estimates from public docs, package metadata, and adapter behavior. See docs/benchmarks.md. Costs are estimates, not procurement quotes.

text-rag and bm25 run in core. Every model, cloud, GPU, visual, service, and framework adapter is optional and reports available=no until its extra, credentials, and runtime are configured.

How to Choose

Why Ragfold

Install Extras

Examples:

pip install ragfold
pip install "ragfold[bm25,sentence-transformers,faiss]"
pip install "ragfold[openai,cohere,voyage]"
pip install "ragfold[lightrag,rag-anything,adaptive-chunking,headroom]"

Python API

import asyncio

from ragfold import EngineRouter
from ragfold.engines.bm25 import BM25Engine
from ragfold.engines.text_rag import TextRagEngine


async def main():
    corpus = [
        {"id": "policy", "text": "Refunds are available for 30 days."},
        {"id": "security", "text": "Accounts require multi-factor authentication."},
    ]
    router = EngineRouter([BM25Engine(), TextRagEngine()])

    result = await router.retrieve(corpus, "refund policy", engine_hint="bm25", top_k=1)
    print(result.passages[0].document_id)

    comparison = await router.compare(
        corpus,
        [{"id": "q1", "query": "refund policy", "relevant_ids": ["policy"]}],
        top_k=1,
    )
    print(comparison.keys())


asyncio.run(main())

Optional LightRAG runtime, with provider/model functions configured by the caller:

from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed

from ragfold.engines.github_rag import LightRAGEngine


engine = LightRAGEngine(
    working_dir="./rag_storage",
    llm_model_func=gpt_4o_mini_complete,
    embedding_func=openai_embed,
)

CLI

ragfold list-engines
ragfold compare examples/corpus.json examples/queries.json --engines text-rag,bm25 --top-k 1
ragfold bench examples --engines text-rag,bm25

corpus.json is a list of objects with id and text. queries.json is a list of objects with id, query, relevant_ids, and optional answers.

Evaluation

Ragfold reports retrieval and answer metrics using the same convention as docfold: predicted value first, reference value second, and higher is better.

Reference-free faithfulness is intentionally a gated slow hook because it requires an LLM judge.

Pipeline Stages

EngineRouter can apply optional lifecycle stages consistently across retrieve(), compare(), and process_batch():

from ragfold import EngineRouter
from ragfold.compression import NoopCompressor
from ragfold.engines.text_rag import TextRagEngine
from ragfold.preprocessing import RecursiveChunker

router = EngineRouter(
    [TextRagEngine()],
    chunker=RecursiveChunker(chunk_size=300, chunk_overlap=50),
    compressor=NoopCompressor(),
)

Heavy integrations such as AdaptiveChunker and HeadroomCompressor stay gated behind optional extras and injected runtime objects.

Architecture

Corpus + Queries
      |
      v
EngineRouter  -- optional reranker --> RetrievalResult / RagAnswer
      |
      +-- lexical: text-rag, bm25
      +-- dense: sentence-transformers, OpenAI, Cohere, Voyage
      +-- visual: ColPali, ColQwen2, PixelRAG, DSE
      +-- github RAG forks: LightRAG, RAG-Anything, agentic-file-search
      +-- framework: LlamaIndex, Haystack, txtai
      +-- vector stores: in-memory, FAISS, Qdrant, Chroma, pgvector
      +-- stages: chunkers, indexers, context compressors, eval exporters

Development

pip install -e ".[dev]"
pytest -m "not slow"

All heavy/cloud/GPU/model tests must be marked slow and must not run in the default CI path.