quantum-reasoning-skill 1.0.0 → 1.1.0

package/benchmark/schemas/metadata.schema.json

@@ -1,53 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/Furox-Art/quantum-reasoning-skill/blob/main/benchmark/schemas/metadata.schema.json",
-  "title": "Quantum Reasoning community benchmark metadata",
-  "type": "object",
-  "additionalProperties": true,
-  "required": [
-    "provider",
-    "model",
-    "run_date",
-    "skill_version",
-    "repetitions_per_case",
-    "baseline",
-    "skill",
-    "failures_recorded"
-  ],
-  "properties": {
-    "provider": {"type": "string", "minLength": 1},
-    "model": {"type": "string", "minLength": 1},
-    "model_version": {"type": ["string", "null"]},
-    "run_date": {"type": "string", "format": "date"},
-    "skill_version": {"type": "string", "minLength": 1},
-    "skill_commit": {"type": ["string", "null"]},
-    "cases_source": {"type": ["string", "null"]},
-    "repetitions_per_case": {"type": "integer", "minimum": 1},
-    "random_seed": {"type": ["integer", "string", "null"]},
-    "hardware_runtime": {"type": ["string", "null"]},
-    "failures_recorded": {"const": true},
-    "baseline": {"$ref": "#/$defs/condition"},
-    "skill": {"$ref": "#/$defs/condition"},
-    "notes": {"type": ["string", "null"]}
-  },
-  "$defs": {
-    "condition": {
-      "type": "object",
-      "additionalProperties": true,
-      "required": [
-        "instruction_config",
-        "sampling",
-        "tool_availability",
-        "context_limit",
-        "output_limit"
-      ],
-      "properties": {
-        "instruction_config": {"type": "string", "minLength": 1},
-        "sampling": {"type": "object"},
-        "tool_availability": {"type": ["array", "object", "string"]},
-        "context_limit": {"type": ["integer", "null"], "minimum": 1},
-        "output_limit": {"type": ["integer", "null"], "minimum": 1}
-      }
-    }
-  }
-}

package/benchmark/schemas/result.schema.json

@@ -1,25 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://github.com/Furox-Art/quantum-reasoning-skill/blob/main/benchmark/schemas/result.schema.json",
-  "title": "Quantum Reasoning benchmark result row",
-  "type": "object",
-  "additionalProperties": true,
-  "required": ["case_id", "answer", "tokens", "tool_calls", "latency_ms"],
-  "properties": {
-    "case_id": {"type": "string", "minLength": 1},
-    "answer": {},
-    "tokens": {"type": "number", "minimum": 0},
-    "tool_calls": {"type": "number", "minimum": 0},
-    "latency_ms": {"type": "number", "minimum": 0},
-    "status": {
-      "type": "string",
-      "enum": ["ok", "refusal", "timeout", "error"]
-    },
-    "branches_total": {"type": "number", "minimum": 0},
-    "branches_distinct": {"type": "number", "minimum": 0},
-    "revived_branches": {"type": "number", "minimum": 0},
-    "recovered_errors": {"type": "number", "minimum": 0},
-    "contradictions_found": {"type": "number", "minimum": 0},
-    "contradictions_resolved": {"type": "number", "minimum": 0}
-  }
-}

package/benchmark/validate_submission.py

