# SaulGPT — Complete Feature Architecture

## Project Overview

SaulGPT is an AI-powered Indian Legal Intelligence Assistant using a 6-layer RAG pipeline to answer legal queries, draft documents, evaluate contracts, and provide structured legal analysis. It uses a 3-phase "Virtual Counsel" flow (Discovery → Strategy → Execution) for legal grievance handling with Llama 3.1 8B via Groq.

---

## 1. Backend Systems

### 1.1 API Server & Request Routing

**Source:** ackend/api_server.py (~1662 lines)

FastAPI server (port 8000) with CORS, Groq LLM initialization, and Knowledge Graph startup.

**Endpoints:**

| Method | Route | Auth | Purpose |
|--------|-------|------|---------|
| POST | /api/chat | Optional | Main chat: pipeline, triage state machine, drafting loop, IRAC |
| POST | /api/chat/stream | Optional | SSE-streaming variant |
| POST | /api/upload | No | Contract upload and evaluation (multipart) |
| GET | /api/document/{session_id} | No | Serve generated .docx as download |
| DELETE | /api/history/{session_id} | No | Clear session history |
| DELETE | /api/draft/state/{session_id} | No | Clear drafting state / cancel interview |
| GET | /api/health | No | Health check |
| GET | /api/conversations | Bearer | List conversations (paginated) |
| POST | /api/conversations | Bearer | Create conversation |
| GET | /api/conversations/{id} | Bearer | Load conversation with messages |
| DELETE | /api/conversations/{id} | Bearer | Delete conversation |
| POST | /api/conversations/migrate | Bearer | Bulk-import guest messages for session takeover |
| POST | /api/auth/signup | No | Register user |
| POST | /api/auth/login | No | Login user |
| GET | /api/auth/me | Bearer | Current user info |

**Request Pipeline** (for /api/chat):
1. Auth resolution (JWT or guest)
2. Conversation resolution (map session_id to conv_id or create new)
3. Message persistence (to SQLite if authenticated)
4. Interview state check
5. Interruption guard (clarification/hypothetical/pushback)
6. **Crisis pre-check** (regex: self-harm, active violence, confinement → helplines, stop)
7. Jurisdiction gate (non-Indian queries → rejected before processing)
8. Direct legal query patterns (15 regex → force knowledge mode)
9. Triage LLM call (classify: off-topic / direct legal / educational / document / grievance)
10. Triage state machine routing (3-phase flow or pass-through)
11. Pipeline dispatch (6-layer RAG fallthrough)
12. Response construction (widget metadata: remapped laws, urgency, jurisdiction)
13. Response persistence (conv_id injected for frontend tracking)

**State Stores:**
- ACTIVE_CONVERSATIONS: session_id → conv_id mapping
- SESSIONS: per-session drafting interview state
- SESSION_DOCUMENTS: generated .docx bytes
- TRIAGE_STATES: per-session 3-phase flow state

**Robust JSON Extraction:** _extract_json() with 4-layer fallback (pure JSON → markdown codeblock → markdown key-value → empty dict) used by all three core agents (triage, discovery, strategy).

---

### 1.2 Crisis Detection & Emergency Response

**Source:** `backend/api_server.py` — `_detect_crisis()` + `_CRISIS_PATTERNS`

Regex-based pre-check that fires **before any LLM call or pipeline processing**, positioned between the jurisdiction gate and the triage classification.

**3 crisis categories:**

| Category | Trigger examples | Response |
|---|---|---|
| **Self-harm** | "kill myself", "suicide", "hurt myself", "end my life" | Suicide prevention helplines (AASRA, iCall, Vandrevala) + emergency number |
| **Active violence** | "beating me right now", "trying to kill me", "weapon" | Police (100), National Emergency (112), Women's Helpline (1091) |
| **Confinement** | "locked in", "held against my will", "passport taken" | Police (100), National Emergency (112) |

**Design principle:** Hard stop — no Discovery, no RAG, no pipeline. The system refuses to process further until the user confirms safety.

---

### 1.3 6-Layer RAG Pipeline

**Source:** ackend/pipeline_orchestrator.py (~700 lines)

Sequential pipeline for all non-drafting queries.

**Layer 0: Conversation Memory (Sliding Window)**
- Per-session verbatim turn memory
- Sliding window: 6 turns verbatim, older turns collapsed into key facts
- Thresholds: collapse at 9 turns, summarize at 12 turns
- Key fact extraction: regex for dates, amounts (INR/Rs.), places, section numbers
- Functions: save_turn_to_memory(), get_history_with_summary()

