Metadata-Version: 2.5
Name: rag-titan
Version: 0.6.1
Summary: A Swiss Army knife for RAG: simple, adaptive and more RAG types in one beginner-friendly package.
Project-URL: Homepage, https://github.com/aion7891/rag-titan
Project-URL: Documentation, https://aion7891.github.io/rag-titan
Project-URL: Repository, https://github.com/aion7891/rag-titan
Project-URL: Issues, https://github.com/aion7891/rag-titan/issues
Project-URL: Changelog, https://github.com/aion7891/rag-titan/blob/main/CHANGELOG.md
Author: Kumar Nishant
License: MIT License
        
        Copyright (c) 2026 Kumar Nishant
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: embeddings,llm,ollama,rag,retrieval-augmented-generation,vector-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: ollama>=0.4.0
Requires-Dist: pypdf>=4.0
Requires-Dist: python-docx>=1.1
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.7; extra == 'tokens'
Description-Content-Type: text/markdown

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/banner.svg" alt="rag-titan: a Swiss Army knife for RAG. Many RAG types, one simple API, runs locally." width="100%"></a>
</p>

<p align="center">
  <a href="https://pypi.org/project/rag-titan/"><img src="https://img.shields.io/pypi/v/rag-titan?label=pypi" alt="PyPI version"></a>
  <a href="https://pypi.org/project/rag-titan/"><img src="https://img.shields.io/pypi/pyversions/rag-titan" alt="Python versions"></a>
  <a href="https://github.com/aion7891/rag-titan/actions/workflows/tests.yml"><img src="https://github.com/aion7891/rag-titan/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
  <a href="https://aion7891.github.io/rag-titan/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg" alt="Documentation"></a>
  <a href="https://github.com/aion7891/rag-titan/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/"><b>📖 Documentation</b></a> ·
  <a href="https://aion7891.github.io/rag-titan/getting-started/">Getting started</a> ·
  <a href="https://aion7891.github.io/rag-titan/rag-types/">Supported RAG types</a> ·
  <a href="https://aion7891.github.io/rag-titan/api/core/">API reference</a> ·
  <a href="https://pypi.org/project/rag-titan/">PyPI</a>
</p>

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/overview.svg" alt="rag-titan overview: index your files once, then ask questions" width="100%"></a>
</p>

## Why rag-titan?

