# millerharry/steerscope architecture

> Architecture diagram of the GitHub repository millerharry/steerscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/millerharry/steerscope
- Repository: https://github.com/millerharry/steerscope

## Overview

Steerscope is an interactive browser-based model-interpretability demo: a prompt and steering settings drive token generation, while per-layer predictions form a decision ladder and the continuation streams into the UI. The checked-in demo currently uses a labeled simulation engine; the README describes real-model and instrumented-ONNX tracks as planned integration. An offline Python pipeline computes steering directions, evaluates their effects, and exports the instrumented graph. Several UI and pipeline relationships below are documented in the README; unsampled implementations are not assumed to be wired at runtime.

Main entry points: [`lib/inference/simEngine.ts`](https://github.com/millerharry/steerscope/blob/main/lib/inference/simEngine.ts) (Preview engine), [`lib/store.ts`](https://github.com/millerharry/steerscope/blob/main/lib/store.ts) (Demo state), [`app/page.tsx`](https://github.com/millerharry/steerscope/blob/main/app/page.tsx) (Home page), [`pipeline/compute_steering.py`](https://github.com/millerharry/steerscope/blob/main/pipeline/compute_steering.py) (Steering extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_home["Home page<br/>[page.tsx]"]
  node_demo["Interactive demo<br/>[Demo.tsx]"]
  node_prompt["Prompt controls<br/>[PromptBar.tsx]"]
  node_steering_ui["Steering sliders<br/>[SteeringPanel.tsx]"]
  node_ladder["Prediction ladder<br/>[LensLadder.tsx]"]
  node_lens_detail["Lens detail<br/>[LensDetail.tsx]"]
  node_token_stream["Token stream<br/>[TokenStream.tsx]"]
  node_load_overlay["Load overlay<br/>[LoadOverlay.tsx]"]
  node_backend_badge["Backend status<br/>[BackendBadge.tsx]"]
  node_hero["Introduction<br/>[Hero.tsx]"]
  node_how_it_works["How it works<br/>[HowItWorks.tsx]"]
  node_status["Project status<br/>[Status.tsx]"]
  node_footer["Footer<br/>[Footer.tsx]"]
  node_reveal["Reveal animation<br/>[reveal.tsx]"]
end

subgraph group_runtime["Inference runtime"]
  node_store["Demo state<br/>[store.ts]"]
  node_engine_factory["Engine factory<br/>[engine.ts]"]
  node_sim_engine["Preview engine<br/>[simEngine.ts]"]
  node_scenarios["Prompt scenarios<br/>[scenarios.ts]"]
  node_backend_detection["Backend detection<br/>[backend.ts]"]
  node_contracts["Inference contracts<br/>[types.ts]"]
end

subgraph group_math["Lens and steering math"]
  node_lens_math["Logit lens math<br/>[logitLensCpu.ts]"]
  node_steering_math["Steering composition<br/>[steering.ts]"]
  node_heatmap["Heatmap scale<br/>[heat.ts]"]
end

subgraph group_pipeline["Model pipeline"]
  node_contrast_sets["Contrast prompt sets<br/>[contrast_sets.py]"]
  node_shared_model["Model conventions<br/>[qwen_common.py]"]
  node_reference_math["Numpy reference math<br/>[refmath.py]"]
  node_steering_compute["Steering extraction"]
  node_steering_eval["Steering evaluation<br/>[eval_steering.py]"]
  node_onnx_export["Instrumented ONNX export<br/>[export_model.py]"]
end

node_visitor(("Visitor"))
node_model["Qwen instruct model"]

node_visitor -->|"opens"| node_home
node_home -->|"renders"| node_hero
node_home -->|"renders"| node_demo
node_home -->|"renders"| node_how_it_works
node_home -->|"renders"| node_status
node_home -->|"renders"| node_footer
node_hero -->|"uses"| node_reveal
node_how_it_works -->|"uses"| node_reveal
node_status -->|"uses"| node_reveal
node_visitor -->|"enters prompt"| node_prompt
node_visitor -->|"sets coefficients"| node_steering_ui
node_demo -.->|"drives demo state"| node_store
node_prompt -.->|"updates prompt"| node_store
node_steering_ui -.->|"updates steering"| node_store
node_store -->|"detects capabilities"| node_backend_detection
node_store -->|"creates engine"| node_engine_factory
node_engine_factory -->|"returns preview"| node_sim_engine
node_sim_engine -->|"matches prompts"| node_scenarios
node_sim_engine -->|"reads behavior limits"| node_steering_math
node_sim_engine -->|"implements contract"| node_contracts
node_store -->|"uses data types"| node_contracts
node_store -->|"uses behavior types"| node_steering_math
node_sim_engine -.->|"emits layer predictions"| node_ladder
node_sim_engine -.->|"streams tokens"| node_token_stream
node_ladder -.->|"shows layer details"| node_lens_detail
node_steering_ui -.->|"regenerates output"| node_sim_engine
node_backend_detection -.->|"reports backend"| node_backend_badge
node_lens_math -.->|"computes layer reads"| node_ladder
node_steering_math -.->|"composes steering"| node_sim_engine
node_contrast_sets -->|"supplies contrasts"| node_steering_compute
node_shared_model -->|"provides model config"| node_steering_compute
node_reference_math -->|"provides CAA math"| node_steering_compute
node_shared_model -->|"provides model config"| node_onnx_export
node_shared_model -->|"provides evaluation config"| node_steering_eval
node_reference_math -.->|"validates parity"| node_lens_math
node_steering_compute -.->|"supplies steering vectors"| node_onnx_export
node_model -.->|"provides activations"| node_steering_compute
node_model -.->|"is evaluated"| node_steering_eval
node_model -.->|"is instrumented"| node_onnx_export
node_heatmap -.->|"colors predictions"| node_ladder

click node_home "https://github.com/millerharry/steerscope/blob/main/app/page.tsx"
click node_demo "https://github.com/millerharry/steerscope/blob/main/components/demo/Demo.tsx"
click node_prompt "https://github.com/millerharry/steerscope/blob/main/components/demo/PromptBar.tsx"
click node_steering_ui "https://github.com/millerharry/steerscope/blob/main/components/demo/SteeringPanel.tsx"
click node_ladder "https://github.com/millerharry/steerscope/blob/main/components/demo/LensLadder.tsx"
click node_lens_detail "https://github.com/millerharry/steerscope/blob/main/components/demo/LensDetail.tsx"
click node_token_stream "https://github.com/millerharry/steerscope/blob/main/components/demo/TokenStream.tsx"
click node_load_overlay "https://github.com/millerharry/steerscope/blob/main/components/demo/LoadOverlay.tsx"
click node_backend_badge "https://github.com/millerharry/steerscope/blob/main/components/demo/BackendBadge.tsx"
click node_hero "https://github.com/millerharry/steerscope/blob/main/components/sections/Hero.tsx"
click node_how_it_works "https://github.com/millerharry/steerscope/blob/main/components/sections/HowItWorks.tsx"
click node_status "https://github.com/millerharry/steerscope/blob/main/components/sections/Status.tsx"
click node_footer "https://github.com/millerharry/steerscope/blob/main/components/sections/Footer.tsx"
click node_reveal "https://github.com/millerharry/steerscope/blob/main/components/ui/reveal.tsx"
click node_store "https://github.com/millerharry/steerscope/blob/main/lib/store.ts"
click node_engine_factory "https://github.com/millerharry/steerscope/blob/main/lib/inference/engine.ts"
click node_sim_engine "https://github.com/millerharry/steerscope/blob/main/lib/inference/simEngine.ts"
click node_scenarios "https://github.com/millerharry/steerscope/blob/main/lib/inference/scenarios.ts"
click node_backend_detection "https://github.com/millerharry/steerscope/blob/main/lib/inference/backend.ts"
click node_contracts "https://github.com/millerharry/steerscope/blob/main/lib/inference/types.ts"
click node_lens_math "https://github.com/millerharry/steerscope/blob/main/lib/inference/logitLensCpu.ts"
click node_steering_math "https://github.com/millerharry/steerscope/blob/main/lib/inference/steering.ts"
click node_heatmap "https://github.com/millerharry/steerscope/blob/main/lib/viz/heat.ts"
click node_contrast_sets "https://github.com/millerharry/steerscope/blob/main/pipeline/contrast_sets.py"
click node_shared_model "https://github.com/millerharry/steerscope/blob/main/pipeline/qwen_common.py"
click node_reference_math "https://github.com/millerharry/steerscope/blob/main/pipeline/refmath.py"
click node_steering_compute "https://github.com/millerharry/steerscope/blob/main/pipeline/compute_steering.py"
click node_steering_eval "https://github.com/millerharry/steerscope/blob/main/pipeline/eval_steering.py"
click node_onnx_export "https://github.com/millerharry/steerscope/blob/main/pipeline/export_model.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_home,node_demo,node_prompt,node_steering_ui,node_ladder,node_lens_detail,node_token_stream,node_load_overlay,node_backend_badge,node_hero,node_how_it_works,node_status,node_footer,node_reveal toneBlue
class node_store,node_engine_factory,node_sim_engine,node_scenarios,node_backend_detection,node_contracts toneAmber
class node_lens_math,node_steering_math,node_heatmap toneMint
class node_contrast_sets,node_shared_model,node_reference_math,node_steering_compute,node_steering_eval,node_onnx_export toneRose
class node_visitor,node_model toneIndigo
```

## Components

### Web experience

- [Home page](https://github.com/millerharry/steerscope/blob/main/app/page.tsx): `app/page.tsx`
- [Interactive demo](https://github.com/millerharry/steerscope/blob/main/components/demo/Demo.tsx): `components/demo/Demo.tsx`
- [Prompt controls](https://github.com/millerharry/steerscope/blob/main/components/demo/PromptBar.tsx): `components/demo/PromptBar.tsx`
- [Steering sliders](https://github.com/millerharry/steerscope/blob/main/components/demo/SteeringPanel.tsx): `components/demo/SteeringPanel.tsx`
- [Prediction ladder](https://github.com/millerharry/steerscope/blob/main/components/demo/LensLadder.tsx): `components/demo/LensLadder.tsx`
- [Lens detail](https://github.com/millerharry/steerscope/blob/main/components/demo/LensDetail.tsx): `components/demo/LensDetail.tsx`
- [Token stream](https://github.com/millerharry/steerscope/blob/main/components/demo/TokenStream.tsx): `components/demo/TokenStream.tsx`
- [Load overlay](https://github.com/millerharry/steerscope/blob/main/components/demo/LoadOverlay.tsx): `components/demo/LoadOverlay.tsx`
- [Backend status](https://github.com/millerharry/steerscope/blob/main/components/demo/BackendBadge.tsx): `components/demo/BackendBadge.tsx`
- [Introduction](https://github.com/millerharry/steerscope/blob/main/components/sections/Hero.tsx): `components/sections/Hero.tsx`
- [How it works](https://github.com/millerharry/steerscope/blob/main/components/sections/HowItWorks.tsx): `components/sections/HowItWorks.tsx`
- [Project status](https://github.com/millerharry/steerscope/blob/main/components/sections/Status.tsx): `components/sections/Status.tsx`
- [Footer](https://github.com/millerharry/steerscope/blob/main/components/sections/Footer.tsx): `components/sections/Footer.tsx`
- [Reveal animation](https://github.com/millerharry/steerscope/blob/main/components/ui/reveal.tsx): `components/ui/reveal.tsx`

### Inference runtime

- [Demo state](https://github.com/millerharry/steerscope/blob/main/lib/store.ts): `lib/store.ts`
- [Engine factory](https://github.com/millerharry/steerscope/blob/main/lib/inference/engine.ts): `lib/inference/engine.ts`
- [Preview engine](https://github.com/millerharry/steerscope/blob/main/lib/inference/simEngine.ts): `lib/inference/simEngine.ts`
- [Prompt scenarios](https://github.com/millerharry/steerscope/blob/main/lib/inference/scenarios.ts): `lib/inference/scenarios.ts`
- [Backend detection](https://github.com/millerharry/steerscope/blob/main/lib/inference/backend.ts): `lib/inference/backend.ts`
- [Inference contracts](https://github.com/millerharry/steerscope/blob/main/lib/inference/types.ts): `lib/inference/types.ts`

### Lens and steering math

- [Logit lens math](https://github.com/millerharry/steerscope/blob/main/lib/inference/logitLensCpu.ts): `lib/inference/logitLensCpu.ts`
- [Steering composition](https://github.com/millerharry/steerscope/blob/main/lib/inference/steering.ts): `lib/inference/steering.ts`
- [Heatmap scale](https://github.com/millerharry/steerscope/blob/main/lib/viz/heat.ts): `lib/viz/heat.ts`

### Model pipeline

- [Contrast prompt sets](https://github.com/millerharry/steerscope/blob/main/pipeline/contrast_sets.py): `pipeline/contrast_sets.py`
- [Model conventions](https://github.com/millerharry/steerscope/blob/main/pipeline/qwen_common.py): `pipeline/qwen_common.py`
- [Numpy reference math](https://github.com/millerharry/steerscope/blob/main/pipeline/refmath.py): `pipeline/refmath.py`
- [Steering extraction](https://github.com/millerharry/steerscope/blob/main/pipeline/compute_steering.py): `pipeline/compute_steering.py`
- [Steering evaluation](https://github.com/millerharry/steerscope/blob/main/pipeline/eval_steering.py): `pipeline/eval_steering.py`
- [Instrumented ONNX export](https://github.com/millerharry/steerscope/blob/main/pipeline/export_model.py): `pipeline/export_model.py`

### Other components

- **Visitor**
- **Qwen instruct model**

## Connections

- Visitor → Home page: opens (evidence: `README.md`)
- Home page → Introduction: renders (evidence: `app/page.tsx`)
- Home page → Interactive demo: renders (evidence: `app/page.tsx`)
- Home page → How it works: renders (evidence: `app/page.tsx`)
- Home page → Project status: renders (evidence: `app/page.tsx`)
- Home page → Footer: renders (evidence: `app/page.tsx`)
- Introduction → Reveal animation: uses (evidence: `components/sections/Hero.tsx`)
- How it works → Reveal animation: uses (evidence: `components/sections/HowItWorks.tsx`)
- Project status → Reveal animation: uses (evidence: `components/sections/Status.tsx`)
- Visitor → Prompt controls: enters prompt (evidence: `README.md`)
- Visitor → Steering sliders: sets coefficients (evidence: `README.md`)
- Interactive demo → Demo state: drives demo state
- Prompt controls → Demo state: updates prompt
- Steering sliders → Demo state: updates steering
- Demo state → Backend detection: detects capabilities (evidence: `lib/store.ts`)
- Demo state → Engine factory: creates engine (evidence: `lib/store.ts`)
- Engine factory → Preview engine: returns preview (evidence: `lib/inference/engine.ts`)
- Preview engine → Prompt scenarios: matches prompts (evidence: `lib/inference/simEngine.ts`)
- Preview engine → Steering composition: reads behavior limits (evidence: `lib/inference/simEngine.ts`)
- Preview engine → Inference contracts: implements contract (evidence: `lib/inference/simEngine.ts`)
- Demo state → Inference contracts: uses data types (evidence: `lib/store.ts`)
- Demo state → Steering composition: uses behavior types (evidence: `lib/store.ts`)
- Preview engine → Prediction ladder: emits layer predictions (evidence: `README.md`)
- Preview engine → Token stream: streams tokens (evidence: `README.md`)
- Prediction ladder → Lens detail: shows layer details (evidence: `README.md`)
- Steering sliders → Preview engine: regenerates output (evidence: `README.md`)
- Backend detection → Backend status: reports backend
- Logit lens math → Prediction ladder: computes layer reads (evidence: `README.md`)
- Steering composition → Preview engine: composes steering (evidence: `README.md`)
- Contrast prompt sets → Steering extraction: supplies contrasts (evidence: `pipeline/compute_steering.py`)
- Model conventions → Steering extraction: provides model config (evidence: `pipeline/compute_steering.py`)
- Numpy reference math → Steering extraction: provides CAA math (evidence: `pipeline/compute_steering.py`)
- Model conventions → Instrumented ONNX export: provides model config (evidence: `pipeline/export_model.py`)
- Model conventions → Steering evaluation: provides evaluation config (evidence: `pipeline/eval_steering.py`)
- Numpy reference math → Logit lens math: validates parity (evidence: `README.md`)
- Steering extraction → Instrumented ONNX export: supplies steering vectors
- Qwen instruct model → Steering extraction: provides activations (evidence: `README.md`)
- Qwen instruct model → Steering evaluation: is evaluated (evidence: `README.md`)
- Qwen instruct model → Instrumented ONNX export: is instrumented (evidence: `README.md`)
- Heatmap scale → Prediction ladder: colors predictions (evidence: `README.md`)
