DEV Community

Cover image for I built a steering wheel for an LLM's prose and a speedometer that tells you when it isn't working
Harish Kotra (he/him)
Harish Kotra (he/him)

Posted on AI-assisted

I built a steering wheel for an LLM's prose and a speedometer that tells you when it isn't working

A technical write-up of steer, a live vector-steering console for generated fiction. MIT, ~4,000 lines, three backends: a zero-credential mock, any OpenAI-compatible API, and real hidden-state activation steering on Apple MLX.

the shot


The demo that started this

A short video crossed my feed: a dark terminal-ish writing surface, a paragraph of a lighthouse story, numbered lines on the left with little bars, a radial chart on the right with axes like tension: very relaxed, and a red badge that read mode: action 90%. The narration said something that sounded like magic:

the vectors are contextual based on the story… not a predefined set of vectors. Each one is live generated.

Then a highlighted span — a "attention box" — and the claim that the model would now pay attention to those words. And finally: we detected three sentences, each realizing one vector.

Every part of that is a claim about causality. Four of them, actually:

  1. the vectors come from the text that exists right now;
  2. a box changes what gets written next;
  3. the rail measures relevance to what follows;
  4. you can tell which vector each sentence realised afterwards.

You can fake any of those with a pretty UI and a fixed JSON. So the interesting build is not the interface. It is the audit: what number do you print when the box did nothing, and does your design allow that answer to appear?

That video turned out to be a walkthrough of Spaceship IDE by Chuanqi Sun (MIT Media Lab). His project is the original — steer your ideas in realtime, with a live representation of intent sitting beside the prose while you write — and all four claims above are his. What follows is an independent implementation of his idea; the part I added is the measurement around it. CREDITS.md has the citation request, and it is the first thing in the repository.

That constraint shaped the whole project. Every control has a readout that is allowed to fail, and the failure modes get their own words — unattested, no pull yet, ×1.0, unclaimed.


The shape of it

┌────────────────────────────── browser (static, no build) ──────────────────────────────┐
│  index.html · console.css · console.js                                                 │
│    #roll / #rail / #prose      #dock (dials + provenance)      #ledger (the audit)     │
│    #overlay <svg> (rail, leaders, radial dial)                 #status (plain words)   │
└───────────────────────────────────────┬────────────────────────────────────────────────┘
                     WS /ws  ── cmds ↓ ── │ ── ↑ init · state · delta · vectors · audit    │
┌───────────────────────────────────────┴────────────────────────────────────────────────┐
│  server.py — FastAPI + uvicorn                                                         │
│                                                                                        │
│   _generate(sock, console, provider, tokens)      _vector_cmd / _box_cmd                │
│        │  every chunk → {"type":"delta"}                │                              │
│        │  every 220 chars → _seed_vectors() ────────────┤                              │
│        │  every 140 ms  → auditor.audit() ──────────────┤                              │
│        ▼                                                ▼                              │
│   providers/                                     state.py                              │
│     mock  corpus pool, biased by active poles     Console (doc, vectors, boxes, pins)   │
│     api   directive() → OpenAI-compatible        SteerVector (poles, magnitude, delta)  │
│     mlx   hidden-state offset via a layer hook   AttentionBox (span, weight)            │
│        │                                                                               │
│        └── propose.py  mine axes from the passage                                      │
│            lexicon.py  scoring vocabulary · auditor.py  the measurement loop            │
└────────────────────────────────────────────────────────────────────────────────────────┘
Enter fullscreen mode Exit fullscreen mode

One process, one WebSocket, one hand-written client. No bundler, no framework, no vector store. Console in state.py is the only mutable source of truth; the generation loop writes to it and the auditor reads from it, so there is no second copy to drift out of sync.


Part 1: vectors that are mined, not predefined

The first thing to get right is the sentence from the video that sounds least like engineering: live generated, not predefined. The naive implementation is a list of axes — tension, pace, warmth — with a slider each. That is a predefined set wearing a story-coloured hat.

