# ABI Observability Dashboard (Legacy)

> **Superseded by**: [`abi-infra/dashboard/`](/dashboard/) — the Next.js dashboard
> (React 19, Recharts, Tailwind) is now the canonical dashboard.
> This Python/static-HTML version remains functional for Node-free environments
> but receives no new features.

Real-time status dashboard for monitoring AI pipeline runs.

## Features

- **Lightweight HTTP API**: Built with Python's `http.server` (no external dependencies)
- **Interactive Web UI**: Single-page dashboard with dark theme and smooth animations
- **Pipeline Visualization**: Color-coded phase nodes showing execution flow
- **Run Metrics**: Tokens, cost, duration, and status tracking
- **Task Details**: Per-task breakdown with LLM provider, tokens, and cost
- **Auto-Refresh**: Updates every 10 seconds automatically
- **Zero Build Step**: Pure HTML/CSS/JavaScript with no npm or build tools

## Quick Start

### 1. Start the Dashboard Server

```bash
# Using default settings (port 8080, ./runs directory)
python -m abi_observability.dashboard

# Custom port
python -m abi_observability.dashboard --port 8000

# Custom runs directory
python -m abi_observability.dashboard --runs-dir /path/to/runs
```

### 2. Open Your Browser

Navigate to: `http://localhost:8080`

### 3. View Your Pipeline Runs

The dashboard will automatically display all run evidence packs from the `runs/` directory.

## Demo

Run the demo script to generate sample data and launch the dashboard:

```bash
python examples/demo_dashboard/run_demo.py
```

This creates:
- A successful multi-phase run (PLANNING → BUILD → TEST)
- A failed run with error details
- A running (incomplete) run

## API Endpoints

### `GET /api/health`

Health check endpoint.

**Response:**
```json
{
  "status": "ok",
  "service": "abi-observability-dashboard"
}
```

### `GET /api/runs`

List recent pipeline runs.

**Query Parameters:**
- `limit` (optional): Maximum number of runs to return (default: 50)

**Response:**
```json
{
  "runs": [
    {
      "run_id": "demo-success-001",
      "status": "success",
      "total_events": 16,
      "total_tokens": 5700,
      "total_cost": 0.0855,
      "started_at": "2025-01-15T10:00:00Z",
      "completed_at": "2025-01-15T10:00:22Z"
    }
  ],
  "total": 1
}
```

### `GET /api/runs/{run_id}`

Get detailed information about a specific run.

**Response:**
```json
{
  "run_id": "demo-success-001",
  "status": "success",
  "total_events": 16,
  "total_spans": 1,
  "total_tokens": 5700,
  "total_cost": 0.0855,
  "duration_ms": 22000,
  "started_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:00:22Z",
  "phases": [
    {
      "name": "PLANNING",
      "status": "completed",
      "started_at": "2025-01-15T10:00:01Z",
      "completed_at": "2025-01-15T10:00:06Z",
      "duration_ms": 5000
    }
  ]
}
```

### `GET /api/runs/{run_id}/tasks`

Get per-task details for a run.

**Response:**
```json
{
  "run_id": "demo-success-001",
  "tasks": [
    {
      "task_id": "task-plan-1",
      "phase": "PLANNING",
      "llm_provider": "anthropic",
      "status": "completed",
      "tokens": 2500,
      "cost": 0.0375,
      "duration_ms": 3000,
      "started_at": "2025-01-15T10:00:02Z",
      "completed_at": "2025-01-15T10:00:05Z"
    }
  ],
  "total": 1
}
```

## Data Source

The dashboard reads run evidence packs from the `runs/` directory. Each run should have:

- `events.ndjson` - Event stream (required)
- `spans.ndjson` - Span traces (optional)
- `manifest.json` - Run metadata (optional)
- `summary.json` - Pre-computed summary (optional)

### Example Directory Structure

```
runs/
├── evidence_pack_demo-success-001/
│   ├── events.ndjson
│   ├── spans.ndjson
│   ├── manifest.json
│   └── summary.json
└── evidence_pack_demo-failed-002/
    ├── events.ndjson
    └── spans.ndjson
```

## Status Indicators

### Run Status
- **Success** (green): Run completed successfully
- **Failed** (red): Run failed or circuit breaker tripped
- **Running** (blue, pulsing): Run in progress
- **Unknown** (yellow): Status cannot be determined

### Phase Status
- **Completed** (green, glowing): Phase finished successfully
- **Running** (blue, animated): Phase currently executing
- **Waiting** (yellow): Phase queued
- **Failed** (red, glowing): Phase encountered errors

## Architecture

### Components

1. **`data_source.py`**: Reads and parses run evidence packs
2. **`dashboard_api.py`**: HTTP server with API endpoints
3. **`static/index.html`**: Interactive web dashboard
4. **`__main__.py`**: CLI entry point

### Design Principles

- **Zero External Dependencies**: Uses only Python standard library
- **Offline-First**: No network calls, works in air-gapped environments
- **Deterministic**: Reads from immutable evidence packs
- **Fast**: Lightweight server with minimal overhead

## Testing

Run the dashboard tests:

```bash
python -m pytest tests/test_dashboard.py -v
```

All 15 dashboard tests should pass:
- 9 `RunDataSource` tests (data layer)
- 6 `DashboardServer` tests (API endpoints)

## Troubleshooting

### Dashboard shows "No runs found"

**Cause**: The `runs/` directory is empty or doesn't exist.

**Solution**:
1. Run the demo: `python examples/demo_dashboard/run_demo.py`
2. Or create run evidence packs in `./runs/`

### Port already in use

**Cause**: Another process is using port 8080.

**Solution**: Use a different port:
```bash
python -m abi_observability.dashboard --port 8081
```

### Cannot connect to server

**Cause**: Firewall blocking localhost connections.

**Solution**: Check firewall settings and ensure localhost (127.0.0.1) is allowed.

### Static files not loading

**Cause**: The `static/index.html` file is missing.

**Solution**: Ensure the package is properly installed or run from the source directory.

## Development

### Adding New Metrics

To add new metrics to the dashboard:

1. Update `RunDataSource` to extract the metric from events
2. Add the metric to API response in `dashboard_api.py`
3. Update the HTML template to display the metric
4. Add tests in `test_dashboard.py`

### Customizing the UI

Edit `static/index.html` to customize:
- Colors and theme (CSS section)
- Layout and components (HTML structure)
- Auto-refresh interval (JavaScript, currently 10s)
- Pipeline visualization (phase node styling)

## Future Enhancements

Potential improvements:
- WebSocket support for real-time updates
- Filtering and search functionality
- Drill-down into individual events
- Export run data as CSV/JSON
- Compare multiple runs side-by-side
- Cost optimization recommendations
