QanoonAI ⚖️🇵🇰

Production-Grade Agentic GraphRAG Platform for Pakistani Law

An intelligent legal assistant that answers questions about Pakistani law — Constitution 1973, Pakistan Penal Code, and Criminal Procedure Code — using multi-agent reasoning, knowledge graphs, and hybrid retrieval with cross-encoder reranking.

---

✨ Key Features

Feature	Description
🤖 Agentic RAG	Multi-agent LangGraph workflow with Planner → Router → Retriever → Generator → Verifier
🕸️ Graph RAG	Neo4j knowledge graph with cross-references, legal concepts, and hierarchy traversal
🔍 Hybrid Retrieval	FAISS vector search + graph traversal + metadata filtering, fused with Reciprocal Rank Fusion (RRF)
🎯 Cross-Encoder Reranking	ms-marco-MiniLM-L-12-v2 reranker for precision ranking
⚡ Redis Caching	LLM response cache, embedding cache, and retrieval cache with configurable TTLs
📦 Large File Upload	Chunked uploads (5 MB) handling files up to 4 TB without RAM overflow
📊 Admin Dashboard	Upload documents, manage ingestion, monitor system health at /admin
🎤 Voice Interface	Speech-to-text (Groq Whisper) and browser-native TTS
🐳 Docker Ready	Full docker-compose with 7 services — one command deployment
🌙 Dark/Light Mode	Modern chat UI with session history, PDF export, and copy buttons

---

📐 Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        Next.js 14 Frontend                          │
│  ┌──────────┐  ┌──────────────┐  ┌───────────┐  ┌──────────────┐  │
│  │ Chat UI  │  │ File Uploader│  │ Doc Mgr   │  │ System Panel │  │
│  └────┬─────┘  └──────┬───────┘  └─────┬─────┘  └──────┬───────┘  │
└───────┼───────────────┼────────────────┼────────────────┼──────────┘
        │               │                │                │