**Layer 1: Query Understanding** (layer1_understanding.py, ~400 lines)
- Language detection (langdetect, fallback "en")
- Intent classification: factual / procedure / definition / comparison / analysis / document / ambiguous
- Entity extraction (spaCy NER: PERSON, ORG, GPE, LAW, DATE, MONEY, TIME)
- Citation extraction (regex: "Section X of Y Act", "Article Z")
- Ambiguity detection (vague phrasing patterns)
- Query reformulation (LLM-based abbreviation expansion)
- spaCy model: en_core_web_sm

**Layer 2: Hybrid Vector Retrieval** (layer2_retrieval.py, ~350 lines)
- Vector DB: ChromaDB, collection "saulgpt_indian_laws"
- Embedding model: all-MiniLM-L6-v2
- Chunks: 1200 chars, 150 overlap (~2409 chunks, 9 acts)
- Hybrid: semantic search + BM25 keyword retrieval
- Cross-encoder reranking: ms-marco-MiniLM-L-6-v2 (8 candidates → 5 results)
- Noise detection: max_score < 0.5 AND spread < 0.15 → web fallback
- Deduplication by content hash
- Citation filtering prioritization

**Layer 3: LLM Reasoning** (layer3_reasoning.py, ~700 lines)
- Model: llama-3.1-8b-instant via Groq (temperature 0.1)
- Mode prompts: knowledge (neutral), analysis (FACTS/ISSUES/LAW/OUTCOME), document (drafting), pathfinder (step-by-step)
- Context: retrieved chunks + conversation history + mode instruction
- Knowledge Graph expansions injected
- Ambiguity handling → clarifying questions

**Layer 4: Response Validation** (layer4_validation.py, ~700 lines)
- Citation verification (regex cross-check against retrieved chunks)
- NLI hallucination check (DeBERTa, fallback to pattern matching)
- Repealed law interception (IPC/CrPC/IEA → BNS/BNSS/BSA; generates remapped_laws)
- Struck-down section detection
- Legal terminology enforcement (informal → formal)
- Disclaimer enforcement
- Remedy validation

**Layer 5: External Data** (layer5_external.py, ~450 lines)
- DuckDuckGo fallback (appends "Indian law indiankanoon indiacode")
- Post-filter to Indian legal domains (.gov.in, indiankanoon.org, indiacode.nic.in)
- IndianKanoon case law scraping (BeautifulSoup)
- Auto-updater (APScheduler, 30-day interval)

**Layer 6: Evaluator** — see Contract Evaluation System (1.6).

---

### 1.4 3-Phase Virtual Counsel Flow

**Source:** ackend/api_server.py (triage state machine), 	riage_state.py, discovery_agent.py, strategy_agent.py, prompts/discovery.py, prompts/strategy.py

Python-enforced state machine replacing old keyword-based triage for legal grievances.

**State Machine** (	riage_state.py, 47 fields):
- current_mode: "idle" | "discovery" | "strategy"
- discovery_profile: structured Phase 1 output
- discovery_turn_count: hard 3-turn cap (Python-enforced)
- strategy_data: SWOT + options
- selected_strategy_id: user-chosen path_a..path_d
- counsel_override: LLM-detected override flag

**Phase 1: Discovery** (discovery_agent.py, prompts/discovery.py)
- Structured 3-turn sequence with fixed objectives per turn:
  - **Turn 0 (Story & Legal Anchor)**: Empathy + brief area-of-law anchor + open-ended story question
  - **Turn 1 (Evidence & Timeline)**: Ask about documentary proof and exact dates; skip if already populated
  - **Turn 2 (Outcome & Priority)**: Ask what the user wants and what matters most; always final turn
- Adaptive skip: each turn checks existing profile and skips if target fields are already filled
- Legal Framework Anchor: LLM names the relevant area of law before asking questions ("This falls under Indian Employment Law")
- Tone Protocol: matches emotional_state (angry/frustrated/desperate/calm)
- Graceful vague-answer handling (no re-asking on "I don't know")
- Hard 3-turn Python cap (enforced by api_server.py line 1205: `discovery_turn >= 2`)
- Discovery Profile output: emotional_state, desired_outcome, evidence_quality, timeline, user_priority, opponent_profile
- 4-layer JSON extraction
- Emotional-language fix: CRITICAL RULE ensures anger/frustration = legal grievance, not off-topic

