quantum-reasoning-skill 1.0.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/LICENSE +21 -21
- package/README.md +181 -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
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
name: Feature request
|
|
2
|
-
description: Propose a change to the reasoning protocol, tooling, benchmarks, or integration contract.
|
|
3
|
-
title: "[Feature]: "
|
|
4
|
-
labels: ["enhancement"]
|
|
5
|
-
body:
|
|
6
|
-
- type: textarea
|
|
7
|
-
id: problem
|
|
8
|
-
attributes:
|
|
9
|
-
label: Problem or limitation
|
|
10
|
-
description: What concrete limitation does this proposal address?
|
|
11
|
-
validations:
|
|
12
|
-
required: true
|
|
13
|
-
- type: textarea
|
|
14
|
-
id: proposal
|
|
15
|
-
attributes:
|
|
16
|
-
label: Proposed change
|
|
17
|
-
description: Describe the behavior or interface you want to add or change.
|
|
18
|
-
validations:
|
|
19
|
-
required: true
|
|
20
|
-
- type: textarea
|
|
21
|
-
id: evidence
|
|
22
|
-
attributes:
|
|
23
|
-
label: Evidence or evaluation plan
|
|
24
|
-
description: If this affects reasoning quality, explain how it could be tested without relying on anecdotal examples alone.
|
|
25
|
-
- type: checkboxes
|
|
26
|
-
id: scope
|
|
27
|
-
attributes:
|
|
28
|
-
label: Scope check
|
|
29
|
-
options:
|
|
30
|
-
- label: This proposal does not present unverified benchmark claims as established results.
|
|
31
|
-
required: true
|
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
## Summary
|
|
2
|
-
|
|
3
|
-
Describe the change and the behavior it affects.
|
|
4
|
-
|
|
5
|
-
## Validation
|
|
6
|
-
|
|
7
|
-
- [ ] I ran `python -m unittest discover -s tests -v`.
|
|
8
|
-
- [ ] I ran `python benchmark/evaluate.py --help`.
|
|
9
|
-
- [ ] I added or updated tests when executable behavior changed.
|
|
10
|
-
- [ ] I updated documentation when the public contract changed.
|
|
11
|
-
- [ ] I did not include private chain-of-thought, secrets, credentials, or fabricated benchmark telemetry.
|
|
12
|
-
|
|
13
|
-
## Benchmark-impacting changes
|
|
14
|
-
|
|
15
|
-
If this changes `SKILL.md`, scoring, collapse/revival behavior, benchmark schemas, or evaluation logic, explain how existing results should be interpreted and whether new community runs are needed.
|
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
name: npm Publish
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
workflow_dispatch:
|
|
5
|
-
push:
|
|
6
|
-
branches: [main]
|
|
7
|
-
paths:
|
|
8
|
-
- "package.json"
|
|
9
|
-
- "index.js"
|
|
10
|
-
|
|
11
|
-
concurrency:
|
|
12
|
-
group: npm-publish
|
|
13
|
-
cancel-in-progress: false
|
|
14
|
-
|
|
15
|
-
permissions:
|
|
16
|
-
contents: read
|
|
17
|
-
|
|
18
|
-
jobs:
|
|
19
|
-
publish:
|
|
20
|
-
runs-on: ubuntu-latest
|
|
21
|
-
steps:
|
|
22
|
-
- uses: actions/checkout@v4
|
|
23
|
-
|
|
24
|
-
- uses: actions/setup-node@v4
|
|
25
|
-
with:
|
|
26
|
-
node-version: "20"
|
|
27
|
-
registry-url: "https://registry.npmjs.org"
|
|
28
|
-
|
|
29
|
-
- name: Publish to npm
|
|
30
|
-
run: npm publish --access public
|
|
31
|
-
env:
|
|
32
|
-
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
|
|
@@ -1,79 +0,0 @@
|
|
|
1
|
-
name: publish-release
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
workflow_run:
|
|
5
|
-
workflows: ["validate-skill"]
|
|
6
|
-
types: [completed]
|
|
7
|
-
branches: [main]
|
|
8
|
-
|
|
9
|
-
permissions:
|
|
10
|
-
contents: write
|
|
11
|
-
|
|
12
|
-
concurrency:
|
|
13
|
-
group: publish-release
|
|
14
|
-
cancel-in-progress: false
|
|
15
|
-
|
|
16
|
-
jobs:
|
|
17
|
-
publish:
|
|
18
|
-
if: ${{ github.event.workflow_run.conclusion == 'success' }}
|
|
19
|
-
runs-on: ubuntu-latest
|
|
20
|
-
steps:
|
|
21
|
-
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
|
|
22
|
-
with:
|
|
23
|
-
ref: ${{ github.event.workflow_run.head_sha }}
|
|
24
|
-
fetch-depth: 0
|
|
25
|
-
|
|
26
|
-
- name: Resolve and validate version
|
|
27
|
-
id: version
|
|
28
|
-
shell: bash
|
|
29
|
-
run: |
|
|
30
|
-
set -euo pipefail
|
|
31
|
-
test -s VERSION
|
|
32
|
-
version="$(tr -d '[:space:]' < VERSION)"
|
|
33
|
-
version="${version#v}"
|
|
34
|
-
if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
|
|
35
|
-
echo "Invalid release version: $version" >&2
|
|
36
|
-
exit 1
|
|
37
|
-
fi
|
|
38
|
-
echo "version=$version" >> "$GITHUB_OUTPUT"
|
|
39
|
-
echo "tag=v${version}" >> "$GITHUB_OUTPUT"
|
|
40
|
-
|
|
41
|
-
- name: Require matching changelog entry
|
|
42
|
-
shell: bash
|
|
43
|
-
env:
|
|
44
|
-
VERSION: ${{ steps.version.outputs.version }}
|
|
45
|
-
run: |
|
|
46
|
-
set -euo pipefail
|
|
47
|
-
grep -Fq "## [$VERSION]" CHANGELOG.md || {
|
|
48
|
-
echo "CHANGELOG.md must contain a ## [$VERSION] section before release." >&2
|
|
49
|
-
exit 1
|
|
50
|
-
}
|
|
51
|
-
|
|
52
|
-
- name: Check existing release
|
|
53
|
-
id: existing
|
|
54
|
-
shell: bash
|
|
55
|
-
env:
|
|
56
|
-
GH_TOKEN: ${{ github.token }}
|
|
57
|
-
TAG: ${{ steps.version.outputs.tag }}
|
|
58
|
-
run: |
|
|
59
|
-
set -euo pipefail
|
|
60
|
-
if gh release view "$TAG" >/dev/null 2>&1; then
|
|
61
|
-
echo "exists=true" >> "$GITHUB_OUTPUT"
|
|
62
|
-
echo "$TAG already exists; nothing to publish."
|
|
63
|
-
else
|
|
64
|
-
echo "exists=false" >> "$GITHUB_OUTPUT"
|
|
65
|
-
fi
|
|
66
|
-
|
|
67
|
-
- name: Create tag and GitHub Release
|
|
68
|
-
if: steps.existing.outputs.exists != 'true'
|
|
69
|
-
shell: bash
|
|
70
|
-
env:
|
|
71
|
-
GH_TOKEN: ${{ github.token }}
|
|
72
|
-
TAG: ${{ steps.version.outputs.tag }}
|
|
73
|
-
TARGET_SHA: ${{ github.event.workflow_run.head_sha }}
|
|
74
|
-
run: |
|
|
75
|
-
set -euo pipefail
|
|
76
|
-
gh release create "$TAG" \
|
|
77
|
-
--target "$TARGET_SHA" \
|
|
78
|
-
--title "$TAG" \
|
|
79
|
-
--generate-notes
|
|
@@ -1,154 +0,0 @@
|
|
|
1
|
-
name: validate-skill
|
|
2
|
-
|
|
3
|
-
on:
|
|
4
|
-
push:
|
|
5
|
-
pull_request:
|
|
6
|
-
|
|
7
|
-
permissions:
|
|
8
|
-
contents: read
|
|
9
|
-
|
|
10
|
-
jobs:
|
|
11
|
-
validate:
|
|
12
|
-
runs-on: ubuntu-latest
|
|
13
|
-
steps:
|
|
14
|
-
- uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
|
|
15
|
-
|
|
16
|
-
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
|
17
|
-
with:
|
|
18
|
-
python-version: "3.12"
|
|
19
|
-
|
|
20
|
-
- name: Validate skill repository contract
|
|
21
|
-
shell: bash
|
|
22
|
-
run: |
|
|
23
|
-
set -euo pipefail
|
|
24
|
-
for required in \
|
|
25
|
-
SKILL.md README.md LICENSE CHANGELOG.md VERSION CONTRIBUTING.md SECURITY.md CITATION.cff \
|
|
26
|
-
examples/usage.md examples/host-integration.md \
|
|
27
|
-
reference/branch_controller.py \
|
|
28
|
-
docs/MEASUREMENT.md docs/COMPATIBILITY.md \
|
|
29
|
-
benchmark/README.md benchmark/cases.jsonl benchmark/evaluate.py benchmark/validate_submission.py \
|
|
30
|
-
benchmark/schemas/case.schema.json benchmark/schemas/result.schema.json \
|
|
31
|
-
benchmark/schemas/metadata.schema.json benchmark/schemas/comparison.schema.json \
|
|
32
|
-
tests/test_reference.py tests/test_benchmark.py tests/test_submission_validation.py \
|
|
33
|
-
.github/ISSUE_TEMPLATE/benchmark-result.yml .github/ISSUE_TEMPLATE/bug-report.yml \
|
|
34
|
-
.github/ISSUE_TEMPLATE/feature-request.yml .github/PULL_REQUEST_TEMPLATE.md; do
|
|
35
|
-
test -s "$required"
|
|
36
|
-
done
|
|
37
|
-
|
|
38
|
-
python - <<'PY'
|
|
39
|
-
from pathlib import Path
|
|
40
|
-
import json
|
|
41
|
-
import re
|
|
42
|
-
|
|
43
|
-
root = Path.cwd().resolve()
|
|
44
|
-
skill = (root / "SKILL.md").read_text(encoding="utf-8")
|
|
45
|
-
lines = skill.splitlines()
|
|
46
|
-
if not lines or lines[0].strip() != "---":
|
|
47
|
-
raise SystemExit("SKILL.md must start with YAML front matter")
|
|
48
|
-
try:
|
|
49
|
-
end = next(i for i, line in enumerate(lines[1:], start=1) if line.strip() == "---")
|
|
50
|
-
except StopIteration as exc:
|
|
51
|
-
raise SystemExit("SKILL.md front matter is not closed") from exc
|
|
52
|
-
fields = {}
|
|
53
|
-
for line in lines[1:end]:
|
|
54
|
-
if ":" in line:
|
|
55
|
-
key, value = line.split(":", 1)
|
|
56
|
-
fields[key.strip()] = value.strip()
|
|
57
|
-
if fields.get("name") != "quantum-reasoning":
|
|
58
|
-
raise SystemExit("SKILL.md front matter must declare name: quantum-reasoning")
|
|
59
|
-
if not fields.get("description"):
|
|
60
|
-
raise SystemExit("SKILL.md front matter must contain a non-empty description")
|
|
61
|
-
if len(lines[end + 1:]) < 20:
|
|
62
|
-
raise SystemExit("SKILL.md body is unexpectedly short")
|
|
63
|
-
|
|
64
|
-
readme = (root / "README.md").read_text(encoding="utf-8")
|
|
65
|
-
for required in (
|
|
66
|
-
"SKILL.md", "examples/usage.md", "examples/host-integration.md",
|
|
67
|
-
"reference/branch_controller.py", "docs/MEASUREMENT.md", "docs/COMPATIBILITY.md",
|
|
68
|
-
"benchmark/README.md", "CONTRIBUTING.md", "SECURITY.md", "CITATION.cff",
|
|
69
|
-
):
|
|
70
|
-
if required not in readme:
|
|
71
|
-
raise SystemExit(f"README.md must reference {required}")
|
|
72
|
-
|
|
73
|
-
markdown_files = [
|
|
74
|
-
root / "README.md", root / "SKILL.md", root / "CONTRIBUTING.md", root / "SECURITY.md",
|
|
75
|
-
root / "examples/usage.md", root / "examples/host-integration.md",
|
|
76
|
-
root / "benchmark/README.md", root / "docs/MEASUREMENT.md", root / "docs/COMPATIBILITY.md",
|
|
77
|
-
]
|
|
78
|
-
link_pattern = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
|
|
79
|
-
for document in markdown_files:
|
|
80
|
-
text = document.read_text(encoding="utf-8")
|
|
81
|
-
for raw_target in link_pattern.findall(text):
|
|
82
|
-
target = raw_target.strip().split("#", 1)[0].split("?", 1)[0]
|
|
83
|
-
if not target or "://" in target or target.startswith(("mailto:", "#")):
|
|
84
|
-
continue
|
|
85
|
-
resolved = (document.parent / target).resolve()
|
|
86
|
-
try:
|
|
87
|
-
resolved.relative_to(root)
|
|
88
|
-
except ValueError as exc:
|
|
89
|
-
raise SystemExit(f"{document.relative_to(root)} links outside repository: {raw_target}") from exc
|
|
90
|
-
if not resolved.exists():
|
|
91
|
-
raise SystemExit(f"Broken relative link in {document.relative_to(root)}: {raw_target}")
|
|
92
|
-
|
|
93
|
-
case_path = root / "benchmark" / "cases.jsonl"
|
|
94
|
-
seen_ids = set()
|
|
95
|
-
for line_number, raw in enumerate(case_path.read_text(encoding="utf-8").splitlines(), start=1):
|
|
96
|
-
if not raw.strip():
|
|
97
|
-
continue
|
|
98
|
-
try:
|
|
99
|
-
case = json.loads(raw)
|
|
100
|
-
except json.JSONDecodeError as exc:
|
|
101
|
-
raise SystemExit(f"benchmark/cases.jsonl:{line_number}: invalid JSON: {exc}") from exc
|
|
102
|
-
required = {"id", "domain", "prompt", "accepted_answers"}
|
|
103
|
-
missing = required - set(case)
|
|
104
|
-
if missing:
|
|
105
|
-
raise SystemExit(f"benchmark/cases.jsonl:{line_number}: missing {sorted(missing)}")
|
|
106
|
-
case_id = str(case["id"])
|
|
107
|
-
if case_id in seen_ids:
|
|
108
|
-
raise SystemExit(f"duplicate benchmark case id: {case_id}")
|
|
109
|
-
seen_ids.add(case_id)
|
|
110
|
-
if not isinstance(case["accepted_answers"], list) or not case["accepted_answers"]:
|
|
111
|
-
raise SystemExit(f"benchmark/cases.jsonl:{line_number}: accepted_answers must be non-empty")
|
|
112
|
-
|
|
113
|
-
schemas = sorted((root / "benchmark" / "schemas").glob("*.schema.json"))
|
|
114
|
-
if len(schemas) < 4:
|
|
115
|
-
raise SystemExit("expected case, result, metadata and comparison JSON Schemas")
|
|
116
|
-
for schema_path in schemas:
|
|
117
|
-
schema = json.loads(schema_path.read_text(encoding="utf-8"))
|
|
118
|
-
if schema.get("$schema") != "https://json-schema.org/draft/2020-12/schema":
|
|
119
|
-
raise SystemExit(f"{schema_path}: expected JSON Schema draft 2020-12")
|
|
120
|
-
if schema.get("type") != "object" or not schema.get("required"):
|
|
121
|
-
raise SystemExit(f"{schema_path}: must define an object with required fields")
|
|
122
|
-
|
|
123
|
-
version = (root / "VERSION").read_text(encoding="utf-8").strip().lstrip("v")
|
|
124
|
-
if not re.fullmatch(r"[0-9]+\.[0-9]+\.[0-9]+(?:[.-][0-9A-Za-z.-]+)?", version):
|
|
125
|
-
raise SystemExit("VERSION is not a valid semantic version")
|
|
126
|
-
cff = (root / "CITATION.cff").read_text(encoding="utf-8")
|
|
127
|
-
for marker in ("cff-version: 1.2.0", "title:", "authors:", "repository-code:", "license: MIT"):
|
|
128
|
-
if marker not in cff:
|
|
129
|
-
raise SystemExit(f"CITATION.cff missing {marker!r}")
|
|
130
|
-
if f"version: {version}" not in cff:
|
|
131
|
-
raise SystemExit("CITATION.cff version must match VERSION")
|
|
132
|
-
|
|
133
|
-
action_use = re.compile(r"uses:\s+(actions/[A-Za-z0-9_.-]+)@([^\s#]+)")
|
|
134
|
-
for workflow in (root / ".github" / "workflows").glob("*.yml"):
|
|
135
|
-
for action, ref in action_use.findall(workflow.read_text(encoding="utf-8")):
|
|
136
|
-
if not re.fullmatch(r"[0-9a-f]{40}", ref):
|
|
137
|
-
raise SystemExit(f"{workflow}: {action} must be pinned to an exact commit SHA")
|
|
138
|
-
|
|
139
|
-
print("Skill repository contract validated successfully.")
|
|
140
|
-
PY
|
|
141
|
-
|
|
142
|
-
- name: Compile Python sources
|
|
143
|
-
run: python -m compileall -q reference benchmark tests
|
|
144
|
-
|
|
145
|
-
- name: Run behavioral tests
|
|
146
|
-
run: python -m unittest discover -s tests -v
|
|
147
|
-
|
|
148
|
-
- name: Validate community benchmark bundles
|
|
149
|
-
run: python benchmark/validate_submission.py --root benchmark/results/community --allow-empty
|
|
150
|
-
|
|
151
|
-
- name: Check benchmark CLIs
|
|
152
|
-
run: |
|
|
153
|
-
python benchmark/evaluate.py --help > /dev/null
|
|
154
|
-
python benchmark/validate_submission.py --help > /dev/null
|
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."}
|