1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
# Web GUI Implementation Plan
## Overview
A lightweight, decoupled web interface for the AI Agent Reasoning Experiment Framework. The goal is to allow non-technical users (e.g., supervisors, dissertation examiners) to understand and interact with the project without using the CLI.
**Core Principle**: Keep it fast, reactive, and modular. No bloat. The GUI is a separate layer that wraps the existing core project without modifying it.
---
## Architecture
### Decoupled Design
```
┌─────────────────────────────────────────────────────────────┐
│ Web GUI (Frontend) │
│ Modular ES6 Vanilla JS + HTML + Chart.js │
└────────────────────────────┬────────────────────────────────┘
│ HTTP / SSE
┌────────────────────────────▼────────────────────────────────┐
│ FastAPI Backend (API) │
│ api/server.py (new, separate) │
│ - Wraps core functions (ConfigLoader, run_from_config) │
│ - Exposes endpoints for scenarios, models, runs, logs │
└────────────────────────────┬────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────┐
│ Core Project (Unchanged) │
│ - src/main.py, src/judge_runner.py │
│ - config.yaml, scenarios/, logs/ │
└─────────────────────────────────────────────────────────────┘
```
### Why This Approach?
1. **Zero Changes to Core**: The dissertation code remains untouched and pure.
2. **Modular Frontend**: Splitting JS and CSS into logical components prevents a monolithic file structure, making future expansions (like new charts) effortless.
3. **No Build Step**: Native ES6 modules mean no Webpack or React overhead.
4. **Showcase-Ready**: Clean, dark-themed "Control Room" dashboard for non-technical users.
---
## File Structure
```
dissertation/
├── api/ # New API layer
│ ├── __init__.py
│ ├── server.py # FastAPI application
│ ├── endpoints/
│ │ ├── __init__.py
│ │ ├── config.py # Config read/write endpoints
│ │ ├── scenarios.py # Scenario discovery endpoints
│ │ ├── runs.py # Experiment run triggers
│ │ └── results.py # Results/logs fetching
│ └── static/ # Frontend (served by FastAPI)
│ ├── index.html # Main DOM
│ ├── css/ # Modular CSS (base, layout, components, etc.)
│ └── js/ # ES6 Modules
│ ├── main.js # Entry point
│ ├── api.js # API wrapper
│ ├── ui.js # Global DOM utilities
│ └── components/ # Specific feature logic (results, config, terminal)
│
├── src/ # Core project (UNCHANGED)
│ ├── main.py
│ ├── runner.py
│ ├── config_loader.py
│ └── ...
│
├── docs/
│ └── web_gui_plan.md # This file
│
└── config.yaml
```
---
## API Endpoints
### 1. Configuration & Discovery (Removed)
*Note: In v0.2.0, the GUI was pivoted to a pure Data Visualization Dashboard. Execution logic (triggering runs, stopping runs, tailing live logs, and configuration editing) has been removed to keep the interface focused on analysis.*
### 2. Results & Analysis
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/results/files`| List all CSV files in the logs directory |
| GET | `/api/results` | Get experiment results (CSV data as JSON), accepts `?file=` |
| GET | `/api/results/images` | List generated visualization images |
| GET | `/api/results/images/{name}` | Serve a specific image |
| GET | `/api/judge/files`| List all judge reports in the configured log directory |
| GET | `/api/judge/results` | Get judge results as JSON, accepts `?file=` |
---
## Implementation Steps
### Phase 1: Backend (FastAPI)
1. **Setup**: Add `fastapi`, `uvicorn` to dependencies (via `uv add`)
2. **Server**: Create `api/server.py` with basic FastAPI app
3. **Data Serving**: Read CSV/JSON files dynamically based on URL queries.
4. **Token Usage**: The CSV data includes token metrics that were injected during the run or post-processed.
### Phase 2: Frontend (Vanilla ES6)
1. **Static Architecture**: Implement a modular JS structure (`js/components/`).
2. **Dashboard Layout**: Fixed left sidebar for global filtering, main viewport for data analysis.
3. **Aesthetics**: "Industrial Control Room" dark theme (high contrast, sans-serif UI).
4. **Interactive Visualizations**: Integrate `Chart.js` to dynamically generate pie, bar, and stacked bar charts from CSV data endpoints.
5. **Chart Zooming**: Implement a full-screen modal overlay for examining charts closely.
### Phase 3: Integration & Polish
1. **Auto-discovery**: Ensure new scenarios and result files populate dropdowns automatically.
2. **Data Parsing**: Ensure long text fields (like judge justifications) wrap nicely in tables.
3. **Global Filters**: Add checkbox filtering to slice data by Model, Scenario, and Oversight level dynamically on the frontend.
4. **Chart Cleanup**: Ensure the Chart.js instances are destroyed and re-created cleanly when switching data sources or filters.
---
## Dependencies
Backend dependencies added via `uv`:
```toml
[dependencies]
fastapi = ">=0.115.0"
uvicorn = {extras = ["standard"], version = ">=0.32.0"}
```
*(sse-starlette was removed as live log streaming is no longer required)*
Frontend uses `Chart.js` via CDN. No other external dependencies are required.
---
## Running the GUI
```bash
# Start the API server
uv run api/server.py
# Open in browser
# http://localhost:8000
```
---
## Features Implemented
- [x] Pure Data Visualization Dashboard
- [x] High-contrast Dark Mode ("Control Room" aesthetic)
- [x] Dynamic File Selection for CSV/Judge Reports
- [x] Multi-select Checkbox Global Filters (Model, Scenario, Oversight)
- [x] Interactive Chart.js Visualizations (Deception Rates, Categories)
- [x] Average & Total Token Usage Visualizations (Prompt vs Completion)
- [x] Click-to-Zoom interactive charts (Modal overlay)
- [x] Responsive data tables with word-wrapping
- [x] Modular ES6 Javascript (No build step)
---
## Author
Created: March 2026
Purpose: Dissertation showcase for AI Agent Reasoning Experiment Framework
|