**Phase 2: Strategy** (strategy_agent.py, prompts/strategy.py)
- SWOT: Strengths, Weaknesses, Opportunities, Threats
- Exactly 4 options (path_a..path_d), each with:
  - route_to: "document" (drafting) or "pathfinder" (procedure)
  - title, description, pros, cons, estimated_timeline, difficulty, success_probability
- Counsel Override for exceptional cases (government opponent, acknowledgment)
- Evidence weakness flagging
- Validation: strips path_e, pads with universal catch-alls, validates route_to
- Unrecognized routing → pathfinder with preamble note

**Phase 3: Execution**
- Document → interview_state field collection
- Pathfinder → 6-layer pipeline in procedural mode
- IRAC Advocate Mode → keyword/button-invoked structured analysis

---

### 1.5 IRAC Advocate Mode

**Source:** ackend/irac_agent.py, prompts/irac.py

Structured legal analysis for law students/advocates. Never invoked as hidden fallback.

**IRAC Structure:** FACTS (neutral) → ISSUES (legal questions) → RULE (RAG-grounded statutes) → APPLICATION (both-sides argumentation) → CONCLUSION (balanced assessment)

**Domain Statute Mappings:** Employment, Contracts, Property, Family, Consumer, Criminal, Torts

**Guardrails:**
- Domain guardrails (no factory acts for white-collar disputes, no constitutional articles unless government opponent)
- All citations RAG-grounded (never outside retrieved docs)
- No verdict — Application argues both sides

**Invocation:** Frontend "Advocate Mode" button + natural language ("advocate", "irac", "deep legal analysis"). Resets to "idle" after output.

---

### 1.6 Document Drafting System

**Interview State** (interview_state.py, ~950 lines)
- State machine: IDLE → INTERVIEWING → DRAFTING → COMPLETE
- Document families: letter, pleading, affidavit, agreement
- 5 predefined schemas: legal_notice, cheque_bounce, employment_notice, fir, rental_agreement
- Each schema: 5-9 fields (sender, recipient, dates, amounts, etc.)

**Dynamic Field Scoping** (dynamic_drafter.py, ~400 lines)
- LLM-driven field identification (max 7 fields)
- Classifies document type from query
- Builds prompt injections from collected values
- Session-cached field scope
- Falls back to static schemas

**Interview Loop:**
- Progressive field-by-field questioning
- Interruption handling (clarification, hypothetical, pushback)
- Unrelated query detection (resets state)
- Progress tracking per message

**Three-Layer Document Gate:**
1. Triage identifies document intent
2. User picks document path from Strategy options
3. Explicit "Shall I draft?" confirmation

**.docx Generation** (document_generator.py, ~980 lines)
- Rendering: python-docx, Times New Roman 12pt, 1-inch margins, 1.5 spacing
- 4-family: letter, pleading, affidavit, agreement
- Primitive functions: add_header, add_title, add_recipient_block, add_subject_line, add_body, add_signature_block, add_enclosures, add_court_details, add_verification, add_pagination

---

### 1.7 Contract Evaluation System

**Source:** ackend/layer6_evaluator.py (~470 lines)

- Format support: PDF (PyMuPDF), DOCX (python-docx)
- Chunking: 5000-character at paragraph boundaries
- Evaluation dimensions: clarity, enforceability, compliance, risk, completeness
- Per-chunk LLM evaluation (llama-3.1-8b-instant)
- Output: overall_score, risk_level (low/medium/high/critical), clauses, summary, recommendations
- Upload max: 50MB

---

### 1.8 Pre-Draft Legal Scrutiny Engine

**Source:** ackend/scrutiny_agent.py (~640 lines)

**ScrutinyResult:** is_valid, issues, warnings, limitation_status, remedy_feasibility, limitation_date, bns_mapping, risk_score (0-100), recommendations

**Checks:**
1. Limitation (12 claim types with periods, exception detection: acknowledgment, continuous wrong, disability, government)
2. Remedy validity
3. BNS/BSA enforcement (IPC/CrPC/IEA → BNS/BNSS/BSA)
4. Field validation per doc type

**Severity Levels:** "serious" (red, blocking), "warning" (gold, acknowledgeable), "info" (teal, acknowledgeable)

---

### 1.9 Legal Knowledge Graph

**Source:** ackend/layer6_knowledge_graph.py (~560 lines)

- NetworkX DiGraph: 89 nodes, 67 edges
- Relationships: Act replacements (IPC→BNS, CrPC→BNSS, IEA→BSA), constitutional hierarchy, cross-act links, procedural chains (FIR→Investigation→Charge Sheet→Trial→Appeal)
- ~30 act aliases resolved to canonical names
- expand_context(): injects graph into pipeline, returns replaced_acts for frontend