- **Many RAG types, one API.** Two today (`simple`, `adaptive`), with more on the way. Switch with one word: `rag_type="adaptive"`.
- **Runs 100% locally** with [Ollama](https://ollama.com), so your documents never leave your machine.
- **Grounded answers.** The model answers only from your files and cites the chunks it used.
- **Chunking your way.** Eight chunkers: by words, characters or model tokens (tiktoken or your own tokenizer), recursive separators, and structure-aware chunkers that keep sentences, paragraphs, heading sections or pages whole. [Try them live in the chunk playground →](https://aion7891.github.io/rag-titan/playground/)
- **PDF, Word, Markdown and text files**, with paragraphs, headings and pages kept for the chunkers.
- **Measure, don't guess.** Compare any chunker with any RAG type on your own questions in one command (`rag-titan evaluate`): recall, MRR, nDCG, answered rate and p95 time, plus every step of a run with `--trace`. [Evaluating RAG →](https://aion7891.github.io/rag-titan/evaluation/)
- **Easy to read, easy to change.** Short files, plain Python, and a docstring on every class. Swap any part by inheriting one base class.

## Install

```bash
pip install rag-titan
ollama pull gemma3:4b && ollama pull nomic-embed-text
```

For token-based chunking, add the extra: `pip install "rag-titan[tokens]"`.

Needs Python 3.10+ and [Ollama](https://ollama.com/download). → [Full setup guide](https://aion7891.github.io/rag-titan/getting-started/)

## Quick start

```python
from rag_titan import RAGTitan

rag = RAGTitan(rag_type="simple")            # or "adaptive"
rag.index(["handbook.pdf", "policy.docx"])

print(rag.ask("How many leave days do I get?"))
# You get 20 paid leave days every year [chunk_0].

print(rag.run("How many leave days do I get?")["log"])   # every step it took
rag.evaluate("questions.json")                           # score it on your own test questions
```

Or from the terminal:

```bash
rag-titan ask --files handbook.pdf --question "How many leave days do I get?"
rag-titan ask --files handbook.pdf --question "How many leave days do I get?" --trace
```

## Evaluate on your own questions

Which chunker and which RAG type work best **for your documents**? Write a few
test questions, each naming the file (or page) that holds the answer, and compare
every combination in one command:

```bash
rag-titan evaluate --files docs/*.md --questions questions.json \
    --rag-type simple adaptive --chunker word paragraph
```

```text
setup                   Recall       MRR      nDCG  Answered     Steps     p50 s     p95 s
simple + word            1.000     1.000     1.000      100%       3.0      0.92      1.26
adaptive + word          1.000     1.000     1.000      100%       5.0      1.67      2.02
simple + paragraph       0.917     1.000     0.936      100%       3.0      0.64      0.81
adaptive + paragraph     1.000     1.000     0.987      100%       6.3      0.96      2.91

Questions to look at:
  simple + paragraph: q_006  recall 0.50  found ['remote_work.md']
```

Then see **why** one question went wrong. Here search found the right file, so
the problem is the answer step, not the chunker:

```text
$ rag-titan ask --files docs/*.md --question "Can I work from Spain for a month?" --trace
1. retrieve     7.47 ms  -> 3 chunks: chunk_2 remote_work.md (0.615), chunk_0 expenses.md (0.540), ...
2. rerank       0.04 ms  -> 2 chunks: chunk_2 remote_work.md (rerank 0.815), chunk_0 expenses.md (rerank 0.690)
3. generate   567.39 ms  -> "I don't know based on the available documents."
```

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/evaluation/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/evaluation-flow.svg" alt="End-to-end evaluation: one index per chunker, every RAG type runs every question, the chunks given to the LLM are scored" width="100%"></a>
</p>

Real runs with `gemma3:4b` on the sample policies in `examples/sample_docs/`. Search-only scoring
(`--retrieval-only`, no LLM) and the Python API are in **[Evaluating RAG →](https://aion7891.github.io/rag-titan/evaluation/)**

## Supported RAG types

**rag-titan supports 2 RAG types.** Pick one with `rag_type`. Every type has `answer()`, and
`run()` that also returns every step it took ([see the steps](https://aion7891.github.io/rag-titan/rag-types/#seeing-every-step-run)):

| Status | RAG type | How it works | Best for | LLM calls |
|---|---|---|---|---|
| ✅ Available | [**Simple RAG**](https://aion7891.github.io/rag-titan/rag-types/#simple-rag-simple)<br>`rag_type="simple"` | Retrieve → Rerank → Generate | Fast answers to clear questions | 1 |
| ✅ Available | [**Adaptive RAG**](https://aion7891.github.io/rag-titan/rag-types/#adaptive-rag-adaptive)<br>`rag_type="adaptive"` | Route → Retrieve → Check evidence → Rewrite & retry | Mixed questions, fewer wrong answers | 2–5 |

```python
from rag_titan import RAG_TYPES
print(RAG_TYPES)        # ['simple', 'adaptive']
```

**Coming next** (not available yet): Corrective RAG · Multi-query RAG · HyDE · Hybrid RAG · Self-RAG · Parent-document RAG · Graph RAG · Agentic RAG. → [Roadmap](https://aion7891.github.io/rag-titan/roadmap/)

> Also included: a tool-calling [agent](https://aion7891.github.io/rag-titan/agents/) loop. It's a separate feature, not a `rag_type`.

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/rag-types/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/simple-rag.svg" alt="Simple RAG: retrieve, rerank, generate, with example scores" width="100%"></a>
</p>

<p align="center">
  <a href="https://aion7891.github.io/rag-titan/rag-types/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/adaptive-rag.svg" alt="Adaptive RAG: route, check evidence, rewrite and retry" width="100%"></a>
</p>

## Explore the docs

Click any picture to open its page.

<table>
  <tr>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/chunking/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/fixed-chunkers.svg" alt="One sentence chunked by characters, words and tokens"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/chunking/">Chunking methods</a></b><br>All 8 chunkers explained, with formulas and animated diagrams.</p>
    </td>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/playground/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/playground.png" alt="Chunk playground: tricky sentences split by the sentence chunker"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/playground/">Chunk playground</a></b><br>Paste your text and watch the chunkers cut it, live in the browser.</p>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/evaluation/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/evaluation-flow.svg" alt="End-to-end evaluation flow"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/evaluation/">Evaluating RAG</a></b><br>Compare any chunker with any RAG type on your own questions.</p>
    </td>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/building-blocks/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/indexing.svg" alt="Indexing pipeline"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/building-blocks/">Building blocks</a></b><br>Load → chunk → embed → store, with the data at every step.</p>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/extending/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/architecture.svg" alt="Swappable architecture"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/extending/">Extending rag-titan</a></b><br>Add your own LLM, vector store, chunker or RAG type.</p>
    </td>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/agents/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/agent.svg" alt="Agent loop"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/agents/">Agents</a></b><br>Let the LLM call your Python functions as tools.</p>
    </td>
  </tr>
  <tr>
    <td width="50%" valign="top">
      <a href="https://aion7891.github.io/rag-titan/cli/"><img src="https://cdn.jsdelivr.net/gh/aion7891/rag-titan@main/docs/assets/images/cli.svg" alt="Command line demo"></a>
      <p><b><a href="https://aion7891.github.io/rag-titan/cli/">Command line</a></b><br><code>rag-titan ask</code> (with <code>--trace</code>), <code>chat</code> and <code>evaluate</code>.</p>
    </td>
    <td width="50%" valign="top"></td>
  </tr>
</table>

| I want to... | Read |
|---|---|
| Install it and ask my first question | [Getting started](https://aion7891.github.io/rag-titan/getting-started/) |
| Pick the right RAG type | [RAG types](https://aion7891.github.io/rag-titan/rag-types/) |
| Pick the right chunker | [Chunking methods](https://aion7891.github.io/rag-titan/chunking/) |
| Try the chunkers on my own text | [Chunk playground](https://aion7891.github.io/rag-titan/playground/) |
| Compare chunkers and RAG types on my questions | [Evaluating RAG](https://aion7891.github.io/rag-titan/evaluation/) |
| See why an answer went wrong | [Seeing every step](https://aion7891.github.io/rag-titan/rag-types/#seeing-every-step-run) |
| Change models, chunk size or reranker | [Configuration](https://aion7891.github.io/rag-titan/configuration/) |
| See every class and method | [API reference](https://aion7891.github.io/rag-titan/api/core/) |

## Contributing

Contributions are welcome! Read [CONTRIBUTING.md](https://github.com/aion7891/rag-titan/blob/main/CONTRIBUTING.md) to get set up. The tests run without Ollama.

## License

[MIT](https://github.com/aion7891/rag-titan/blob/main/LICENSE) © Kumar Nishant
