quantum-reasoning-skill 1.1.0 → 1.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +205 -71
- package/VERSION +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,86 +1,220 @@
|
|
|
1
|
-
# Quantum Reasoning Skill
|
|
2
|
-
|
|
3
|
-
[](https://pypi.org/project/quantum-reasoning-skill/)
|
|
4
|
-
[](https://www.npmjs.com/package/quantum-reasoning-skill)
|
|
5
|
-
[](https://pypi.org/project/quantum-reasoning-skill/#stats)
|
|
6
|
-
[](LICENSE)
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
1
|
+
# Quantum Reasoning Skill
|
|
2
|
+
|
|
3
|
+
[](https://pypi.org/project/quantum-reasoning-skill/)
|
|
4
|
+
[](https://www.npmjs.com/package/quantum-reasoning-skill)
|
|
5
|
+
[](https://pypi.org/project/quantum-reasoning-skill/#stats)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
|
|
8
|
+
A model-facing [Agent Skill](SKILL.md) that keeps several genuinely different hypotheses
|
|
9
|
+
alive, tests each against evidence and tools, revives alternatives when new evidence arrives,
|
|
10
|
+
and collapses to the best-supported answer only at the end. It is a **metaphor, not quantum
|
|
11
|
+
computing** — "measurement" means letting evidence collapse a branch.
|
|
12
|
+
|
|
13
|
+
> **Status: protocol implemented, controller benchmark published, model evaluation pending.**
|
|
14
|
+
> The skill contract, the reference controller, the benchmark harness and a deterministic
|
|
15
|
+
> falsification benchmark are here and run. **A baseline-vs-skill model evaluation has NOT
|
|
16
|
+
> been published**, so this project makes **no claim that it improves any language model's
|
|
17
|
+
> accuracy.** See [Benchmark status](#benchmark-status) before citing any number from here.
|
|
18
|
+
|
|
19
|
+
## Quick start
|
|
20
|
+
|
|
21
|
+
`SKILL.md` is the deliverable. Three verified paths reach it:
|
|
22
|
+
|
|
20
23
|
```bash
|
|
24
|
+
# 1. from a clone — nothing to install
|
|
25
|
+
git clone https://github.com/Furox-Art/quantum-reasoning-skill.git
|
|
26
|
+
cd quantum-reasoning-skill
|
|
27
|
+
python docs/quickstart.py
|
|
28
|
+
|
|
29
|
+
# 2. from PyPI — SKILL.md ships inside the wheel
|
|
21
30
|
pip install quantum-reasoning-skill
|
|
31
|
+
quantum-reasoning --validate
|
|
32
|
+
|
|
33
|
+
# 3. from npm — also published
|
|
34
|
+
npm i quantum-reasoning-skill
|
|
35
|
+
npx quantum-reasoning --validate
|
|
22
36
|
```
|
|
23
37
|
|
|
24
|
-
|
|
25
|
-
|
|
38
|
+
Copy `SKILL.md` into your host's skill directory, keeping the YAML front matter.
|
|
39
|
+
[`docs/getting-started.md`](docs/getting-started.md) walks the install; prompt shapes are in
|
|
40
|
+
[`examples/usage.md`](examples/usage.md), host integration shapes in
|
|
41
|
+
[`examples/host-integration.md`](examples/host-integration.md), and required host
|
|
42
|
+
capabilities in [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md).
|
|
43
|
+
|
|
44
|
+
`docs/quickstart.py` verifies the checkout, parses the front matter, exercises the controller
|
|
45
|
+
and smoke-tests the benchmark harness; it calls no model and invents no metrics. **Its
|
|
46
|
+
verified output is in [`docs/quickstart.md`](docs/quickstart.md)**, which is the single source
|
|
47
|
+
for it — including the scenario where the thresholds *refuse* to collapse, the clearest
|
|
48
|
+
evidence they are uncalibrated defaults. It is not duplicated here, because a pasted copy
|
|
49
|
+
drifts.
|
|
50
|
+
|
|
51
|
+
## Distribution and the surface it exposes
|
|
52
|
+
|
|
53
|
+
Three channels ship `SKILL.md`, all on one version: a `git clone` (everything); the PyPI
|
|
54
|
+
wheel (`SKILL.md` + `VERSION` as package data, plus `reference/`, `benchmark/`, `docs/`,
|
|
55
|
+
`examples/`, and a `quantum-reasoning` console script); and the npm tarball (`SKILL.md`,
|
|
56
|
+
`VERSION`, `index.js`, `LICENSE`, `README.md`, and a `quantum-reasoning` bin). Both packaged
|
|
57
|
+
artifacts are verified against the **built** artifact, not a checkout.
|
|
26
58
|
|
|
27
|
-
|
|
28
|
-
session.open_branch("strangler-fig incremental")
|
|
29
|
-
session.open_branch("big-bang rewrite")
|
|
30
|
-
session.open_branch("modular monolith refactor")
|
|
59
|
+
### Supply-chain attestations
|
|
31
60
|
|
|
32
|
-
|
|
33
|
-
session.evaluate(evidence="current deploys take 45min", branch="modular monolith", impact=+0.2)
|
|
61
|
+
Only some published versions carry a build attestation, so check before relying on one:
|
|
34
62
|
|
|
35
|
-
|
|
36
|
-
|
|
63
|
+
| release | npm attestation | PyPI PEP 740 attestation |
|
|
64
|
+
| --- | --- | --- |
|
|
65
|
+
| `1.1.0` (npm) | yes — SLSA provenance and npm publish attestation, Sigstore | n/a |
|
|
66
|
+
| `1.1.1` (npm and PyPI) | **no** | **no** |
|
|
67
|
+
|
|
68
|
+
`1.1.1` was published through the long-lived-token path, which cannot produce a Sigstore
|
|
69
|
+
attestation. Attestations are bound to a publish event and cannot be added afterwards, so
|
|
70
|
+
this is permanent for that version. The package itself is unchanged and passes the same
|
|
71
|
+
release contract as every other version; only the provenance *record* is missing.
|
|
72
|
+
|
|
73
|
+
If you need to verify how a build was produced, use `1.1.0` on npm. To check an attestation
|
|
74
|
+
yourself:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
curl -sS -o /dev/null -w '%{http_code}\n' \
|
|
78
|
+
https://registry.npmjs.org/-/npm/v1/attestations/quantum-reasoning-skill@1.1.0 # 200
|
|
79
|
+
curl -sS -o /dev/null -w '%{http_code}\n' \
|
|
80
|
+
https://registry.npmjs.org/-/npm/v1/attestations/quantum-reasoning-skill@1.1.1 # 404
|
|
37
81
|
```
|
|
38
82
|
|
|
39
|
-
|
|
83
|
+
A missing attestation is not evidence of tampering. Versions are locked
|
|
84
|
+
across `VERSION`, `pyproject.toml`, `package.json`, `CITATION.cff` and `CHANGELOG.md` — read
|
|
85
|
+
the value from `VERSION`, not a badge ([details](CONTRIBUTING.md#toolchain-pinning)).
|
|
86
|
+
|
|
87
|
+
There is **no `ReasoningSession` class**. An earlier README claimed one, it never existed, and
|
|
88
|
+
asserting it made the release gate unsatisfiable. The real surface is two *non-compatible*
|
|
89
|
+
CLIs plus a library:
|
|
90
|
+
|
|
91
|
+
| Surface | Flags it actually accepts |
|
|
92
|
+
| --- | --- |
|
|
93
|
+
| `quantum-reasoning` — **Python** console script ([`bin/quantum-reasoning`](bin/quantum-reasoning)) | `--skill-file PATH`, `--validate`, `--json`, `--quiet`, `--help` |
|
|
94
|
+
| `npx quantum-reasoning` — **npm** CLI ([`index.js`](index.js)) | `--validate`, `--json`, `--path`, `--help` |
|
|
95
|
+
| `reference.branch_controller` — Python library | importable; see [Reference controller](#reference-controller) |
|
|
96
|
+
| `quantum_reasoning_skill.SKILL.md`, `.VERSION` | the shipped asset, as package data |
|
|
97
|
+
|
|
98
|
+
`--path` is npm-only; `--skill-file` and `--quiet` are Python-only. An unsupported flag exits
|
|
99
|
+
`2`.
|
|
100
|
+
|
|
101
|
+
## Release contract
|
|
102
|
+
|
|
103
|
+
[`bin/check_release_contract.py`](bin/check_release_contract.py) is the gate CI runs before
|
|
104
|
+
any release. It asserts that `SKILL.md` resolves inside the installed wheel, that the
|
|
105
|
+
`quantum-reasoning` entry point is installed and succeeds against the installed asset, that
|
|
106
|
+
`reference.branch_controller` imports with a callable API, and that the version agrees
|
|
107
|
+
everywhere.
|
|
108
|
+
|
|
109
|
+
**Twelve public names in `reference/branch_controller.py` are frozen** — `DEFAULT_THRESHOLDS`,
|
|
110
|
+
`Branch`, `BranchMetrics`, `BranchState`, `Thresholds`, `branch_score`, `classify_branch`,
|
|
111
|
+
`collapse_decision`, `diversity_ratio`, `recommended_width`, `uncertainty_from_branches`,
|
|
112
|
+
`update_branch_state`. Renaming or removing any one **halts the release**. `WEIGHTS` is
|
|
113
|
+
deliberately *not* on the list: the scoring model can change without breaking the contract.
|
|
114
|
+
|
|
115
|
+
A **negative-control mode** proves the gate is fail-closed across four scenarios — removing
|
|
116
|
+
the installed `SKILL.md`, emptying it, and feeding the controller check a stub missing its
|
|
117
|
+
public API and a module returning wrong values — requiring each to be rejected. It does **not**
|
|
118
|
+
exercise `VERSION` or the console entry point.
|
|
119
|
+
|
|
120
|
+
## Reference controller
|
|
121
|
+
|
|
122
|
+
The control loop behind the protocol: it scores branches, moves them between `active` /
|
|
123
|
+
`dormant` / `rejected`, revives recoverable ones, and decides when a search may collapse. It
|
|
124
|
+
never generates reasoning and never calls a model — it only consumes measurements you supply.
|
|
125
|
+
|
|
126
|
+
| Function | Role |
|
|
127
|
+
| --- | --- |
|
|
128
|
+
| `WEIGHTS`, `DEFAULT_THRESHOLDS`, `Thresholds` | the scoring model: per-metric weights, and the state / revival / collapse thresholds |
|
|
129
|
+
| `BranchMetrics`, `Branch`, `BranchState` | input types; `BranchMetrics` rejects values outside `[0, 1]` |
|
|
130
|
+
| `branch_score`, `effective_independence` | weighted score in `[0, 1]`, after penalising branches that share assumptions or near-duplicate a leader |
|
|
131
|
+
| `classify_branch`, `update_branch_state`, `should_revive` | move a branch to `dormant` or `rejected`, or revive it on material new evidence |
|
|
132
|
+
| `collapse_decision` | `(can_collapse, reason, leader)`; refuses when the margin is too small or a strong alternative is unresolved |
|
|
133
|
+
| `uncertainty_from_branches`, `normalized_entropy` | normalised Shannon entropy over surviving branch scores |
|
|
134
|
+
| `recommended_width` | uncertainty → suggested branch count for the next step |
|
|
135
|
+
| `diversity_ratio`, `rank_branches` | fraction of branch pairs that are materially distinct; ordering helper |
|
|
136
|
+
|
|
137
|
+
Weights and thresholds are **reference defaults, not validated constants** —
|
|
138
|
+
[`docs/MEASUREMENT.md`](docs/MEASUREMENT.md) gives the formulas and the list of values that
|
|
139
|
+
must be calibrated first.
|
|
140
|
+
|
|
141
|
+
## Benchmark harness
|
|
142
|
+
|
|
143
|
+
[`benchmark/`](benchmark/README.md) measures whether the skill helps rather than merely
|
|
144
|
+
producing more text: `benchmark/evaluate.py` (evaluator), `benchmark/validate_submission.py`
|
|
145
|
+
(machine-validates a reproducible bundle), `benchmark/paths.py` (path confinement that rejects
|
|
146
|
+
`..` traversal and symlink escapes), `benchmark/cases.jsonl`, and four JSON Schemas — `case`,
|
|
147
|
+
`result`, `metadata`, `comparison`.
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
python benchmark/evaluate.py --cases benchmark/cases.jsonl --skill skill-results.jsonl
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Inputs are confined to `--cases-dir` (default: each input's own directory), `--output` must
|
|
154
|
+
stay inside it, and reads are bounded by `--max-bytes`. Both `python benchmark/evaluate.py`
|
|
155
|
+
and `python -m benchmark.evaluate` work.
|
|
156
|
+
|
|
157
|
+
## Tests, tooling and governance
|
|
158
|
+
|
|
159
|
+
About **43% of the Python here is tests** — 1,575 of 3,635 lines across **9 test modules**,
|
|
160
|
+
run with the standard library's `unittest` on Python 3.10–3.14 on Linux, Windows and macOS.
|
|
161
|
+
They cover the controller, the benchmark harness, import hardening, path boundaries,
|
|
162
|
+
dependency-lock drift and release-gate polling; `tests/test_readme_badges.py` keeps this
|
|
163
|
+
file's badges honest. The toolchain is pinned twice — `pyproject.toml`'s `dev` group with
|
|
164
|
+
`==`, and [`constraints.txt`](constraints.txt) with `==` **and** `--hash` digests for the full
|
|
165
|
+
transitive closure ([details](CONTRIBUTING.md#toolchain-pinning)).
|
|
166
|
+
|
|
167
|
+
Also here: [`codemeta.json`](codemeta.json) for machine-readable citation beside
|
|
168
|
+
[`CITATION.cff`](CITATION.cff); five issue templates (bug, feature, question, benchmark
|
|
169
|
+
result, plus a chooser in `config.yml`) and a pull-request template; a
|
|
170
|
+
[Code of Conduct](CODE_OF_CONDUCT.md) with a scientific-integrity section; a
|
|
171
|
+
[Security policy](SECURITY.md).
|
|
172
|
+
|
|
173
|
+
## The protocol
|
|
174
|
+
|
|
175
|
+
`SKILL.md` is the normative contract. In short: **frame** the problem (verified vs assumed) →
|
|
176
|
+
**open branches** (genuinely different, not paraphrases) → **evaluate independently** (on
|
|
177
|
+
evidence, not eloquence) → **cross-check** (independently reached conclusions get reinforced)
|
|
178
|
+
→ **prune and revive** (kill contradicted paths, keep dormant ones recoverable) → **collapse**
|
|
179
|
+
(only when one path is clearly better supported). `SKILL.md` also scopes when *not* to use it:
|
|
180
|
+
trivially answerable questions should not pay branching cost.
|
|
181
|
+
|
|
182
|
+
## Benchmark status
|
|
183
|
+
|
|
184
|
+
**What has been measured — the controller, not the model.** On 9 deterministic falsification
|
|
185
|
+
scenarios, the multi-hypothesis branch controller achieved **100% final accuracy versus 22%**
|
|
186
|
+
for a single-hypothesis policy that commits to its first leader (0/4 on falsification
|
|
187
|
+
scenarios, 0/3 on revival scenarios; both policies scored 2/2 on the control scenarios). It
|
|
188
|
+
abandoned the falsified hypothesis at the same evidence step the falsification arrived, and
|
|
189
|
+
revived a rejected-then-supported alternative in 3/3 revival scenarios. Confidence calibration
|
|
190
|
+
showed **no difference** (Brier score 0.033 vs 0.033), and the accuracy gain cost **109.6%
|
|
191
|
+
more tokens** per scenario. Methodology and reproduction:
|
|
192
|
+
[`benchmark/falsification/METHODOLOGY.md`](benchmark/falsification/METHODOLOGY.md).
|
|
193
|
+
|
|
194
|
+
These results measure the reference decision controller on **synthetic evidence streams**, not
|
|
195
|
+
any language model. `benchmark/cases.jsonl` holds six deterministic smoke-test cases that
|
|
196
|
+
prove the harness runs; they are explicitly **not sufficient evidence of reasoning
|
|
197
|
+
improvement**. A baseline-vs-skill **model** evaluation has not been published, so this
|
|
198
|
+
project makes **no claim that it improves any language model's accuracy or costs less
|
|
199
|
+
compute.** Anyone can evaluate on models they have access to; every submitted
|
|
200
|
+
number must carry provenance (script, skill commit, provider and exact model version, run date,
|
|
201
|
+
sampling parameters, repetitions, platform), and one positive run establishes no general claim.
|
|
202
|
+
Rules: [CONTRIBUTING.md](CONTRIBUTING.md#benchmark-provenance-requirements).
|
|
40
203
|
|
|
41
204
|
## How it compares
|
|
42
205
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
1. **Frame the problem** - what do we actually know vs. assume?
|
|
53
|
-
2. **Open branches** - generate genuinely different approaches, not paraphrases
|
|
54
|
-
3. **Evaluate independently** - each branch gets judged on evidence, not eloquence
|
|
55
|
-
4. **Cross-check** - branches that reach the same conclusion independently get boosted
|
|
56
|
-
5. **Prune and revive** - kill contradicted paths, but keep dormant ones that might come back
|
|
57
|
-
6. **Collapse** - only when one answer is clearly better than the rest
|
|
58
|
-
|
|
59
|
-
## Why "quantum"?
|
|
60
|
-
|
|
61
|
-
It's a metaphor, not a claim about actual quantum computing. The idea is to keep possibilities in superposition until measurement (evidence) forces a collapse. Most AI systems measure too early.
|
|
62
|
-
|
|
63
|
-
## Common use cases
|
|
64
|
-
|
|
65
|
-
- **Multi-branch reasoning** for difficult questions where one early answer can anchor the rest of the analysis.
|
|
66
|
-
- **AI agent planning and decision support** with explicit competing hypotheses.
|
|
67
|
-
- Evidence-based **problem solving, search, pruning, and branch selection**.
|
|
68
|
-
- Scientific or technical analysis where independent approaches should be compared before a conclusion is chosen.
|
|
69
|
-
- Benchmarking reasoning systems that need an inspectable explore-score-prune-merge protocol.
|
|
206
|
+
This table describes *mechanisms*, not measured performance. Nothing here has been
|
|
207
|
+
benchmarked against the rows above it.
|
|
208
|
+
|
|
209
|
+
| Approach | Mechanism | Limitation |
|
|
210
|
+
| --- | --- | --- |
|
|
211
|
+
| Chain-of-Thought ([Wei et al., 2022](https://arxiv.org/abs/2201.11903)) | One linear reasoning path | Early anchoring; alternatives are never kept alive |
|
|
212
|
+
| Tree-of-Thought ([Yao et al., 2023](https://arxiv.org/abs/2305.10601)) | Branch plus heuristic scoring | Scoring is fixed in advance; no evidence weighting or revival |
|
|
213
|
+
| Self-consistency ([Wang et al., 2022](https://arxiv.org/abs/2203.11171)) | Samples one prompt N times | Paraphrase diversity, not hypothesis diversity |
|
|
214
|
+
| **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. |
|
|
70
215
|
|
|
71
216
|
## Documentation
|
|
72
217
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
- [Branch controller reference](reference/branch_controller.py)
|
|
77
|
-
- [Measurement methodology](docs/MEASUREMENT.md)
|
|
78
|
-
- [Compatibility notes](docs/COMPATIBILITY.md)
|
|
79
|
-
- [Benchmark documentation](benchmark/README.md)
|
|
80
|
-
- [Contributing](CONTRIBUTING.md)
|
|
81
|
-
- [Security](SECURITY.md)
|
|
82
|
-
- [Citation metadata](CITATION.cff)
|
|
83
|
-
|
|
84
|
-
## License
|
|
85
|
-
|
|
86
|
-
MIT.
|
|
218
|
+
Everything lives in [`docs/index.md`](docs/index.md) — getting started, quickstart and its
|
|
219
|
+
verified output, measurement methodology, host compatibility, report forms. Release history:
|
|
220
|
+
[CHANGELOG.md](CHANGELOG.md). License: [MIT](LICENSE).
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
1.1.
|
|
1
|
+
1.1.2
|