Spectra Scope

State & Parameter Examination via Captured Traces

Open a transformer and watch its organs work.

Spectra Scope is a model-anatomy inspector. Point it at a transformer and it opens the model up — tokenizer, embeddings, attention, experts, MLP, output head — and shows each stage working on a real prompt, with live traces, honest gauges, and co-operative viewing you can share over the web.

It is not an OpenAI-style chat client. It loads a model in-process and hangs forward hooks on its modules, so what you see is the actual computation: the attention a head paid, the experts a token routed to, the residual stream as it moves layer to layer.

---

🚧 Coming soon — multi-device, engine-tapped

The app is being updated to work across devices — e.g. a model served on multiple DGX Sparks — using vLLM: we are testing a companion plugin that taps the model through its serving engine rather than only in-process. Other engines to come with time.

First artifact published with this lane: GLM-5.3-Flash Internals — a measured profile (attention-sink anatomy, FP8 margins to 260k context, sparse-indexer selection maps) of a 45-layer hybrid MoE captured live on a two-node vLLM serve.

---

What's in the box

Two halves, one repo:

app/	the application	a nine-tab UI (face), a Tauri 2 desktop shell, and a Rust collab-server that serves the face and relays co-op sessions
hooks/	the trace engine	a FastAPI service that loads a model, attaches capture taps, and serves the traces the app reads

The face talks to the engine over a single URL (SPECTRA_ENGINE_URL) — so the UI and the model can live on different machines. Nothing is hardcoded to a host; every operator path is an environment variable with a sane default.

The nine tabs walk the model from input to output: Tokenizer · Embeddings · Attention · Experts · MLP · Output · System · Notebook · Options. A transport bar scrubs the run token by token; every tab re-renders at the scrubbed position.

There's also an AI seat — a drawer where any OpenAI-compatible model can read the live trace (the tab you're on, the token you've scrubbed to, each panel's own summary) and explain it in plain language. Point it at a local or hosted endpoint; it's model-agnostic by design.

📖 How it actually works: docs/HOW_IT_WORKS.md is the deep guide — every hook and sidecar and what it brings, why the options are shaped the way they are, and the do's and don'ts that keep a run from breaking or wedging the machine. It doubles as the operating manual for the AI seat, so a connected model can read it as ground truth.

---

Model support & honest limitations

Spectra Scope's whole ethos is gauges that don't lie — so here is exactly what it does and doesn't do today.

Architectures — dense and MoE, and it knows the difference. The taps read the model's config and adapt. On a Mixture-of-Experts model the Experts tab shows real routing — which experts each token was sent to, per-layer load. On a dense model there are no experts, and the Experts lane says so plainly ("config declares no experts (dense)") rather than inventing them. Absent is reported as absent.

Tested on. The hooks have been exercised end-to-end on:

family	dense	MoE
Gemma 3/4	—	✓ (128 experts)
Qwen 3 / 3.5	✓ (up to 64 layers)	✓ (256 experts)

Other HuggingFace transformers in the same mold are expected to work — the taps key off standard config fields, not per-model special-casing — but "expected" is not "verified," and only the families above have actually been run.

Where it runs, and where it doesn't — yet. Spectra Scope was built and tested on a single NVIDIA DGX Spark (one unified-memory device). The taps are in-process forward hooks, so what matters is whether the model lives in one process. Three cases, told straight:

• One device — tested. The model loads onto a single GPU (or CPU) and the taps hook it in-process. This is the path actually exercised in development.

• One machine, several GPUs — should work, untested. The hooks are process-local: they fire on the model's modules no matter which GPU inside a single machine holds them. A model spread across several GPUs in one box should inspect fine — it simply hasn't been verified, because the development hardware was a single-device Spark. This is expected to work; it just wasn't testable here.

• Multiple machines — not supported today. When a model is split across two or more hosts (e.g. tensor-parallel across a pair of Sparks), the current app cannot span the nodes: the hooks run in one process on one host and can't reach the rank on another. This is not fundamentally impossible — it's a limitation of the app as it stands, not of the idea.

So: what fits one machine is what you can inspect. A checkpoint large enough that it only loads by splitting across several hosts is out of reach for now.

