Legal AI Orchestrator

AI-powered legal task management system with a swipe-based decision interface.

Stack: Next.js + FastAPI + LangGraph + PostgreSQL + OpenRouter

---

Quick Start (5 minutes)

Prerequisites

• Node.js 18+
• Python 3.11+
• Docker Desktop (for Postgres)
• OpenRouter API key (free tier available)

Setup

# 1. Clone the repo
git clone https://github.com/a1vcm/swamphacks2026.git
cd swamphacks2026

# 2. Copy environment file and add your API key
cp .env.example .env
# Edit .env and add your OPENROUTER_API_KEY

# 3. Install dependencies
make install

# 4. Start the database
make dev

# 5. Run database migrations (first time only)
cd apps/api && pip install -r requirements.txt
alembic revision --autogenerate -m "initial"
alembic upgrade head
cd ../..

# 6. Start the servers (use 2 terminal windows)

# Terminal 1 - Backend API
make api
# API running at http://localhost:8000
# API docs at http://localhost:8000/docs

# Terminal 2 - Frontend
make web
# Frontend running at http://localhost:3000

Verify It Works

curl http://localhost:8000/health
# Should return: {"status":"healthy","environment":"development"}

---

Project Structure

├── apps/
│   ├── api/                  # FastAPI Backend
│   │   ├── app/
│   │   │   ├── main.py       # Entry point
│   │   │   ├── config.py     # Settings (env vars)
│   │   │   ├── agents/       # LangGraph AI agents
│   │   │   │   ├── orchestrator.py   # Routes inputs to specialists
│   │   │   │   ├── graph.py          # LangGraph workflow
│   │   │   │   └── specialists/      # Specialist agent implementations
│   │   │   ├── routers/      # API endpoints
│   │   │   │   ├── tasks.py          # Task CRUD + process
│   │   │   │   ├── cases.py          # Case management
│   │   │   │   └── feedback.py       # Analytics
│   │   │   ├── models/       # Database models
│   │   │   └── services/     # LLM client (OpenRouter)
│   │   └── tests/
│   │
│   └── web/                  # Next.js Frontend
│       └── src/
│           ├── app/          # Pages (App Router)
│           ├── components/   # React components
│           │   ├── ui/       # Shadcn components
│           │   └── tasks/    # TaskCard, SwipeContainer
│           ├── lib/          # API client, auth
│           └── types/        # TypeScript types
│
├── docker/                   # Docker configs
├── .github/workflows/        # CI/CD
├── Makefile                  # Dev commands
└── .env.example              # Environment template

---

Team Tasks

🔴 Backend Team (apps/api/)

1. Implement Orchestrator Classification

File: app/agents/orchestrator.py

async def classify(self, content: str, channel: str) -> str:
    # TODO: Use self.llm to classify input into categories:
    # - "client_communication"
    # - "document_processing"
    # - "research_request"
    # - "evidence_review"
    pass

2. Implement Specialist Agents

Directory: app/agents/specialists/

Create these files with LLM-powered logic:

• client_comms.py - Draft responses to client messages
• records_wrangler.py - Categorize and organize documents
• legal_research.py - Research case law and precedents
• evidence_analyzer.py - Analyze evidence relevance

3. Wire Up Process Endpoint

File: app/routers/tasks.py → process_input() function

Replace the placeholder with actual orchestrator call.

---

🔵 Frontend Team (apps/web/)

1. Create Login Page

File: src/app/(auth)/login/page.tsx

Use NextAuth with the credentials provider (password: "demo" for hackathon).

2. Create Dashboard

File: src/app/(dashboard)/page.tsx

• Display pending tasks
• Use SwipeContainer component for swipe decisions
• Show stats from /api/feedback/stats

3. Enhance Swipe UI

File: src/components/tasks/SwipeContainer.tsx

Add animations, gestures, or feedback form on reject.

---

Available Commands

Command	Description
make dev	Start Postgres container
make api	Run FastAPI server (port 8000)
make web	Run Next.js server (port 3000)
make install	Install all dependencies
make test	Run all tests
make lint	Run linters
make db-migrate	Apply database migrations
make db-reset	Reset database

---

API Reference

Health Check

GET /health

Cases

GET  /api/cases           # List cases
POST /api/cases           # Create case {"title": "...", "description": "..."}
GET  /api/cases/{id}      # Get case

Tasks

GET  /api/tasks                    # List tasks
GET  /api/tasks?status=pending     # Filter by status
POST /api/tasks/process            # Process input → create task
POST /api/tasks/{id}/decide        # Submit decision {"accepted": true/false}

Feedback

GET /api/feedback/stats    # Get acceptance rate stats
GET /api/feedback/recent   # Recent decisions

---

Environment Variables

# Required
OPENROUTER_API_KEY=sk-or-...        # Get at openrouter.ai

# Optional (have defaults)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/legal_ai
NEXTAUTH_SECRET=generate-a-secret   # openssl rand -base64 32

---

Architecture

┌─────────────────────────────────────────────────────────┐
│              Frontend (Next.js + Shadcn)                │
│  • Swipe interface for task decisions                   │
│  • NextAuth.js authentication                           │
└─────────────────────────┬───────────────────────────────┘
                          │ REST API
┌─────────────────────────▼───────────────────────────────┐
│              Backend (FastAPI + LangGraph)              │
│  • Orchestrator classifies inputs                       │
│  • Specialist agents generate recommendations           │
│  • OpenRouter for LLM access (Claude, GPT-4, etc.)     │
└─────────────────────────┬───────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────┐
│              Database (PostgreSQL)                      │
│  • cases, inputs, tasks, decisions                      │
└─────────────────────────────────────────────────────────┘

---

Troubleshooting

"Connection refused" on API calls

• Make sure Postgres is running: make dev
• Check API is running: make api

"Module not found" in Python

• Install deps: cd apps/api && pip install -r requirements.txt

Database errors

• Reset: make db-reset
• Run migrations: make db-migrate

OpenRouter errors

• Check your API key in .env
• Verify at https://openrouter.ai/keys

---

Deployment

• Frontend: Connect repo to Vercel (auto-deploys)
• Backend: Connect to Railway or Render
• Database: Railway Postgres or Render Postgres

---

Built for SwampHacks 2026 🐊