BreakState tests whether latent line-position representations causally control fixed-width line-breaking decisions in small language models.
This repository is a compact mechanistic-interpretability research scaffold, not a finished causal result. It currently supports controlled fixed-width linebreaking datasets, behavioral scoring, activation readouts, held-out-family splits, metadata baselines, shuffled-label controls, and cache identity checks.
| Area | Status | Claim boundary |
|---|---|---|
| Dataset invariants | Implemented and unit-tested | Exact labels for controlled ASCII fixed-width wrapping |
| Behavioral scoring | Implemented | Behavioral evidence only, not an internal mechanism |
| Activation readouts | Implemented with Hugging Face hidden states | Decodability diagnostics, not calibrated beliefs |
| Controls | Held-out-family splits, metadata baselines, shuffled labels | Required before interpreting a readout |
| Causal interventions | Not implemented | No causal or posterior claim is supported yet |
The current evidence ceiling is methodological: high activation readout accuracy can be explained by metadata shortcuts or output confidence, so decodability is treated as a checkpoint rather than mechanistic proof.
When a small language model predicts whether the next word fits on the current fixed-width line, do internal representations of current position, remaining space, or inferred line width causally affect the newline-versus-continuation decision?
The code builds controlled prompt families where line width, current character count, remaining space, next-word length, source family, and semantic continuation can be varied separately. The current implementation uses Hugging Face model outputs for behavioral scores and hidden-state readouts. The next causal phase should move the intervention path onto TransformerLens hooks before any patching or steering result is claimed.
Create an environment and run the local verification suite:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
python -m pytest -qGenerate a small deterministic dataset:
python scripts/generate_dataset.py --output /tmp/breakstate_demo.jsonlOptional model-backed commands require the model extra:
python -m pip install -e ".[model]"
python scripts/run_loop7_behavioral_smoke.py --help
python scripts/run_probe_smoke.py --helpsrc/linebreak_uncertainty/: dataset, wrapping, scoring, activation, probe, attention, geometry, and control utilities.scripts/: reproducible dataset, behavioral, probe, attention, and summary entry points.tests/: invariants for datasets, splits, cache identity, probes, summaries, and command-line surfaces.data/source_manifests/: small public fixture manifests and source notices.docs/experiment-ledger.md: concise status ledger and claim boundaries.docs/dataset-schema.md: linebreaking example schema and label semantics.docs/limitations.md: current evidence boundary.UPSTREAM.md: upstream dependency and future TransformerLens integration notes.
The checked-in repository supports local engineering verification and controlled readout diagnostics. It does not contain a completed causal intervention, a calibrated internal uncertainty metric, a scale result, or a claim about closed models. Any future causal claim should include raw records, deterministic summaries, a preregistered intervention position, random-direction controls, unrelated-position controls, and held-out source-family evaluation.
The current task uses ASCII monospace wrapping, small open models, controlled
fixtures, and simple readout probes. It excludes Unicode layout, typography,
manual line breaks, production formatters, multilingual text, and closed-model
internals. See docs/limitations.md for the full scope boundary.
This repository is released under the license in this checkout. The research
question is motivated by fixed-width linebreaking work in transformer circuits;
see docs/literature.md and UPSTREAM.md for attribution and dependency notes.