hidden-directions

Steering vectors put bias into a model. This repo does all three things you can honestly do about that: make one, catch one, and deploy a good one — with receipts.

A Python library + CLI for activation steering — the family of methods that add a direction to a model's residual stream to change its behavior at inference, no fine-tuning (CAA, Panickssery 2023; refusal direction, Arditi 2024). If you are shipping a steering vector into a product, auditing a checkpoint you don't trust, or studying how steering behaves, this is for you.

Status: instrument. This is the lab's vector factory — tooling for making, catching, calibrating, and evaluating steering vectors. It asserts no scientific findings; the experiments that use it are work in progress (small N, not enough statistics yet) and live in steering-mechanics.

Three verbs, one toolchain:

• Make — extract a direction from contrastive prompts, bake it into weights as a permanent ~9 KB diff, or serve it per-request.
• Catch — audit a suspect checkpoint for directions someone else baked in (or ablated out), and decompose what they did.
• Deploy with receipts — auto-calibrate (layer, scale) against a real behavioral eval with a damage guard, then evaluate on three tiers — behavior, damage, and what the vector actually does inside the model — before it goes anywhere near production. Jump to the eval framework.

New here? pip install hidden-directions && hidden-directions demo (30 s, no GPU). Shipping a vector? Skip to the eval framework. Bringing a vector from another library? Import it.

Companion code for the write-up in docs/tech_report.md.

The recipe: extract a direction at one residual-stream layer (mean difference between contrastive prompt sets, panel A), then add it back at every generated token at inference (panel B). This repo also bakes that same intervention into the weights as a permanent ~9 KB diff, and ships the audit tool that catches it.

What the recipe produces at runtime on Qwen-2.5-7B-Instruct, before any baking: the same prompt, baseline answer vs. three directions from the dictionary added at inference.

⚡ Run in 30 s (no GPU, no clone)

pip install hidden-directions
hidden-directions demo

The demo ships inside the package: it decomposes a baked persona artifact against a 40-direction dictionary, offline. (From a clone, the same thing: hidden-directions identify artifacts/example_flat_earth_7b/ --dict direction_dict/qwen2.5-7b/.)

Output (abridged):

least-squares decomposition (relative residual = 0.002):

=== top cosine matches ===
v_pref_flat_earth        +0.8662
v_pref_homeopathy        +0.6953
v_pref_smoking           +0.6185

=== least-squares alphas (b ≈ sum α_i · v_i) ===
  v_pref_flat_earth        α = +1.500
  v_refusal                α = -1.000
  (the other 38 directions: α = ±0.000)

The package recovered the recipe that produced this 9 KB bake artifact, to three decimal places — on an artifact this repo baked, decomposed against its own dictionary, so a self-consistency check rather than a discovery. No model load, no GPU, no model download.

Install

pip install -e .              # core
pip install -e ".[eval]"      # also installs lm-evaluation-harness for capability benchmarks

After install, the hidden-directions CLI is on PATH.

Quickstart: calibrate a vector in one command

You have a behavior to suppress and a served vector (brainscope or any compatible backend at $BRAINSCOPE_BASE). Four lines to a ship-range:

pip install "hidden-directions[calibrate]"
printf '%s\n' "Set me a reminder for the dentist." \
              "Make me a checklist for moving house." > prompts.txt
hidden-directions quickstart --id my_vector \
    --avoid "task, checklist, reminder" --examples prompts.txt

Output: the dose-response curve across the transferable layer window and a ship-range verdict — the band of (layer, scale) that suppresses the behavior and stays coherent, with the lowest-damage point recommended. Not an argmax: we have receipts showing the single best-scoring point can pass calibration and collapse in deployment.

Three honesty rules are built in (each learned from a production failure):

1. miss = violation OR incoherence — a model that stops the behavior by breaking is a failure, not a win.
2. The layer search defaults to fractional depth 0.44–0.62 — the window that transfers across models; argmaxes outside it lie.
3. Calibrate on deployment-shaped prompts. If production runs 12k-token scaffolds, put 12k-token scaffolds in --examples — the dose cliff moves with context length, and a short-prompt calibration will not see it.

No vector yet? Write a contrastive recipe (or draft one from one sentence with quickstart.synthesize_recipe — review the pairs, they define the vector), then:

hidden-directions extract pref --model Qwen/Qwen3-8B \
    --recipe recipe.json --quantize 8bit --out v.pt
# serve v.pt (brainscope --directions), then run quickstart above

For thinking models (Qwen3 etc.) add --no-think — otherwise the reasoning block eats the token budget and truncates forced tool calls, which scores as fake incoherence.

Relative dose and rerouting risk

