Paralegal AI - Intelligent Legal Research System

AI Legal Tender Hackathon - Phase 2
Status: ✅ PRODUCTION READY
Performance: 41.7 cases/sec | 100 concurrent workers | 10.6M cases accessible

🚀 What We Built

An intelligent legal research system that combines:

Saul-7B Legal AI for smart query generation
CourtListener API for access to 10.6M legal opinions (FREE!)
Hyper-parallelized scraping with 100 concurrent workers
AMD MI300X GPU acceleration (192GB VRAM)
Continuous learning through automated case discovery

Performance Highlights

OLD SYSTEM:  ~5-10 cases/sec  (sequential, 3 workers)
NEW SYSTEM:  ~41.7 cases/sec  (async, 100 workers)
IMPROVEMENT: 4-8x FASTER! 🚀

Test Results (October 26, 2025)

✅ TEST 1: CourtListener API - 3/3 endpoints working
✅ TEST 2: Saul-7B Query Generator - 3-5 intelligent queries per question
✅ TEST 3: Intelligent Scraper - 5 cases in <1 second
✅ TEST 4: Hyper-Parallelized Orchestrator - 20 cases in 1.93s (10.4 cases/sec)
✅ TEST 5: Performance Benchmark - 41.7 cases/sec peak, 135 total cases in 20.73s

📖 Documentation

Essential Reading

SYSTEM_DOCUMENTATION.md ⭐ START HERE
- Complete system overview
- Architecture and flow diagrams
- Performance metrics and benchmarks
- API reference
- Quick start guide
- Troubleshooting
INTELLIGENT_SCRAPING_SYSTEM.md
- System architecture
- Component details
- Integration guide
CLEANUP_PLAN.md
- Repository audit
- File organization
- Cleanup status

Supporting Documentation

FAISS_EXECUTION_GUIDE.md - RAG system setup
DATABASE_DOCUMENTATION.md - Database schema
MODEL_SETUP_GUIDE.md - AI model deployment
GPU_OPTIMIZATION_GUIDE.md - AMD MI300X optimization

🏗️ Architecture

System Flow

User Question
     ↓
Saul-7B Legal AI (Query Generation)
     ↓
3-5 Optimized Search Queries
     ↓
100 Concurrent Workers (Async HTTP)
     ↓
CourtListener API (10.6M Cases)
     ↓
41.7 cases/second scraped
     ↓
Auto-cached to JSON
     ↓
Enhanced Legal Research Results

Core Components

AMD_server/ml_pipeline/
├── intelligent_scraper.py     # Multi-mode scraper (API/web/hybrid)
├── query_generator.py          # Saul-7B query generation
├── auto_integration.py         # RAG integration pipeline
├── orchestrator.py             # Hyper-parallelized coordinator
├── rag_embeddings.py           # FAISS embeddings system
└── data_loader.py              # Database integration

🚀 Quick Start

Prerequisites

# Hardware
- AMD MI300X GPU (192GB VRAM)
- Ubuntu Linux
- PostgreSQL database

# Software
- Python 3.12+
- vLLM server (Saul-7B-Instruct-v1)
- CourtListener API token

Installation

# 1. Clone repository
git clone https://github.com/BonelessWater/Paralegal.git
cd Paralegal

# 2. Set up virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install dependencies
./quick_fix_dependencies.sh

# 4. Configure API token
export COURTLISTENER_API_TOKEN="your_token_here"

Running Tests

# Run complete system test (all 5 tests)
./test_complete_system.sh

# Expected output:
# ✅ CourtListener API access verified
# ✅ Saul-7B generating 3-5 queries
# ✅ Async scraping at 40+ cases/sec
# ✅ 135 total cases scraped in 20.73s

Usage Example

from AMD_server.ml_pipeline.orchestrator import ScrapingOrchestrator

# Initialize orchestrator with 100 concurrent workers
orchestrator = ScrapingOrchestrator(max_concurrent=100)

# Research a legal question
results = await orchestrator.research_question_async(
    "Can my employer fire me for filing a workers comp claim?"
)

# Results include:
# - Generated queries: 3-5 intelligent legal queries
# - Scraped cases: 20-60 relevant legal opinions
# - Integration stats: success/failure metrics
# - Performance data: cases/sec, total time

📊 Key Features

1. Intelligent Query Generation

Uses Saul-7B Legal AI to analyze user questions
Generates 3-5 optimized search queries
Routes to optimal source (CourtListener vs LexisNexis)
Assigns priority (HIGH/MEDIUM/LOW)

2. Hyper-Parallelized Scraping

100 concurrent workers (up from 3)
Async/await throughout the pipeline
41.7 cases/second peak performance
4-8x faster than baseline

3. Multi-Source Integration

