tau_rag/README.md

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

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):

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:

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:

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

# 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.