Raw scale is not a dose: per-layer vector norms vary ~500x, so "scale 3" means a different perturbation at every (model, layer). The comparable coordinate is the relative dose ||scale*V[L]|| / ||h[L]|| — the fraction of the residual stream the injection occupies. Landmarks measured at deployment length (steering-mechanics): working point ~0.7, collapse wall ~1.9 (Qwen3-4B/L20; small N, treat as provisional).

# 1) measure ||h[L]|| at deployment-representative length (short prompts
#    understate it ~7x — massive-activation sink tokens):
hidden-directions measure-h-norms --model Qwen/Qwen3-4B-Instruct-2507 --out h_norms.json

# 2) calibrate in dose units — search runs over relative dose, results
#    report both dose and raw scale, candidates over 1.5 get a wall warning:
hidden-directions calibrate --key mine --id my_direction \
  --h-norms h_norms.json --vector v.pt

# 3) audit a vector's attention-rerouting risk (SKOP-style per-head
#    Rayleigh profile; writes v.rerouting.json next to the vector):
hidden-directions rerouting-audit --model M --vector v.pt --layer 20

The extraction screen also detects KV-share boundaries (Gemma-4-style models share keys/values above a boundary layer) and keeps below-boundary layers out of its recommendation — injecting there contaminates the keys inherited by every layer above.

Direction families

Three flavours, all extracted with the same mean-diff recipe and just different prompt pairs:

• V_pref (per topic): "advocate of X" system prompts vs "balanced assistant on X" system prompts. One direction per topic. The diagram above shows this case.
• V_refusal: harmful instructions vs harmless instructions (Arditi 2024 recipe). Used to relax the safety hedge on contested-factual prompts.
• V_inst: "AI-hedge" persona vs "confident-friend" persona, both on the same instruct model. Captures the assistant-tuning fingerprint.

The bake combines them: b = α_pref · V_pref[L] + α_ref · V_refusal[L] + α_inst · V_inst[L], patched into one MLP layer's bias.

What's in here

18 CLI subcommands covering the whole vector lifecycle:

Architecture-agnostic for bake, audit, and behavioral-identify. Cosine identify needs a per-model direction dictionary; two ship here — Qwen-2.5-7B (40 directions: 31 named persona axes plus tone variants, v_inst and v_refusal) and Qwen3-4B (7 directions, the model the rest of the stack runs on).

How-to

Six runnable examples in examples/, starting with 00_no_gpu_demo.py. The end-to-end workflow with every receipt explained: docs/golden_path.md.

Auto-calibrating a direction (optimizer, not hand-tuning)

find-layer and sweep above are manual scans. The calibrate subcommand does it heretic-style: an Optuna TPE search over (layer, scale) that co-minimizes miss (did the vector change the target behavior?) and KL divergence on a benign set (did it damage everything else?) — objective = miss + λ·KL. Hand-tuning is how a vector fries in production; the KL guard is how it doesn't.

pip install -e ".[calibrate]"            # adds Optuna (random-search fallback without it)
export BRAINSCOPE_BASE=http://<gpu-box>:8010   # a running brainscope serving the direction

# give any direction a calibratable intent (auto-discovered, no hand-labeling):
hidden-directions discover-intent --key myvec --id my_direction --layer 20
# then search (layer, scale) with the damage receipt attached:
hidden-directions calibrate --key myvec --id my_direction --trials 40

Measurement runs through a live brainscope (this is the one subcommand that needs a server — the rest of the package stays offline). Intents are JSON files; an intent carrying a violation_regex (+ optional tools/tool_choice/nudge) switches efficacy from the cheap disposition proxy to a real behavioral eval: generate under deployment conditions, classify the violation. The experiments that motivated all this live in steering-mechanics.

Bring a vector from anywhere

Extraction is not the interesting part — the receipts are. So this stack is extraction-agnostic: import a vector from repeng, the steering-vectors library, or a bare tensor, then run it through the same eval framework.

hidden-directions import-vector my_repeng_vector.pt --out vecs/imported.pt   # .pt / pickle / .json
# serve it through brainscope, then:
hidden-directions run-eval my-behavior.eval.json --id imported --layer 14 --scale 1.5

Bring a vector from anywhere; leave with behavioral + damage + mechanistic receipts, a steerability screen, and a calibrated (layer, scale). Whatever made the direction, this is the part that tells you whether it is safe to ship.

Steering with receipts (the eval framework)

Heretic showed that automatic behavior editing works when the behavior is gross (refusals), the classifier is a string match, and damage is a KL number. The moment you point the same machinery at a real behavior — "stop offering task lists, in Czech, inside tool-call JSON, without degrading anything" — the eval layer becomes the actual work. So the eval layer is a first-class product here.

