# TAU-RAG

> Unified, modular RAG framework that consolidates the six existing RAG projects
> (KG-RAG, Enhanced-RAG, LRLM-RAG, Signals-Adapter, LawDBHeb, RAG-Monitor) into
> a single pluggable pipeline.

## Pipeline

```
Query ──► Understand ──► MultiRetrieve ──► Fuse ──► Rerank ──► Generate ──► Verify ──► Response
                                                                              │
                                                                              ▼
                                                                         signals.v1
```

## Design principles

1. **Everything is pluggable.** Every stage defines a Protocol/ABC. Swap BM25 for Elasticsearch, swap OpenAI for Claude, swap LRLM for E5 — no core change.
2. **Zero hard deps at import-time.** Heavy libs (torch, faiss, openai, etc.) are lazy-imported inside the adapter that needs them.
3. **Platform-agnostic.** The pipeline object is a pure Python orchestrator. Connect it to FastAPI, CLI, a notebook, a Zoom bot, or an MCP server — each integration is a thin adapter under `api/`.
4. **Same data types end-to-end.** `core.types` defines `Query`, `Document`, `Chunk`, `Retrieved`, `RAGResponse`, `Signals`. No adapter invents its own.
5. **Living config.** `core.config.Config` is a dataclass you can persist/load as YAML/JSON.

## Folder layout

```
tau_rag/
├── core/          # types · interfaces · config
├── understand/    # query classification + decomposition
├── retrieve/      # BM25 · Dense · LRLM · Graph · Gematria · Hilbert · Mock · Multi
├── fuse/          # RRF · Weighted · Borda
├── rerank/        # CrossEncoder · StructureFilter · Chain
├── generate/      # OpenAI · Anthropic · Local · Mock · Prompts
├── verify/        # StructureVerifier · Citations · Faithfulness · Composite
├── signals/       # TAU-Ω · Drift · Computer
├── loaders/       # LawDBHeb · JSONL · TxtFolder
├── bench/         # Metrics · Harness
├── pipeline.py    # Orchestrator
├── api/           # FastAPI · CLI · MCP · LangGraph
├── configs/       # hebrew_legal.json · mock.json
├── examples/      # demo_end_to_end · demo_hybrid_benchmark
└── tests/         # pytest suite + smoke/regression coverage
```

## Quickstart

```python
from tau_rag import Pipeline, Config, Query

pipe = Pipeline.from_config(Config.default())
resp = pipe.run(Query(text="מה חובות המעביד בנושא שעות נוספות?"))
print(resp.answer, resp.omega, resp.sources)
```

## Run the demo

The package folder is `tau_rag/`. Python needs **its parent** on the path so
`import tau_rag` resolves. Three options, pick whichever feels natural:

**A) Use the bundled runner (works from anywhere, no PATH fiddling):**
```bash
cd tau_rag
python3 run.py tau_rag.examples.demo_end_to_end
python3 run.py tau_rag.examples.demo_hybrid_benchmark
python3 run.py tau_rag.api.cli "מה חובות המעביד?" --preset hebrew_legal
```

**B) Run from the parent directory:**
```bash
cd tau_platform_v4          # one level above tau_rag/
python3 -m tau_rag.examples.demo_end_to_end
python3 -m tau_rag.examples.demo_hybrid_benchmark
```

**C) Set PYTHONPATH:**
```bash
cd tau_rag
PYTHONPATH=.. python3 -m tau_rag.examples.demo_end_to_end
```

### Common mistake
Running `python3 -m tau_rag.xxx` from **inside** `tau_rag/` will fail with
`ModuleNotFoundError: No module named 'tau_rag'` — because cwd contains the
*contents* of the package, not the package itself. Use option A or B.

CI, Docker, and local test commands in this repo assume that same layout:
`tau_rag/` is the package directory, and its parent must be on `PYTHONPATH`.

## Run the API

```bash
# Option A
cd tau_rag && python3 run.py uvicorn tau_rag.api.fastapi_app:app --reload

# Option B
cd tau_platform_v4 && uvicorn tau_rag.api.fastapi_app:app --reload
```

## Platform adapters

| Platform      | Adapter                                        |
|---------------|------------------------------------------------|
| FastAPI HTTP  | `tau_rag.api.fastapi_app:app`                 |
| CLI           | `python -m tau_rag.api.cli "query"`           |
| Notebook      | `from tau_rag import Pipeline`                |
| MCP server    | `tau_rag.api.mcp_server` (scaffold)           |
| Zoom bot      | `tau_rag.api.zoom_bot` (scaffold)             |
| LangGraph     | `tau_rag.api.langgraph_node` (scaffold)       |

See `RAG_Projects_Ultimate_Report.html` (in the parent folder) for the full design
document, math, and roadmap. That file and this code move together — every update
here is logged there.