---

### 1.10 Authentication & User Persistence

**JWT Auth** (ackend/auth.py, 42 lines)
- bcrypt hashing (passlib)
- JWT: 30-day expiry, HS256

**SQLite DB** (ackend/database.py, ~170 lines)
- Tables: users, conversations, messages
- WAL mode, foreign keys, thread-local connections
- bulk_import_messages() for guest session takeover

---

### 1.11 Legal Data Ingestion Pipeline

**Scraper** (ackend/scraper/, 4 files + config)
- LegalScraperEngine: IndiaCodeScraper (DSpace) + KanoonScraper (BeautifulSoup)
- 25 scrapeable acts in config

**Chunking & Embedding** (2_chunk_and_embed.py, ~469 lines)
- Chunk: 1200 chars, 150 overlap
- Embedding: all-MiniLM-L6-v2
- Universal key detector (14+ key variants per field)
- 5 JSON structures supported
- Lineage header: [Act: X] [Section Y: Z].

**Embedded Acts (9):** BNS 2023, Constitution of India, BNSS 2023, CPC, Negotiable Instruments Act, Hindu Marriage Act, Motor Vehicles Act, BSA 2023, Indian Divorce Act

---

### 1.12 RAG Evaluation Suite

**Source:** ackend/eval_pipeline.py (~250 lines)

8 gold-standard test cases (knowledge, analysis, pathfinder). Metrics: retrieval_coverage, citation_accuracy, hallucination_score, overall_score.

---

## 2. Frontend Application

### 2.1 Core Chat Interface

**Source:** saulgpt-ui/src/App.jsx (935 lines)

**19 State Variables:**
- Auth: token, user, authLoading
- Chat: messages, input, loading, loadingLabel, forceMode, interviewActive
- UI: showSuggestions, showDropZone, showGlossary, glossaryCategory, showSidebar
- Session: convId, refreshTrigger

**Sub-components (inline):**
- TypingIndicator({ label }): animated bot-typing dots
- InterviewProgress({ pct }): progress bar (0-100%)
- RiskBadge({ risk }): color-coded pill (High/Medium/Low)
- PipelineMeta({ data }): collapsible debug panel (citations, repealed laws, validation, confidence)
- Message({ msg, onTriageChoice }): single chat message renderer with markdown, widgets, and export bar
- DropZone({ onFile, disabled }): drag-and-drop contract upload

**7 useEffect Hooks:**
1. convRef sync (prevents stale overwrites)
2. Persist convId to localStorage
3. Page refresh recovery (load conversation from API on mount)
4. Persist guest messages (last 6)
5. Auto-scroll on message/loading change
6. Auto-resize textarea
7. Cross-tab auth sync (storage event listener)

**Key Functions:**
- api(): axios instance with Bearer token + 401 interceptor (auto-logout)
- sendMessage(): core send → POST /api/chat → handle interview/triage/complete states
- handleFile(): contract upload → POST /api/upload
- handleTriageChoice(): triage card → sendMessage
- clearChat(), cancelInterview(), handleAuth(), logout()

**Welcome Screen:** Animated seal, "Your Counsel Awaits", feature cards (Ask/Draft/Evaluate), 5 suggested queries.

**Send Flow:** Validation → optimistic append → POST /api/chat → response processing → loading=false.

**Mode Selector:** 5 buttons (Auto, Knowledge, Analysis, Document, Pathfinder).

**Chat Input:** Auto-resizing textarea, contextual placeholder, disabled during loading, file upload button, send button with spinner.

---

### 2.2 Document Drafting UI

- Interview badge ("Drafting Mode Active" with gold pulse) replaces mode selector during interview
- Cancel button (red, clears draft state)
- Input placeholder changes to "Type your answer..." during interview
- InterviewProgress per message
- .docx download button on completion (meta.document_ready flag)

### 2.3 Contract Evaluation UI

- DropZone (drag-and-drop, accepts PDF/DOCX/TXT, 50MB max)
- Upload button (paperclip icon, disabled during loading)
- "Running Red Pen evaluation..." loading label
- Evaluation response with risk level display

### 2.4 Response Widget System

Each widget conditionally renders based on response metadata:

**BNSCorrectionNotice** (BNSCorrectionNotice.jsx, 118 lines):
- "LEGISLATION UPDATE 2024" card
- Maps old law (IPC/CrPC/IEA, strikethrough red) → new law (BNS/BNSS/BSA, green check)
- Triggered by meta.remapped_laws

