Skip to main content
Version: 0.2

Features Overview

This page describes what the app can do, in plain language. Each section covers what it looks like for the user, why it exists, and how it works under the hood.

1. Signing In and Your Profile​

What you see​

A small avatar button in the top-right corner of the page. If you're not signed in, it shows a person silhouette. After signing in, it shows your profile picture (from GitHub or Google) or your first initial.

Clicking it opens a dropdown panel with:

  • Sign-in form (email + password)
  • OAuth buttons for GitHub and Google
  • Profile card (when signed in) with your name, email, avatar, and a Sign out button

Clicking anywhere outside the dropdown closes it. Pressing the x in the corner also closes it.

Why it exists​

The app has two modes: signed-in (your real data, your projects, live streaming) and offline (the 3D brain still runs without a server connection). The avatar button is the single entry point for managing your session across both modes.

How it works​

  • src/auth/gate.ts owns the avatar button and dropdown container
  • src/ui/signin-view.ts owns the form content inside the dropdown
  • Your session is stored in Supabase Auth (the same backend that powers your data)
  • If Supabase is unavailable, the gate is bypassed entirely and the app runs on its simulation mode

2. The Observability Panel ("Trace Ingestion")​

What you see​

A dedicated Observability activity-bar page with:

  • A file drop zone: drag and drop a .json trace file to import it
  • Three buttons: Load sample trace, View traces, Go live
  • A project switcher dropdown (if you have multiple projects)
  • A summary tile showing recent cost, tokens, error rate, and latency percentiles

Why it exists​

This is where you bring AI agent execution data (called "traces" and "spans") into the visualizer. Traces are the raw record of what your AI did: every LLM call, tool execution, retrieval step, etc.

How it works​

  • Trace files follow the OpenInference or OTLP format (industry standards from Arize Phoenix and OpenTelemetry)
  • After import, the data is written to Supabase (your cloud database) and the 3D brain can replay it
  • The summary tile calculates cost using a price book of model token rates (e.g., GPT-4o mini at $X per million tokens)
  • The panel is mounted into the Observability workbench view, not the Chat area, so the chat keeps its full height

3. Live Mode: Real-Time Brain Streaming​

What you see​

Click Go live and the button switches to Stop live and shows a running count like Stop live (42). New execution spans from your AI agents stream into the 3D brain in real time, and the brain animates as each span arrives.

Why it exists​

Instead of importing a file after the fact, you can watch your AI agents work in real time. If an agent is running a long task (e.g., a RAG pipeline processing documents), you see the brain light up as each step completes.

How it works​

  • The app subscribes to a Supabase Realtime channel: think of it as a live feed from your database
  • When a new span is inserted into the spans table, the channel fires an event
  • Spans arrive in bursts, so they're aggregated into 250ms windows (this prevents the brain from being overwhelmed: even thousands of spans per second collapse into at most 5 stimuli per window)
  • Each span maps to a brain region based on its kind: LLM calls → language regions, tool calls → attention regions, retrieval → visual regions, errors → auditory alarm
  • Project switching: If you're live and switch to a different project, the bridge automatically stops and restarts for the new project
  • Auto-start: If you're signed in and the brain is ready, live mode starts automatically on page load

Technical notes​

  • The Realtime channel filters by project_id so you only see your active project's spans
  • The spans table must be enabled in Supabase's Realtime publication (already configured)
  • If Supabase is unavailable, live mode silently disables itself: the brain still works on simulation

4. Replay: Animate Past Traces​

What you see​

After importing a trace file, click View traces to open the trace list. Click any trace row to see a waterfall timeline of its spans, then click Replay to watch the 3D brain animate through the spans in chronological order.

Why it exists​

Replay lets you visually "re-experience" what an AI agent did: you can see where errors lit up alarm regions, where heavy LLM calls saturated the language areas, and how long each step took relative to the whole.

How it works​

  • Each span has a start_time and latency_ms
  • The replay engine maps time proportionally: a 100ms span gets a short stimulus, a 2-second span gets a long one
  • Spans with ERROR status get higher intensity and route to the auditory alarm region
  • The replay is cancellable: click away or switch traces mid-replay to stop it cleanly
  • Multiple traces with the same session can be replayed in sequence

5. Project Switcher​

What you see​

A dropdown in the observability panel header showing the active project name. Click to pick from a list of all your projects.

Why it exists​

Each project is a separate AI agent (or pipeline) you're monitoring. You might have a "RAG agent" project, a "customer support bot" project, etc. Switching projects changes which data the observability panel and live bridge focus on.

How it works​

  • Projects are stored in the projects table in Supabase
  • The switcher subscribes to project state changes and notifies the rest of the app when the active project changes
  • The summary tile, trace list, cost calculations, and live bridge all re-query for the new project
  • If you're in live mode when you switch, the Realtime subscription automatically reconnects to the new project's channel

6. Cost and Performance Summary​

What you see​

A compact tile showing:

  • Cost: estimated dollars spent on LLM tokens (based on a price book of model rates)
  • Tokens: total prompt + completion tokens consumed
  • Traces: number of agent runs recorded
  • Error rate: percentage of traces that ended in error
  • P50 / P95 latency: median and 95th percentile response times