CourtListener: 10.6M opinions, FREE API
LexisNexis: Premium cases, web scraping
Smart routing: Common cases → CourtListener, Rare cases → LexisNexis

4. GPU Acceleration

AMD MI300X (192GB VRAM)
FAISS on GPU for fast similarity search
Sentence transformers for embeddings

🎯 Performance Metrics

Benchmark Results

Metric	Result
Peak Scraping Speed	41.7 cases/sec
Average Throughput	6.5 cases/sec
Concurrent Workers	100 workers
Total Cases Tested	135 cases
Time for 135 Cases	20.73 seconds
API Rate Limit	5,000 req/hour
Database Size	10.6M opinions
Speed Improvement	4-8x faster 🚀

🔧 Configuration

Environment Variables

# Required
COURTLISTENER_API_TOKEN=your_token_here  # Get from courtlistener.com
VLLM_BASE_URL=http://localhost:8000      # Saul-7B vLLM server

# Database
DB_HOST=134.199.202.8
DB_NAME=paralegal_db
DB_USER=paralegal_user
DB_PASSWORD=hackathon2024

# Optional
LEXISNEXIS_USERNAME=your_username        # For premium scraping
LEXISNEXIS_PASSWORD=your_password

Performance Tuning

# In orchestrator.py
max_concurrent = 100   # Concurrent workers (50-200)
batch_size = 20        # Cases per query (10-50)
rate_limit = 1.0       # Seconds between requests (0.5-2.0)

🧪 Testing

Test Suite

./test_complete_system.sh

Runs 5 comprehensive tests:

CourtListener API Access - Verifies token and endpoints
Query Generator - Tests Saul-7B generation
Intelligent Scraper - Tests async scraping (5 cases)
Hyper-Parallelized Orchestrator - Tests full pipeline (60 cases)
Performance Benchmark - Tests concurrent research (135 cases)

Expected Results

✅ TEST 1: 3/3 endpoints working
✅ TEST 2: 3-5 queries generated per question
✅ TEST 3: 5 cases scraped in <1 second
✅ TEST 4: 20 cases in 1.93s (10.4 cases/sec)
✅ TEST 5: 41.7 cases/sec peak, 135 cases in 20.73s

🐛 Troubleshooting

Common Issues

"Model not found"

# Check vLLM server is running
curl http://localhost:8000/v1/models
# Should return: Equall/Saul-7B-Instruct-v1

"API rate limit exceeded"

# Verify your CourtListener token
echo $COURTLISTENER_API_TOKEN

# Reduce concurrent workers
# In orchestrator.py: max_concurrent = 50

"Module not found"

# Install missing dependencies
./quick_fix_dependencies.sh

📁 Project Structure

Paralegal/
├── SYSTEM_DOCUMENTATION.md          # ⭐ Complete system docs
├── CLEANUP_PLAN.md                  # Repository audit
├── README.md                        # This file
├── test_complete_system.sh          # Test suite
├── quick_fix_dependencies.sh        # Dependency installer
│
├── AMD_server/ml_pipeline/          # Core system
│   ├── intelligent_scraper.py       # Multi-mode scraper
│   ├── query_generator.py           # LLM query generation
│   ├── auto_integration.py          # RAG integration
│   ├── orchestrator.py              # Coordinator
│   ├── rag_embeddings.py            # FAISS system
│   └── data_loader.py               # Database
│
└── docs/                            # Documentation
    ├── INTELLIGENT_SCRAPING_SYSTEM.md
    ├── FAISS_EXECUTION_GUIDE.md
    ├── DATABASE_DOCUMENTATION.md
    ├── MODEL_SETUP_GUIDE.md
    └── GPU_OPTIMIZATION_GUIDE.md

🤝 Team

Project: Paralegal AI
Team: BonelessWater
Hackathon: AI Legal Tender - Phase 2
Hardware: AMD MI300X GPU Server

📄 License

MIT License

🙏 Acknowledgments

AMD - MI300X GPU server access
CourtListener - FREE legal opinion API
Equall/Saul-7B - Legal AI model
vLLM - Fast inference server
AI Legal Tender - Hackathon organizers

Last Updated: October 26, 2025
Version: 2.0.0
Status: ✅ PRODUCTION READY

Name		Name	Last commit message	Last commit date
Latest commit History 216 Commits
AMD_server		AMD_server
backend		backend
deployment		deployment
docs		docs
frontend		frontend
scraper		scraper
.env.example		.env.example
.gitignore		.gitignore
ADK_white_background.png		ADK_white_background.png
Architecture.png		Architecture.png
QUICK_START.md		QUICK_START.md
README.md		README.md
requirements.txt		requirements.txt

Jbadro/Lawgorithm

Folders and files

Latest commit

History

Repository files navigation