**VetoCard** (VetoCard.jsx, 144 lines):
- Collapsible scrutiny result with severity levels
- Serious: red pulsing, blocking gate (Consult Lawyer / Draft Demand Letter)
- Warning/Info: gold/teal, acknowledgment checkbox
- Sections: Limitation Act, Remedy Not Recognized, Law Updated BNS/BNSS
- Auto-corrections display

**UrgencyBanner** (UrgencyBanner.jsx, 83 lines):
- Critical (<30d): red pulsing, siren icon
- Warning (<90d): amber static, clock icon
- Shows limitation days + deadline date
- Triggered by urgency_flags or limitation_days

**JurisdictionBadge** (JurisdictionBadge.jsx, 151 lines):
- Court level: 8 types (Supreme Court gold, High Court teal, District Court green, etc.)
- Jurisdiction type: 8 icons (Civil, Criminal, Consumer, Family, Revenue, etc.)
- Territorial + pecuniary info
- Court description footnote

**TriageCards** (TriageCards.jsx, 121 lines):
- "Strategic Options" with info banners (limitation, jurisdiction)
- Clickable option cards (gold label + description + arrow)
- Action row: SWOT toggle, "Explain These Options", "Advocate Mode"
- Expandable SWOT analysis (4 color-coded boxes)

**PipelineMeta:** Collapsible debug panel showing mode, domain, laws, graph insights, case law, elapsed time, citations, validation status, confidence, hallucination warnings.

**Export Bar:** Copy (clipboard), Download PDF (jsPDF), Download .docx (backend URL).

### 2.5 Conversation Management

**Source:** saulgpt-ui/src/ConversationsSidebar.jsx (87 lines)

- Left panel (260px) with mobile backdrop overlay
- Header: "Chats (N)" + New (+) + Close (X)
- Conversation list: title (truncated 28 chars), relative time, delete on hover
- Active: gold border highlight
- Pagination: "Load more (N remaining)" button
- useEffect: fetches on mount + refreshTrigger change, AbortController cleanup
- Sidebar toggle via hamburger button

**loadConversation():** Clears UI → sets convId early → fetches messages → populates → handles error with message in chat

**newConversation():** Clears UI → setConvId(null) → creates on backend → triggers sidebar refresh

**deleteConversation():** Deletes on backend → clears local state if active → triggers sidebar refresh

### 2.6 Authentication & Session Management

**AuthPage** (AuthPage.jsx, 66 lines):
- Tabbed login/signup form
- Migration overlay (guest session takeover spinner)
- JWT stored in localStorage

**Session Features:**
- Page refresh recovery (loads last conversation from API)
- Guest message persistence (last 6 in localStorage)
- Guest session takeover (bulk-import on login)
- Cross-tab auth sync (storage event listener → auto-logout)
- 401 interceptor (expired token → logout)

### 2.7 Supporting Utilities

**LegalGlossary** (LegalGlossary.js, 287 lines):
- 200+ Indian legal terms with plain-language definitions
- 10 categories: Constitutional, Criminal Law, Criminal Procedure, Commercial Law, Civil Procedure, Consumer Law, Labour Law, Property Law, Family Law, General
- Functions: scanForTerms(), getTermDefinition(), getTermsByCategory(), getCategories()
- Glossary sidebar with category filter + search

**PDF Generation** (usePDF.js, 405 lines):
- jsPDF-based A4 PDF generator
- Professional formatting: letterhead, gold rules, document type label, validation badge, citations block, auto page breaks
- Color palette: gold, ink, sage, red, amber
- Section starters for 13 pattern types
- 25mm margins (Indian legal standard)

---

## 3. Agent Architecture

### 3.1 Central LLM Client

**Source:** ackend/agents/llm_client.py

4 pre-initialized ChatGroq instances:
- Researcher: mixtral-8x7b-32768 (temperature 0.1)
- Drafter: llama-3.1-8b-instant (temperature 0.1)
- Reviewer: llama-3.1-8b-instant (temperature 0.1)
- Triage: llama-3.1-8b-instant (temperature 0.1)

All load GROQ_API_KEY from .env.

### 3.2 Agent Manager & Routing

**Source:** ackend/agents/manager.py

AgentManager with mode detection (regex patterns) and route dispatch:
- legal_query → ResearcherAgent
- case_analysis → ResearcherAgent (analysis mode)
- pathfinder → ResearcherAgent (pathfinder mode)
- document → DrafterAgent
- interviewing → DrafterAgent
- evaluate → ReviewerAgent
- scrutiny → ReviewerAgent

