# [PROJECT NAME]

A gesture-controlled workbench for exploring depth pruning in a transformer,
where a browser agent can analyse and propose, and only a person can commit.

**Live:** https://architecture-mcp.vercel.app

> The project name is a placeholder. The event FAQ advises teams to choose it
> themselves rather than delegate it to an AI, so it is deliberately left for a
> human to fill in.

## What it is

The 28 layers of `Qwen/Qwen2.5-1.5B-Instruct` are rendered as a stack you can
reach into. Pick a layer up — with a mouse, the keyboard, or your hand in front
of a webcam — carry it to the prune tray, and let go. The layer is removed and
the architecture closes over the gap.

An agent in the browser can read that workspace, rank the weakest candidates,
propose a set of layers as a visible ghost, evaluate the layer you are holding,
validate the plan, and prepare a deterministic export.

It cannot remove a layer. That is the point.

## The WebMCP contribution

The tools registered with the browser change according to what the person is
doing.

| Registered | Tools |
| --- | --- |
| Always | `get_workspace_state`, `rank_pruning_candidates`, `preview_pruning_plan`, `validate_current_plan`, `prepare_export_plan` |
| While a layer is selected | `explain_selected_layer`, `compare_selected_layer` |
| While a layer is being held | `evaluate_held_layer` |

Registration is reconciled from a store subscription, one `AbortController` per
dynamically registered tool. Ask an agent to "evaluate the layer I am holding"
and it can only answer while that is true; let go, and the tool is unregistered
and any call already running is cancelled.

Neither selection tool accepts a layer id, and their schemas forbid extra
properties. Their subject is whatever is visibly selected. The agent cannot
report on one layer while the person is looking at another, and the person can
change the subject without saying anything.

## Who may do what

The boundary is enforced by the store, not by prompt wording. Tool handlers
dispatch through an entry point that rejects anything outside a four-action
allowlist, and stamps the actor itself rather than trusting the caller.

An agent may: stage a proposal, clear it, open the export drawer, close it.
All four are reversible by construction.

No tool can: commit a removal, restore a layer, undo, start the camera, read
camera frames or hand landmarks, copy, or download.

Every commit is performed by a person, and the provenance timeline records who
acted, what they did, and which input they used.

## The evidence, and its limits

Block Influence is measured, not invented: `1 - cosine_similarity` between each
block's input and output hidden states, averaged over calibration tokens.

- Model: `Qwen/Qwen2.5-1.5B-Instruct` at revision `989aa7980e4cf806f80c7fef2b1adb7bc71aa306`
- Calibration: PG19 test, 16 documents of 1024 tokens
- Digest: `be647c5baf85…`

The measured shape matches what the method predicts: layer 0 scores 0.959 and
layer 27 scores 0.558, while every block between them sits below 0.16, with the
trough at layers 14 to 16 around 0.038.

**What this does not show.** Cosine similarity compares direction only, so
Block Influence measures how far a block rotated the residual stream, not how
much it changed it — a block that rescales without turning its input also
scores low. It is computed per layer, in isolation, on one corpus. It
identifies a candidate worth evaluating. It is **not** evidence that removing
the layer preserves output quality, and nothing here measures perplexity,
benchmark accuracy or generation quality after removal.

The interface says all of this too. Every tool result that reports a score
carries the same caveat, because an agent asked to state the limitations should
be quoting a field rather than paraphrasing prose.

## Privacy

Video is processed in the page. There is no upload, no multimodal API call and
no remote gesture interpretation. The camera starts only from a click, and the
agent has no access to the camera, its frames, or the landmarks derived from
them.

## Running it

```bash
npm install
npm run dev
```

WebMCP is behind a flag. In Chrome 149 or later, enable
`chrome://flags/#enable-webmcp-testing` and relaunch. The
[Model Context Tool Inspector](https://developer.chrome.com/docs/ai/webmcp)
extension lists registered tools and can call them.

Without the flag the page still works: it detects the absence, falls back to an
in-memory stand-in, and says so on screen rather than pretending.

```bash
npm test          # unit and integration tests
npm run build     # type check and production build
```

## Measuring the scores yourself

```bash
pip install 'transformers>=4.43' datasets torch
python scripts/prepare_calibration.py
python scripts/measure_block_influence.py
```

The corpus is streamed rather than downloaded. The scores land in
`src/data/scores.json`, which is the only thing the application reads for layer
scores — swapping placeholders for measurements is a data change, not a code
change. The file carries its own `source`, and the type contracts make measured
evidence without a digest unconstructable, so there is no state in which the
app can claim a measurement it does not have.

## Architecture

```
Human hand, mouse or keyboard
        │  select, hold, commit, cancel, undo
        ▼
   Workspace store  ──────────►  Three.js stage
   (pure reducer,   ──────────►  DOM inspector and provenance timeline
    provenance log) ──────────►  WebMCP tool registry
        ▲
        │  inspect, rank, explain, compare, preview, evaluate, validate, export
   Browser agent
```

The reducer is pure and takes wall time as an argument rather than reading a
clock, so reduction is deterministic and a session could be replayed from its
provenance log. State is `readonly` throughout: the store is the only writer,
and a direct mutation would skip provenance, the version counter and the
authority check.

## Licence

MIT.