@@ -1,114 +0,0 @@
-"""Validate reproducible community benchmark result bundles."""
-from __future__ import annotations
-import argparse, json, re
-from datetime import date
-from pathlib import Path
-import evaluate
-
-REQUIRED_FILES = {"metadata.json", "cases.jsonl", "baseline.jsonl", "skill.jsonl", "comparison.json", "README.md"}
-COND_FIELDS = {"instruction_config", "sampling", "tool_availability", "context_limit", "output_limit"}
-META_FIELDS = {"provider", "model", "run_date", "skill_version", "repetitions_per_case", "baseline", "skill", "failures_recorded"}
-
-
-def load_json(path: Path):
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError) as exc:
-        raise ValueError(f"{path}: invalid JSON: {exc}") from exc
-
-
-def validate_metadata(meta: dict) -> None:
-    if not isinstance(meta, dict):
-        raise ValueError("metadata.json must contain a JSON object")
-    missing = META_FIELDS - set(meta)
-    if missing:
-        raise ValueError(f"metadata.json missing fields: {sorted(missing)}")
-    for key in ("provider", "model", "skill_version"):
-        if not isinstance(meta[key], str) or not meta[key].strip():
-            raise ValueError(f"metadata.{key} must be a non-empty string")
-    try:
-        date.fromisoformat(meta["run_date"])
-    except Exception as exc:
-        raise ValueError("metadata.run_date must be YYYY-MM-DD") from exc
-    if not isinstance(meta["repetitions_per_case"], int) or meta["repetitions_per_case"] < 1:
-        raise ValueError("metadata.repetitions_per_case must be >= 1")
-    if meta["failures_recorded"] is not True:
-        raise ValueError("metadata.failures_recorded must be true")
-    for name in ("baseline", "skill"):
-        value = meta[name]
-        if not isinstance(value, dict):
-            raise ValueError(f"metadata.{name} must be an object")
-        missing_cond = COND_FIELDS - set(value)
-        if missing_cond:
-            raise ValueError(f"metadata.{name} missing fields: {sorted(missing_cond)}")
-        if not isinstance(value["instruction_config"], str) or not value["instruction_config"].strip():
-            raise ValueError(f"metadata.{name}.instruction_config must be non-empty")
-        if not isinstance(value["sampling"], dict):
-            raise ValueError(f"metadata.{name}.sampling must be an object")
-        for limit in ("context_limit", "output_limit"):
-            v = value[limit]
-            if v is not None and (not isinstance(v, int) or v < 1):
-                raise ValueError(f"metadata.{name}.{limit} must be null or >= 1")
-
-
-def _case_map(cases):
-    out = {}
-    for case in cases:
-        evaluate.validate_case(case)
-        cid = str(case["id"])
-        if cid in out:
-            raise ValueError(f"duplicate case id: {cid}")
-        out[cid] = case
-    return out
-
-
-def validate_bundle(bundle: Path) -> None:
-    missing = REQUIRED_FILES - {p.name for p in bundle.iterdir() if p.is_file()}
-    if missing:
-        raise ValueError(f"{bundle}: missing files: {sorted(missing)}")
-    validate_metadata(load_json(bundle / "metadata.json"))
-    cases = evaluate.read_jsonl(bundle / "cases.jsonl")
-    case_by_id = _case_map(cases)
-    baseline = evaluate.read_jsonl(bundle / "baseline.jsonl")
-    skill = evaluate.read_jsonl(bundle / "skill.jsonl")
-    for row in baseline + skill:
-        evaluate.validate_result(row)
-    for label, rows in (("baseline", baseline), ("skill", skill)):
-        ids = [str(r["case_id"]) for r in rows]
-        if len(ids) != len(set(ids)):
-            raise ValueError(f"{bundle}: duplicate {label} case_id")
-        if set(ids) != set(case_by_id):
-            raise ValueError(f"{bundle}: {label} must contain exactly one row for every case")
-    expected = {
-        "skill": evaluate.summarize(cases, skill),
-        "baseline": evaluate.summarize(cases, baseline),
-    }
-    expected["comparison"] = evaluate.compare(expected["baseline"], expected["skill"])
-    submitted = load_json(bundle / "comparison.json")
-    if submitted != expected:
-        raise ValueError(f"{bundle}: comparison.json does not match evaluator recomputation")
-    if not (bundle / "README.md").read_text(encoding="utf-8").strip():
-        raise ValueError(f"{bundle}: README.md must not be empty")
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--root", type=Path, default=Path("benchmark/results/community"))
-    parser.add_argument("--allow-empty", action="store_true")
-    args = parser.parse_args()
-    root = args.root
-    if not root.exists():
-        if args.allow_empty:
-            return 0
-        raise SystemExit(f"community benchmark root not found: {root}")
-    bundles = sorted(p for p in root.iterdir() if p.is_dir())
-    if not bundles and not args.allow_empty:
-        raise SystemExit("no community benchmark bundles found")
-    for bundle in bundles:
-        validate_bundle(bundle)
-        print(f"validated {bundle}")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/docs/COMPATIBILITY.md