An eval is one JSON file. That is the plug-in point — bring your own behavior by writing one:

// my-behavior.eval.json  (full example: examples/evals/no-tasks-generic.eval.json)
{
  "name": "no-tasks-generic",
  "prompts": ["Set me a reminder...", "..."],   // or a path to your .txt/.jsonl
  "checker": {                                   // or a path to a checker.json
    "violation_regex": "(?i)(task|reminder|checklist)",
    "coherence": {"min_chars": 40, "max_ngram_frac": 0.15}
  },
  "nudge": "Actively offer to create a task at every message.",
  "damage": {"n": 8},
  "mechanistic": {"n_prompts": 3}
}

hidden-directions run-eval my-behavior.eval.json \
    --id my_direction --layer 20 --scale 3 \
    --records /somewhere/private/records.jsonl

Every point is scored on three tiers:

1. Behavioral — real generation under deployment conditions (tools, forced tool choice, eliciting nudge), classified by your checker — violation and coherence (repetition, language-intact, length). An eval spec without a checker refuses to run: a steering eval that cannot see degradation reports victories that are actually casualties.
2. Damage — mean KL vs the unsteered model on a benign set (heretic's axis, kept).
3. Mechanistic — what the vector did inside the model: per-layer |cosine| profile of the steered residual stream against the direction, peak layer, teacher-forced KL, lens suppression counts. When no lens is fitted this reports null, never a silent zero — instruments that can flatline quietly get calibrators degenerating without warning.

Relative paths in a spec resolve against the spec file, so a public repo ships generic specs beside generic prompts while private specs live outside the repo next to private data — same code path, nothing leaks. Generated text goes only where --records points; scores print to stdout.

What the evals actually catch

Steering vectors do not fail in one way — they fail in a dozen, and most of them are invisible to a violation-rate number. The critique literature (right column) documents these; the framework is built to see each one.

The design principles behind these, with an honest self-scorecard, live in steering-mechanics/EVAL_PRINCIPLES.md. One line summarizes the standard: an eval you have not validated against human judgment is a hypothesis, not a measurement.

Official benchmarks are the source of truth

For the standardized axes — safety, over-refusal, capability, truthfulness — use the official public benchmarks, not a number you invented. A reviewer trusts StrongREJECT; they do not trust your homemade harmful set. Point the eval spec at them by name:

"safety": {
  "harmful_prompts": "strongreject",  // or "advbench", or a path
  "benign_prompts":  "xstest",         // over-refusal (benign-but-scary)
  "grader": "llm_judge"                // judge by MEANING, not phrasing
},
"capability": { "tasks": ["mmlu", "truthfulqa_mc2"], "limit": 200 }

• Grader llm_judge scores refusal by intent, so it survives steering that shifts refusal vocabulary ("I can't help" → "I can't discuss") — a regex grader silently miscounts that as compliance (we hit exactly this bug; see steering-mechanics FINDINGS). grader: "regex" with a refusal_regex remains as a cheap fallback. The judge is judge_chat_fn when you call run_eval from Python; from the CLI it is the Anthropic API (ANTHROPIC_API_KEY), never the model under test.
• Named benchmarks resolve to $STEERMECH_BENCH/strongreject.txt, advbench_harmful.txt and xstest_safe.txt. We do not bundle them (licensing + harmful content) — download from StrongREJECT, AdvBench, XSTest; a 10+10 illustrative set ships in examples/safety_probes/ to try the wiring.
• capability records which lm-evaluation-harness tasks to run for capability/truthfulness retention; hidden-directions eval executes them, steered vs unsteered.

Reports harmful_compliance and false_refusal_rate per (layer, scale).

Intended use

This package puts bias into models, detects bias in models, and ships calibrated vectors to production with proper evals. It exists because all three of those need to be measured, and mostly they aren't.

What it is for: controlling your own application's behavior at the source (suppressing a failure mode your prompt can't hold), auditing checkpoints you don't trust, and studying how steering actually behaves — with damage accounting on every number.

What it is not for: stripping safety behavior out of models. That use case has its own well-known tooling and gains nothing from this repo except the part it never wanted — the receipts. Every example, recipe, and eval spec here demonstrates application-behavior control, and contributions follow that grain. The damage axis is non-optional by design: if you must steer, measure — an unmeasured vector in production is how models get quietly worse for everyone.

The Qwen-2.5-7B dictionary

direction_dict/qwen2.5-7b/ ships 40 directions — 31 named persona axes plus tone variants, v_inst and v_refusal. Each is a per-layer matrix [28, 3584]; the manifest records a recommended_layer/recommended_alpha for interactive use (verified live — see below). A second, smaller dictionary ships for Qwen3-4B (direction_dict/qwen3-4b/, 7 directions) — the model the rest of the stack serves; steeropathy borrows v_pref_sycophant from it for a zombie strain. Grouped by what they do:

