Skip to main content

RAG Framework

PyPI version Python 3.10+ License: MIT CI codecov GitHub issues PRs Welcome GitHub contributors GitHub stars

A modular, extensible Python framework for building Retrieval-Augmented Generation (RAG) pipelines. Plug in your own loaders, embedders, vector stores, and generators — or use the built-in implementations to get started in minutes.


Features

  • Modular by design — every component (loader, chunker, embedder, retriever, generator) is an abstract base class you can swap out
  • Works out of the box — built-in text/Markdown loaders, fixed-size chunker, in-memory cosine retriever, and placeholder implementations that need no API keys
  • Extensible ecosystem — simple contracts mean integrating OpenAI, HuggingFace, ChromaDB, FAISS, or any other tool is just a subclass away
  • Batteries-optional — core dependency is numpy only; add [pdf], [openai], [chromadb], … as you need them
  • Fully tested — pytest-based test suite with coverage reporting
  • Contributor-friendly — clear abstractions, good first issues, and detailed contributing guide

Architecture

                     ┌─────────────────────────────────────┐
                     │            RAGPipeline               │
                     └─────────────┬───────────────────────┘
                                   │
          ┌────────────────────────┼─────────────────────────┐
          │                        │                         │
          ▼                        ▼                         ▼
  ┌───────────────┐       ┌──────────────┐         ┌──────────────────┐
  │ DocumentLoader│──────▶│  TextChunker │──────┐  │                  │
  └───────────────┘       └──────────────┘      │  │                  │
  (TextFileLoader,        (FixedSizeChunker,     │  │                  │
   MarkdownLoader,         SentenceChunker,      │  │                  │
   PDFLoader*, …)          SemanticChunker*)     │  │                  │
                                                 ▼  │                  │
                                          ┌──────────────┐             │
                                          │   Embedder   │             │
                                          └──────┬───────┘             │
                                                 │  (RandomEmbedder,   │
                                                 │   OpenAIEmbedder*,  │
                                                 │   HFEmbedder*)      │
                                                 ▼                     │
                                          ┌──────────────┐             │
                                          │  Retriever   │             │
                                          └──────┬───────┘             │
                                                 │  (InMemoryRetriever,│
                                                 │   FAISSRetriever*,  │
                                                 │   ChromaRetriever*) │
                                                 ▼                     │
                                          ┌──────────────┐             │
                                          │  Generator   │◀────────────┘
                                          └──────────────┘
                                    (EchoGenerator,
                                     OpenAIGenerator*,
                                     AnthropicGenerator*)

  * = open contribution opportunity — see .github/GOOD_FIRST_ISSUES.md

Optional reranking is supported between retrieval and generation via Reranker; CrossEncoderReranker uses the existing [huggingface] extra.


Installation

# Core (numpy only)
pip install ragframework

# With PDF support
pip install "ragframework[pdf]"

# With HuggingFace embeddings (local, no API key)
pip install "ragframework[huggingface]"

# With a vector store
pip install "ragframework[faiss]"
pip install "ragframework[chromadb]"

# With the Anthropic generator
pip install "ragframework[anthropic]"

# Everything
pip install "ragframework[all]"

Requires Python 3.10 or newer. To install the latest unreleased code from main, or to contribute, see CONTRIBUTING.md for the editable-install setup.


Quick Start

from ragframework import RAGPipeline, RAGConfig
from ragframework.document import TextFileLoader
from ragframework.embeddings import RandomEmbedder   # swap for OpenAIEmbedder
from ragframework.retriever import InMemoryRetriever  # swap for FAISSRetriever
from ragframework.generator import EchoGenerator      # swap for OpenAIGenerator

config = RAGConfig(
    chunk_size=512,
    chunk_overlap=64,
    top_k=5,
    embedding_dim=384,
)

pipeline = RAGPipeline.from_config(
    config,
    loader=TextFileLoader(),
    embedder=RandomEmbedder(dim=384),
    retriever=InMemoryRetriever(),
    generator=EchoGenerator(),
)

# Ingest documents
n_chunks = pipeline.ingest_many(["intro.txt", "reference.txt"])
print(f"Indexed {n_chunks} chunks")

# Query, optionally overriding config.top_k for this call
response = pipeline.query("What is this document about?", top_k=3)
print(f"Question: {response.query}")
print(response.answer)
for chunk in response.source_chunks:
    print(f"  Source: {chunk.metadata.get('source')} — {chunk.content[:80]}…")

See the Getting Started guide for an introduction to the components and optional integrations.

Loading CSV and JSON Lines

The built-in tabular loaders need no additional dependencies. Each CSV data row or JSON Lines object becomes a separate document:

from ragframework.document import CSVLoader, JSONLLoader

csv_loader = CSVLoader(
    content_columns=["title", "body"],
    metadata_columns=["url", "date"],
    id_column="id",
)
documents = csv_loader.load("articles.csv")

