Atomizer/atomizer-dashboard/README.md

# Atomizer Dashboard

Real-time optimization monitoring and control dashboard for the Atomizer optimization engine.

## Features

### Core Dashboard
- **Real-time WebSocket streaming** - Instant updates on new trials
- **Interactive charts** - Convergence, Pareto front, parallel coordinates, parameter importance
- **Chart library toggle** - Switch between Plotly (interactive) and Recharts (fast)
- **Pruning alerts** - Toast notifications for failed trials
- **Data export** - Download trial history as JSON or CSV
- **Study discovery** - Automatically detects all active studies
- **Connection monitoring** - WebSocket status indicator

### Optimization Control
- **Start/Kill optimization** - Launch or force-kill optimization processes
- **Validate top N** - Run FEA validation on best neural network predictions
- **Process monitoring** - Real-time status of running optimizations
- **Console output** - Live logs from optimization process

### Claude Code Integration
- **Embedded terminal** - Full Claude Code CLI in the dashboard
- **Context-aware** - Automatically loads CLAUDE.md and .claude/ skills
- **WebSocket PTY** - Real terminal emulation with xterm.js

### Study Reports
- **Markdown viewer** - View study README and reports
- **Auto-generated reports** - Generate OPTIMIZATION_REPORT.md

---

## Quick Start

### 1. Install Backend Dependencies
```bash
cd atomizer-dashboard/backend
pip install -r requirements.txt
```

### 2. Install Frontend Dependencies
```bash
cd atomizer-dashboard/frontend
npm install
```

### 3. Start the Backend
```bash
# From backend directory
python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
```

### 4. Start the Frontend
```bash
# From frontend directory
npm run dev
```

### 5. Access the Dashboard
- **Frontend**: http://localhost:5173
- **API docs**: http://localhost:8000/docs

---

## Architecture

### Backend Stack
- **FastAPI** - Modern async Python web framework
- **Uvicorn** - ASGI server
- **WebSockets** - Real-time communication
- **psutil** - Process management

### Frontend Stack
- **React 18** + **Vite** + **TypeScript**
- **TailwindCSS** - Utility-first CSS
- **Recharts** / **Plotly** - Charting libraries
- **xterm.js** - Terminal emulator
- **React Query** - Server state management

---

## File Structure

```
atomizer-dashboard/
├── backend/
│   ├── api/
│   │   ├── main.py                    # FastAPI app entry
│   │   ├── routes/
│   │   │   ├── optimization.py        # Study REST endpoints
│   │   │   ├── claude.py              # Claude chat API (legacy)
│   │   │   └── terminal.py            # Claude Code terminal WebSocket
│   │   ├── services/
│   │   │   └── claude_agent.py        # Anthropic API agent (legacy)
│   │   └── websocket/
│   │       └── optimization_stream.py # Real-time trial streaming
│   └── requirements.txt
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── ClaudeTerminal.tsx     # Claude Code terminal
│   │   │   ├── ConsoleOutput.tsx      # Optimization logs
│   │   │   ├── StudyReportViewer.tsx  # Markdown report viewer
│   │   │   ├── dashboard/
│   │   │   │   ├── ControlPanel.tsx   # Start/Stop/Validate
│   │   │   │   └── MetricCard.tsx
│   │   │   └── plotly/                # Plotly chart components
│   │   ├── pages/
│   │   │   ├── Home.tsx               # Study selection
│   │   │   └── Dashboard.tsx          # Main monitoring view
│   │   └── context/
│   │       └── StudyContext.tsx       # Global study state
│   └── package.json
│
└── README.md (this file)
```

---

## API Documentation

### REST Endpoints

#### Studies
- `GET /api/optimization/studies` - List all studies
- `GET /api/optimization/studies/{id}/status` - Get study status
- `GET /api/optimization/studies/{id}/history` - Get trial history
- `GET /api/optimization/studies/{id}/config` - Get optimization config
- `GET /api/optimization/studies/{id}/readme` - Get study README
- `GET /api/optimization/studies/{id}/report` - Get generated report
- `GET /api/optimization/studies/{id}/console` - Get console output
- `GET /api/optimization/studies/{id}/process` - Get process status
- `GET /api/optimization/studies/{id}/metadata` - Get study metadata
- `GET /api/optimization/studies/{id}/pareto-front` - Get Pareto front

#### Control
- `POST /api/optimization/studies/{id}/start` - Start optimization
- `POST /api/optimization/studies/{id}/stop` - Kill optimization process
- `POST /api/optimization/studies/{id}/validate` - Validate top N predictions
- `POST /api/optimization/studies/{id}/report/generate` - Generate report
- `POST /api/optimization/studies/{id}/optuna-dashboard` - Launch Optuna dashboard

#### Claude Code
- `GET /api/terminal/status` - Check Claude CLI availability
- `WebSocket /api/terminal/claude` - Terminal session

### WebSocket Endpoints
- `ws://localhost:8000/api/ws/optimization/{study_id}` - Trial stream
- `ws://localhost:8000/api/terminal/claude` - Claude Code terminal

---

## Claude Code Terminal

The dashboard includes an embedded Claude Code terminal that provides the full CLI experience:

### Features
- Real terminal emulation with xterm.js
- WebSocket-based PTY communication
- Automatic context loading (CLAUDE.md, .claude/skills/)
- Expand/minimize mode

### Requirements
- Claude Code CLI installed: `npm install -g @anthropic-ai/claude-code`
- Authenticated with Claude Code

### Usage
1. Click "Claude Code" button in dashboard header
2. Click "Connect" to start a session
3. Claude starts in Atomizer root with full context
4. Use all Claude Code features (tools, file editing, etc.)

---

## Control Panel

### Start Optimization
Launches `run_optimization.py` with configurable options:
- Max iterations
- FEA batch size
- Tuning trials
- Ensemble size
- Patience
- Fresh start option

### Kill Process
Force-kills the optimization process and all child processes:
- Gets child processes before killing parent
- Kills children bottom-up
- Uses SIGKILL for immediate termination

### Validate Top N
Runs FEA validation on the best N neural network predictions to verify accuracy.

---

## Troubleshooting

### Dashboard shows "Failed to fetch"
- Ensure backend is running: `http://localhost:8000/health`
- Check CORS settings in `backend/api/main.py`

### Claude Code terminal not connecting
- Verify Claude CLI is installed: `claude --version`
- Check that you're authenticated with Claude Code
- Look for errors in browser console

### Charts not updating
- Check WebSocket connection status
- Verify optimization is running
- Check backend console for errors

### Process won't stop
- Use "Kill Process" button (force kill)
- Check Task Manager for orphaned processes

---

## Development

### Running Tests
```bash
# Backend
cd backend
pytest

# Frontend
cd frontend
npm run test
```

### Building for Production
```bash
# Frontend
cd frontend
npm run build
```

### Type Checking
```bash
cd frontend
npx tsc --noEmit
```

---

**Status**: Full React dashboard with Claude Code integration