### 3.3 Sub-Agents

**TriageAgent** (gents/triage.py): Query classification (LLM + keyword fallback), TOWS analysis generation.

**ResearcherAgent** (gents/researcher.py): Knowledge Q&A, case analysis (FACTS/ISSUES/LAW/OUTCOME), pathfinder (step-by-step). Includes IPC/CrPC→BNS/BNSS mapping.

**DrafterAgent** (gents/drafter.py): Document type detection, field collection, LLM document generation.

**ReviewerAgent** (gents/reviewer.py): Contract evaluation, pre-draft scrutiny, limitation check, red flag detection, veto check.

---

## 4. Data Layer & Cloud Persistence

### 4.1 Supabase Managed PostgreSQL (Primary Cloud Database)
- **Host:** `aws-0-ap-southeast-1.pooler.supabase.com`
- **Port:** `5432` (Session Mode) / `6543` (Transaction Mode)
- **Engine:** IPv4 Connection Pooler bypassing IPv6 container restrictions
- **Tables:** `users`, `conversations`, `messages`
- **Indexes:** `idx_conversations_user_id`, `idx_messages_conv_id`, `idx_messages_conversation_id`
- **Concurrency:** Multi-device simultaneous read/write with zero file-locking bottlenecks

### 4.2 Local SQLite Fallback
- **File:** `backend/saulgpt.db`
- **Mode:** WAL (Write-Ahead Logging) for concurrent access
- Automatically activated if `DATABASE_URL` is omitted in local development

### 4.3 ChromaDB (Vector Store)
- **Collection:** `saulgpt_indian_laws` & `landmark_precedents`
- **Embeddings:** `sentence-transformers/all-MiniLM-L6-v2` pinned to `device="cpu"`
- **Total Chunks:** 2,449+ statutory and case law segments
- **Path:** `data/vector_db/`

### 4.4 JSON Raw Data Sources
- **Path:** `data/raw_data/`
- Contains canonical acts: BNS 2023, BNSS 2023, BSA 2023, CPC 1908, NIA 1881, HMA 1955, MVA 1988, IDA 1869, Constitution of India

### 4.5 Relational GNN Knowledge Graph (In-Memory)
- NetworkX DiGraph + PyTorch continuous embeddings (TransE/RotatE in $\mathbb{R}^{64}$)
- 73 canonical legal relations, 268 nodes, 172 triples

---

## 5. Pre-Trial Studio & Moot Court Arena

**Source:** `backend/trial_studio/`, `saulgpt-ui/src/TrialStudio.jsx`

Interactive adversarial courtroom simulation providing rigorous trial preparation before an actual hearing.

### 5.1 Hostile Section 146 BSA Cross-Examiner
- Implements aggressive cross-examination tactics targeting documentary gaps, oral inconsistencies, and tax filing contradictions under Section 146 of the Bharatiya Sakshya Adhiniyam, 2023.
- Formulates multi-turn traps designed to impeach witness credibility.

### 5.2 Confidential Corner Coach & Tactical Counsel
- Operates in real time alongside the courtroom examination.
- Real-time exposure gauge (Low / Medium / High Risk).
- Flags formal procedural objections (e.g. hearsay, leading questions, questions without foundation).
- Provides verbatim, safe witness rejoinders that avoid fatal admissions.
- Suggests tangible evidentiary plugs to introduce into the record.

### 5.3 Precedent Intelligence Engine
- Indexed database of **50,000+ landmark Supreme Court and High Court judgments** across 8 frameworks: BNS, BNSS, BSA, NI Act, CPA 2019, Contract Act, Limitation Act, Arbitration Act.
- Fallback keyword detection matches dispute patterns to governing precedents.

### 5.4 Split-Chamber UI
- Left Column: Formal Courtroom Chamber with judge/counsel dialogue stream and witness stand.
- Right Column: Confidential Corner Coach Console with live exposure meter and objection arsenal.

---

## 6. Section 63 BSA Digital Evidence Grounding

**Source:** `backend/evidence_processor.py`, `saulgpt-ui/src/EvidenceUploader.jsx`

End-to-end processing and certification of electronic records under Section 63 of the Bharatiya Sakshya Adhiniyam, 2023 (formerly Section 65B IEA).

### 6.1 Cryptographic Hash Verification
- Dual-tier SHA-256 integrity calculation: computed client-side in the browser on file selection, and independently re-verified server-side on upload.
- Detects any bitwise tampering during transit.

