Merge branch 'feature/web-gui'

1 files changed, 170 insertions, 0 deletions

diff --git a/docs/web_gui_plan.md b/docs/web_gui_plan.md
new file mode 100644
index 0000000..f43b0d0
--- /dev/null
+++ b/docs/web_gui_plan.md
@@ -0,0 +1,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