@@ -1,44 +0,0 @@
-# Host compatibility
-
-Quantum Reasoning is model-agnostic, but not every host exposes the same controls. Compatibility is therefore defined by capabilities rather than by provider branding.
-
-## Compatibility levels
-
-| Level | Required capabilities | What works |
-| --- | --- | --- |
-| Protocol-only | Host can persist or inject `SKILL.md` instructions | Multi-branch protocol, falsification rules, stopping/collapse policy |
-| Measurable | Protocol-only plus aggregate run telemetry | Benchmark result schema, diversity/revival/contradiction measurements |
-| Controller-assisted | Measurable plus a host-side loop that can call `reference/branch_controller.py` or equivalent logic | Deterministic scoring, state transitions, uncertainty-based width and collapse checks |
-
-A host is incompatible only when it cannot reliably apply the skill instructions, truncates/replaces them in a way that changes the protocol, or prevents the requested task/tool access.
-
-## Required host contract
-
-A compatible integration should preserve these invariants:
-
-1. `SKILL.md` is supplied as a persistent system/developer/skill instruction, not as untrusted task content.
-2. The same task constraints and tool permissions apply to all candidate branches.
-3. Tool observations are treated as evidence and are not fabricated.
-4. Private chain-of-thought is not required or stored. Only aggregate control-plane telemetry may be emitted.
-5. If numeric branch telemetry is unavailable, the host follows the qualitative protocol and omits unavailable measurements rather than inventing them.
-6. Baseline-vs-skill benchmarks keep the model/version, tools, sampling and budget policy fixed.
-
-## Integration patterns
-
-### 1. Native skill directory
-
-If a host supports a skill/plugin directory, install the repository so that `SKILL.md` is the skill entry point and keep its YAML front matter intact.
-
-### 2. Persistent instruction wrapper
-
-If the host has no native skill format, load the contents of `SKILL.md` into the persistent system/developer instruction layer before the user task. Do not prepend it to benchmark prompts only in the skill condition unless the baseline wrapper is otherwise identical.
-
-### 3. Controller-assisted agent
-
-A host with an explicit agent loop can map observable aggregate branch measurements to `BranchMetrics` and use `reference/branch_controller.py` for ranking, state changes and collapse decisions. The reference controller does not generate hidden reasoning or call an LLM.
-
-See [`../examples/host-integration.md`](../examples/host-integration.md) for concrete generic examples.
-
-## Provider/model claims
-
-This repository intentionally does not label specific commercial models as "supported" without a reproducible third-party run. Community results may document a provider/model combination under `benchmark/results/community/`, but those results are measurements from the submitter, not a permanent compatibility guarantee.

package/docs/MEASUREMENT.md

@@ -1,131 +0,0 @@
-# Measurement and branch-control specification
-
-This document turns the qualitative protocol in `SKILL.md` into an auditable reference policy. It does **not** claim that these constants are optimal or scientifically validated. They are initial defaults that must be calibrated against benchmark data.
-
-## 1. Observable branch metrics
-
-Each branch is represented by normalized values in `[0, 1]`:
-
-- `evidence`: support from verified facts or observations
-- `verification`: strength of independent checks
-- `independence`: independence from other branches
-- `information_gain`: expected value of further work on the branch
-- `contradiction`: severity of conflict with verified facts
-- `unresolved_assumptions`: remaining unsupported assumptions
-- `normalized_cost`: relative compute/tool cost already consumed
-- `shared_assumption_ratio`: overlap in critical assumptions with the current leader
-- `semantic_similarity_to_leader`: redundancy signal for near-duplicate branches
-
-These values are control metadata. They must not require exposing private chain-of-thought.
-
-## 2. Correlation penalty
-
-A branch should not receive full independence credit when it shares assumptions or is effectively a paraphrase of the leader.
-
-```text
-correlation = max(shared_assumption_ratio, semantic_similarity_to_leader)
-effective_independence = independence * (1 - correlation)
-```
-
-## 3. Reference support score
-
-The reference implementation uses:
-
-```text
-score = clamp01(
-    0.15
-  + 0.25 * evidence
-  + 0.25 * verification
-  + 0.15 * effective_independence
-  + 0.10 * information_gain
-  - 0.15 * contradiction
-  - 0.05 * unresolved_assumptions
-  - 0.05 * normalized_cost
-)
-```
-
-The weights are deliberately explicit so they can be benchmarked and changed. They are not hidden policy.
-
-## 4. State transitions
-
-Reference defaults:
-
-- reject when `contradiction >= 0.85`
-- move to dormant when `score < 0.35`
-- otherwise keep active
-
-A dormant branch is revived when at least one material change occurs relative to its previous measurement:
-
-- evidence increases by `>= 0.15`, or
-- verification increases by `>= 0.25`, or
-- contradiction decreases by `>= 0.20`
-
-A rejected branch is not automatically revived by the reference controller. A caller may explicitly reopen it if the supposedly verified fact that caused rejection is itself invalidated.
-
-## 5. Dynamic search width
-
-Uncertainty is estimated from the normalized Shannon entropy of surviving branch scores.
-
-Reference width policy:
-
-| uncertainty | branch range |
-|---|---:|
-| `< 0.25` | 2–3 |
-| `0.25–0.55` | 4–6 |
-| `>= 0.55` | 6–10 |
-
-This is a compute-allocation recommendation, not a requirement to generate the maximum branch count.
-
-## 6. Collapse criteria
-
-The reference controller permits collapse only when all applicable checks pass:
-
-1. leader score `>= 0.78`
-2. leader verification `>= 0.75`
-3. leader contradiction `<= 0.15`
-4. if a runner-up exists, leader margin `>= 0.12`
-5. no unresolved high-information alternative remains close enough to plausibly change the outcome
-
-If these checks fail, the system should continue verification, keep multiple surviving alternatives, or report unresolved alternatives rather than manufacture certainty.
-
-## 7. Diversity diagnostic
-
-Given pairwise semantic similarities, a pair is treated as redundant when similarity is `>= 0.85` by default.
-
-```text
-diversity_ratio = materially_distinct_pairs / all_measured_pairs
-```
-
-This metric is intentionally simple. Embedding model choice, similarity calibration and domain effects must be reported by any experiment that uses it.
-
-## 8. What must be calibrated
-
-Benchmarking should test at least:
-
-- score weights
-- contradiction rejection threshold
-- dormant threshold
-- revival deltas
-- collapse score and margin
-- semantic duplicate threshold
-- uncertainty-to-width mapping
-
-Calibration must use a development set separate from final held-out evaluation.
-
-## 9. Failure modes to measure
-
-A serious evaluation should label and count:
-
-- early lock-in
-- duplicated branches
-- shared-assumption failure
-- false contradiction detection
-- failure to revive a correct dormant branch
-- excessive search after the answer is already established
-- premature collapse
-- tool-confirmation bias
-- accuracy gain that is explained only by substantially higher compute
-
-## 10. Reproducibility rule
-
-Any reported improvement must include the baseline configuration and raw aggregate result files needed to reproduce the comparison. Do not publish only a selected percentage or a hand-picked example.