### 6.2 Cheque OCR & 30-Day Statutory Clock
- Extracts bank return memos, dishonour codes (e.g. "Funds Insufficient", "Account Closed"), drawer/payee names, and amount.
- Automatically calculates the mandatory 30-day statutory notice window under Section 138 NIA.

### 6.3 Debtor Audio Admission & Limitation Extender
- Transcribes and semantically parses voice admissions and debt promises.
- Applies Section 18 of the Limitation Act, 1963 to compute revised limitation expiry dates based on valid acknowledgments of liability.

### 6.4 Court-Admissible Electronic Certificate Generation
- Automatically drafts a formal Section 63 BSA compliance certificate.
- Details device identifiers, cryptographic hash, extraction date, custodian signature block, and truth verification.
- 1-click integration transmits certified evidence directly into the Pre-Trial Studio.

---

## 7. Actor-Critic Fine-Grained Process Reward Model (FG-PRM)

**Source:** `backend/actor_critic.py`, `backend/layer4_validation.py`

Neuro-symbolic reinforcement validation that scrutinizes reasoning chains before emitting legal counsel.

### 7.1 Multi-Dimensional Step Evaluation
- Evaluates four orthogonal dimensions:
  1. **Factuality & Citation Validity:** Verifies whether cited sections actually exist and match the proposition.
  2. **Statutory Applicability:** Prevents application of repealed statutes (IPC/CrPC) or struck-down provisions.
  3. **Logical Soundness & Neutrality:** Checks for non-sequiturs or premature conclusions.
  4. **Tone & Client Empathy:** Ensures professional, measured legal counsel matching client distress.

### 7.2 Dynamic Token Budgeting (`max_tokens=800`)
- PRM feedback loop strictly constrained to `max_tokens=800`.
- Eliminates Groq free-tier 1000 OTPM rate limit exceptions (`429 rate_limit_exceeded`) while preserving comprehensive critique.

### 7.3 Fast-Path Bypasses
- Low-complexity queries bypass secondary critic passes, ensuring sub-second response latency.

---

## 8. High-Capacity Contract Evaluator (Layer 6)

**Source:** `backend/layer6_evaluator.py`, `saulgpt-ui/src/App.jsx`

Deep structural analysis of commercial and employment agreements.

### 8.1 25,000-Character Single-Pass Ingestion
- Evaluates extensive multi-page contracts in a unified prompt context, eliminating fragmentation and cross-chunk context loss.

### 8.2 Indian Contract Act 1872 Auditing
- **Section 27 (Restraint of Trade):** Flags void post-employment non-compete clauses.
- **Section 28 (Restraint of Legal Proceedings):** Identifies illegal time limits on litigation.
- **Section 74 (Liquidated Damages vs. Penalties):** Scrutinizes disproportionate penalty clauses.

### 8.3 Tri-Level Risk Scoring
- 🔴 **High Risk:** Void/unlawful terms requiring immediate deletion.
- 🟡 **Medium Risk:** Unbalanced commercial exposure (unilateral indemnity, unlimited liability).
- 🟢 **Low Risk:** Fair, reciprocal covenants.
- Outputs concrete, redlined clause replacements ready for negotiation.

---

## 9. 4-Family Court-Grade Document Factory

**Source:** `backend/interview_state.py`, `backend/document_generator.py`

Synthesizes print-ready, legally enforceable documents in Microsoft Word (`.docx`) and vector PDF formats.

### 9.1 Supported Document Families
1. **Letter / Notice Family (`letter`):**
   - Section 138 NIA Cheque Bounce Notices, Demand Notices for Unpaid Salary, Tenancy Default Notices.
   - Formal RPAD header, Sender `FROM:` block, Recipient `TO:` block, 15-day statutory demand clause, advocate signature block.
2. **Pleading Family (`pleading`):**
   - Civil Plaints under Order VII Rule 1 CPC, Section 223 BNSS Criminal Complaints.
   - Enforces the **Triad of Survival:** Cause of Action & Limitation, Territorial/Pecuniary Jurisdiction, and Court Valuation with Order VI Rule 15 verification split.
3. **Affidavit Family (`affidavit`):**
   - Sworn deponent affidavits with 5.5-inch stamp paper top margin and dual notary verification (personal knowledge vs. legal advice).
4. **Agreement Family (`agreement`):**
   - Commercial Leases, SLAs, NDAs with recitals, operative covenants, Section 7 Arbitration clause, and dual witness blocks.

