Quantum Reasoning Skill
A model-facing Agent Skill that keeps several genuinely different hypotheses alive, tests each against evidence and tools, revives alternatives when new evidence arrives, and collapses to the best-supported answer only at the end. It is a metaphor, not quantum computing — "measurement" means letting evidence collapse a branch.
Status: protocol implemented, controller benchmark published, model evaluation pending. The skill contract, the reference controller, the benchmark harness and a deterministic falsification benchmark are here and run. A baseline-vs-skill model evaluation has NOT been published, so this project makes no claim that it improves any language model's accuracy. See Benchmark status before citing any number from here.
Quick start
SKILL.md is the deliverable. Three verified paths reach it:
# 1. from a clone — nothing to install
git clone https://github.com/Furox-Art/quantum-reasoning-skill.git
cd quantum-reasoning-skill
python docs/quickstart.py
# 2. from PyPI — SKILL.md ships inside the wheel
pip install quantum-reasoning-skill
quantum-reasoning --validate
# 3. from npm — also published
npm i quantum-reasoning-skill
npx quantum-reasoning --validate
Copy SKILL.md into your host's skill directory, keeping the YAML front matter.
docs/getting-started.md walks the install; prompt shapes are in
examples/usage.md, host integration shapes in
examples/host-integration.md, and required host
capabilities in docs/COMPATIBILITY.md.
docs/quickstart.py verifies the checkout, parses the front matter, exercises the controller
and smoke-tests the benchmark harness; it calls no model and invents no metrics. Its
verified output is in docs/quickstart.md, which is the single source
for it — including the scenario where the thresholds refuse to collapse, the clearest
evidence they are uncalibrated defaults. It is not duplicated here, because a pasted copy
drifts.
Distribution and the surface it exposes
Three channels ship SKILL.md, all on one version: a git clone (everything); the PyPI
wheel (1.2.0 packaging: SKILL.md, VERSION, reference/, benchmark/, docs/ and
examples/ ship under the quantum_reasoning_skill/ package namespace, plus a
quantum-reasoning console script backed by quantum_reasoning_skill.cli); and the npm
tarball (SKILL.md, VERSION, index.js, LICENSE, README.md, and a
quantum-reasoning bin). Both packaged artifacts are verified against the built
artifact, not a checkout. Checkouts and installed distributions use the same canonical
paths: the reference controller and benchmark harness live under
quantum_reasoning_skill/, so the wheel and the source tree expose one import layout.
Supply-chain attestations
Only some published versions carry a build attestation, so check before relying on one:
| release | npm attestation | PyPI PEP 740 attestation |
|---|---|---|
1.1.0 (npm) |
yes — SLSA provenance and npm publish attestation, Sigstore | n/a |
1.1.1 (npm and PyPI) |
no | no |
1.1.1 was published through the long-lived-token path, which cannot produce a Sigstore
attestation. Attestations are bound to a publish event and cannot be added afterwards, so
this is permanent for that version. The package itself is unchanged and passes the same
release contract as every other version; only the provenance record is missing.
If you need to verify how a build was produced, use 1.1.0 on npm. To check an attestation
yourself:
curl -sS -o /dev/null -w '%{http_code}\n' \
https://registry.npmjs.org/-/npm/v1/attestations/quantum-reasoning-skill@1.1.0 # 200
curl -sS -o /dev/null -w '%{http_code}\n' \
https://registry.npmjs.org/-/npm/v1/attestations/quantum-reasoning-skill@1.1.1 # 404
A missing attestation is not evidence of tampering. Versions are locked
across VERSION, pyproject.toml, package.json, CITATION.cff and CHANGELOG.md — read
the value from VERSION, not a badge (details).
There is no ReasoningSession class. An earlier README claimed one, it never existed, and
asserting it made the release gate unsatisfiable. The real surface is two non-compatible
CLIs plus a library:
| Surface | Flags it actually accepts |
|---|---|
quantum-reasoning — Python console script; implementation quantum_reasoning_skill.cli (checkout launcher: bin/quantum-reasoning) |
--skill-file PATH, --validate, --json, --quiet, --help |
npx quantum-reasoning — npm CLI (index.js) |
--validate, --json, --path, --help |
quantum_reasoning_skill.reference.branch_controller — Python library |
importable; see Reference controller |
quantum_reasoning_skill.SKILL.md, .VERSION |
the shipped asset, as package data |
--path is npm-only; --skill-file and --quiet are Python-only. An unsupported flag exits
2.
Release contract
bin/check_release_contract.py is the gate CI runs before
any release. It asserts that SKILL.md resolves inside the installed wheel, that the
quantum-reasoning entry point is installed and succeeds against the installed asset, that
quantum_reasoning_skill.reference.branch_controller imports with a callable API, and that the version agrees
everywhere.
Twelve public names in quantum_reasoning_skill/reference/branch_controller.py are frozen — DEFAULT_THRESHOLDS,
Branch, BranchMetrics, BranchState, Thresholds, branch_score, classify_branch,
collapse_decision, diversity_ratio, recommended_width, uncertainty_from_branches,
update_branch_state. Renaming or removing any one halts the release. WEIGHTS is
deliberately not on the list: the scoring model can change without breaking the contract.
A negative-control mode proves the gate is fail-closed across four scenarios — removing
the installed SKILL.md, emptying it, and feeding the controller check a stub missing its
public API and a module returning wrong values — requiring each to be rejected. It does not
exercise VERSION or the console entry point.
Reference controller
The control loop behind the protocol: it scores branches, moves them between active /
dormant / rejected, revives recoverable ones, and decides when a search may collapse. It
never generates reasoning and never calls a model — it only consumes measurements you supply.
| Function | Role |
|---|---|
WEIGHTS, DEFAULT_THRESHOLDS, Thresholds |
the scoring model: per-metric weights, and the state / revival / collapse thresholds |
BranchMetrics, Branch, BranchState |
input types; BranchMetrics rejects values outside [0, 1] |
branch_score, effective_independence |
weighted score in [0, 1], after penalising branches that share assumptions or near-duplicate a leader |
classify_branch, update_branch_state, should_revive |
move a branch to dormant or rejected, or revive it on material new evidence |
collapse_decision |
(can_collapse, reason, leader); refuses when the margin is too small or a strong alternative is unresolved. The high-information guard runs before the generic margin check — its band sits inside the generic one, so the other order hides it |
uncertainty_from_branches, normalized_entropy |
normalised Shannon entropy over surviving branch scores |
recommended_width |
uncertainty → suggested branch count for the next step |
diversity_ratio, rank_branches |
fraction of branch pairs that are materially distinct; ordering helper |
Weights and thresholds are reference defaults, not validated constants —
docs/MEASUREMENT.md gives the formulas and the list of values that
must be calibrated first.
Benchmark harness
quantum_reasoning_skill/benchmark/ measures whether the skill helps rather than merely
producing more text: quantum_reasoning_skill/benchmark/evaluate.py (evaluator),
quantum_reasoning_skill/benchmark/validate_submission.py
(machine-validates a reproducible bundle), quantum_reasoning_skill/benchmark/paths.py
(path confinement that rejects .. traversal and symlink escapes),
quantum_reasoning_skill/benchmark/cases.jsonl, and four JSON Schemas — case,
result, metadata, comparison.
python quantum_reasoning_skill/benchmark/evaluate.py \
--cases quantum_reasoning_skill/benchmark/cases.jsonl \
--skill skill-results.jsonl
--cases is optional: it defaults to the packaged seed cases. Paths are resolved against the
current working directory, so the command above runs unchanged from a fresh clone. If a named
file does not exist the evaluator prints a typed error, names the flag, and exits 2 — it never
substitutes placeholder rows, because a fabricated measurement is worse than a missing one.
Inputs are confined to --cases-dir (default: each input's own directory), --output must
stay inside it, and reads are bounded by --max-bytes. Both
python quantum_reasoning_skill/benchmark/evaluate.py and
python -m quantum_reasoning_skill.benchmark.evaluate work.
Tests, tooling and governance
About 53% of the Python here is tests — 5,543 of 10,512 lines across 25 test modules,
run with the standard library's unittest on Python 3.10–3.14 (Linux) and 3.12 (Windows, macOS).
They cover the controller, the benchmark harness, import hardening, path boundaries,
dependency-lock drift and release-gate polling; the documented benchmark command run as a
subprocess against a clean copy of the tree; the paths filters that decide when a release
publishes, derived from pyproject.toml and package.json rather than hand-listed; and
tests/test_docs_counts.py, which recomputes the counts in this paragraph so they cannot go
stale, beside tests/test_readme_badges.py keeping this file's badges honest. The toolchain is
pinned twice — pyproject.toml's dev group with
==, and constraints.txt with == and --hash digests for the full
transitive closure (details).
All numeric comparisons in the suite use one documented tolerance
(conftest.NUMERIC_TOLERANCE = 1e-6), chosen because the committed artifacts round their
floats to six decimals — exact equality rejects correct artifacts
(rationale).
Also here: codemeta.json for machine-readable citation beside
CITATION.cff; five issue templates (bug, feature, question, benchmark
result, plus a chooser in config.yml) and a pull-request template; a
Code of Conduct with a scientific-integrity section; a
Security policy.
The protocol
SKILL.md is the normative contract. In short: frame the problem (verified vs assumed) →
open branches (genuinely different, not paraphrases) → evaluate independently (on
evidence, not eloquence) → cross-check (independently reached conclusions get reinforced)
→ prune and revive (kill contradicted paths, keep dormant ones recoverable) → collapse
(only when one path is clearly better supported). SKILL.md also scopes when not to use it:
trivially answerable questions should not pay branching cost.
Benchmark status
What has been measured — the controller, not the model. On 9 deterministic falsification
scenarios, the multi-hypothesis branch controller achieved 100% final accuracy versus 22%
for a single-hypothesis policy that commits to its first leader (0/4 on falsification
scenarios, 0/3 on revival scenarios; both policies scored 2/2 on the control scenarios). It
abandoned the falsified hypothesis at the same evidence step the falsification arrived, and
revived a rejected-then-supported alternative in 3/3 revival scenarios. Confidence calibration
showed no difference (Brier score 0.033 vs 0.033), and the accuracy gain cost 109.6%
more tokens per scenario. Methodology and reproduction:
quantum_reasoning_skill/benchmark/falsification/METHODOLOGY.md.
These results measure the reference decision controller on synthetic evidence streams, not
any language model. quantum_reasoning_skill/benchmark/cases.jsonl holds six deterministic smoke-test cases that
prove the harness runs; they are explicitly not sufficient evidence of reasoning
improvement. A baseline-vs-skill model evaluation has not been published, so this
project makes no claim that it improves any language model's accuracy or costs less
compute. Anyone can evaluate on models they have access to; every submitted
number must carry provenance (script, skill commit, provider and exact model version, run date,
sampling parameters, repetitions, platform), and one positive run establishes no general claim.
Rules: CONTRIBUTING.md.
How it compares
This table describes mechanisms, not measured performance. Nothing here has been benchmarked against the rows above it.
| Approach | Mechanism | Limitation |
|---|---|---|
| Chain-of-Thought (Wei et al., 2022) | One linear reasoning path | Early anchoring; alternatives are never kept alive |
| Tree-of-Thought (Yao et al., 2023) | Branch plus heuristic scoring | Scoring is fixed in advance; no evidence weighting or revival |
| Self-consistency (Wang et al., 2022) | Samples one prompt N times | Paraphrase diversity, not hypothesis diversity |
| This skill | Branches with evidence-weighted scores, correlation penalties, dormancy with revival, explicit collapse criteria | Not yet validated: no published result. Branch breadth costs tokens and latency. Needs a host that persists instructions. |
Documentation
Everything lives in docs/index.md — getting started, quickstart and its
verified output, measurement methodology, host compatibility, report forms. Release history:
CHANGELOG.md. License: MIT.
Metadata
Release files for quantum-reasoning-skill 1.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| quantum_reasoning_skill-1.2.0.tar.gz | 168.4 kB | With provenance | Details for quantum_reasoning_skill-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| quantum_reasoning_skill-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for quantum_reasoning_skill-1.2.0-py3-none-any.whl |
Total release size: 248.3 kB
Release files / quantum_reasoning_skill-1.2.0.tar.gz
| Download URL | quantum_reasoning_skill-1.2.0.tar.gz |
|---|---|
| Size | 168.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
abe81378ef3d752b2c71ca01171ff69859da0e10d1ad670d38930446ecf72103
|
|
BLAKE2b-256 checksum How to use checksums |
fb7a89b4bfee510b9046329ad685ebb8eeeddccac1a409e1f228509858883f1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / quantum_reasoning_skill-1.2.0-py3-none-any.whl
| Download URL | quantum_reasoning_skill-1.2.0-py3-none-any.whl |
|---|---|
| Size | 79.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0dde1013b8497ee254bcd23969e96ca5f2b1d3739751724b59bdf0febd632d4e
|
|
BLAKE2b-256 checksum How to use checksums |
f01f6f33dc517b2f377dcd189e864e9b1229946e112a9a39e394eb01723f4151
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for quantum-reasoning-skill 1.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for quantum_reasoning_skill-1.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.