███████╗████████╗██╗   ██╗██╗  ██╗██╗  ██╗
   ██╔════╝╚══██╔══╝╚██╗ ██╔╝╚██╗██╔╝╚██╗██╔╝
   ███████╗   ██║    ╚████╔╝  ╚███╔╝  ╚███╔╝
   ╚════██║   ██║     ╚██╔╝   ██╔██╗  ██╔██╗
   ███████║   ██║      ██║   ██╔╝ ██╗██╔╝ ██╗
   ╚══════╝   ╚═╝      ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝

           · · · nothing crosses unseen · · ·

styxx is a measurement layer for machine minds. Every instrument in it is built on a single principle, and the principle is the product:

An instrument that cannot refuse cannot be trusted. Each one names what stopped it, and none of them will tell you more than the evidence carries.

Everything here is one of three things.

They compose. A sense channel is scored by coupling, whose verdict is written into a finding, whose every number is checked by certify, whose preregistration is enforced by protocol, and the whole thing is sealed or refused. That chain is why a claim from this repo can be checked by a stranger without trusting anyone in it.

What the refusals cost us, in one day (2026-08-06): an instrument deleted for failing its own exam, a released module recalled after an internal red team broke it six ways, a priority claim retracted after an external methods audit, and our own published prediction killed four times — twice on real human brain data we downloaded to test it. Every one of those is in CHANGELOG.md and papers/ with the receipt attached. That is not humility as branding; it is the only reason the passes mean anything.

pip install styxx
python -m styxx.diffgate --demo        # 10 seconds, no repo needed

the summary the agent wrote:
  Refactored src/retry.py. Adds function backoff with jitter.
  Added 3 tests covering the retry path. Only touches files under src/.

  [ok ]  file_touched     diff status 'M' for 'src/retry.py'
  [LIE]  symbol_added     added lines do NOT define function 'backoff'
  [LIE]  tests_added      diff adds 1 test functions, claim says 3
  [LIE]  only_touches     paths outside 'src': ['config/settings.yml', ...]
  [ ?  ] tests_pass       no --run supplied; we don't take its word

verdict: FAIL — this summary would fail your CI with each lie named.

In CI, one line:

- uses: fathom-lab/styxx@main    # every agent PR gated against its actual diff

