adi-o3-multipass/README_GUI.md

Brief Extractor GUI

Modern web interface for the Enhanced Brief Processing System with real-time progress tracking, multi-model AI processing, and Microsoft SSO authentication.

Quick Start

Development Mode

1. Install Dependencies:

# Backend
pip install -r server_requirements.txt

# Frontend
cd frontend
npm install
cd ..

2. Configure Environment:

# Copy and edit .env file with your API keys
# DEV_MODE=true is already set for local development

3. Start Services:

# Terminal 1: Backend
python run_server.py

# Terminal 2: Frontend
cd frontend
npm run dev

4. Access Application:

• Frontend: http://localhost:3000
• Backend API: http://localhost:8000
• Health Check: http://localhost:8000/health

Production Deployment

1. Configure Authentication:

# Update .env with your Microsoft Azure AD app registration:
MSAL_CLIENT_ID=your-client-id
MSAL_CLIENT_SECRET=your-client-secret
MSAL_TENANT_ID=your-tenant-id
DEV_MODE=false

2. Deploy with Docker:

# Build and start all services
docker-compose up -d

# Check status
docker-compose ps
docker-compose logs -f

Architecture

Backend (Python/Quart)

• Async web framework with WebSocket support
• Job queue system with concurrent processing
• Multi-model AI integration preserving existing processing logic
• Real-time progress tracking via WebSocket
• MSAL authentication with dev mode bypass
• File management with auto-cleanup

Frontend (React/TypeScript)

• Modern React with TypeScript and Vite
• Real-time updates via WebSocket
• MSAL integration for SSO authentication
• Model configuration interface
• Progress visualization with provider status
• Responsive design with Tailwind CSS

Key Features

✅ Multi-file upload with drag-and-drop ✅ Real-time progress for all processing stages ✅ Model selection (primary + consolidation models) ✅ Cost estimation before processing ✅ Live log streaming for active jobs ✅ Batch operations (multi-upload, batch download) ✅ Authentication (MSAL SSO + dev mode) ✅ Auto-cleanup of processed files ✅ Docker deployment ready

API Endpoints

Authentication

• GET /api/auth/config - Get MSAL configuration
• POST /api/auth/validate - Validate access token
• GET /api/auth/user - Get current user info
• POST /api/auth/logout - Get logout URL

Jobs

• POST /api/jobs - Upload files and create jobs
• GET /api/jobs - List user's jobs
• GET /api/jobs/<id> - Get job details
• GET /api/jobs/<id>/download - Download CSV result
• GET /api/jobs/<id>/logs - Get job logs
• DELETE /api/jobs/<id> - Delete job
• POST /api/jobs/batch-download - Download multiple CSVs as ZIP

Configuration

• GET /api/config/models - Available models with pricing
• GET /api/config/defaults - Default configuration
• POST /api/config/estimate - Estimate processing cost
• POST /api/config/validate - Validate model configuration

System

• GET /health - Health check
• GET /api/config/system - System information

WebSocket Events

Job Lifecycle

• queue.snapshot - Initial job list
• job.created - New job added to queue
• job.progress - Progress update
• job.provider_update - Individual model status
• job.log - Real-time log entry
• job.completed - Job finished successfully
• job.failed - Job failed with error
• job.deleted - Job removed

Environment Variables

See .env file for complete configuration. Key settings:

# Development
DEV_MODE=true                    # Bypass MSAL in development
ALLOWED_ORIGINS=http://localhost:3000

# Authentication (Production)
MSAL_CLIENT_ID=your-client-id
MSAL_CLIENT_SECRET=your-secret
MSAL_TENANT_ID=your-tenant-id

# Performance
MAX_CONCURRENT_JOBS=2
MAX_UPLOAD_SIZE_MB=200
FILE_RETENTION_HOURS=24

# All existing AI model API keys remain the same

CLI Compatibility

The original CLI interface remains fully functional:

# Original usage still works
python core/process_brief_enhanced.py document.pdf

# With custom models
python core/process_brief_enhanced.py document.pdf \
  --primary-models openai-gpt5,anthropic-sonnet4 \
  --consolidation-model anthropic-opus4

Development Notes

Project Structure

├── server/                 # Quart backend
│   ├── api/               # REST endpoints
│   ├── auth/              # MSAL authentication
│   ├── jobs/              # Job management
│   ├── ws/                # WebSocket handling
│   └── runners/           # Job processing
├── core/                  # Original processing logic (moved)
├── frontend/              # React frontend
├── prompts/               # AI prompts and schemas
└── docker-compose.yml     # Container orchestration

Adding Features

• New API endpoints: Add to server/api/
• WebSocket events: Extend ws/manager.py
• UI components: Add to frontend/src/components/
• Processing logic: Modify core/ modules

Testing

# Backend tests
cd server
python -m pytest

# Frontend tests
cd frontend
npm test

# Integration tests
docker-compose -f docker-compose.test.yml up --abort-on-container-exit

Production Checklist

• Configure Microsoft Azure AD app registration
• Set production environment variables
• Configure HTTPS certificates
• Set up monitoring and logging
• Configure backup for processed files
• Set up alerts for processing failures
• Load test with expected file volumes

Support

For issues or questions:

1. Check logs: docker-compose logs
2. Health check: Visit /health endpoint
3. WebSocket status: Check browser dev tools
4. File permissions: Ensure server/data/ is writable

The GUI provides the same powerful multi-model AI processing as the CLI with an intuitive web interface, real-time progress tracking, and enterprise authentication.