quantum-reasoning-skill 1.1.0 → 1.1.1
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 +166 -71
- package/VERSION +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,86 +1,181 @@
|
|
|
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, effectiveness not yet demonstrated.** The skill contract,
|
|
14
|
+
> the reference controller and the benchmark harness are here and run. **No
|
|
15
|
+
> baseline-vs-skill model evaluation has been published**, so this project makes **no claim
|
|
16
|
+
> that it improves accuracy or costs less compute.** See
|
|
17
|
+
> [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, 1.1.0
|
|
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. Versions are locked
|
|
58
|
+
across `VERSION`, `pyproject.toml`, `package.json`, `CITATION.cff` and `CHANGELOG.md` — read
|
|
59
|
+
the value from `VERSION`, not a badge ([details](CONTRIBUTING.md#toolchain-pinning)).
|
|
60
|
+
|
|
61
|
+
There is **no `ReasoningSession` class**. An earlier README claimed one, it never existed, and
|
|
62
|
+
asserting it made the release gate unsatisfiable. The real surface is two *non-compatible*
|
|
63
|
+
CLIs plus a library:
|
|
64
|
+
|
|
65
|
+
| Surface | Flags it actually accepts |
|
|
66
|
+
| --- | --- |
|
|
67
|
+
| `quantum-reasoning` — **Python** console script ([`bin/quantum-reasoning`](bin/quantum-reasoning)) | `--skill-file PATH`, `--validate`, `--json`, `--quiet`, `--help` |
|
|
68
|
+
| `npx quantum-reasoning` — **npm** CLI ([`index.js`](index.js)) | `--validate`, `--json`, `--path`, `--help` |
|
|
69
|
+
| `reference.branch_controller` — Python library | importable; see [Reference controller](#reference-controller) |
|
|
70
|
+
| `quantum_reasoning_skill.SKILL.md`, `.VERSION` | the shipped asset, as package data |
|
|
71
|
+
|
|
72
|
+
`--path` is npm-only; `--skill-file` and `--quiet` are Python-only. An unsupported flag exits
|
|
73
|
+
`2`.
|
|
74
|
+
|
|
75
|
+
## Release contract
|
|
76
|
+
|
|
77
|
+
[`bin/check_release_contract.py`](bin/check_release_contract.py) is the gate CI runs before
|
|
78
|
+
any release. It asserts that `SKILL.md` resolves inside the installed wheel, that the
|
|
79
|
+
`quantum-reasoning` entry point is installed and succeeds against the installed asset, that
|
|
80
|
+
`reference.branch_controller` imports with a callable API, and that the version agrees
|
|
81
|
+
everywhere.
|
|
26
82
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
83
|
+
**Twelve public names in `reference/branch_controller.py` are frozen** — `DEFAULT_THRESHOLDS`,
|
|
84
|
+
`Branch`, `BranchMetrics`, `BranchState`, `Thresholds`, `branch_score`, `classify_branch`,
|
|
85
|
+
`collapse_decision`, `diversity_ratio`, `recommended_width`, `uncertainty_from_branches`,
|
|
86
|
+
`update_branch_state`. Renaming or removing any one **halts the release**. `WEIGHTS` is
|
|
87
|
+
deliberately *not* on the list: the scoring model can change without breaking the contract.
|
|
31
88
|
|
|
32
|
-
|
|
33
|
-
|
|
89
|
+
A **negative-control mode** proves the gate is fail-closed across four scenarios — removing
|
|
90
|
+
the installed `SKILL.md`, emptying it, and feeding the controller check a stub missing its
|
|
91
|
+
public API and a module returning wrong values — requiring each to be rejected. It does **not**
|
|
92
|
+
exercise `VERSION` or the console entry point.
|
|
34
93
|
|
|
35
|
-
|
|
36
|
-
|
|
94
|
+
## Reference controller
|
|
95
|
+
|
|
96
|
+
The control loop behind the protocol: it scores branches, moves them between `active` /
|
|
97
|
+
`dormant` / `rejected`, revives recoverable ones, and decides when a search may collapse. It
|
|
98
|
+
never generates reasoning and never calls a model — it only consumes measurements you supply.
|
|
99
|
+
|
|
100
|
+
| Function | Role |
|
|
101
|
+
| --- | --- |
|
|
102
|
+
| `WEIGHTS`, `DEFAULT_THRESHOLDS`, `Thresholds` | the scoring model: per-metric weights, and the state / revival / collapse thresholds |
|
|
103
|
+
| `BranchMetrics`, `Branch`, `BranchState` | input types; `BranchMetrics` rejects values outside `[0, 1]` |
|
|
104
|
+
| `branch_score`, `effective_independence` | weighted score in `[0, 1]`, after penalising branches that share assumptions or near-duplicate a leader |
|
|
105
|
+
| `classify_branch`, `update_branch_state`, `should_revive` | move a branch to `dormant` or `rejected`, or revive it on material new evidence |
|
|
106
|
+
| `collapse_decision` | `(can_collapse, reason, leader)`; refuses when the margin is too small or a strong alternative is unresolved |
|
|
107
|
+
| `uncertainty_from_branches`, `normalized_entropy` | normalised Shannon entropy over surviving branch scores |
|
|
108
|
+
| `recommended_width` | uncertainty → suggested branch count for the next step |
|
|
109
|
+
| `diversity_ratio`, `rank_branches` | fraction of branch pairs that are materially distinct; ordering helper |
|
|
110
|
+
|
|
111
|
+
Weights and thresholds are **reference defaults, not validated constants** —
|
|
112
|
+
[`docs/MEASUREMENT.md`](docs/MEASUREMENT.md) gives the formulas and the list of values that
|
|
113
|
+
must be calibrated first.
|
|
114
|
+
|
|
115
|
+
## Benchmark harness
|
|
116
|
+
|
|
117
|
+
[`benchmark/`](benchmark/README.md) measures whether the skill helps rather than merely
|
|
118
|
+
producing more text: `benchmark/evaluate.py` (evaluator), `benchmark/validate_submission.py`
|
|
119
|
+
(machine-validates a reproducible bundle), `benchmark/paths.py` (path confinement that rejects
|
|
120
|
+
`..` traversal and symlink escapes), `benchmark/cases.jsonl`, and four JSON Schemas — `case`,
|
|
121
|
+
`result`, `metadata`, `comparison`.
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
python benchmark/evaluate.py --cases benchmark/cases.jsonl --skill skill-results.jsonl
|
|
37
125
|
```
|
|
38
126
|
|
|
39
|
-
|
|
127
|
+
Inputs are confined to `--cases-dir` (default: each input's own directory), `--output` must
|
|
128
|
+
stay inside it, and reads are bounded by `--max-bytes`. Both `python benchmark/evaluate.py`
|
|
129
|
+
and `python -m benchmark.evaluate` work.
|
|
130
|
+
|
|
131
|
+
## Tests, tooling and governance
|
|
132
|
+
|
|
133
|
+
About **43% of the Python here is tests** — 1,575 of 3,635 lines across **9 test modules**,
|
|
134
|
+
run with the standard library's `unittest` on Python 3.10–3.14 on Linux, Windows and macOS.
|
|
135
|
+
They cover the controller, the benchmark harness, import hardening, path boundaries,
|
|
136
|
+
dependency-lock drift and release-gate polling; `tests/test_readme_badges.py` keeps this
|
|
137
|
+
file's badges honest. The toolchain is pinned twice — `pyproject.toml`'s `dev` group with
|
|
138
|
+
`==`, and [`constraints.txt`](constraints.txt) with `==` **and** `--hash` digests for the full
|
|
139
|
+
transitive closure ([details](CONTRIBUTING.md#toolchain-pinning)).
|
|
140
|
+
|
|
141
|
+
Also here: [`codemeta.json`](codemeta.json) for machine-readable citation beside
|
|
142
|
+
[`CITATION.cff`](CITATION.cff); five issue templates (bug, feature, question, benchmark
|
|
143
|
+
result, plus a chooser in `config.yml`) and a pull-request template; a
|
|
144
|
+
[Code of Conduct](CODE_OF_CONDUCT.md) with a scientific-integrity section; a
|
|
145
|
+
[Security policy](SECURITY.md).
|
|
146
|
+
|
|
147
|
+
## The protocol
|
|
148
|
+
|
|
149
|
+
`SKILL.md` is the normative contract. In short: **frame** the problem (verified vs assumed) →
|
|
150
|
+
**open branches** (genuinely different, not paraphrases) → **evaluate independently** (on
|
|
151
|
+
evidence, not eloquence) → **cross-check** (independently reached conclusions get reinforced)
|
|
152
|
+
→ **prune and revive** (kill contradicted paths, keep dormant ones recoverable) → **collapse**
|
|
153
|
+
(only when one path is clearly better supported). `SKILL.md` also scopes when *not* to use it:
|
|
154
|
+
trivially answerable questions should not pay branching cost.
|
|
155
|
+
|
|
156
|
+
## Benchmark status
|
|
157
|
+
|
|
158
|
+
**There are no published benchmark results.** `benchmark/cases.jsonl` holds six deterministic
|
|
159
|
+
smoke-test cases that prove the harness runs; they are explicitly **not sufficient evidence of
|
|
160
|
+
reasoning improvement**. Anyone can evaluate on models they have access to; every submitted
|
|
161
|
+
number must carry provenance (script, skill commit, provider and exact model version, run date,
|
|
162
|
+
sampling parameters, repetitions, platform), and one positive run establishes no general claim.
|
|
163
|
+
Rules: [CONTRIBUTING.md](CONTRIBUTING.md#benchmark-provenance-requirements).
|
|
40
164
|
|
|
41
165
|
## How it compares
|
|
42
166
|
|
|
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.
|
|
167
|
+
This table describes *mechanisms*, not measured performance. Nothing here has been
|
|
168
|
+
benchmarked against the rows above it.
|
|
169
|
+
|
|
170
|
+
| Approach | Mechanism | Limitation |
|
|
171
|
+
| --- | --- | --- |
|
|
172
|
+
| Chain-of-Thought ([Wei et al., 2022](https://arxiv.org/abs/2201.11903)) | One linear reasoning path | Early anchoring; alternatives are never kept alive |
|
|
173
|
+
| 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 |
|
|
174
|
+
| Self-consistency ([Wang et al., 2022](https://arxiv.org/abs/2203.11171)) | Samples one prompt N times | Paraphrase diversity, not hypothesis diversity |
|
|
175
|
+
| **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
176
|
|
|
71
177
|
## Documentation
|
|
72
178
|
|
|
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.
|
|
179
|
+
Everything lives in [`docs/index.md`](docs/index.md) — getting started, quickstart and its
|
|
180
|
+
verified output, measurement methodology, host compatibility, report forms. Release history:
|
|
181
|
+
[CHANGELOG.md](CHANGELOG.md). License: [MIT](LICENSE).
|
package/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
1.1.
|
|
1
|
+
1.1.1
|