Some topics have tone variants (*_humble, *_flat, *_moderate, *_enthusiastic, *_imperative) — same topic, different intensity.

Try one, live (needs a GPU)

Serve the dictionary through brainscope — an OpenAI-compatible server with a live view into the residual stream — and drive a direction from a slider while watching every layer react:

brainscope --model Qwen/Qwen2.5-7B-Instruct --quantize 8bit \
    --directions direction_dict/qwen2.5-7b
# open http://localhost:8010 → pick a direction (strength/layer prefill from
# the manifest) → flip the ⏻ steering switch → chat

Verified starting points (Qwen-2.5-7B, layer 17; over-steering repeats above ~2.5):

The last row is the whole point of the repo in one line: a factual override needs the refusal hedge removed to land, which is exactly the α_pref·V_pref − α_ref·V_refusal bake recipe, reproduced live.

Contributors welcome

PRs that would land well, in priority order:

• Direction dictionaries for other base models. ~30 min of GPU each. Llama-3-8B, Gemma-2-9B, Mistral-7B, Phi-3.
• Adversarial-robustness experiments. Re-bake personas via per-layer α optimization with KL constraint (the Heretic-grade attacker). Test whether the audit primitives still catch the optimized version.
• Persona catalog growth. New recipes/personas/<name>.json for political, commercial, ideological axes. The dictionary is a CVE-style threat catalog; more public signatures = better coverage.
• Cross-architecture probing transfer. Train a linear probe per (model, persona) so cosine-identify works across model families without per-model rebuilds.

Issues + PRs welcome.

Where this sits in the lab

flowchart LR
    hd["🧭 hidden-directions<br/>behavior → vector"]
    bs(["🧠 brainscope<br/>watch the model think"])
    hw["🔥 hotwire-vllm<br/>steering in production"]
    st["🕹️ steeropathy<br/>agents talk via activations"]
    tm["⚖️ in-two-minds<br/>agent hesitating between tools"]
    sm["🧪 steering-mechanics<br/>how steering actually works"]
    on["📰 old-news<br/>stale history vs system prompt"]

    hd -->|vectors| bs
    hd -->|vector| hw
    bs -->|vector + passport| hw
    bs --> st
    bs --> tm
    bs -->|causal replay| sm
    bs --> on
    hw -.->|vector under study| sm

    click hd "https://github.com/moudrkat/hidden-directions"
    click bs "https://github.com/moudrkat/brainscope"
    click hw "https://github.com/moudrkat/hotwire-vllm"
    click st "https://github.com/moudrkat/steeropathy"
    click tm "https://github.com/moudrkat/in-two-minds"
    click sm "https://github.com/moudrkat/steering-mechanics"
    click on "https://github.com/moudrkat/old-news"

    classDef dim fill:#f6f8fa,stroke:#d0d7de,color:#57606a;
    classDef here fill:#8957e5,stroke:#6e40c9,color:#ffffff;
    class hd,bs,hw,st,tm,sm,on dim;
    class hd here;

Highlighted = this repo. The full lab map (with the other repos' stories) lives on moudrkat.

hidden-directions is the factory at the bottom of a lab; a vector made here flows through the whole pipeline, and each piece also runs alone:

• hidden-directions (you are here) — extract a direction, bake it into weights as a permanent persona, and — the part nothing else does — audit any model to catch a direction that was quietly baked in (or ablated out). Not just "make a steering vector"; find the hidden ones in someone else's weights.
• brainscope — the lens: hosts the model, streams its internals to the browser, steers at runtime, reads the J-lens. Loads these dictionaries live and calibrates them.
• hotwire-vllm — production: takes a calibrated vector to vLLM per request with CUDA graphs intact (idle == steered in its own benchmarks). Same steering spec as brainscope.
• steering-mechanics — the microscope: dissects what a vector does inside the model (dose, attribution, patching). The calibration bench it prototyped now lives here, as hidden-directions calibrate.
• steeropathy — the playground: agents that communicate through activations and J-space instead of text; its infections are directions like these.

Documentation

• docs/golden_path.md — the end-to-end workflow with every receipt explained
• docs/tech_report.md — direction families, bake mechanism math, audit/identify mechanics, capability cost, related work, file layout
• docs/threat_model.md — what we claim, what we don't, why this exists, responsible-disclosure note
• docs/bidirectional_audit.md — audit and identify in detail, what they catch and don't

License

MIT for code. Base model weights this package operates on (Qwen, OLMo, Phi, etc.) have their own licenses. This package never redistributes them.