diff options
Diffstat (limited to 'docs/web_gui_plan.md')
| -rw-r--r-- | docs/web_gui_plan.md | 170 |
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 |