README.md

---
title: LexRAG
emoji: ⚖️
colorFrom: indigo
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
---

# LexRAG — Hybrid-Search Legal RAG

**🔗 Live demo:** https://huggingface.co/spaces/RV302001/lexrag

Retrieval-augmented Q&A over real Indian court judgments
([opennyaiorg/InJudgements_dataset](https://huggingface.co/datasets/opennyaiorg/InJudgements_dataset),
Apache-2.0). Answers are grounded in retrieved judgments and cite their sources;
hallucinated citations are stripped before display.

## How it works

1. **Hybrid retrieval** — one SQL CTE fuses two arms with Reciprocal Rank Fusion:
   - **Vector**: pgvector cosine (`<=>`) over `bge-small-en-v1.5` embeddings (384-dim), HNSW index.
   - **Keyword**: Postgres full-text `ts_rank_cd` over a generated `tsvector`, GIN index.
2. **Generation** — Groq `llama-3.1-8b-instant`, temp 0.1, strict "answer only from context, cite `[case_name]`" prompt.
3. **Validation** — citations not matching a retrieved case name are stripped.

Data lives in an **external Neon Postgres** (pgvector), so it persists across
Space restarts. The Space holds no data — only the app + embedding model.

## Stack

FastAPI · SQLAlchemy 2.0 + Alembic · Postgres 15 + pgvector (Neon) ·
sentence-transformers · Groq · plain HTML/JS. No Celery/Redis.

## Configuration

Set these as **Space secrets** (or local `.env`, see `.env.example`):

| Secret | Description |
|--------|-------------|
| `DATABASE_URL` | Neon connection string (pgvector enabled) |
| `GROQ_API_KEY` | Groq API key |

## One-time setup (offline, run locally)

```bash
pip install -r requirements.txt
alembic upgrade head                 # create extension, table, HNSW + GIN indexes
python -m ingest.build_index         # load 300 judgments -> chunk -> embed -> insert
```

Then deploy: push this repo to a Hugging Face Space (Docker SDK) with the two secrets set.

## Local run

```bash
uvicorn app.main:app --host 0.0.0.0 --port 7860
```

Endpoints: `GET /` (UI), `POST /ask {question}`, `GET /health`.