Skip to main content
Glama
README.md
# Sarkari Sahayak — सरकारी सहायक

Bilingual (Hindi/English) agentic-RAG MCP server over RBI regulations. Every answer cites retrieved passages — or the system refuses.

🚧 **Under active development** (S4 MCP + REST closed; next: S5 UI / optional MIRACL benches).

## Roadmap

- [x] S0 Bootstrap (repo skeleton, CI, docs)
- [x] S1 Ingestion
- [x] S2 Retrieval + benchmarks
- [x] S3 Agent (cite-or-refuse)
- [x] S4 MCP + REST (`SahayakService`, rate limit, `/v1/ask`, `/mcp`; Cursor + Claude screenshots in `docs/img/`)
- [ ] S5 UI + Flight Recorder
- [ ] S6 Ship v1.0
- [ ] S7 v1.1 Supersession + Marathi

## Quick start

```bash
# Day-to-day (lint, unit tests, typecheck without PDF deps)
uv sync --group dev

# S1 ingest / PDF+OCR (CI installs this for pyright)
uv sync --group dev --extra ingest

# S2 harness unit tests (ranx) — also what CI uses with ingest
uv sync --group dev --extra ingest --extra evals

# Local E5 / FlagEmbedding for ingest + bench-quick (not in default CI)
uv sync --group dev --extra ingest --extra evals --extra ml

make check
uv run sahayak version
```

`make check` and GitHub Actions install **ingest** + **evals** so `pymupdf` and `ranx` resolve. Real embeddings need `--extra ml` locally. See `CONTRIBUTING.md`.

### Benchmarks (local)

```bash
make up
uv sync --group dev --extra ingest --extra evals --extra ml
make bench-quick   # IndicQA-hi → docs/results/retrieval.json + .md
```

On Apple Silicon, E5 uses MPS when available (`PYTORCH_ENABLE_MPS_FALLBACK=1` if needed).

### Serve (REST + MCP)

```bash
make up
ollama serve   # if not already running
uv run sahayak serve          # http://127.0.0.1:8000
curl -s http://127.0.0.1:8000/health
# Cursor: .cursor/mcp.json → http://127.0.0.1:8000/mcp
# Claude Desktop: stdio via python -m sahayak.mcp_server (see docs/guide/sahayak/S4-mcp-server.md)
```

Client proof screenshots: `docs/img/s4-cursor-mcp-tools.png`, `s4-cursor-cited-answer.png`, `s4-claude-desktop-mcp.png`.

### Agent live smoke (local Ollama)

```bash
ollama serve   # if not already running
ollama pull qwen3:4b-instruct
uv run pytest -m llm -q   # excluded from default CI / make check
```

See `docs/results/agent-notes.md` for measured pass rates.

See `docs/guide/` for the full implementation guide and `AGENTS.md` for contributor rules.