package/examples/host-integration.md

@@ -1,57 +0,0 @@
-# Host integration examples
-
-These examples describe integration shapes without depending on a specific provider.
-
-## Native skill host
-
-Install the repository or copy `SKILL.md` into the host's skill directory. Preserve the YAML front matter and load the file as a persistent skill instruction.
-
-## Persistent instruction host
-
-Conceptually, the host should build the request as:
-
-```text
-persistent instructions:
-  <contents of SKILL.md>
-
-task:
-  <user request>
-```
-
-Do not require the model to print private reasoning. The final answer may remain concise while the host records only observable aggregate telemetry.
-
-## Controller-assisted host
-
-A host-side agent loop may use the optional reference controller:
-
-```python
-from reference.branch_controller import Branch, BranchMetrics, collapse_decision
-
-branch = Branch(
-    branch_id="candidate-a",
-    metrics=BranchMetrics(
-        evidence=0.8,
-        verification=0.9,
-        independence=0.7,
-        information_gain=0.6,
-        contradiction=0.1,
-        unresolved_assumptions=0.2,
-        normalized_cost=0.3,
-        shared_assumption_ratio=0.1,
-        semantic_similarity_to_leader=0.2,
-    ),
-)
-```
-
-The host supplies only measurements it can actually observe. Missing telemetry must not be guessed.
-
-## Benchmark wrapper
-
-For an A/B benchmark, keep everything fixed except the presence of the skill:
-
-```text
-baseline = normal persistent instructions + task
-skill    = normal persistent instructions + SKILL.md + same task
-```
-
-Use the same model/version, tools, sampling settings and budget policy for both conditions. See [`../benchmark/README.md`](../benchmark/README.md).

package/examples/usage.md

@@ -1,31 +0,0 @@
-# Usage examples
-
-The skill is designed to be invoked only when branching improves reliability.
-
-## Scientific hypothesis
-
-```text
-Use the quantum-reasoning skill. Keep several materially different mechanisms alive, identify what evidence would falsify each one, use available tools to test them, and collapse only after cross-comparison.
-```
-
-## Mathematics
-
-```text
-Use the quantum-reasoning skill. Explore independent solution strategies, test edge cases and counterexamples, verify the strongest path, and return only the final derivation and important uncertainty.
-```
-
-## Debugging
-
-```text
-Use the quantum-reasoning skill. Maintain multiple root-cause hypotheses, design the cheapest discriminating test for each, eliminate contradicted causes, revive alternatives if new evidence conflicts with the leader, then give the most supported diagnosis.
-```
-
-## Planning / architecture
-
-```text
-Use the quantum-reasoning skill. Generate genuinely different architectures, compare assumptions and failure modes, allocate more analysis to unresolved high-impact choices, and synthesize the strongest design only after verification.
-```
-
-## Expected behavior
-
-The model should not print a large internal reasoning tree. It should use the branching protocol internally and return a concise result, the evidence that matters, remaining uncertainty, and genuinely unresolved alternatives when necessary.