quantum-reasoning-skill 1.0.0 → 1.1.0
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/LICENSE +21 -21
- package/README.md +86 -133
- package/SKILL.md +146 -146
- package/VERSION +1 -1
- package/index.js +207 -1
- package/package.json +41 -1
- package/.github/ISSUE_TEMPLATE/benchmark-result.yml +0 -81
- package/.github/ISSUE_TEMPLATE/bug-report.yml +0 -38
- package/.github/ISSUE_TEMPLATE/feature-request.yml +0 -31
- package/.github/PULL_REQUEST_TEMPLATE.md +0 -15
- package/.github/workflows/npm-publish.yml +0 -32
- package/.github/workflows/publish-release.yml +0 -79
- package/.github/workflows/validate-skill.yml +0 -154
- package/CHANGELOG.md +0 -51
- package/CITATION.cff +0 -17
- package/CONTRIBUTING.md +0 -88
- package/SECURITY.md +0 -17
- package/benchmark/README.md +0 -134
- package/benchmark/cases.jsonl +0 -6
- package/benchmark/evaluate.py +0 -257
- package/benchmark/schemas/case.schema.json +0 -20
- package/benchmark/schemas/comparison.schema.json +0 -64
- package/benchmark/schemas/metadata.schema.json +0 -53
- package/benchmark/schemas/result.schema.json +0 -25
- package/benchmark/validate_submission.py +0 -114
- package/docs/COMPATIBILITY.md +0 -44
- package/docs/MEASUREMENT.md +0 -131
- package/examples/host-integration.md +0 -57
- package/examples/usage.md +0 -31
- package/reference/branch_controller.py +0 -256
- package/tests/test_benchmark.py +0 -120
- package/tests/test_reference.py +0 -128
- package/tests/test_submission_validation.py +0 -78
package/CHANGELOG.md
DELETED
|
@@ -1,51 +0,0 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project are documented here.
|
|
4
|
-
|
|
5
|
-
## [Unreleased]
|
|
6
|
-
|
|
7
|
-
## [0.3.1] - 2026-09-07
|
|
8
|
-
|
|
9
|
-
### Added
|
|
10
|
-
|
|
11
|
-
- Community benchmark contribution policy in `CONTRIBUTING.md`.
|
|
12
|
-
- GitHub **Benchmark result**, **Bug report**, and **Feature request** issue forms.
|
|
13
|
-
- Pull-request checklist for tests, documentation, benchmark integrity, and sensitive-data hygiene.
|
|
14
|
-
- Draft 2020-12 JSON Schemas for benchmark cases, result rows, experiment metadata, and comparison output.
|
|
15
|
-
- `benchmark/validate_submission.py` for machine-validating reproducible community benchmark bundles.
|
|
16
|
-
- Tests that reject missing benchmark artifacts, tampered comparisons, and incomplete integrity metadata.
|
|
17
|
-
- Capability-based host compatibility contract in `docs/COMPATIBILITY.md`.
|
|
18
|
-
- Generic native-skill, persistent-instruction, and controller-assisted integration examples.
|
|
19
|
-
- `SECURITY.md` vulnerability-reporting policy.
|
|
20
|
-
- `CITATION.cff` research-software citation metadata.
|
|
21
|
-
|
|
22
|
-
### Changed
|
|
23
|
-
|
|
24
|
-
- Benchmark documentation now explicitly assigns real-model evaluation to users and contributors rather than requiring maintainer-run access to every model/provider.
|
|
25
|
-
- Community benchmark PRs now include the exact `cases.jsonl` used and are re-evaluated by CI from their raw baseline/skill files.
|
|
26
|
-
- Third-party benchmark submissions are treated as reproducible external measurements, not automatic project endorsements or universal performance claims.
|
|
27
|
-
- Release publishing now runs only after `validate-skill` succeeds on `main`; a failed validation cannot publish a release.
|
|
28
|
-
- GitHub Actions dependencies are pinned to exact commit SHAs and CI enforces future pinning.
|
|
29
|
-
- CI now validates schemas, version/citation consistency, host/documentation links, and community result bundles.
|
|
30
|
-
|
|
31
|
-
## [0.3.0] - 2026-09-07
|
|
32
|
-
|
|
33
|
-
### Added
|
|
34
|
-
|
|
35
|
-
- Deterministic reference branch controller with explicit scoring and state transitions.
|
|
36
|
-
- Shared-assumption and semantic-correlation penalty.
|
|
37
|
-
- Quantified dormant/rejected state rules and branch revival triggers.
|
|
38
|
-
- Uncertainty-based recommended search width.
|
|
39
|
-
- Explicit collapse criteria and leader-margin checks.
|
|
40
|
-
- Measurement specification documenting formulas and calibration requirements.
|
|
41
|
-
- Reproducible baseline-vs-skill benchmark protocol.
|
|
42
|
-
- Seed benchmark cases and JSONL result schema.
|
|
43
|
-
- Benchmark evaluator for accuracy, token/tool cost, latency, branch diversity, error recovery and contradiction resolution.
|
|
44
|
-
- Behavioral unit tests for the branch controller and benchmark evaluator.
|
|
45
|
-
- CI checks for Python compilation, benchmark schema validation and behavioral tests.
|
|
46
|
-
- Automated GitHub tag and Release publishing driven by the `VERSION` file.
|
|
47
|
-
|
|
48
|
-
### Changed
|
|
49
|
-
|
|
50
|
-
- `SKILL.md` now distinguishes qualitative protocol rules from unvalidated reference thresholds.
|
|
51
|
-
- `README.md` now documents the measurable framework and makes clear that empirical performance improvement has not yet been demonstrated.
|
package/CITATION.cff
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
cff-version: 1.2.0
|
|
2
|
-
message: "If you use this software or reasoning protocol, please cite it using the metadata below."
|
|
3
|
-
title: "Quantum Reasoning Skill"
|
|
4
|
-
type: software
|
|
5
|
-
authors:
|
|
6
|
-
- name: "Furox-Art"
|
|
7
|
-
repository-code: "https://github.com/Furox-Art/quantum-reasoning-skill"
|
|
8
|
-
url: "https://github.com/Furox-Art/quantum-reasoning-skill"
|
|
9
|
-
license: MIT
|
|
10
|
-
version: 0.3.1
|
|
11
|
-
date-released: 2026-09-07
|
|
12
|
-
keywords:
|
|
13
|
-
- reasoning
|
|
14
|
-
- language-models
|
|
15
|
-
- agent-systems
|
|
16
|
-
- test-time-compute
|
|
17
|
-
- benchmarking
|
package/CONTRIBUTING.md
DELETED
|
@@ -1,88 +0,0 @@
|
|
|
1
|
-
# Contributing
|
|
2
|
-
|
|
3
|
-
Contributions are welcome for the reasoning protocol, reference controller, tests, documentation, benchmark cases, host integrations and independently run model evaluations.
|
|
4
|
-
|
|
5
|
-
Before changing host-facing behavior, read [`docs/COMPATIBILITY.md`](./docs/COMPATIBILITY.md). Executable behavior changes should include tests.
|
|
6
|
-
|
|
7
|
-
## Community-run benchmarks
|
|
8
|
-
|
|
9
|
-
The project does **not** require the maintainer to purchase access to every model or provider. Real model evaluations are intentionally community-run.
|
|
10
|
-
|
|
11
|
-
The repository provides:
|
|
12
|
-
|
|
13
|
-
- the benchmark protocol;
|
|
14
|
-
- deterministic seed cases;
|
|
15
|
-
- machine-readable JSON Schemas;
|
|
16
|
-
- the result evaluator;
|
|
17
|
-
- a reproducible submission validator;
|
|
18
|
-
- CI validation and comparison tooling.
|
|
19
|
-
|
|
20
|
-
Users may run controlled baseline-vs-skill experiments on models and providers they already have access to and submit the results for review.
|
|
21
|
-
|
|
22
|
-
### Required metadata
|
|
23
|
-
|
|
24
|
-
Every submitted model evaluation must identify at least:
|
|
25
|
-
|
|
26
|
-
- provider;
|
|
27
|
-
- exact model and model version when available;
|
|
28
|
-
- run date;
|
|
29
|
-
- skill version/commit when available;
|
|
30
|
-
- baseline and skill prompt/instruction configuration;
|
|
31
|
-
- temperature/sampling parameters;
|
|
32
|
-
- context and output limits;
|
|
33
|
-
- tool availability;
|
|
34
|
-
- number of repetitions per case;
|
|
35
|
-
- random seed when supported;
|
|
36
|
-
- local hardware/runtime details for local models;
|
|
37
|
-
- whether failures, refusals and timeouts were retained.
|
|
38
|
-
|
|
39
|
-
Do not omit failed runs.
|
|
40
|
-
|
|
41
|
-
### Required artifacts for a benchmark PR
|
|
42
|
-
|
|
43
|
-
Place each submitted run under:
|
|
44
|
-
|
|
45
|
-
```text
|
|
46
|
-
benchmark/results/community/<provider>-<model>-<YYYY-MM-DD>/
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
Every bundle must include:
|
|
50
|
-
|
|
51
|
-
```text
|
|
52
|
-
metadata.json
|
|
53
|
-
cases.jsonl
|
|
54
|
-
baseline.jsonl
|
|
55
|
-
skill.jsonl
|
|
56
|
-
comparison.json
|
|
57
|
-
README.md
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
The exact contracts are in [`benchmark/schemas/`](./benchmark/schemas/). `cases.jsonl` must contain the exact evaluated cases, including custom cases when used.
|
|
61
|
-
|
|
62
|
-
`comparison.json` must be produced by `benchmark/evaluate.py` from the submitted raw result files rather than edited manually. Before submitting, run:
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
python benchmark/validate_submission.py --root benchmark/results/community
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
CI recomputes the comparison and rejects a bundle when its raw evidence and reported comparison disagree.
|
|
69
|
-
|
|
70
|
-
### Result integrity
|
|
71
|
-
|
|
72
|
-
- Use the same model/version, task set, tools, sampling settings and budget policy for baseline and skill conditions.
|
|
73
|
-
- Do not expose or submit private chain-of-thought.
|
|
74
|
-
- Do not fabricate missing telemetry.
|
|
75
|
-
- Clearly disclose custom benchmark cases, prompt wrappers, provider-specific adapters and any modifications to `SKILL.md`.
|
|
76
|
-
- Third-party benchmark submissions are measurements from their submitters, not project-maintainer endorsements.
|
|
77
|
-
- A single positive run is not sufficient to establish a general performance claim.
|
|
78
|
-
|
|
79
|
-
### How to submit
|
|
80
|
-
|
|
81
|
-
You can either:
|
|
82
|
-
|
|
83
|
-
1. open a **Benchmark result** issue using the repository issue template and link to your artifacts; or
|
|
84
|
-
2. open a pull request containing the reproducible result bundle described above.
|
|
85
|
-
|
|
86
|
-
For ordinary defects, use the **Bug report** form. For proposed behavior or protocol changes, use the **Feature request** form.
|
|
87
|
-
|
|
88
|
-
For code or protocol changes, include tests when the change is executable and explain which behavior is being changed. Follow the pull-request checklist in `.github/PULL_REQUEST_TEMPLATE.md`.
|
package/SECURITY.md
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
# Security policy
|
|
2
|
-
|
|
3
|
-
## Supported versions
|
|
4
|
-
|
|
5
|
-
Security fixes are applied to the current `main` branch and the latest published release.
|
|
6
|
-
|
|
7
|
-
## Reporting a vulnerability
|
|
8
|
-
|
|
9
|
-
Do not publish exploit details, credentials, tokens, private benchmark data, or other sensitive material in a public issue.
|
|
10
|
-
|
|
11
|
-
Prefer GitHub's private **Report a vulnerability** / Security Advisory flow when it is available for this repository. If that private channel is unavailable, open a minimal public issue that only requests a private contact path and does not include vulnerability details.
|
|
12
|
-
|
|
13
|
-
## Scope
|
|
14
|
-
|
|
15
|
-
Relevant reports include vulnerabilities in repository automation, benchmark ingestion/validation, release workflows, or reference code that could cause untrusted contributed content to execute unexpectedly, alter releases, or expose secrets.
|
|
16
|
-
|
|
17
|
-
Reasoning-quality disagreements and ordinary protocol bugs are not security vulnerabilities; use the normal bug-report issue form for those.
|
package/benchmark/README.md
DELETED
|
@@ -1,134 +0,0 @@
|
|
|
1
|
-
# Benchmark protocol
|
|
2
|
-
|
|
3
|
-
This directory measures whether the skill improves results rather than merely producing more reasoning text.
|
|
4
|
-
|
|
5
|
-
## Who runs the benchmarks
|
|
6
|
-
|
|
7
|
-
Real model evaluations are intentionally **community-run**. The repository supplies the benchmark protocol, seed cases, JSON Schemas, evaluator and submission validator; users run experiments on the models/providers they have access to.
|
|
8
|
-
|
|
9
|
-
Maintainer-run access to every commercial or local model is not required. The project therefore separates **benchmark infrastructure** from **third-party empirical results**.
|
|
10
|
-
|
|
11
|
-
Submitted results are evidence from the contributor who produced them. They are not automatically endorsed by the project and should not be generalized beyond the tested model/version/configuration without replication.
|
|
12
|
-
|
|
13
|
-
## Principle
|
|
14
|
-
|
|
15
|
-
Run the **same model, model version, task set, tool access, temperature/sampling settings, and token budget policy** twice:
|
|
16
|
-
|
|
17
|
-
1. baseline: normal instructions without `SKILL.md`
|
|
18
|
-
2. skill: the same setup with `SKILL.md`
|
|
19
|
-
|
|
20
|
-
Do not compare different models and attribute the difference to the skill.
|
|
21
|
-
|
|
22
|
-
## Seed cases
|
|
23
|
-
|
|
24
|
-
`cases.jsonl` contains deterministic smoke-test cases. They are intentionally small and are **not sufficient evidence of reasoning improvement**. A serious evaluation should add difficult held-out tasks from the target domains and report their provenance/licensing.
|
|
25
|
-
|
|
26
|
-
Each case has:
|
|
27
|
-
|
|
28
|
-
```json
|
|
29
|
-
{"id":"...","domain":"...","prompt":"...","accepted_answers":["..."]}
|
|
30
|
-
```
|
|
31
|
-
|
|
32
|
-
## Machine-readable schemas
|
|
33
|
-
|
|
34
|
-
The contracts are versioned with the repository:
|
|
35
|
-
|
|
36
|
-
- [`schemas/case.schema.json`](./schemas/case.schema.json) — one benchmark case
|
|
37
|
-
- [`schemas/result.schema.json`](./schemas/result.schema.json) — one baseline/skill result row
|
|
38
|
-
- [`schemas/metadata.schema.json`](./schemas/metadata.schema.json) — experiment metadata
|
|
39
|
-
- [`schemas/comparison.schema.json`](./schemas/comparison.schema.json) — evaluator comparison output
|
|
40
|
-
|
|
41
|
-
A result row requires:
|
|
42
|
-
|
|
43
|
-
```json
|
|
44
|
-
{
|
|
45
|
-
"case_id": "math-arithmetic-001",
|
|
46
|
-
"answer": "323",
|
|
47
|
-
"tokens": 120,
|
|
48
|
-
"tool_calls": 0,
|
|
49
|
-
"latency_ms": 950
|
|
50
|
-
}
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
Failed/refused runs should still be represented rather than silently removed. The optional `status` field may be `ok`, `refusal`, `timeout`, or `error`.
|
|
54
|
-
|
|
55
|
-
Skill-aware runners may additionally record observable aggregate telemetry such as `branches_total`, `branches_distinct`, `revived_branches`, `recovered_errors`, `contradictions_found`, and `contradictions_resolved`. Do not store private chain-of-thought.
|
|
56
|
-
|
|
57
|
-
## Evaluate one run
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
python benchmark/evaluate.py \
|
|
61
|
-
--cases benchmark/cases.jsonl \
|
|
62
|
-
--skill path/to/skill-results.jsonl
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
## Compare baseline vs skill
|
|
66
|
-
|
|
67
|
-
```bash
|
|
68
|
-
python benchmark/evaluate.py \
|
|
69
|
-
--cases benchmark/cases.jsonl \
|
|
70
|
-
--baseline path/to/baseline-results.jsonl \
|
|
71
|
-
--skill path/to/skill-results.jsonl \
|
|
72
|
-
--output comparison.json
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
The evaluator reports exact-answer accuracy, mean token use, tool calls, latency, branch diversity, revival/error recovery, contradiction resolution, and baseline-to-skill deltas.
|
|
76
|
-
|
|
77
|
-
## Required experimental controls
|
|
78
|
-
|
|
79
|
-
For a publishable comparison, record at minimum:
|
|
80
|
-
|
|
81
|
-
- provider and exact model/version
|
|
82
|
-
- date of the run
|
|
83
|
-
- decoding/sampling parameters
|
|
84
|
-
- context and output limits
|
|
85
|
-
- tool availability
|
|
86
|
-
- prompt wrapper/system instructions
|
|
87
|
-
- number of repetitions per case
|
|
88
|
-
- random seed when the provider supports one
|
|
89
|
-
- hardware/runtime details for local models
|
|
90
|
-
- failures, refusals and timeouts rather than silently dropping them
|
|
91
|
-
|
|
92
|
-
Use multiple repetitions for stochastic models and report confidence intervals. Keep benchmark cases separate from any prompts used while designing or tuning the skill.
|
|
93
|
-
|
|
94
|
-
## Submitting community results
|
|
95
|
-
|
|
96
|
-
Results can be submitted in either of two ways:
|
|
97
|
-
|
|
98
|
-
1. Open a **Benchmark result** issue and provide the required metadata plus links/attachments to the result artifacts.
|
|
99
|
-
2. Open a pull request containing a reproducible result bundle under:
|
|
100
|
-
|
|
101
|
-
```text
|
|
102
|
-
benchmark/results/community/<provider>-<model>-<YYYY-MM-DD>/
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
Every benchmark-result PR bundle must contain:
|
|
106
|
-
|
|
107
|
-
```text
|
|
108
|
-
metadata.json
|
|
109
|
-
cases.jsonl
|
|
110
|
-
baseline.jsonl
|
|
111
|
-
skill.jsonl
|
|
112
|
-
comparison.json
|
|
113
|
-
README.md
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
Including `cases.jsonl` inside the bundle makes the exact evaluated case set immutable and reviewable even when custom cases are used.
|
|
117
|
-
|
|
118
|
-
Generate `comparison.json` with `benchmark/evaluate.py`; do not hand-edit it. Before opening a PR, validate the bundle:
|
|
119
|
-
|
|
120
|
-
```bash
|
|
121
|
-
python benchmark/validate_submission.py --root benchmark/results/community
|
|
122
|
-
```
|
|
123
|
-
|
|
124
|
-
CI runs the same validator. It rejects missing artifacts, incomplete metadata, duplicate/missing case results, and a `comparison.json` that differs from a fresh evaluator recomputation.
|
|
125
|
-
|
|
126
|
-
See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) for the complete submission and integrity policy.
|
|
127
|
-
|
|
128
|
-
## Interpretation
|
|
129
|
-
|
|
130
|
-
A useful result is not simply "skill accuracy is higher". Report the trade-off between accuracy and compute. A skill that gains 1 percentage point while using 5x tokens may be undesirable for many workloads.
|
|
131
|
-
|
|
132
|
-
The reference thresholds in `reference/branch_controller.py` are defaults to test, not validated constants. Benchmark evidence should drive later calibration.
|
|
133
|
-
|
|
134
|
-
The project makes no universal performance claim from a single model, provider, benchmark or contributor submission. Independent replication is preferred.
|
package/benchmark/cases.jsonl
DELETED
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
{"id":"math-arithmetic-001","domain":"mathematics","prompt":"Compute 17 * 19.","accepted_answers":["323"],"notes":"Exact-answer sanity case."}
|
|
2
|
-
{"id":"math-algebra-001","domain":"mathematics","prompt":"Solve x^2 - 5x + 6 = 0. Return the roots in ascending order separated by a comma.","accepted_answers":["2, 3","2,3"],"notes":"Checks independent verification of a simple factorization."}
|
|
3
|
-
{"id":"logic-contradiction-001","domain":"logic","prompt":"Premises: All A are B. No B are C. Some A are C. Are the premises jointly consistent? Answer yes or no.","accepted_answers":["no"],"notes":"Requires contradiction detection."}
|
|
4
|
-
{"id":"debug-python-001","domain":"debugging","prompt":"A Python function is intended to return the first item of xs: def first(xs): return xs[1]. What integer index should replace 1?","accepted_answers":["0"],"notes":"Minimal root-cause diagnosis."}
|
|
5
|
-
{"id":"science-units-001","domain":"scientific-reasoning","prompt":"A car travels at 20 m/s for 15 s at constant speed. How many meters does it travel? Return only the number.","accepted_answers":["300"],"notes":"Simple quantitative verification case."}
|
|
6
|
-
{"id":"probability-001","domain":"probability","prompt":"A fair coin is flipped twice. What is the probability of exactly one head? Return a decimal.","accepted_answers":["0.5",".5"],"notes":"Checks enumeration versus shortcut reasoning."}
|
package/benchmark/evaluate.py
DELETED
|
@@ -1,257 +0,0 @@
|
|
|
1
|
-
"""Evaluate baseline and quantum-reasoning runs from JSONL files.
|
|
2
|
-
|
|
3
|
-
The evaluator uses only the Python standard library. It does not call a model.
|
|
4
|
-
External runners can write one result row per case and this script will validate,
|
|
5
|
-
score, summarize, and compare those runs without inventing missing measurements.
|
|
6
|
-
"""
|
|
7
|
-
|
|
8
|
-
from __future__ import annotations
|
|
9
|
-
|
|
10
|
-
import argparse
|
|
11
|
-
import json
|
|
12
|
-
import math
|
|
13
|
-
import statistics
|
|
14
|
-
from pathlib import Path
|
|
15
|
-
from typing import Any, Iterable
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
REQUIRED_RESULT_FIELDS = {
|
|
19
|
-
"case_id",
|
|
20
|
-
"answer",
|
|
21
|
-
"tokens",
|
|
22
|
-
"tool_calls",
|
|
23
|
-
"latency_ms",
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
OPTIONAL_TELEMETRY_FIELDS = {
|
|
27
|
-
"branches_total",
|
|
28
|
-
"branches_distinct",
|
|
29
|
-
"revived_branches",
|
|
30
|
-
"recovered_errors",
|
|
31
|
-
"contradictions_found",
|
|
32
|
-
"contradictions_resolved",
|
|
33
|
-
}
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
def read_jsonl(path: Path) -> list[dict[str, Any]]:
|
|
37
|
-
rows: list[dict[str, Any]] = []
|
|
38
|
-
with path.open("r", encoding="utf-8") as handle:
|
|
39
|
-
for line_number, raw in enumerate(handle, start=1):
|
|
40
|
-
line = raw.strip()
|
|
41
|
-
if not line:
|
|
42
|
-
continue
|
|
43
|
-
try:
|
|
44
|
-
value = json.loads(line)
|
|
45
|
-
except json.JSONDecodeError as exc:
|
|
46
|
-
raise ValueError(f"{path}:{line_number}: invalid JSON: {exc}") from exc
|
|
47
|
-
if not isinstance(value, dict):
|
|
48
|
-
raise ValueError(f"{path}:{line_number}: row must be a JSON object")
|
|
49
|
-
rows.append(value)
|
|
50
|
-
return rows
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
def normalize_answer(value: Any) -> str:
|
|
54
|
-
return " ".join(str(value).strip().casefold().split())
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
def validate_case(case: dict[str, Any]) -> None:
|
|
58
|
-
for field in ("id", "domain", "prompt", "accepted_answers"):
|
|
59
|
-
if field not in case:
|
|
60
|
-
raise ValueError(f"case missing required field: {field}")
|
|
61
|
-
if not isinstance(case["accepted_answers"], list) or not case["accepted_answers"]:
|
|
62
|
-
raise ValueError(f"case {case['id']!r}: accepted_answers must be a non-empty list")
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
def validate_result(result: dict[str, Any]) -> None:
|
|
66
|
-
missing = REQUIRED_RESULT_FIELDS - set(result)
|
|
67
|
-
if missing:
|
|
68
|
-
raise ValueError(
|
|
69
|
-
f"result {result.get('case_id', '<unknown>')!r} missing fields: "
|
|
70
|
-
+ ", ".join(sorted(missing))
|
|
71
|
-
)
|
|
72
|
-
for field in ("tokens", "tool_calls", "latency_ms"):
|
|
73
|
-
value = result[field]
|
|
74
|
-
if not isinstance(value, (int, float)) or value < 0:
|
|
75
|
-
raise ValueError(f"result {result['case_id']!r}: {field} must be non-negative")
|
|
76
|
-
for field in OPTIONAL_TELEMETRY_FIELDS:
|
|
77
|
-
if field in result:
|
|
78
|
-
value = result[field]
|
|
79
|
-
if not isinstance(value, (int, float)) or value < 0:
|
|
80
|
-
raise ValueError(
|
|
81
|
-
f"result {result['case_id']!r}: {field} must be non-negative"
|
|
82
|
-
)
|
|
83
|
-
if "branches_distinct" in result and "branches_total" in result:
|
|
84
|
-
if result["branches_distinct"] > result["branches_total"]:
|
|
85
|
-
raise ValueError(
|
|
86
|
-
f"result {result['case_id']!r}: branches_distinct cannot exceed branches_total"
|
|
87
|
-
)
|
|
88
|
-
if "contradictions_resolved" in result and "contradictions_found" in result:
|
|
89
|
-
if result["contradictions_resolved"] > result["contradictions_found"]:
|
|
90
|
-
raise ValueError(
|
|
91
|
-
f"result {result['case_id']!r}: contradictions_resolved cannot exceed contradictions_found"
|
|
92
|
-
)
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
def answer_is_correct(case: dict[str, Any], answer: Any) -> bool:
|
|
96
|
-
normalized = normalize_answer(answer)
|
|
97
|
-
accepted = {normalize_answer(value) for value in case["accepted_answers"]}
|
|
98
|
-
return normalized in accepted
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
def safe_mean(values: Iterable[float]) -> float | None:
|
|
102
|
-
materialized = list(values)
|
|
103
|
-
if not materialized:
|
|
104
|
-
return None
|
|
105
|
-
return statistics.fmean(materialized)
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
def safe_ratio(numerator: float, denominator: float) -> float | None:
|
|
109
|
-
if denominator == 0:
|
|
110
|
-
return None
|
|
111
|
-
return numerator / denominator
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
def summarize(cases: list[dict[str, Any]], results: list[dict[str, Any]]) -> dict[str, Any]:
|
|
115
|
-
for case in cases:
|
|
116
|
-
validate_case(case)
|
|
117
|
-
for result in results:
|
|
118
|
-
validate_result(result)
|
|
119
|
-
|
|
120
|
-
case_by_id = {str(case["id"]): case for case in cases}
|
|
121
|
-
if len(case_by_id) != len(cases):
|
|
122
|
-
raise ValueError("case ids must be unique")
|
|
123
|
-
|
|
124
|
-
result_by_id: dict[str, dict[str, Any]] = {}
|
|
125
|
-
for result in results:
|
|
126
|
-
case_id = str(result["case_id"])
|
|
127
|
-
if case_id in result_by_id:
|
|
128
|
-
raise ValueError(f"duplicate result for case_id {case_id!r}")
|
|
129
|
-
if case_id not in case_by_id:
|
|
130
|
-
raise ValueError(f"result references unknown case_id {case_id!r}")
|
|
131
|
-
result_by_id[case_id] = result
|
|
132
|
-
|
|
133
|
-
missing_cases = sorted(set(case_by_id) - set(result_by_id))
|
|
134
|
-
evaluated = []
|
|
135
|
-
for case_id, result in result_by_id.items():
|
|
136
|
-
case = case_by_id[case_id]
|
|
137
|
-
evaluated.append((case, result, answer_is_correct(case, result["answer"])))
|
|
138
|
-
|
|
139
|
-
total = len(evaluated)
|
|
140
|
-
correct = sum(int(is_correct) for _, _, is_correct in evaluated)
|
|
141
|
-
|
|
142
|
-
branch_rows = [
|
|
143
|
-
result
|
|
144
|
-
for _, result, _ in evaluated
|
|
145
|
-
if "branches_total" in result and "branches_distinct" in result
|
|
146
|
-
]
|
|
147
|
-
contradiction_rows = [
|
|
148
|
-
result
|
|
149
|
-
for _, result, _ in evaluated
|
|
150
|
-
if "contradictions_found" in result and "contradictions_resolved" in result
|
|
151
|
-
]
|
|
152
|
-
|
|
153
|
-
total_branches = sum(row["branches_total"] for row in branch_rows)
|
|
154
|
-
distinct_branches = sum(row["branches_distinct"] for row in branch_rows)
|
|
155
|
-
contradictions_found = sum(row["contradictions_found"] for row in contradiction_rows)
|
|
156
|
-
contradictions_resolved = sum(
|
|
157
|
-
row["contradictions_resolved"] for row in contradiction_rows
|
|
158
|
-
)
|
|
159
|
-
|
|
160
|
-
return {
|
|
161
|
-
"cases_defined": len(cases),
|
|
162
|
-
"cases_evaluated": total,
|
|
163
|
-
"missing_case_ids": missing_cases,
|
|
164
|
-
"accuracy": safe_ratio(correct, total),
|
|
165
|
-
"mean_tokens": safe_mean(float(result["tokens"]) for _, result, _ in evaluated),
|
|
166
|
-
"mean_tool_calls": safe_mean(
|
|
167
|
-
float(result["tool_calls"]) for _, result, _ in evaluated
|
|
168
|
-
),
|
|
169
|
-
"mean_latency_ms": safe_mean(
|
|
170
|
-
float(result["latency_ms"]) for _, result, _ in evaluated
|
|
171
|
-
),
|
|
172
|
-
"branch_diversity_ratio": safe_ratio(distinct_branches, total_branches),
|
|
173
|
-
"revival_rate_per_case": safe_mean(
|
|
174
|
-
float(result.get("revived_branches", 0)) for _, result, _ in evaluated
|
|
175
|
-
),
|
|
176
|
-
"error_recovery_rate_per_case": safe_mean(
|
|
177
|
-
float(result.get("recovered_errors", 0)) for _, result, _ in evaluated
|
|
178
|
-
),
|
|
179
|
-
"contradiction_resolution_rate": safe_ratio(
|
|
180
|
-
contradictions_resolved, contradictions_found
|
|
181
|
-
),
|
|
182
|
-
}
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
def percent_change(new: float | None, old: float | None) -> float | None:
|
|
186
|
-
if new is None or old is None or old == 0:
|
|
187
|
-
return None
|
|
188
|
-
return ((new - old) / old) * 100.0
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
def absolute_change(new: float | None, old: float | None) -> float | None:
|
|
192
|
-
if new is None or old is None:
|
|
193
|
-
return None
|
|
194
|
-
return new - old
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
def compare(baseline: dict[str, Any], skill: dict[str, Any]) -> dict[str, Any]:
|
|
198
|
-
return {
|
|
199
|
-
"accuracy_delta": absolute_change(skill["accuracy"], baseline["accuracy"]),
|
|
200
|
-
"tokens_percent_change": percent_change(
|
|
201
|
-
skill["mean_tokens"], baseline["mean_tokens"]
|
|
202
|
-
),
|
|
203
|
-
"tool_calls_percent_change": percent_change(
|
|
204
|
-
skill["mean_tool_calls"], baseline["mean_tool_calls"]
|
|
205
|
-
),
|
|
206
|
-
"latency_percent_change": percent_change(
|
|
207
|
-
skill["mean_latency_ms"], baseline["mean_latency_ms"]
|
|
208
|
-
),
|
|
209
|
-
"branch_diversity_delta": absolute_change(
|
|
210
|
-
skill["branch_diversity_ratio"], baseline["branch_diversity_ratio"]
|
|
211
|
-
),
|
|
212
|
-
"contradiction_resolution_delta": absolute_change(
|
|
213
|
-
skill["contradiction_resolution_rate"],
|
|
214
|
-
baseline["contradiction_resolution_rate"],
|
|
215
|
-
),
|
|
216
|
-
}
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
def ensure_finite(value: Any, label: str) -> None:
|
|
220
|
-
if isinstance(value, float) and not math.isfinite(value):
|
|
221
|
-
raise ValueError(f"{label} is not finite")
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
def main() -> int:
|
|
225
|
-
parser = argparse.ArgumentParser()
|
|
226
|
-
parser.add_argument("--cases", type=Path, required=True)
|
|
227
|
-
parser.add_argument("--skill", type=Path, required=True)
|
|
228
|
-
parser.add_argument("--baseline", type=Path)
|
|
229
|
-
parser.add_argument("--output", type=Path)
|
|
230
|
-
args = parser.parse_args()
|
|
231
|
-
|
|
232
|
-
cases = read_jsonl(args.cases)
|
|
233
|
-
skill_results = read_jsonl(args.skill)
|
|
234
|
-
skill_summary = summarize(cases, skill_results)
|
|
235
|
-
|
|
236
|
-
payload: dict[str, Any] = {"skill": skill_summary}
|
|
237
|
-
if args.baseline:
|
|
238
|
-
baseline_results = read_jsonl(args.baseline)
|
|
239
|
-
baseline_summary = summarize(cases, baseline_results)
|
|
240
|
-
payload["baseline"] = baseline_summary
|
|
241
|
-
payload["comparison"] = compare(baseline_summary, skill_summary)
|
|
242
|
-
|
|
243
|
-
for section_name, section in payload.items():
|
|
244
|
-
if isinstance(section, dict):
|
|
245
|
-
for key, value in section.items():
|
|
246
|
-
ensure_finite(value, f"{section_name}.{key}")
|
|
247
|
-
|
|
248
|
-
rendered = json.dumps(payload, indent=2, sort_keys=True)
|
|
249
|
-
print(rendered)
|
|
250
|
-
if args.output:
|
|
251
|
-
args.output.parent.mkdir(parents=True, exist_ok=True)
|
|
252
|
-
args.output.write_text(rendered + "\n", encoding="utf-8")
|
|
253
|
-
return 0
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
if __name__ == "__main__":
|
|
257
|
-
raise SystemExit(main())
|
|
@@ -1,20 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://github.com/Furox-Art/quantum-reasoning-skill/blob/main/benchmark/schemas/case.schema.json",
|
|
4
|
-
"title": "Quantum Reasoning benchmark case",
|
|
5
|
-
"type": "object",
|
|
6
|
-
"additionalProperties": true,
|
|
7
|
-
"required": ["id", "domain", "prompt", "accepted_answers"],
|
|
8
|
-
"properties": {
|
|
9
|
-
"id": {"type": "string", "minLength": 1},
|
|
10
|
-
"domain": {"type": "string", "minLength": 1},
|
|
11
|
-
"prompt": {"type": "string", "minLength": 1},
|
|
12
|
-
"accepted_answers": {
|
|
13
|
-
"type": "array",
|
|
14
|
-
"minItems": 1,
|
|
15
|
-
"items": {}
|
|
16
|
-
},
|
|
17
|
-
"source": {"type": ["string", "null"]},
|
|
18
|
-
"license": {"type": ["string", "null"]}
|
|
19
|
-
}
|
|
20
|
-
}
|
|
@@ -1,64 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
-
"$id": "https://github.com/Furox-Art/quantum-reasoning-skill/blob/main/benchmark/schemas/comparison.schema.json",
|
|
4
|
-
"title": "Quantum Reasoning benchmark comparison output",
|
|
5
|
-
"type": "object",
|
|
6
|
-
"additionalProperties": false,
|
|
7
|
-
"required": ["baseline", "skill", "comparison"],
|
|
8
|
-
"properties": {
|
|
9
|
-
"baseline": {"$ref": "#/$defs/summary"},
|
|
10
|
-
"skill": {"$ref": "#/$defs/summary"},
|
|
11
|
-
"comparison": {
|
|
12
|
-
"type": "object",
|
|
13
|
-
"additionalProperties": false,
|
|
14
|
-
"required": [
|
|
15
|
-
"accuracy_delta",
|
|
16
|
-
"tokens_percent_change",
|
|
17
|
-
"tool_calls_percent_change",
|
|
18
|
-
"latency_percent_change",
|
|
19
|
-
"branch_diversity_delta",
|
|
20
|
-
"contradiction_resolution_delta"
|
|
21
|
-
],
|
|
22
|
-
"properties": {
|
|
23
|
-
"accuracy_delta": {"type": ["number", "null"]},
|
|
24
|
-
"tokens_percent_change": {"type": ["number", "null"]},
|
|
25
|
-
"tool_calls_percent_change": {"type": ["number", "null"]},
|
|
26
|
-
"latency_percent_change": {"type": ["number", "null"]},
|
|
27
|
-
"branch_diversity_delta": {"type": ["number", "null"]},
|
|
28
|
-
"contradiction_resolution_delta": {"type": ["number", "null"]}
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
},
|
|
32
|
-
"$defs": {
|
|
33
|
-
"summary": {
|
|
34
|
-
"type": "object",
|
|
35
|
-
"additionalProperties": false,
|
|
36
|
-
"required": [
|
|
37
|
-
"cases_defined",
|
|
38
|
-
"cases_evaluated",
|
|
39
|
-
"missing_case_ids",
|
|
40
|
-
"accuracy",
|
|
41
|
-
"mean_tokens",
|
|
42
|
-
"mean_tool_calls",
|
|
43
|
-
"mean_latency_ms",
|
|
44
|
-
"branch_diversity_ratio",
|
|
45
|
-
"revival_rate_per_case",
|
|
46
|
-
"error_recovery_rate_per_case",
|
|
47
|
-
"contradiction_resolution_rate"
|
|
48
|
-
],
|
|
49
|
-
"properties": {
|
|
50
|
-
"cases_defined": {"type": "integer", "minimum": 0},
|
|
51
|
-
"cases_evaluated": {"type": "integer", "minimum": 0},
|
|
52
|
-
"missing_case_ids": {"type": "array", "items": {"type": "string"}},
|
|
53
|
-
"accuracy": {"type": ["number", "null"]},
|
|
54
|
-
"mean_tokens": {"type": ["number", "null"]},
|
|
55
|
-
"mean_tool_calls": {"type": ["number", "null"]},
|
|
56
|
-
"mean_latency_ms": {"type": ["number", "null"]},
|
|
57
|
-
"branch_diversity_ratio": {"type": ["number", "null"]},
|
|
58
|
-
"revival_rate_per_case": {"type": ["number", "null"]},
|
|
59
|
-
"error_recovery_rate_per_case": {"type": ["number", "null"]},
|
|
60
|
-
"contradiction_resolution_rate": {"type": ["number", "null"]}
|
|
61
|
-
}
|
|
62
|
-
}
|
|
63
|
-
}
|
|
64
|
-
}
|