### 9.2 Zero Prompt Leakage & Clean Formatting
- **Sanitization Pipeline:** Strips all `[User Goal: document]` tags, instruction strings, and raw dictionary keys.
- **Deterministic Fallback Spec Engine:** If the LLM spec generator times out, `build_fallback_spec()` automatically constructs an authentic, clause-complete legal document.
- **Resilient Cloud Delivery:** Cached in memory and on disk (`./generated_docs/`), delivered via Axios blob stream with fallback browser navigation.

---

## 10. Security, Cloud Infrastructure & BYOK Architecture

### 10.1 Hugging Face Spaces ZeroGPU Backend
- Configured via `app.py` unifying Gradio 5.20 and FastAPI on port 7860.
- Dynamic GPU allocation (`zero-a10g`) with PyTorch embeddings strictly pinned to CPU to prevent ZeroGPU CUDA supervisor aborts.

### 10.2 Bring Your Own Key (BYOK)
- Users can provide their personal Groq API keys (`gsk_...`) in `ApiKeyModal.jsx`.
- Stored exclusively in the user's browser `localStorage` and passed per-request via the `X-Groq-Api-Key` HTTP header.
- Zero server-side key logging or persistence.

---

## File Reference Summary

**Backend (25 root + 4 trial_studio + 6 agents + 8 prompts + 4 scraper + 3 tests = 50 Python files)**
- `app.py` — ZeroGPU Gradio 5.20 + FastAPI server entrypoint
- `deploy_hf.py` — Automated deployment script for Hugging Face Spaces
- `api_server.py` — Core FastAPI controller and route dispatcher
- `pipeline_orchestrator.py` — 6-layer deterministic RAG controller
- `actor_critic.py` — Actor-Critic Fine-Grained Process Reward Model
- `evidence_processor.py` — Section 63 BSA electronic evidence & certification
- `layer1_understanding.py` — Query understanding, Hindi HyDE, spaCy NER
- `layer2_retrieval.py` — ChromaDB vector retrieval & Cross-Encoder (CPU)
- `layer3_reasoning.py` — LLM response generation via Groq
- `layer4_validation.py` — DeBERTa NLI & SC Struck-Down Firewall
- `layer5_external.py` — IndianKanoon / DuckDuckGo live search fallback
- `layer6_evaluator.py` — 25,000-character contract risk evaluation
- `layer6_knowledge_graph.py` — Relational legal knowledge graph (NetworkX)
- `interview_state.py` — Document drafting state machine & fallback spec engine
- `document_generator.py` — 4-family .docx generation (Letter, Pleading, Affidavit, Agreement)
- `dynamic_drafter.py` — Dynamic field scoping
- `scrutiny_agent.py` — Pre-draft limitation and validity scrutiny
- `discovery_agent.py` — Phase 1: 3-turn empathetic investigation
- `strategy_agent.py` — Phase 2: SWOT matrix & 4-path generation
- `irac_agent.py` — Advocate Mode IRAC structured brief generator
- `triage_state.py` — 3-phase flow state machine
- `database.py` — Supabase PostgreSQL + SQLite dual CRUD engine
- `auth.py` — JWT authentication and bcrypt password hashing
- `eval_pipeline.py` — Automated RAG benchmarking suite
- `trial_studio/cross_examiner_agent.py` — Hostile Sec 146 BSA cross-examiner
- `trial_studio/defense_fortifier_agent.py` — Corner Coach procedural objections
- `trial_studio/precedent_engine.py` — 50,000+ landmark judgments index
- `trial_studio/session_manager.py` — Moot court session persistence

**Frontend (16 script + 6 CSS files)**
- `App.jsx` — Core Omni-Box chat interface & session controller
- `AuthPage.jsx` — JWT Login/Signup & guest session migration
- `ConversationsSidebar.jsx` — Supabase cloud-synced conversation list
- `TrialStudio.jsx` — Split-Chamber Pre-Trial Moot Court Arena
- `EvidenceUploader.jsx` — Sec 63 BSA evidence uploader with hash verification
- `TriageCards.jsx` — Strategic SWOT 4-path cards
- `VetoCard.jsx` — Scrutiny blocker & limitation warning card
- `BNSCorrectionNotice.jsx` — 2024 Transition notification banner
- `JurisdictionBadge.jsx` — Court pecuniary & territorial indicator
- `UrgencyBanner.jsx` — Statutory limitation countdown banner
- `ApiKeyModal.jsx` — Bring-Your-Own-Key (BYOK) modal
- `LegalGlossary.js` — 200+ Indian legal term dictionary
- `usePDF.js` — Client-side jsPDF A4 vector rendering engine
- `App.css`, `TrialStudio.css`, `EvidenceUploader.css` — Courtroom styling