Atomizer/atomizer-dashboard

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

cd atomizer-dashboard/backend
pip install -r requirements.txt

2. Install Frontend Dependencies

cd atomizer-dashboard/frontend
npm install

3. Start the Backend

# From backend directory
python -m uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

4. Start the Frontend

# 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

# Backend
cd backend
pytest

# Frontend
cd frontend
npm run test

Building for Production

# Frontend
cd frontend
npm run build

Type Checking

cd frontend
npx tsc --noEmit

---

Status: Full React dashboard with Claude Code integration