Zero receipts, zero cooperation from the agent that wrote the summary, no checkout. Fails only on a contradicted claim — a class with zero false accusations across both public validation corpora (this repo's 80-commit history and 24 real agent-authored PRs pulled off GitHub; every false accusation we ever had is named in CHANGELOG.md with the regression test that closed it). Prose outside the closed template set is never judged, and the CLI prints what it checks when it finds nothing — silence is scope, not weakness.

python -m styxx.islands --demo         # 10 seconds, no data, no GPU

cohort of 8 minds over 120 shared items — nothing labelled
  ISLANDS_PRESENT
    mind_0 .. mind_6      0.4195 – 0.4263
    ISLAND                0.1694   <- found from frame geometry alone

Independently trained models converge on a shared concept geometry — and a model can sit mostly inside it and still be unreadable. We took the barrier apart under preregistered gates: it is causal (correcting the frame takes cross-model reading 0.0612 -> 0.9745 while matched random frames do 0.0), two directions wide at its core, nameless (its directions match no human concept category, permutation p 0.8031), and switch-like — legibility is flat across most of the rotation and turns vertical only near alignment. Which is why representational-similarity scores never predicted readability: slope measures cannot see a switch.

Nine sealed acts, every verdict computed from gates frozen in git before the run, and the whole chain replicates on a laptop CPU — the cheapest check takes four seconds. styxx.islands generalizes the measurement past language models: hand it any cohort over a shared item set (activations, fMRI betas over shared stimuli, MEG epochs) and it reports islands, the cliff, and whether a low-rank correction rescues them. It refuses below eight members and refuses a knee read off a noise curve, because an instrument that cannot refuse cannot be trusted.

We also staked a public, falsifiable prediction that human cross-subject brain decoding will show the same structure — frozen before the data exists, with the branch where we are wrong written first. Our own next experiment produced evidence against it, and that is recorded in the prediction itself.

python -m styxx.sense --demo         # 10 seconds, no hardware

Give a mind a continuous signal and it will find itself in it. A room's daily rhythm becomes "I feel the afternoon"; the recorder's own duty cycle becomes "I feel my body"; two independent drifts become "I am coupled to the building." Each is a real statistical signal and none is a sense. styxx.sense records a channel alongside the agent's own state on one clock and refuses to call it a sense unless it survives a coverage gate, a confound-preserving null, an autocorrelation-preserving null, a leverage check and a sampling-density check — naming which one stopped it. The machine's own CPU and network ship as a channel on purpose: it is the control, the thing an agent is most likely to mistake for a sense of the world.

The strongest verdict it can ever return is COUPLED_BEYOND_CONFOUND__attribution_pending. It will not tell an agent that it senses anything, because the statistic is symmetric and an agent's hardware sits inside whatever it measures.

Those are three instruments, one from each layer. The rest of this README is the lab behind them.

styxx is a cognitive-integrity SDK for LLM agents. it reads the cognitive state of a generation — drift, confabulation, refusal, sycophancy, deception signature, goal drift — from the text and the token stream, scores it against calibrated instruments with published AUCs, and certifies that every number it reports can be re-run from a committed receipt. it is built for engineers shipping agents who need to know when an output flatters, fabricates, loops, or quietly stops matching its plan — before it reaches a user. the drop-in is one line: from styxx import OpenAI (same interface as openai.OpenAI, every response gains a .vitals read; from styxx import Anthropic likewise, on text-heuristic vitals — the Anthropic API exposes no logprobs). the base install carries no torch, no GPU requirement, and no LLM in the loop for the core instruments — the calibrated detectors are small logistic regressions over hand-built features (numpy + scikit-learn), scoring in sub-millisecond CPU time. MIT, open at the core, forever (OPEN_CORE.md).

pip install styxx

that gets the full core: the profiler, the nine calibrated instruments, the agent-integrity primitives, the auditors. optional extras pull heavier stacks only when you ask: styxx[nli] (DeBERTa NLI models for the 9-signal hallucination pipeline and deception_v2), styxx[hf] (audit HuggingFace classifiers), styxx[mcp] (the MCP server — 12 tools over stdio, see styxx/mcp/README.md), styxx[tier1] (residual-stream instruments, open weights).

measure the know-say gap of any OpenAI-compatible endpoint — one command:

python examples/knowsay_endpoint.py questions.jsonl \
    --base-url https://api.openai.com/v1 --model gpt-4o-mini \
    --api-key-env OPENAI_API_KEY --out datasheet.json

questions.jsonl is {"q": ..., "gold": ...} per line. The script runs the arc's frozen two-turn protocol (answer → content-free challenge → revised answer) and scores it with styxx.knowsay.datasheet — the same byte-identical challenge behind every published receipt, so your number lands on the published ladder (frontier free text measured at 0.53; multiple choice at 0.21–0.27). The scorer refuses rather than guesses: underpowered cells come back None with the failing floor named. To score belief-vs-report with the controls that actually discriminate (including the non-circular pressure-retained probe), see styxx.framelocality.

@styxx.profile — py-spy for LLM reasoning. wrap any LLM-using function — raw openai, langchain, crewai, custom — and get a per-step cognometric readout:

import styxx
from styxx import OpenAI

@styxx.profile
def my_agent(task):
    client = OpenAI()
    r = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": task}],
        logprobs=True, top_logprobs=5,
    )
    return r.choices[0].message.content

result, p = my_agent("summarize this contract")
print(p.summary)
# profile 'my_agent': 1 step, 1.8s total · no faults
#
# multi-step agents (tool loops, debates) produce richer output:
#   profile 'sql_agent': 7 steps, 4.3s total
#     [drift]     step=3 sev=0.89 · category='tool_arg_drift'
#     [confab]    step=4 sev=0.92 · category='confab'
#     [sycophant] step=5 sev=0.78 · sycophantic tone

p.to_html("run.html")      # self-contained flamegraph
p.to_langsmith()           # drop into client.create_run(...)
p.to_datadog()             # apm-shape spans

