right-rag 0.1.2

Domain-structured RAG pipeline template

right-rag

right-rag is a domain-structured RAG template for documents where plain text chunking loses important context: laws, policies, contracts, manuals, academic papers, handbooks, and other hierarchical corpora.

It is built around one rule: model the document structure first, then choose the retrieval method. Vector search, keyword search, SQL, graph retrieval, and custom domain lookup are all implementation choices, not framework assumptions.

Why right-rag

Most RAG quality problems come from weak evidence modeling:

• rules are separated from their exceptions
• answers cannot be traced to exact source units
• metadata exists but is not usable by retrieval
• the index technology dictates the design

right-rag keeps the core generic and lets each project define what valid evidence means for its domain.

Architecture

flowchart LR
    A[Source documents] --> B[Document loaders]
    B --> C[Unit parsers]
    C --> D[Semantic units]
    D --> E[Chunk parsers]
    E --> F[Retrieval-ready chunks]
    D --> G[Unit savers]
    F --> H[Chunk savers]
    G --> I[Unit artifacts]
    H --> J[Chunk artifacts]
    I --> K[Retrievers]
    J --> K
    K --> L[Answer generator]
    L --> M[Answer with evidence]
    M --> N[Evaluators and reports]

flowchart TD
    subgraph Index
      A[Load documents] --> B[Parse units] --> C[Parse chunks] --> D[Save artifacts]
    end

    subgraph Query
      E[User query] --> F[Retrieve from artifacts] --> G[Generate answer]
    end

    subgraph Evaluate
      H[Evaluation cases] --> E
      G --> I[Evaluate] --> J[Report]
    end

Install

pip install right-rag

Or run without a permanent install:

uvx --from right-rag right-rag --help

Requires Python 3.13+.

Quick Start

right-rag init my-rag
cd my-rag

Put documents in:

data/documents/

Run the pipeline:

right-rag index
right-rag query "your question"
right-rag evaluate

Generated local artifacts:

• output/units/
• output/chunks/
• .right-rag-state.json
• output/evaluation/

The default parsers are smoke-test implementations. Production projects should replace them with domain-specific plugins under spec/.

Project Template

right-rag init creates:

my-rag/
  right_rag.toml
  data/documents/
  eval/cases.example.json
  output/
  spec/
    document_loaders/
    unit_parsers/
    chunk_parsers/
    unit_savers/
    chunk_savers/
    retrievers/
    answer_generators/
    evaluators/
    reporters/

Extension Points

Folder	Purpose
spec/document_loaders/	Load source documents from files, APIs, stores, or custom extractors.
spec/unit_parsers/	Convert documents into a faithful ParsedUnit tree.
spec/chunk_parsers/	Convert semantic Unit objects into retrieval-ready Chunk records.
spec/unit_savers/	Persist units and return unit artifacts.
spec/chunk_savers/	Persist chunks and return chunk artifacts.
spec/retrievers/	Retrieve evidence from artifacts.
spec/answer_generators/	Generate answers from retrieved evidence.
spec/evaluators/	Score query outputs.
spec/reporters/	Write evaluation reports.

Domain Modeling

Start by inspecting the source documents. Choose units that match the author's real structure:

• laws: act -> chapter -> section -> clause -> subclause
• contracts: agreement -> article -> clause -> schedule item
• policies: policy -> section -> rule -> exception
• manuals: manual -> chapter -> procedure -> step
• academic papers: paper -> section -> subsection -> paragraph/table/figure note

Good unit parsers:

• preserve hierarchy with ParsedUnit.subunits
• set source spans when possible
• keep fulltext faithful to the source
• store provenance in attributes or metadata
• reject unsupported formats visibly
• avoid catch-all parsers

Good chunk parsers:

• chunk inside a single unit
• keep rules with their exceptions and limitations
• carry citation and filter attributes
• prefer fewer useful chunks over many tiny fragments

Evaluation

right-rag evaluate eval/cases.example.json --output output/evaluation/report.md

The default evaluator is for smoke tests and regression checks. Real projects should add domain-specific evaluators under spec/evaluators/.

Development

git clone https://github.com/sunmodza/right-rag.git
cd right-rag
uv sync
python -m compileall src/right_rag
python -m unittest discover -s tests
uv build

Run plugin discovery:

uv run python -c "from right_rag.registry import build_registry; r=build_registry(); print(r.document_loaders, r.unit_parsers, r.chunk_parsers, r.unit_savers, r.chunk_savers)"

Release

Publishing runs on version tags:

git tag v0.1.1
git push origin v0.1.1

PyPI Trusted Publishing is configured for:

• project: right-rag
• workflow: publish.yml
• environment: pypi

Design Rules

• Put domain logic in spec/.
• Keep src/right_rag/pipeline.py focused on orchestration.
• Return ParsedUnit from unit parsers.
• Let the library create Unit.
• Treat metadata as stored context, not control flow.
• Do not couple the framework to vector search, keyword search, SQL, or graph retrieval.
• Use stdlib before adding dependencies.