jsonl_loader = JSONLLoader(content_key="text", metadata_keys=["source"], id_key="id")
documents = jsonl_loader.load("articles.jsonl")

Content fields are joined with separator="\n"; JSONL also accepts a list of content keys. Both loaders accept encoding, and CSV accepts delimiter. Without an explicit ID field, IDs use the source path hash and zero-based row index. Metadata contains the file source, a reserved zero-based row_index, and only the selected metadata fields. Selecting a metadata field named source replaces the file path with that field's value.

CSV errors identify one-based data rows (excluding the header); malformed JSON or missing keys identify one-based lines. JSONL requires string content and string or integer IDs, preserves the types of selected metadata values, and rejects blank lines and non-object records with LoaderError. Empty files return no documents.

Loading HTML files and pages

HTMLLoader uses Python's standard library and needs no additional dependencies:

from ragframework.document import HTMLLoader

loader = HTMLLoader(timeout=10.0, user_agent="my-rag-app/1.0")
documents = loader.load("saved-page.html")
# The same loader accepts an HTTP(S) URL:
# documents = loader.load("https://example.com/article")

Each source produces one document with source, title, and format="html" metadata. The loader omits scripts, styles, navigation, templates, noscript, and head text while preserving the first document title separately, excluding SVG and MathML titles. It collapses whitespace and separates block elements without breaking inline words or punctuation. It reads static HTML and does not execute JavaScript. Local files default to UTF-8 (encoding is configurable); HTTP responses use their declared charset or fall back to that encoding. File, network, and decoding failures raise LoaderError. A page without readable text produces a document with empty content.

Implementing your own component

from ragframework.base import Embedder

class MyEmbedder(Embedder):
    def embed(self, texts: list[str]) -> list[list[float]]:
        # call your embedding API / model here
        ...

That's it — plug MyEmbedder() into RAGPipeline and everything else stays the same.


Roadmap

Community contributions are the engine that drives this roadmap. Pick up a Good First Issue and open a PR!

Priority Item Status
High DOCX document loader (#2) Done (0.4.0)
High OpenAI embeddings integration (#6) Done (0.4.0)
High PDF document loader (#1) Done (0.2.0)
High HuggingFace Sentence Transformers embedder (#7) Done (0.2.0)
High OpenAI generator (#8) Done (0.3.0)
High Anthropic generator (#20) Done (0.2.0)
Medium FAISS vector store retriever (#4) Done (0.2.0)
Medium ChromaDB retriever integration (#5) Done (0.2.0)
Medium Recursive chunker (#3) Done (0.2.0)
Medium Async pipeline support (#9) Done (0.2.0)
Medium Optional reranking stage (#38) Done (0.2.0)
Medium HTML, CSV and JSONL loaders (#35, #36) Done (0.3.0)
Medium Directory loader (#34) Done (0.4.0)
Medium Token-based chunker (#44) Done (0.4.0)
Medium Structured logging (#41) Done (0.4.0)
Medium Retriever.__len__() and clear() (#46) Done (0.4.0)
Low Jupyter notebook examples (#10) Done (0.2.0)

Contributing

Contributions are what make open source great. Please read CONTRIBUTING.md before opening a PR.

  1. Fork the repo and create a branch: git checkout -b feat/my-feature
  2. Install dev dependencies: pip install -e ".[dev]"
  3. Enable the Git hooks: pre-commit install (Python 3.10 is required for the isolated mypy hook)
  4. Write your code and tests
  5. Run the checks: pre-commit run --all-files and pytest tests/ -v
  6. Open a pull request

License

Distributed under the MIT License. See LICENSE for more information.


Acknowledgements

Architecture inspired by RAG-Anything by HKUDS.

Metadata

Release files for ragframework 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ragframework 0.4.0
File Size Uploaded Provenance Actions
ragframework-0.4.0.tar.gz 38.7 kB With provenance Details for ragframework-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ragframework 0.4.0
File Interpreter ABI Platform Actions
ragframework-0.4.0-py3-none-any.whl Python 3 none any Details for ragframework-0.4.0-py3-none-any.whl

Total release size: 83.3 kB

Release files / ragframework-0.4.0.tar.gz

Download URL ragframework-0.4.0.tar.gz
Size 38.7 kB
Tags Source
SHA-256 checksum
How to use checksums
fca1a53d4dbf05f2a2919499228213fde3478e86e59428938cb85efa7a4807f5
BLAKE2b-256 checksum
How to use checksums
c7aa23c7c9431f2a74616de3472d9c71146c79baf2cd505ed9808ad8eee11ed3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Release files / ragframework-0.4.0-py3-none-any.whl

Download URL ragframework-0.4.0-py3-none-any.whl
Size 44.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ccad5f2b876aaffbbe719a18e96928eb7c5a669fb575cff3b548b5ba91363516
BLAKE2b-256 checksum
How to use checksums
26b129695d92d4ba6c4d07af4c83aff7b7a7fdf44c18aaa6902ebb814841ab72
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Security for ragframework 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ragframework-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page