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**:
```bash
# Backend
pip install -r server_requirements.txt

# Frontend
cd frontend
npm install
cd ..
```

2. **Configure Environment**:
```bash
# Copy and edit .env file with your API keys
# DEV_MODE=true is already set for local development
```

3. **Start Services**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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:

```bash
# 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:

```bash
# 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
```bash
# 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.