A "+" suffix (e.g., 1000+) means the tile hit its sample cap and the true value is higher.

Why it exists​

You need at-a-glance health metrics without digging into individual traces. This tile answers: "Is my agent expensive? Is it slow? Is it breaking?"

How it works​

  • Calculates cost by matching each span's llm_model + token_count_prompt/token_count_completion against a price book from the token_prices table
  • Error rate counts traces with status_code = 'ERROR'
  • Latency percentiles use the p50/p95 of trace durations
  • Uses a bounded window of the most recent 1,000 spans/traces to keep the tile fast regardless of project size

7. Live AI Chat​

What you see​

The Chat tab in the left panel behaves like a real assistant. It streams an answer token by token, keeps a local transcript, and shows feedback controls on assistant messages after the answer is saved. The chat header includes a dark, searchable 9Router-backed model picker grouped by provider, and each assistant message shows the provider/model that produced it.

Why it exists​

The chat turns the visualizer into an interactive assistant for explaining the current simulation state, discussing trace behavior, and testing the same API routing path that production chat clients can use.

How it works​

  • The browser calls Supabase Edge Functions, not the 9Router API directly
  • 9Router credentials live only in Edge Function secrets
  • The run-chat?models=1 path discovers available models from 9Router and returns sanitized model metadata for the picker
  • The picker is custom app UI, not a native browser select; it supports search, provider grouping, variant badges, keyboard navigation, and outside-click dismissal
  • The run-chat function streams model output back to the UI and writes a Phoenix/OpenInference-style trace and LLM span for every turn
  • The chat-feedback function writes thumbs feedback as user_feedback annotations on the assistant span

8. The 3D Brain​

What you see​

A living, animated 3D brain in the center of the page. It pulses with color when stimuli arrive (from traces, live mode, or the built-in simulation). The camera can orbit, zoom, and be repositioned.

Why it exists​

This is the app's signature view: a spatial metaphor for "what is the AI thinking right now." Different brain regions represent different kinds of computation: language (LLM calls), visual (retrieval/embedding), attention (tool use), and auditory (errors/alarms).

How it works​

  • Built with Three.js (WebGL) and a WebAssembly physics simulation (Rust compiled to WASM via rust/web-brain-wasm)
  • The brain is a grid of "cells" that each have an internal state (charge, decay, etc.)
  • Stimuli are injected via neuralNet.injectStimulus({ type, intensity, durationMs })
  • The brain runs on its own requestAnimationFrame loop: it's always alive, even without data
  • A lil-gui panel in the bottom-left lets you tweak simulation parameters in real time

9. Trace List and Waterfall Views​

What you see​

Trace list: A grid of all imported traces, sortable by time, latency, status, and model. Each row shows the trace name, duration, and status badge.

Waterfall: Click a trace to see a horizontal timeline of its spans, styled like a Gantt chart. Click any span to open a detail drawer showing its attributes, token counts, cost, and any annotations.

Why it exists​

This is the deep-dive view for when you need to understand exactly what happened in an agent run: which tools it called, which LLM model it used, how many tokens it spent, and where errors occurred.

How it works​

  • Traces and spans are fetched from Supabase via the DAL (Data Access Layer)
  • The waterfall uses span.start_time and span.latency_ms to position each block on the timeline
  • Color coding: green for OK, red for ERROR, amber for slow spans
  • Span details include JSON-blob attributes (the raw OpenInference data)

10. Error Reporting and Diagnostics​

What you see​

A small diagnostics log panel (accessible via keyboard shortcut or the UI) showing any errors the app encountered: failed imports, network issues, etc.

Why it exists​

The app is designed to never crash. If something fails (e.g., Supabase is down), it degrades gracefully and logs what happened. The diagnostics panel is where you go to find out why something didn't work as expected.

How it works​

  • Every DAL call returns a Result<T>: either { ok: true, value } or { ok: false, error }: instead of throwing
  • Errors are funneled through reportError() which routes them to the diagnostics logger
  • The logger preserves error codes (e.g., supabase.select_failed), context (which query, which project), and stack traces

11. Offline Mode​

What you see​

The app loads and the 3D brain runs even if Supabase is unavailable (no internet, Docker not running, self-hosted instance down).

Why it exists​

The brain's simulation mode doesn't require a backend. You can still interact with it, tweak parameters, and watch the simulation: you just can't import traces, go live, or manage projects.

How it works​

  • isSupabaseConfigured() checks if .env has the required URL and anon key
  • If missing, the observability panel shows "Supabase: not configured"
  • The auth gate is bypassed: you skip straight to the app
  • All DAL calls return supabase.not_configured errors instead of failing

What's Coming​

These features are designed and planned but not yet live:

FeatureStatusPlan
OTLP HTTP receiver (ingest spans via API)DesignedPlan 007 Phase 6
Evaluator framework (automated scoring of agent outputs)DAL readyPlan 007 Phase 7
Live AI Chat with feedback annotationsLive9Router + Supabase Edge Functions
Annotation system (human + LLM annotations on spans)Live for chat feedback; evaluator annotations use identifiersPhoenix-style annotations
Typesense federated search (search across all projects)Live: Plan 008 completeTypesense Cloud
Session grouping (group related traces into sessions)DAL readyPlan 007 Phase 4