─────── │ ──── FastAPI ──│────────────────│────────────────│──────────
        ▼               ▼                ▼                ▼
  ┌──────────┐   ┌────────────┐   ┌───────────┐   ┌──────────┐
  │ /chat/*  │   │ /upload/*  │   │/documents │   │ /health  │
  └────┬─────┘   └──────┬─────┘   └───────────┘   └──────────┘
       │                │
       ▼                ▼
  ┌──────────────┐  ┌──────────────────┐
  │  LangGraph   │  │ Celery Worker    │
  │  Agents      │  │ (Background)     │
  │              │  │                  │
  │  Planner     │  │  ZIP Extract     │
  │  Router      │  │  PDF Chunking    │
  │  Retriever   │  │  Embedding       │
  │  Generator   │  │  FAISS Indexing  │
  │  Verifier    │  │  Graph Building  │
  └──────┬───────┘  └──────────────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐ ┌───────┐ ┌──────────┐
│ FAISS  │ │  Neo4j   │ │ Redis │ │PostgreSQL│
│ Vectors│ │  Graph   │ │ Cache │ │ Sessions │
└────────┘ └──────────┘ └───────┘ └──────────┘

Agent Workflow

graph LR
    A[Planner] --> B[Router]
    B --> C[Retriever]
    C --> D[Generator]
    D --> E{Verify?}
    E -->|Low Confidence| F[Verifier]
    F -->|Retry| C
    E -->|High Confidence| G[Formatter]
    G --> H[Response]

Loading

The Planner analyzes the query and selects a retrieval strategy:

• vector_only — simple factual questions
• hybrid — complex questions needing both vector + graph context
• graph_heavy — relationship/cross-reference queries

---

🗂️ Project Structure

QanoonAI/
├── app.py                          # FastAPI application entry point
├── docker-compose.yml              # 7-service orchestration
├── Dockerfile                      # Backend multi-stage build
├── Dockerfile.frontend             # Next.js multi-stage build
├── requirements.txt                # Python dependencies
├── .env.example                    # Environment variable template
│
├── backend/
│   ├── core/
│   │   ├── config.py               # Central settings (Pydantic)
│   │   ├── dependencies.py         # Singleton dependency injection
│   │   ├── redis_client.py         # Redis client with connection pool
│   │   ├── celery_app.py           # Celery task queue configuration
│   │   └── logging.py              # Structured logging
│   │
│   ├── agents/
│   │   ├── graph.py                # LangGraph multi-agent workflow
│   │   ├── prompts.py              # System prompts for all agents
│   │   └── tools.py                # Shared agent tools
│   │
│   ├── embeddings/
│   │   ├── local_embedder.py       # sentence-transformers (all-mpnet-base-v2)
│   │   └── cache.py                # Redis-backed embedding cache
│   │
│   ├── vectorstore/
│   │   └── faiss_store.py          # FAISS IndexFlatIP + metadata sidecar
│   │
│   ├── graph/
│   │   ├── neo4j_client.py         # Neo4j driver singleton
│   │   ├── schema.py               # Graph schema (nodes, relationships)
│   │   ├── builder.py              # Knowledge graph builder
│   │   └── retriever.py            # Graph traversal retriever
│   │
│   ├── ingestion/
│   │   ├── chunker.py              # Hierarchical legal chunker
│   │   ├── pipeline.py             # Ingestion orchestrator
│   │   └── tasks.py                # Celery ingestion tasks
│   │
│   ├── retrieval/
│   │   ├── hybrid_retriever.py     # FAISS + Graph + Metadata + RRF
│   │   ├── reranker.py             # Cross-encoder reranker
│   │   └── cache.py                # Retrieval result cache
│   │
│   ├── llm/
│   │   └── groq_client.py          # Cached Groq client with retry
│   │
│   ├── uploads/
│   │   ├── storage.py              # Chunked file storage manager
│   │   ├── processor.py            # PDF/ZIP document processor
│   │   └── tasks.py                # Background upload processing
│   │
│   ├── rag/
│   │   └── rag_pipeline.py         # RAG pipeline facade
│   │
│   ├── api/
│   │   └── routes.py               # All API endpoints
│   │
│   ├── persistence/
│   │   └── postgres.py             # PostgreSQL session storage
│   │
│   ├── voice/
│   │   ├── speech_to_text.py       # Groq Whisper STT
│   │   ├── text_to_speech.py       # TTS utilities
│   │   └── voice_utils.py          # Audio helpers
│   │
│   ├── utils/
│   │   └── citations.py            # Legal citation formatting
│   │
│   ├── health.py                   # Service health checks
│   │
│   └── data/raw/                   # Source PDFs
│       ├── constitution_1973.pdf
│       ├── ppc.pdf
│       └── crpc1898.pdf
│
├── frontend/
│   ├── app/
│   │   ├── page.tsx                # Main chat page
│   │   ├── layout.tsx              # Root layout
│   │   ├── globals.css             # Styling
│   │   ├── admin/
│   │   │   └── page.tsx            # Admin dashboard
│   │   └── components/
│   │       ├── ChatInterface.tsx   # Chat logic + streaming
│   │       ├── MessageBubble.tsx   # Message rendering
│   │       ├── Sidebar.tsx         # Session history
│   │       ├── FileUploader.tsx    # Chunked upload + progress
│   │       ├── DocumentManager.tsx # Document table
│   │       ├── VoiceButton.tsx     # Voice input/output
│   │       └── LoadingDots.tsx     # Typing animation
│   └── package.json
│
├── scripts/
│   ├── entrypoint.sh               # Docker entrypoint
│   └── ingest.sh                   # Ingestion runner
│
└── streamlit_app.py                # Legacy Streamlit UI

---

🚀 Quick Start

Option 1: Docker (Recommended)

# 1. Clone the repository
git clone https://github.com/Free-devloper/QanoonAI.git
cd QanoonAI

# 2. Configure environment
cp .env.example .env
# Edit .env → add your GROQ_API_KEY (free at https://console.groq.com)

# 3. Start all services (backend, frontend, postgres, redis, neo4j, celery)
docker-compose up -d

# 4. Run initial ingestion (processes the 3 built-in law PDFs)
docker-compose exec backend python -m backend.ingestion.pipeline

# 5. Open the app
# Chat:  http://localhost:3000
# Admin: http://localhost:3000/admin
# Neo4j: http://localhost:7474

Option 2: Local Development

# 1. Clone and setup Python
git clone https://github.com/Free-devloper/QanoonAI.git
cd QanoonAI
python -m venv venv
venv\Scripts\activate          # Windows
# source venv/bin/activate     # Linux/Mac
pip install -r requirements.txt

# 2. Start required services (Redis, Neo4j, PostgreSQL)
# Install and run them locally, or use Docker for just the infra:
docker-compose up -d postgres redis neo4j

# 3. Configure environment
cp .env.example .env
# Edit .env → add GROQ_API_KEY, set DATABASE_URL to your local postgres

# 4. Run ingestion
python -m backend.ingestion.pipeline

# 5. Start backend
uvicorn app:app --reload --port 8000

# 6. Start frontend (separate terminal)
cd frontend
npm install
npm run dev

# 7. Open http://localhost:3000

---

⚙️ Configuration

All settings are configured via environment variables. See .env.example for the full list.

Required Variables

Variable	Description	Example
GROQ_API_KEY	Groq API key (free tier)	gsk_xxxx...
DATABASE_URL	PostgreSQL connection string	postgresql://user:pass@localhost:5432/dbname

Optional Variables

Variable	Default	Description
REDIS_URL	redis://localhost:6379/0	Redis connection
NEO4J_URI	bolt://localhost:7687	Neo4j connection
NEO4J_PASSWORD	neo4j_password	Neo4j auth
LLM_MODEL	llama-3.3-70b-versatile	Groq model
EMBEDDING_MODEL_LOCAL	all-mpnet-base-v2	Local embedding model
TOP_K_RESULTS	6	Number of retrieved chunks
CHUNK_SIZE	800	Text chunk size (chars)

Note: Redis and Neo4j are optional — the system degrades gracefully without them (uses in-memory fallbacks). PostgreSQL is required for session persistence.

---

📚 Supported Laws

Law	File	Coverage
🏛️ Constitution of Pakistan 1973	constitution_1973.pdf	All 280 Articles + Amendments
⚖️ Pakistan Penal Code (PPC)	ppc.pdf	All 511 Sections
📋 Criminal Procedure Code (CrPC) 1898	crpc1898.pdf	All 565 Sections

Adding New Documents

1. Navigate to Admin Dashboard → http://localhost:3000/admin
2. Drag & drop PDF or ZIP files onto the upload zone
3. The system processes them in the background:
   • ZIP → extract PDFs → validate → chunk → embed → index
   • Large files (up to 4 TB) are handled via chunked uploads — never loaded into RAM
4. Check progress in real-time or come back later — processing continues independently

---

🛠️ Tech Stack

Layer	Technology
LLM	Groq Cloud (llama-3.3-70b-versatile)
Embeddings	Local sentence-transformers/all-mpnet-base-v2 (768-dim)
Reranker	cross-encoder/ms-marco-MiniLM-L-12-v2
Vector Store	FAISS (IndexFlatIP + IndexIDMap)
Knowledge Graph	Neo4j 5 Community
Agent Framework	LangGraph (StateGraph)
Backend	FastAPI + Uvicorn
Frontend	Next.js 14 + React 18 + TailwindCSS
Cache	Redis 7 (LLM + embedding + retrieval caching)
Task Queue	Celery with Redis broker
Database	PostgreSQL 16 (chat session persistence)
Voice	Groq Whisper (STT) + Web Speech API (TTS)
Container	Docker Compose (7 services)

---

🐳 Docker Services

Service	Port	Description
backend	8000	FastAPI application
frontend	3000	Next.js UI
postgres	5432	Chat session storage
redis	6379	Caching + Celery broker
neo4j	7474 / 7687	Knowledge graph
celery-worker	—	Background task processing

---

📡 API Endpoints

Chat

Method	Endpoint	Description
POST	/api/v1/chat	Send a message, get a response
POST	/api/v1/chat/stream	Streaming response (SSE)

Sessions

Method	Endpoint	Description
GET	/api/v1/sessions	List all chat sessions
GET	/api/v1/sessions/{id}	Get session messages
DELETE	/api/v1/sessions/{id}	Delete a session
PATCH	/api/v1/sessions/{id}	Rename a session

Upload & Documents

Method	Endpoint	Description
POST	/api/v1/upload/init	Initialize chunked upload
POST	/api/v1/upload/chunk	Upload a file chunk
POST	/api/v1/upload/complete	Signal upload done → triggers background processing
GET	/api/v1/upload/progress/{id}	SSE progress stream
GET	/api/v1/documents	List uploaded documents
DELETE	/api/v1/documents/{name}	Delete a document

System

Method	Endpoint	Description
POST	/api/v1/ingest	Trigger document ingestion
GET	/api/v1/ingest/status	Ingestion pipeline status
GET	/api/v1/health	Service health check
GET	/api/v1/graph/stats	Neo4j graph statistics
GET	/api/v1/cache/stats	Redis cache hit rates

Voice

Method	Endpoint	Description
POST	/api/v1/voice/stt	Speech-to-text (audio → text)

---

📤 Large File Upload Architecture

QanoonAI handles files from kilobytes to terabytes without crashing:

Browser                         Backend                          Disk
  │                               │                               │
  │── File.slice(0, 5MB) ────────►│── stream 8KB buffer ────────►│ chunk_000
  │── File.slice(5MB, 10MB) ─────►│── stream 8KB buffer ────────►│ chunk_001
  │── ... (progress bar) ────────►│── stream 8KB buffer ────────►│ chunk_N
  │                               │                               │
  │── POST /upload/complete ─────►│── concatenate (8KB buf) ────►│ file.zip
  │◄── {"status":"processing"} ──│                               │
  │                               │                               │
  │  ✅ Client can disconnect     │── Background Worker ────────►│
  │     here. Processing runs     │   Extract ZIP (streaming)     │
  │     independently.            │   Validate PDFs               │
  │                               │   Chunk text                  │
  │  (Optional: SSE monitoring)   │   Generate embeddings         │
  │◄── SSE: "embedding 60%" ─────│   Index into FAISS + Neo4j   │
  │◄── SSE: "complete 100%" ─────│                               │

Peak RAM usage: ~100 MB regardless of file size.

---

🔮 Future Roadmap

• Authentication & role-based access (admin vs user)
• Urdu language support (multilingual model + Urdu prompts)
• RAGAS evaluation framework integration
• LangSmith monitoring dashboard
• S3 storage backend for cloud deployments
• Kubernetes Helm chart
• Civil law corpus expansion (CPC, Contract Act, Family Law)

---

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

• Groq — Ultra-fast LLM inference (free tier)
• LangGraph — Multi-agent orchestration
• FAISS — Efficient similarity search
• Neo4j — Graph database
• sentence-transformers — Local embedding models

---

Built with ❤️ for Pakistan's legal community