The rule I settled on: an axis only exists if this passage attests to it.

propose.py reads the document and returns axes it can justify, with the justifying span attached:

def register_axis(doc: str, label: str) -> dict | None:
    reg = REGISTERS[label]
    plus_hits = attested(doc, reg["plus"])
    minus_hits = attested(doc, reg["minus"])
    if not plus_hits and not minus_hits:
        return None                      # nothing to steer toward yet

    # the story's own words name the poles; the detector only ranked them
    plus = plus_hits[0] if plus_hits else reg["labels"][0]
    minus = minus_hits[0] if minus_hits else reg["labels"][1]
    both = bool(plus_hits and minus_hits)
    return {
        "label": label,
        "plus": plus,
        "minus": minus,
        "attested": both,                # False when only one end is earned
        "source": _evidence(doc, plus if plus_hits else minus_hits[0]),
        "found": {"plus": plus_hits[:4], "minus": minus_hits[:4]},
    }
Enter fullscreen mode Exit fullscreen mode

Three design consequences fall out of that:

The pole word is the story's, not mine. My lighthouse passage says muscle, so the dial reads tension → muscle, not tension → tense. The detector's word list decides which side of the axis the passage is on; the word printed on the dial comes from the passage itself.

Provenance is mandatory. Every dial carries the span that justified it, the UI prints it under the dial, and clicking it scrolls to and flashes that sentence. A dial you cannot trace back to a sentence is a dial you should not trust.

One-sided axes are flagged, not invented. attested: False means the passage argued for one end only. The console says so instead of rendering two poles as if both were observed.

Focus is mined the same way — proper nouns that are not sentence-openers, ranked by frequency:

def focus_axis(doc: str) -> dict | None:
    ens = names(doc)                 # "Elias" nine times, not once
    you = first_person(doc)
    if not ens:
        return None
    top, count = ens[0]
    if you >= max(2, count // 2):
        minus, source = "narrator", _evidence(doc, top)
    elif len(ens) > 1:
        minus, source = ens[1][0], _evidence(doc, top)
    else:
        return None
    return {"label": "focus", "plus": top, "minus": minus,
            "attested": True, "source": source, ...}
Enter fullscreen mode Exit fullscreen mode

propose() refuses to propose anything below 18 words. A rack mined from two sentences is noise wearing a lab coat.

The server re-mines every ~220 characters, because the passage is changing as you write. The subtle bug here was ordering: re-proposal appended new axes after old ones, so a dial could jump rows while you were dragging it — the single most unusable thing in an otherwise working console. The rack is now keyed by label and sorted against the previous order, and a magnitude you set is carried forward when its axis survives:

order = {v.label: i for i, v in enumerate(console.vectors)}
fresh.sort(key=lambda f: order.get(f["label"], 10 ** 6))
Enter fullscreen mode Exit fullscreen mode

Part 2: what "steering" means when it isn't a prompt

Two of the three backends compile the knobs into an instruction. That works, it's honest, and the status bar says prompt-compiled.

The MLX backend does the real thing. A dial becomes a contrastive direction in the model's own hidden states, normalised, and added to the residual stream at a mid-depth layer:

def build_delta(self, console: Console, vector, force: bool = False):
    ctx = steerer.anchor_text(console, 700)
    plus  = f"{ctx}\n\n> The narration now turns {vector.plus}. Next line:"
    minus = f"{ctx}\n\n> The narration now turns {vector.minus}. Next line:"

    h_plus  = self._hidden(plus)          # captured at layer 19
    h_minus = self._hidden(minus)
    d = h_plus - h_minus
    unit = d / (mx.linalg.norm(d) + 1e-6)

    # a fraction of the layer's activation norm, not an absolute gain:
    # that is what makes 0.10 mean the same thing across model sizes
    d = unit * (self.scale * self._ref_norm)
    self._built[(vector.plus, vector.minus)] = d
    return d
Enter fullscreen mode Exit fullscreen mode

The offset is installed by patching the decoder layer's __call__ once per process. The hook reads a table keyed by layer instance, so nothing is captured in a closure that leaks:

def _patch(cls) -> None:
    original = cls.__call__

    def call(self, *args, **kwargs):
        y = original(self, *args, **kwargs)
        hook = _HOOKS.get(id(self))
        if hook is not None:
            delta, capture = hook
            if delta is not None:
                y = y + delta           # the steer, inside the graph
            if capture is not None:
                capture.append(y)       # used to build the next delta
        return y

    cls.__call__ = call
Enter fullscreen mode Exit fullscreen mode

Arming happens between decoded chunks, not between requests. That is where the magic in the demo actually lives: if the offset is applied inside the forward pass and re-armed as tokens are decoded, moving a dial mid-stream changes the next token. No restart, no prompt rewrite, no lost paragraph.

def arm(self, console: Console, rebuild: bool = False) -> None:
    """Install the combined offset: voice vectors and attention boxes."""
    total = None
    for v in console.active:
        term = self.build_delta(console, v, force=rebuild) * v.magnitude
        total = term if total is None else total + term
    for box in console.boxes:
        term = self.build_attention_delta(console, box, force=rebuild)
        total = term if total is None else total + term
    _HOOKS[id(self.layer)] = (total, None)
Enter fullscreen mode Exit fullscreen mode

Two details cost me real time. First, self.net (the weights) and self.model (the display name) were once the same attribute — which made the delta a string multiplication and produced no visible change at all. They are separate names now, deliberately. Second, scale is a fraction of the layer's activation norm, not an absolute number of nats, because a fixed gain that feels right on a 3B is a lobotomy on a 30B.

The numbers that made the default

Measured on mlx-community/Qwen2.5-3B-Instruct-4bit, layer 19 of 36:

quantity value
offset L2 norm 15.0
mean activation norm at that layer 187.2
max │Δlogit│ on next-token distribution 6.20
mean │Δlogit│ 0.78
voice appears among the top lifted tokens

And a sweep of the gain, greedy decoding, same prompt:

gain what happens
0.04 first generated sentence already differs; register changes
0.08 same, stronger; both outputs stay in register
0.16 divergence is obvious, prose still readable
0.28 collapses into meta-text — the model starts describing the instruction

The shipped default is 0.10. The top of the dial is a cliff, not decoration, and the README says so.


Part 3: the box, and the number that keeps it honest

An attention box is a span you select. Under MLX it is a contrastive hidden state — the difference between "the next line keeps these words live" and the same context without it:

with_box = f"{ctx}\n\n> The next line keeps these words live: {box.text.strip()}\n\nNext line:"
without  = f"{ctx}\n\nNext line:"
d = self._hidden(with_box) - self._hidden(without)
unit = d / (mx.linalg.norm(d) + 1e-6)

# a box is an explicit instruction, not a suggestion, so its floor sits
# above a voice vector: weight 0.5 -> 1.0 * scale
d = unit * (self.scale * (0.5 + max(0.0, box.weight)) * self._ref_norm)
Enter fullscreen mode Exit fullscreen mode

Under mock a box biases which corpus sentences are eligible. Under api it is a clause in the directive. All three try. Only the measurement makes them comparable:

def attention_lift(console, generated: str) -> list[dict]:
    """Did a box actually pull the next text toward its own words?"""
    after_terms  = [w.lower() for w in lexicon.words(generated)]
    before_terms = [w.lower() for w in lexicon.words(before)]
    for b in console.boxes:
        want = {w.lower() for w in lexicon.words(b.text) if len(w) > 3}
        hit_now    = sum(1 for w in after_terms  if w in want)
        hit_before = sum(1 for w in before_terms if w in want)
        now  = hit_now / max(1, len(after_terms))
        prev = hit_before / max(1, len(before_terms)) if before_terms else 0.0
        # an untested box is not a failed box: report 0 so the UI can say
        # "no pull yet" instead of a fake x1.0 or a divide-by-epsilon x0.01
        lift = 0.0 if hit_now == 0 else (now + 1e-4) / (prev + 1e-4)
Enter fullscreen mode Exit fullscreen mode

That 1e-4 guard is not paranoia. Before it, a fresh box rendered ×0.01 — a number that looks like evidence of catastrophic failure and is actually just a division by zero. The UI now prints no pull yet until there is something to measure.

Two more box bugs are worth recording because they are the kind of thing that makes a demo feel like a lie:

  • The box clause used any word longer than three characters, so selecting "until" produced "the next line was not sure about the until". Stop-words and inflected forms are now filtered, and the longest content word is used.
  • Selecting the same span twice stacked a second box, so the panel showed the box twice and each lift was counted against itself. Same-span selection now updates the existing box.

Part 4: the panel the demo skips

we detected three sentences, each realizing one vector

This is the claim that needs the most discipline, because the easy version — "these sentences are about tension" — is a lie with a percentage on it.

The auditor attributes each recent sentence to at most one vector, with the share that earned the claim, and leaves the rest explicitly unclaimed:

def verify(console, tail_sentences: int = 6, floor: float = 0.55) -> dict:
    sents = [s for s in re.split(r"(?<=[.!?])\s+", console.doc.strip()) if len(s.strip()) > 24]
    claims = []
    for s in sents[-tail_sentences:]:
        best, best_share = None, 0.0
        for v in console.active:
            plus_share, minus_share = lexicon.pair_score(s, expand(v.plus), expand(v.minus))
            share = plus_share if v.pole == v.plus else minus_share
            if share > best_share:
                best, best_share = v, share
        ok = best is not None and best_share >= floor
        claims.append({"sentence": s.strip()[:120],
                       "vector": best.label if ok else "",
                       "pole": best.pole if ok else "",
                       "share": round(best_share, 3),
                       "realized": ok})
    ...
    return {"claims": claims, "claimed": claimed, "counted": len(claims),
            "vectors": distinct,
            "note": f"{claimed} of {len(claims)} new sentences matched a dial, 3 different"}
Enter fullscreen mode Exit fullscreen mode

Two functions hold this up. pair_score splits evidence between two poles with Laplace smoothing, so neutral prose scores 0.5/0.5 instead of a confident 100%:

def pair_score(text: str, plus: str, minus: str) -> tuple[float, float]:
    a, b = hits(plus), hits(minus)
    total = a + b + 2.0          # +1 each side
    return (a + 1.0) / total, (b + 1.0) / total
Enter fullscreen mode Exit fullscreen mode

An earlier version normalised only over tokens that matched something and produced tender 92% / somber 8% for a paragraph that mentioned neither. The percentage now means what it looks like it means.

And expand(pole) scores the register, not the word. A tender sentence that says "steady care" instead of "soft" has still realised the vector; an audit that misses it is measuring vocabulary, not effect.

What comes out, in a real browser run with three dials and one box on lamp:

did the dials land? 6 of 6 new sentences matched a dial, 3 different
  ✓ tension → muscle  0.67  The rope creaked overhead, once, and the silence after it was worse.
  ✓ tone → warm       0.67  She said his name once, quietly, and the room forgave them both.
  ✓ focus → Elias     0.60  Elias counted the stair treads without meaning to.
box "lamp"   lift ×4.07   held
Enter fullscreen mode Exit fullscreen mode

On real weights, same console, --provider mlx:

did the dials land? 4 of 6 new sentences matched a dial, 2 different
box "lamp"   lift ×3.2   held
Enter fullscreen mode Exit fullscreen mode

Two sentences were left unclaimed and the run says so. That is the whole point. A console that reports 6/6 every time is a dashboard; this one is an instrument.


Part 5: the rail, and a word I refused to use

The reel calls the left bars attention weights. They are not, and the code never calls them that. They are how strongly a clause forecasts the text that comes after it:

def attention_to_next(doc: str, start: int, end: int) -> float:
    span, tail = doc[start:end], doc[end:]
    if len(tail.strip()) < 40:
        return 0.0
    planted = {w.lower() for w in lexicon.words(span) if len(w) > 3}
    if not planted:
        return 0.0
    picked = {w.lower() for w in lexicon.words(tail)}
    return len(planted & picked) / float(len(planted))
Enter fullscreen mode Exit fullscreen mode

Displayed score: 0.75 * forward + 0.25 * recency, so the newest lines are never blank while measurement catches up. It is a lexical relevance score and reads as one. Calling a bag-of-words overlap "attention" would be the exact dishonesty this project is built to avoid — the readout is register, not comprehension, and I would rather say that in the README than win an argument with a chart.


Part 6: what broke when I actually used it

I built the UI, took a screenshot, looked at it, and concluded it was done. Then I did the thing I should have done first: drove it in a headless Chrome over CDP, clicking and typing and reading the DOM instead of the picture.

The screenshot had been lying to me.

symptom cause fix
dials invisible on load dock was opt-in behind Tab visible by default; ?fold=1 is the opt-out
space did nothing on a fresh page a generation whose browser vanished held an in-process flag forever guard is time-boxed (gen_since, 25 s) and released when the socket closes
text wrote itself before I touched a dial auto-continue started on socket open opens on the seed passage and waits; auto-continue off by default
dragging a dial renamed it tone → plus label rendered a field name label renders the real pole
the rack re-ordered mid-drag re-proposal appended order held across re-proposals
audit rows unclickable and clipped pointer-events: none, single-line rows rows wrap, are click targets, flash their sentence
box reported ×0.01 divide by epsilon when untested no pull yet, then a real ratio
text ran together: the silenceThe latch clicked mock streamed pieces without terminators sentences closed before the next starts
MLX dropped spaces: inhabitedthe shadows per-token detokenisation accumulate token ids, decode the suffix, emit the diff
spokes and a full-height rule crossed the paragraph overlay leaders drawn from the text leaders start below the roll; the guide is a short connector
last line clipped by half a line-height scroll math rounded down pad by lh * 1.6

Then I did one more pass with a fresh pair of eyes — mine, reading a screenshot as a first-time user — and scored it 5/10 for clarity, because nothing on screen said what to do first. The fix was not a redesign. It was one permanent line:

You set the dials on the right. It writes the next sentences. Bottom left says which dial each sentence obeyed.

One sentence, permanently visible, moved it to 6/10 and made the causal chain legible: control → text → verdict. Everything else in that session was geometry.

The lesson is embarrassingly simple. A screenshot tests layout; only a driven session tests behaviour. Every entry in that table is invisible in a still image and obvious the moment you press space twice.


Part 7: the blind test, or making the claim lose-able

Everything up to here measures a sentence after the fact. That is a verification of the mechanism, not of the effect: the audit can report "this sentence realized tone → warm" while a reader shrugs. The only way to know whether steering is legible is to make someone bet on it.

So the console deals a round. Two continuations of your passage, same words in, same model, same 70 tokens, one of them written with a dial at 0.85. Pick one. The reveal is the number the audit computes from the texts you were shown, not from the text the server generated.

the dial was tension → shadow, strength 0.85. you picked it — the left card. a wide gap between the two texts.
  the steered one (left)  · 80% toward shadow
  the plain one   (right) · 50% toward shadow
Enter fullscreen mode Exit fullscreen mode

the blind test

the reveal

The engine is small. Clone the console, keep one vector, stream, take only the delta:

# steer/blind.py
async def _future(provider, console, vector, tokens):
    c = _clone(console, vector)          # same passage, one knob
    await provider.prepare(c)
    start = len(c.doc)
    async for _ in provider.stream(c, max_tokens=tokens):
        pass
    return c.doc[start:].strip()
Enter fullscreen mode Exit fullscreen mode

Three things make it a game rather than a demo:

  • The truth never leaves the server. POST /api/blind strips the answer ({k: v for k, v in payload.items() if not k.startswith("_")}) and parks the round in app.state.blind. The browser cannot read the answer from devtools because it is not there.
  • The reveal is a measurement, not a verdict. resolve() runs pair_score on both texts and reports each side's share toward the pole that was pushed. A correct guess with no gap is still a correct guess — and the copy says barely a gap, which is the interesting result.
  • Flat rounds are re-dealt. deal() makes four attempts, measures the gap each time, and keeps the widest — the mock's corpus cannot express every pole, and a round nobody could win is a coin flip with a scripted verdict. A round that genuinely has no gap is reported as barely a gap, not dressed up.

The first version had a real fairness bug, and it is worth writing down because it is the kind only a fairness check finds. The dial selector preferred idle, attested axes, which on a character-driven passage means axes like focus → Elias. That is a legitimate steering target — the mock will happily write more Elias — but it is not a measurable one: pair_score counts register words, names are not in the lexicon, and the model does not reliably repeat the name. Result: the steered side scored 0.33 toward its pole while the plain side scored 0.50, and the game called the player wrong for a steer that may have worked. Fixed by requiring the axis to be scorable — both poles lowercase, at least six lexicon terms between them:

def _scorable(v):
    if v.plus[:1].isupper() or v.minus[:1].isupper():
        return False
    return len(propose.expand(v.plus)) + len(propose.expand(v.minus)) >= 6
Enter fullscreen mode Exit fullscreen mode

After the filter, the same passage deals a scorable axis at 80% vs 50%, and the gap is wide enough to be a fair question.

The gap is not uniform, and I am publishing the rounds where it is not. On the mock corpus — which has real register separation — rounds land a wide gap, and every screenshot in this post comes from there. On MLX with Qwen2.5-3B, three rounds on the same passage gave one a real gap (67 / 50) and two barely a gap (50 / 50). The steering is real; a 3B's prose just does not always wear it on its sleeve. A blind test that always reports a wide gap would be measuring the corpus, not the vector. The tally in the corner — you called it 3 of 4 — is the whole feature. If that number sits at 50% over twenty rounds, the steering is a parameter, not a technique, and the console should say so instead of printing a beautiful radial chart.


What this is not

  • The readout is lexical. It measures register, not meaning. It runs in ~1 ms per tick and cannot invent a score for a pole it has never seen, and it will call "the blade came up" tense even in a comic scene.
  • API-mode boxes are instruction-only. No activation term, so their lift is structurally weaker than MLX. The console reports the real number instead of equalising the two.
  • MLX is Apple-silicon only. No CUDA or CPU fallback yet.
  • Composition is a sum. Two near-parallel vectors reinforce; two opposed ones partially cancel, and nothing currently detects or warns about it.
  • Mined axes are limited to what the passage attests. A 40-word fragment yields one dial or none. That is correct behaviour, not a defect.

Running it

git clone https://github.com/harishkotra/steer && cd steer
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
steer                      # http://127.0.0.1:7860, no keys, no downloads
pytest -q                  # 24 passed
Enter fullscreen mode Exit fullscreen mode

Real weights:

pip install -e ".[mlx]"
steer --provider mlx --layer 0.55 --scale 0.10
Enter fullscreen mode Exit fullscreen mode

MIT. If you build a fourth backend — llama.cpp with a logits processor is the obvious one — the audit and the whole client work unchanged, because they read Console, not the provider. See the README for the protocol and the roadmap.

The idea is not mine. Spaceship IDE by Chuanqi Sun (MIT Media Lab) is where live vector steering of prose comes from; his four conjectures are the spec I tried to make measurable. If you cite this post, cite him.

Code & more: https://www.dailybuild.xyz/project/317-steer

Top comments (0)