---

Requirements

• Python 3.10+ (for the engine)
• Rust / Cargo (for the collab-server and the desktop shell)
• Node.js 18+ (only if you build the Tauri desktop app)
• A local model in HuggingFace format to inspect (any size that fits your device). An NVIDIA GPU is optional — the engine runs on CPU too, just slower.

---

Install

git clone https://github.com/Zek-Takai/spectra-scope.git spectra-scope
cd spectra-scope

# Python engine environment (creates ./venv and installs requirements.txt)
scripts/setup.sh

Torch note. setup.sh installs torch first. On a plain x86 CUDA box the default wheel is right. On other platforms, point it at the matching CUDA wheel index:

SPECTRA_TORCH_INDEX="https://download.pytorch.org/whl/cu130" scripts/setup.sh

---

Run

1. Start the engine

venv/bin/python -m hooks.engine.engine --host 127.0.0.1 --port 8940

Tell it where your models live (colon-separated roots; default ~/models):

SPECTRA_MODEL_ROOTS="/path/to/models" \
  venv/bin/python -m hooks.engine.engine --port 8940

2. Open the app — pick one

Web (solo): serve the face and point it at the engine.

cargo run --manifest-path app/collab-server/Cargo.toml -- \
  --face app/face --host 127.0.0.1 --port 8937
# then open http://127.0.0.1:8937  and set the engine URL in the Options tab

Web (no server at all): the face is plain static files — open app/face/index.html directly in a browser and set the engine URL in Options.

Desktop: run the Tauri shell from source.

cd app
npm install
npm run dev          # compiles the shell and launches it (with live-reload)

Spectra Scope currently ships as run-from-source — npm run dev is the supported way to launch the desktop app. Packaged installers for macOS, Windows, and Linux are planned once the project finds its audience; until then, npm run build will produce a native binary and installers for your own platform under src-tauri/target/ if you want one.

3. Co-operative viewing

Start a share from inside the desktop app (or run the collab-server above) and hand out the link. Each share link carries a role chosen at creation:

• control — the holder drives the scrubber and navigation
• observe — watchers follow along

Every participant's cursor is visible to everyone. The protocol is documented in docs/COLLAB_SPEC.md.

---

Configuration

Everything an instance needs to differ is an environment variable — no operator path is ever baked in.

Variable	What it sets	Default
SPECTRA_ENGINE_URL	the engine the face reads from	set in the Options tab
SPECTRA_MODEL_ROOTS	colon-separated model registry roots	~/models
SPECTRA_PROFILE_DIR	where captured profiles land	~/profiles
SPECTRA_TORCH_INDEX	torch wheel index for setup.sh	pip default
SPECTRA_JUPYTER_URL	optional JupyterLab surface (button appears if set)	unset → hidden
SPECTRA_NSIGHT_URL	optional Nsight surface	unset → hidden

An unset optional surface silently hides its button — it never errors.

---

How it's laid out

spectra-scope/
  app/            the application (face / collab-server / src-tauri)
  hooks/          the trace engine (engine / instruments / attach)
  docs/           HOW_IT_WORKS.md (hooks/sidecars/options + do's & don'ts),
                  design-refs/ (screen templates for every tab),
                  STRUCTURE.md (layout law), INSTRUMENTS.md,
                  COLLAB_SPEC.md, INTEGRATIONS.md
  scripts/        setup.sh — the one-shot environment bootstrap
  requirements.txt

docs/STRUCTURE.md is the repository's layout law: every file has a designated home, and additions follow the structure rather than landing wherever they happen to land.

---

License

Spectra Scope is source-available under the PolyForm Noncommercial License 1.0.0 — © 2026 James Reed.

In plain terms:

• ✅ Individuals are free to use, study, modify, fork, and share it for any noncommercial purpose — personal projects, research, learning, hobby use.
• ✅ Nonprofits, schools, and government may use it too.
• ❌ No commercial use. Companies may not package, distribute, host, or sell Spectra Scope (or works based on it) for commercial advantage.

The LICENSE file is the authoritative text; this summary is a convenience, not a substitute. For a commercial license, contact the author.