Spaces:

Lvvbaaal
/

legalgpt-api

Running on Zero

App Files Files Community

legalgpt-api / docs /SETUP_GUIDE.md

Lvvbaaal

Deploy backend updates from local workspace

e809c21 verified 6 days ago

preview code

Raw History Blame Contribute Delete

10 kB

# 💻 SaulGPT Local Development & Setup Guide

**Document Version:** 2.2.0  
**Target Release:** Production Cloud & Local Workstation  

This guide walks you through setting up, configuring, and testing the full **SaulGPT** stack on your local development machine.

---

## 📋 1. Prerequisites

Before starting, ensure you have the following installed on your machine:
- **Python:** 3.10 or 3.11 ([python.org](https://www.python.org/downloads/))
- **Node.js:** 18+ LTS ([nodejs.org](https://nodejs.org/))
- **Git:** Latest version
- **A Groq Cloud API Key:** Free tier from [console.groq.com](https://console.groq.com/)

---

## ⚡ 2. One-Click Quick Start (Windows)

For rapid local testing on Windows:

1. **One-Time Setup:**
   Double-click `scripts\setup.bat` — This will create the Python virtual environment (`.venv`), install all backend dependencies, download the spaCy English NLP model, and run `npm install` in `saulgpt-ui/`.

2. **Run the Application:**
   Double-click `start.vbs` — It silently launches:
   - Python FastAPI backend on `http://localhost:8000`
   - React + Vite development server on `http://localhost:5173`
   - Automatically opens your default web browser to the app.

---

## 🛠️ 3. Step-by-Step Manual Setup

### 3.1 Backend Configuration
```bash
# 1. Clone the repository
git clone https://github.com/lbbaalaji0406/legalgpt.git
cd legalgpt
# 2. Create and activate virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate
# 3. Install dependencies
pip install -r backend/requirements.txt
pip install -r requirements.txt
# 4. Download spaCy English model
python -m spacy download en_core_web_sm
```

### 3.2 Environment Variables Configuration
Create a `.env` file in the project root:
```bash
copy .env.example .env
```

Populate the following variables:
```ini
# LLM Provider (Groq Cloud)
GROQ_API_KEY=gsk_your_groq_api_key_here
GROQ_MODEL=llama-3.1-8b-instant
# Persistence Mode:
# Leave blank to use local SQLite (backend/saulgpt.db)
# OR provide a Supabase IPv4 Pooler connection string for cloud sync:
DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-ap-southeast-1.pooler.supabase.com:5432/postgres
# Security & Public URL
JWT_SECRET=development-secret-key-replace-in-production
PUBLIC_API_URL=http://localhost:8000
```

### 3.3 Vector Database Verification
Pre-embedded ChromaDB vector collections are included in `data/vector_db/` (~2,449 chunks across 9 acts and landmark precedents). If you need to rebuild the vector database from raw JSON sources:
```bash
cd backend
python 02_chunk_and_embed.py
cd ..
```

### 3.4 Frontend Setup
```bash
cd saulgpt-ui
npm install
cd ..
```

---

## 🏃 4. Running the Application

### Terminal 1: Backend API Server
```bash
cd backend
..\.venv\Scripts\python.exe -m uvicorn api_server:app --host 0.0.0.0 --port 8000 --reload
```
The FastAPI documentation is available at: `http://localhost:8000/docs`

### Terminal 2: React Frontend UI
```bash
cd saulgpt-ui
npm run dev
```
The development UI is available at: `http://localhost:5173`

---

## 🧪 5. Testing & Evaluation

### 5.1 Automated RAG Pipeline Evaluation
Run the automated evaluation suite to benchmark retrieval accuracy, hallucination prevention, and keyword precision across 8 gold-standard test scenarios:
```bash
cd backend
..\.venv\Scripts\python.exe eval_pipeline.py
```

### 5.2 Isolated Agent Endpoint Testing
You can test specific subsystems directly using `curl` or Postman:

```bash
# 1. Health & Database Check
curl http://localhost:8000/api/health
# 2. Knowledge Retrieval (Layer 2 + Layer 3)
curl "http://localhost:8000/api/test/knowledge?q=What+is+Section+138+of+Negotiable+Instruments+Act"
# 3. Advocate Mode IRAC Analysis
curl "http://localhost:8000/api/test/analysis?q=Employer+withheld+three+months+salary+without+cause"
# 4. Procedural Pathfinder
curl "http://localhost:8000/api/test/pathfinder?q=How+do+I+file+an+e-FIR+for+cyber+theft"
# 5. Document Drafter Scrutiny Test
curl -X POST http://localhost:8000/api/test/scrutiny \
  -H "Content-Type: application/json" \
  -d '{"doc_type": "cheque_bounce", "date_of_default": "2024-05-10", "notice_date": "2024-05-20"}'
```

---

## 📂 6. Repository Layout & File Map

```
legalgpt-master/
├── ARCH.md                     # Quick-Reference Architecture & Topology Map
├── CLAUDE.md                   # Agent Memory, Conventions & Session Logs
├── DEPLOYMENT_GUIDE.md         # Production Cloud Deployment Guide
├── README.md                   # Project Overview & Hugging Face Frontmatter
├── app.py                      # ZeroGPU Gradio 5.20 + FastAPI Entrypoint
├── deploy_hf.py                # Automated Hugging Face Space Deployment Script
├── requirements.txt            # Root dependencies for Hugging Face container
│
├── backend/                    # Python Backend
│   ├── api_server.py           # Core FastAPI application & route dispatcher
│   ├── pipeline_orchestrator.py# 6-Layer Deterministic RAG controller
│   ├── actor_critic.py         # Actor-Critic Fine-Grained Process Reward Model
│   ├── interview_state.py      # Document drafting state machine & fallback spec
│   ├── document_generator.py   # 4-Family .docx generator (RPAD, Pleadings, Affidavits)
│   ├── evidence_processor.py   # Section 63 BSA Digital Certs & Forensic Processor
│   ├── layer1_understanding.py # Query understanding, Hindi HyDE, spaCy NER
│   ├── layer2_retrieval.py     # ChromaDB vector retrieval & Cross-Encoder (CPU)
│   ├── layer3_reasoning.py     # Groq LLM synthesis & IRAC reasoning
│   ├── 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)
│   ├── database.py             # Dual Supabase PostgreSQL + SQLite CRUD engine
│   ├── auth.py                 # JWT token generation & bcrypt authentication
│   ├── 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
│   ├── scrutiny_agent.py       # Pre-draft limitation and validity scrutiny
│   ├── eval_pipeline.py        # Automated RAG benchmarking test harness
│   │
│   ├── trial_studio/           # Pre-Trial Studio & Moot Court Subsystem
│   │   ├── cross_examiner_agent.py   # Hostile Sec 146 BSA cross-examination
│   │   ├── defense_fortifier_agent.py# Corner Coach procedural objections
│   │   ├── precedent_engine.py       # 50,000+ SC/HC landmark judgments index
│   │   └── session_manager.py        # Moot session persistence
│   │
│   ├── agents/                 # Specialized Agent Definitions
│   │   ├── manager.py          # Sub-agent dispatch manager
│   │   ├── llm_client.py       # Centralized Groq LLM client factory
│   │   ├── triage.py           # Query classification
│   │   ├── researcher.py       # Knowledge retrieval agent
│   │   ├── drafter.py          # Document interview agent
│   │   └── reviewer.py         # Contract reviewer agent
│   │
│   └── prompts/                # LLM Prompt Templates
│       ├── triage.py
│       ├── discovery.py
│       ├── strategy.py
│       └── irac.py
│
├── saulgpt-ui/                 # React 18 + Vite Frontend
│   ├── src/
│   │   ├── App.jsx             # Main Omni-Box interface & state router
│   │   ├── AuthPage.jsx        # JWT Authentication & guest session takeover
│   │   ├── ConversationsSidebar.jsx # Cloud-persisted conversation history
│   │   ├── TrialStudio.jsx     # Split-Chamber Pre-Trial Moot Court Arena
│   │   ├── EvidenceUploader.jsx# Sec 63 BSA drag-and-drop evidence uploader
│   │   ├── TriageCards.jsx     # Phase 2 SWOT strategic path cards
│   │   ├── VetoCard.jsx        # Scrutiny blocker & limitation warning
│   │   ├── BNSCorrectionNotice.jsx # 2024 Transition notification badge
│   │   ├── JurisdictionBadge.jsx   # Court pecuniary & territorial indicator
│   │   ├── UrgencyBanner.jsx   # Statutory limitation countdown banner
│   │   ├── ApiKeyModal.jsx     # Bring-Your-Own-Key (BYOK) settings modal
│   │   ├── LegalGlossary.js    # 200+ Indian legal term dictionary
│   │   └── usePDF.js           # Client-side jsPDF vector rendering engine
│   ├── package.json
│   └── vite.config.js
│
├── docs/                       # Technical & Architectural Documentation
│   ├── ARCHITECTURE.md         # Comprehensive system architecture & data flows
│   ├── FDD.md                  # Functional Design Document
│   ├── TDD.md                  # Technical Design Document
│   ├── CHANGELOG_DECISIONS.md  # Architectural Decision Records (ADRs 001 - 030)
│   ├── FEATURES.md             # Complete 10-module feature breakdown
│   ├── API_REFERENCE.md        # REST API endpoints & schemas
│   └── SETUP_GUIDE.md          # This setup guide
│
├── data/
│   ├── raw_data/               # JSON statutory texts (BNS, BNSS, BSA, CPC, NIA, etc.)
│   └── vector_db/              # Pre-embedded ChromaDB vector indexes
│
└── scripts/
    ├── setup.bat               # Windows automated setup script
    └── start.bat               # Windows startup batch script
```

	# 💻 SaulGPT Local Development & Setup Guide

	Document Version: 2.2.0
	Target Release: Production Cloud & Local Workstation

	This guide walks you through setting up, configuring, and testing the full SaulGPT stack on your local development machine.

	---

	## 📋 1. Prerequisites

	Before starting, ensure you have the following installed on your machine:
	- Python: 3.10 or 3.11 ([python.org](https://www.python.org/downloads/))
	- Node.js: 18+ LTS ([nodejs.org](https://nodejs.org/))
	- Git: Latest version
	- A Groq Cloud API Key: Free tier from [console.groq.com](https://console.groq.com/)

	---

	## ⚡ 2. One-Click Quick Start (Windows)

	For rapid local testing on Windows:

	1. One-Time Setup:
	Double-click `scripts\setup.bat` — This will create the Python virtual environment (`.venv`), install all backend dependencies, download the spaCy English NLP model, and run `npm install` in `saulgpt-ui/`.

	2. Run the Application:
	Double-click `start.vbs` — It silently launches:
	- Python FastAPI backend on `http://localhost:8000`
	- React + Vite development server on `http://localhost:5173`
	- Automatically opens your default web browser to the app.

	---

	## 🛠️ 3. Step-by-Step Manual Setup

	### 3.1 Backend Configuration
	```bash
	# 1. Clone the repository
	git clone https://github.com/lbbaalaji0406/legalgpt.git
	cd legalgpt

	# 2. Create and activate virtual environment
	python -m venv .venv

	# On Windows:
	.venv\Scripts\activate
	# On Linux/macOS:
	source .venv/bin/activate

	# 3. Install dependencies
	pip install -r backend/requirements.txt
	pip install -r requirements.txt

	# 4. Download spaCy English model
	python -m spacy download en_core_web_sm
	```

	### 3.2 Environment Variables Configuration
	Create a `.env` file in the project root:
	```bash
	copy .env.example .env
	```

	Populate the following variables:
	```ini
	# LLM Provider (Groq Cloud)
	GROQ_API_KEY=gsk_your_groq_api_key_here
	GROQ_MODEL=llama-3.1-8b-instant

	# Persistence Mode:
	# Leave blank to use local SQLite (backend/saulgpt.db)
	# OR provide a Supabase IPv4 Pooler connection string for cloud sync:
	DATABASE_URL=postgresql://postgres.[ref]:[password]@aws-0-ap-southeast-1.pooler.supabase.com:5432/postgres

	# Security & Public URL
	JWT_SECRET=development-secret-key-replace-in-production
	PUBLIC_API_URL=http://localhost:8000
	```

	### 3.3 Vector Database Verification
	Pre-embedded ChromaDB vector collections are included in `data/vector_db/` (~2,449 chunks across 9 acts and landmark precedents). If you need to rebuild the vector database from raw JSON sources:
	```bash
	cd backend
	python 02_chunk_and_embed.py
	cd ..
	```

	### 3.4 Frontend Setup
	```bash
	cd saulgpt-ui
	npm install
	cd ..
	```

	---

	## 🏃 4. Running the Application

	### Terminal 1: Backend API Server
	```bash
	cd backend
	..\.venv\Scripts\python.exe -m uvicorn api_server:app --host 0.0.0.0 --port 8000 --reload
	```
	The FastAPI documentation is available at: `http://localhost:8000/docs`

	### Terminal 2: React Frontend UI
	```bash
	cd saulgpt-ui
	npm run dev
	```
	The development UI is available at: `http://localhost:5173`

	---

	## 🧪 5. Testing & Evaluation

	### 5.1 Automated RAG Pipeline Evaluation
	Run the automated evaluation suite to benchmark retrieval accuracy, hallucination prevention, and keyword precision across 8 gold-standard test scenarios:
	```bash
	cd backend
	..\.venv\Scripts\python.exe eval_pipeline.py
	```

	### 5.2 Isolated Agent Endpoint Testing
	You can test specific subsystems directly using `curl` or Postman:

	```bash
	# 1. Health & Database Check
	curl http://localhost:8000/api/health

	# 2. Knowledge Retrieval (Layer 2 + Layer 3)
	curl "http://localhost:8000/api/test/knowledge?q=What+is+Section+138+of+Negotiable+Instruments+Act"

	# 3. Advocate Mode IRAC Analysis
	curl "http://localhost:8000/api/test/analysis?q=Employer+withheld+three+months+salary+without+cause"

	# 4. Procedural Pathfinder
	curl "http://localhost:8000/api/test/pathfinder?q=How+do+I+file+an+e-FIR+for+cyber+theft"

	# 5. Document Drafter Scrutiny Test
	curl -X POST http://localhost:8000/api/test/scrutiny \
	-H "Content-Type: application/json" \
	-d '{"doc_type": "cheque_bounce", "date_of_default": "2024-05-10", "notice_date": "2024-05-20"}'
	```

	---

	## 📂 6. Repository Layout & File Map

	```
	legalgpt-master/
	├── ARCH.md # Quick-Reference Architecture & Topology Map
	├── CLAUDE.md # Agent Memory, Conventions & Session Logs
	├── DEPLOYMENT_GUIDE.md # Production Cloud Deployment Guide
	├── README.md # Project Overview & Hugging Face Frontmatter
	├── app.py # ZeroGPU Gradio 5.20 + FastAPI Entrypoint
	├── deploy_hf.py # Automated Hugging Face Space Deployment Script
	├── requirements.txt # Root dependencies for Hugging Face container
	│
	├── backend/ # Python Backend
	│ ├── api_server.py # Core FastAPI application & route dispatcher
	│ ├── pipeline_orchestrator.py# 6-Layer Deterministic RAG controller
	│ ├── actor_critic.py # Actor-Critic Fine-Grained Process Reward Model
	│ ├── interview_state.py # Document drafting state machine & fallback spec
	│ ├── document_generator.py # 4-Family .docx generator (RPAD, Pleadings, Affidavits)
	│ ├── evidence_processor.py # Section 63 BSA Digital Certs & Forensic Processor
	│ ├── layer1_understanding.py # Query understanding, Hindi HyDE, spaCy NER
	│ ├── layer2_retrieval.py # ChromaDB vector retrieval & Cross-Encoder (CPU)
	│ ├── layer3_reasoning.py # Groq LLM synthesis & IRAC reasoning
	│ ├── 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)
	│ ├── database.py # Dual Supabase PostgreSQL + SQLite CRUD engine
	│ ├── auth.py # JWT token generation & bcrypt authentication
	│ ├── 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
	│ ├── scrutiny_agent.py # Pre-draft limitation and validity scrutiny
	│ ├── eval_pipeline.py # Automated RAG benchmarking test harness
	│ │
	│ ├── trial_studio/ # Pre-Trial Studio & Moot Court Subsystem
	│ │ ├── cross_examiner_agent.py # Hostile Sec 146 BSA cross-examination
	│ │ ├── defense_fortifier_agent.py# Corner Coach procedural objections
	│ │ ├── precedent_engine.py # 50,000+ SC/HC landmark judgments index
	│ │ └── session_manager.py # Moot session persistence
	│ │
	│ ├── agents/ # Specialized Agent Definitions
	│ │ ├── manager.py # Sub-agent dispatch manager
	│ │ ├── llm_client.py # Centralized Groq LLM client factory
	│ │ ├── triage.py # Query classification
	│ │ ├── researcher.py # Knowledge retrieval agent
	│ │ ├── drafter.py # Document interview agent
	│ │ └── reviewer.py # Contract reviewer agent
	│ │
	│ └── prompts/ # LLM Prompt Templates
	│ ├── triage.py
	│ ├── discovery.py
	│ ├── strategy.py
	│ └── irac.py
	│
	├── saulgpt-ui/ # React 18 + Vite Frontend
	│ ├── src/
	│ │ ├── App.jsx # Main Omni-Box interface & state router
	│ │ ├── AuthPage.jsx # JWT Authentication & guest session takeover
	│ │ ├── ConversationsSidebar.jsx # Cloud-persisted conversation history
	│ │ ├── TrialStudio.jsx # Split-Chamber Pre-Trial Moot Court Arena
	│ │ ├── EvidenceUploader.jsx# Sec 63 BSA drag-and-drop evidence uploader
	│ │ ├── TriageCards.jsx # Phase 2 SWOT strategic path cards
	│ │ ├── VetoCard.jsx # Scrutiny blocker & limitation warning
	│ │ ├── BNSCorrectionNotice.jsx # 2024 Transition notification badge
	│ │ ├── JurisdictionBadge.jsx # Court pecuniary & territorial indicator
	│ │ ├── UrgencyBanner.jsx # Statutory limitation countdown banner
	│ │ ├── ApiKeyModal.jsx # Bring-Your-Own-Key (BYOK) settings modal
	│ │ ├── LegalGlossary.js # 200+ Indian legal term dictionary
	│ │ └── usePDF.js # Client-side jsPDF vector rendering engine
	│ ├── package.json
	│ └── vite.config.js
	│
	├── docs/ # Technical & Architectural Documentation
	│ ├── ARCHITECTURE.md # Comprehensive system architecture & data flows
	│ ├── FDD.md # Functional Design Document
	│ ├── TDD.md # Technical Design Document
	│ ├── CHANGELOG_DECISIONS.md # Architectural Decision Records (ADRs 001 - 030)
	│ ├── FEATURES.md # Complete 10-module feature breakdown
	│ ├── API_REFERENCE.md # REST API endpoints & schemas
	│ └── SETUP_GUIDE.md # This setup guide
	│
	├── data/
	│ ├── raw_data/ # JSON statutory texts (BNS, BNSS, BSA, CPC, NIA, etc.)
	│ └── vector_db/ # Pre-embedded ChromaDB vector indexes
	│
	└── scripts/
	├── setup.bat # Windows automated setup script
	└── start.bat # Windows startup batch script
	```