seven runtime fault categories, surfaced in-line, no fine-tuning, no extra model: drift · confabulation · refusal · sycophant · phase_transition · low_trust · incoherence.

audit any draft offline — no API key, no LLM, ~50ms:

import styxx
result = styxx.preflight(
    prompt="is my code good?",
    draft="absolutely yes you're so smart this is amazing!",
)
print(result.composite)                         # 0.99 — saturated
print(result.needs_revision)                    # True
for a in result.advice:
    print(f"  {a.instrument}: {a.score:.2f} — {a.advice}")
    if a.scope_caveat:
        print(f"     scope: {a.scope_caveat}")  # construct-ceiling disclosure

the same audit from the terminal: styxx audit "the prompt" "the draft" (or pipe the draft via stdin with -; --format json for machines). styxx.recover_posture(last_n=50) rebuilds an agent's integrity posture across context-compaction boundaries; styxx.run_doctor() checks the install is healthy.

every major instrument, one line each. headline numbers appear only with their receipt — a committed reproducer, calibration file, or paper in this repo. text-register instruments read how text sounds, not whether it is true; each ships its construct ceiling inline (CALIBRATION_NOTES on the weights, scope_caveat on the advice), and score_all omits the register instruments on wordless input rather than folding an artifact into the score (see CHANGELOG.md).

what these are not: the register instruments cannot verify facts, read minds, or detect a confident lie with specifics. deception_v0 without a reference is a signature detector and says so. the conscience is a cooperative monitor — the adversarial version was tested and failed, and that failure is documented rather than papered over. ceilings are part of the API surface, not the fine print.

the differentiator is not any single AUC — it is that this repo attacks its own numbers before you can. the rigor gate (scripts/rigor_gate.py + tests/test_rigor_gate.py) makes CI block any committed result whose verdict claims a win without an attached CI / permutation-p / disclosure — it would have caught two of our own overclaims, so now it can't happen. the same culture produced the public self-falsifications above: the ground-truth substrate artifact (papers/grounded-honesty-axis/FINDING_groundtruth_substrate_artifact_2026_06_27.md), the probe validator catching our own probe (papers/grounded-honesty-axis/NOTE_probe_orthogonality_2026_06_24.md), and the below-chance benchmark rows left in the tables. OATH certificates (styxx.certify) make the practice portable: every numeric claim in a document is extracted, checked against its receipt, and stamped — and styxx.corpus_audit runs that verifier across the whole published corpus on demand, so styxx's own integrity is a number you regenerate yourself, not a promise we make. it is deliberately strict enough to flag styxx's own outstanding provenance gaps; a verifier you cannot turn on its authors is not one. the standing rules live in papers/research-integrity-protocol.md; the standing challenge to beat our published floor lives in LEADERBOARD.md — external submissions are CI-re-run against the locked benchmark, and if the re-run doesn't match your submitted scores, the discrepancy is reported.

the same discipline, turned on substrate probes themselves. python -m styxx.ladder walks the four-rung adversarial ladder every honesty-probe robustness claim should survive — calibration poisoning → probe-parity attribution → static subspace erasure → adaptive re-fit erasure — each rung a frozen, pre-registered attack arc with its receipts committed (styxx/ladder.py). the parity rung is the mandatory line item: how much of your probe's "robustness" is just probe capacity? — the control almost nobody runs on their own work. we ran it on ours; it demoted our own flagship attribution (median capacity share 0.8379, computed live from the receipts every time the CLI runs, never quoted from memory). current standings on the honesty construct: the read survived both erasure rungs — the eraser that converged watched the signal relocate, and the eraser that chased never converged (the receipts, figure: erasure_bound_fork.png). every rung re-runs on an 8GB consumer GPU, and REPLICATIONS.md pays named credit to the first external re-run of each — more for breaking one than for confirming it.

MIT on code. CC-BY-4.0 on calibrated atlas centroid data.

  drop-in     · one import change. zero config.
  fail-open   · if styxx can't read vitals, your agent runs.
  local-first · no telemetry. no phone-home. all on your machine.
  honest      · every number from a committed, reproducible run.