VRE Workstation — interactive graph exploration UI

[anormang1992]

Summary

Build a local web-based UI (the "VRE Workstation") that allows users to interactively explore the epistemic graph — clicking nodes to inspect depths and relata, creating edges via drag-and-connect, tailing live trace activity, viewing and defining policies, and managing VRE networks. Launched via a new CLI command.

Problem Statement

The epistemic graph is currently operable only through code — the Python API, seed scripts, and the policy wizard CLI. There is no visual way to:

• Explore the graph structure and understand how concepts relate
• Inspect a node's depth levels, properties, and relata at a glance
• Navigate relata as links to connected nodes
• Watch grounding activity in real time as the agent operates
• Define or modify policies on relata

For graph authors and integrators, this means understanding the graph requires reading Neo4j queries or printing EpistemicResult objects. For users reviewing agent behavior, there is no way to see what the agent knew (or didn't know) at a given point in time without parsing raw trace data.

Proposed Solution

A lightweight local web application served by FastAPI with WebSocket support:

Graph Visualization

• Interactive node-link diagram of the epistemic graph
• Nodes represent primitives; edges represent relata
• Visual encoding of depth levels (e.g. color intensity, node size) and provenance source
• WebSocket-driven live updates: nodes "light up" in real time when the graph is queried during agent operation, giving users a live view of epistemic activity

Node Inspector Panel

• Click a node to reveal a detail panel showing:
  • All depth levels with their properties
  • All relata (incoming and outgoing) with type, depth annotations, and links to target/source nodes
  • Provenance metadata per depth and relatum
  • Aggregate usage metrics (grounding counts, failure counts, last exercised) per Add aggregate usage metrics to Primitive nodes #35

Edge Creation

• Drag-and-connect interaction to propose new relata between nodes
• Form to specify relation type, source depth, and target depth
• Persists to the graph via the repository layer

Live Trace Viewer

• Tails the current day's JSONL trace log in real time via WebSocket
• Each trace entry is a single-line summary: concepts queried, gaps encountered, learning outcomes, grounding result
• Option to retrieve and browse previous days' trace files when available
• Filtering by concept, result type, date

Policy Management

• View policies attached to APPLIES_TO relata
• Define new policies or modify existing ones through a form interface
• Policy evaluation dry-run against current graph state

CLI Launch

• New CLI command (e.g. vre workstation or vre ui) to start the local server
• Configurable port, optional browser auto-open

Architecture

• Backend: FastAPI with WebSocket endpoints for live graph activity and trace tailing
• Frontend: lightweight SPA (technology TBD — could be vanilla JS, htmx, or a small framework)
• Local-only: serves on localhost, no authentication required, no cloud dependency
• Read-write: the workstation can modify the graph (edge creation, policy definition) through the same repository interface the engine uses
• Prerequisite for VRE Networks: the workstation will serve as the management interface for VRE network configuration and monitoring

VRE Design Alignment

• Inspectability: CLAUDE.md Section 8 lists inspectability as the first optimization criterion. A visual UI with live activity is the most direct expression of this value.
• Epistemic honesty made visible: The workstation makes the agent's knowledge boundaries tangible — users can see exactly what the agent knows, at what depth, and why, in real time.
• No VRE contract changes: The workstation is a UI layer over existing APIs. It does not modify the grounding contract, policy evaluation, or learning loop.
• Minimal footprint: FastAPI + a lightweight frontend adds minimal dependencies. The UI is local-only and infrastructure-free.

Acceptance Criteria

• FastAPI application with WebSocket support, launched via CLI command
• Graph visualization displaying all primitives and relata
• WebSocket-driven node highlighting when concepts are queried in real time
• Node click reveals detail panel with depths, properties, relata (as navigable links), and provenance
• Drag-and-connect edge creation with relation type and depth annotation
• Live trace viewer tailing current day's JSONL with WebSocket updates
• Option to load and browse previous days' trace logs
• Policy viewer displaying policies on APPLIES_TO relata
• Policy creation/modification form
• Aggregate metrics displayed per node (when available)
• Works with both Neo4j and future repository backends

Open Questions

• What frontend technology? htmx keeps it simple and server-rendered; a JS framework (Svelte, React) enables richer interactivity but adds build complexity
• Should the graph visualization use a specific library (e.g. d3-force, cytoscape.js, vis.js)?
• Should the workstation support graph seeding/import (e.g. upload a seed script or JSON)?
• Should there be a read-only mode for safe exploration vs. a write mode for graph authoring?
• What WebSocket message format for live graph activity — just node IDs that were touched, or richer event payloads?

Dependencies

• Persist grounding traces to daily JSONL files #34 (Persist grounding traces to JSONL) — required for the trace viewer
• Add aggregate usage metrics to Primitive nodes #35 (Aggregate usage metrics on primitives) — required for per-node metric display
• Policy system (existing) — already implemented, workstation provides UI over it