autoresearch-core 0.1.1__tar.gz

autoresearch_core-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q --cov=autoresearch_core --cov-report=term-missing --cov-fail-under=95
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

autoresearch_core-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Publishes on a version tag (e.g. v0.1.1) via PyPI Trusted Publishing (OIDC).
+# One-time setup on PyPI: project → Publishing → add a Trusted Publisher with
+#   owner: ca1773130n   repo: autoresearch-core
+#   workflow: publish.yml   environment: pypi
+# No API token is stored anywhere.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/autoresearch-core
+    permissions:
+      id-token: write  # OIDC for Trusted Publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

autoresearch_core-0.1.1/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.coverage
+dist/

autoresearch_core-0.1.1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `autoresearch-core` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/), and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.1.1] - 2026-06-03
+### Fixed
+- Reject non-finite metric values (`1e999` → `inf`, `nan`) in `parse_metrics_line`
+  and `validate_metric_spec`, matching JS `JSON.parse` semantics.
+- `approach_hash` collapses internal whitespace before hashing.
+- `build_dead_end_record` raises unless the verdict is a deterministic refutation.
+- `resolve_gates` tolerates a non-mapping `research_gates` config value.
+- `ExperimentResult` defensively copies `metrics` so the frozen instance is immutable.
+
+## [0.1.0] - 2026-06-03
+### Added
+- Initial release: `MetricSpec`, deterministic `Verdict` (`measure`), failure
+  classifier (H2/H3/H4), gate model, decision policy (`decide`,
+  `detect_plateau`, `should_promote_dead_end`), promotion record shapes, and the
+  adapter `Protocol`s (`Spawn`, `Retriever`, `KnowledgeGraph`, `ExperimentRunner`,
+  `Store`). Pure-Python, zero runtime dependencies; behaviour parity-tested
+  against the GRD autoresearch loop.

autoresearch_core-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cameleon X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

autoresearch_core-0.1.1/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: autoresearch-core
+Version: 0.1.1
+Summary: Decision-contracts library: deterministic verdict/gate/failure/promotion logic for autoresearch loops.
+Project-URL: Homepage, https://github.com/ca1773130n/autoresearch-core
+Project-URL: Repository, https://github.com/ca1773130n/autoresearch-core
+Project-URL: Issues, https://github.com/ca1773130n/autoresearch-core/issues
+Project-URL: Changelog, https://github.com/ca1773130n/autoresearch-core/blob/main/CHANGELOG.md
+Author-email: Cameleon X <ca1773130n@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agent,autoresearch,decision-contracts,deterministic,research-loop,verdict
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# autoresearch-core
+
+[![CI](https://github.com/ca1773130n/autoresearch-core/actions/workflows/ci.yml/badge.svg)](https://github.com/ca1773130n/autoresearch-core/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/autoresearch-core.svg)](https://pypi.org/project/autoresearch-core/)
+[![Python](https://img.shields.io/pypi/pyversions/autoresearch-core.svg)](https://pypi.org/project/autoresearch-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A tiny, **pure-Python decision-contracts library** for autoresearch / agentic
+loops: a *deterministic* verdict (metric / comparator / target), failure
+classification, gates, and promotion record shapes — the disciplined decision
+core, with **zero runtime dependencies** and **no I/O**.
+
+You bring the loop, the retrieval, the runner, and the storage; you bind them to
+the library's `Protocol`s and call `measure` / `decide` / `should_promote_dead_end`
+at your decision points. The verdict logic is parity-tested against the GRD
+autoresearch loop.
+
+## Install
+
+```bash
+pip install autoresearch-core
+```
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Quickstart
+
+```python
+from autoresearch_core import (
+    MetricSpec, ExperimentResult, measure, parse_metrics_line, should_promote_dead_end,
+)
+
+spec = MetricSpec(metric_key="recall_at_10", comparator=">=", target=0.8)
+
+# An experiment prints `__RESULT__ {"recall_at_10": 0.83}` on stdout:
+metrics = parse_metrics_line(stdout)        # -> {"recall_at_10": 0.83}
+verdict = measure(spec, ExperimentResult(metrics=metrics, exit_code=0))
+
+verdict.verdict          # "supported" | "refuted" | "inconclusive"  (deterministic)
+verdict.evidence_level   # "deterministic"
+should_promote_dead_end(verdict)            # True only for a deterministic refutation
+```
+
+## What it owns (and what it doesn't)
+
+**Owns — the decision discipline:**
+- `MetricSpec` + the `__RESULT__` result contract (`parse_metrics_line`, `validate_metric_spec`)
+- `DeterministicVerdict` / `measure` (metric vs target → supported / refuted / inconclusive)
+- failure classification (`classify_run_failure` → `H2` / `H3` / `H4`)
+- gates (`resolve_gates`, `check_gate`)
+- policy (`decide`, `detect_plateau`, `should_promote_dead_end`)
+- promotion record shapes (`DeadEndRecord`, `KnowhowRecord`, `approach_hash`, `should_skip`)
+
+**Doesn't own — bind these via `ports.py` `Protocol`s to your own infra:**
+`Spawn`, `Retriever`, `KnowledgeGraph`, `ExperimentRunner`, `Store`.
+
+## Verdict authority
+
+`DeterministicVerdict` is the default and the reason this package exists. Other
+strategies (an LLM judge, an exit-code check) can be plugged in via the
+`VerdictStrategy` protocol, but **only a deterministic refutation auto-promotes a
+dead-end** — non-deterministic verdicts are advisory. Every verdict records its
+`strategy` and `evidence_level`, so the decision trail stays auditable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q --cov=autoresearch_core
+```
+
+## License
+
+MIT © Cameleon X — see [LICENSE](LICENSE).

autoresearch_core-0.1.1/README.md

@@ -0,0 +1,74 @@
+# autoresearch-core
+
+[![CI](https://github.com/ca1773130n/autoresearch-core/actions/workflows/ci.yml/badge.svg)](https://github.com/ca1773130n/autoresearch-core/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/autoresearch-core.svg)](https://pypi.org/project/autoresearch-core/)
+[![Python](https://img.shields.io/pypi/pyversions/autoresearch-core.svg)](https://pypi.org/project/autoresearch-core/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A tiny, **pure-Python decision-contracts library** for autoresearch / agentic
+loops: a *deterministic* verdict (metric / comparator / target), failure
+classification, gates, and promotion record shapes — the disciplined decision
+core, with **zero runtime dependencies** and **no I/O**.
+
+You bring the loop, the retrieval, the runner, and the storage; you bind them to
+the library's `Protocol`s and call `measure` / `decide` / `should_promote_dead_end`
+at your decision points. The verdict logic is parity-tested against the GRD
+autoresearch loop.
+
+## Install
+
+```bash
+pip install autoresearch-core
+```
+
+Requires Python 3.11+. No runtime dependencies.
+
+## Quickstart
+
+```python
+from autoresearch_core import (
+    MetricSpec, ExperimentResult, measure, parse_metrics_line, should_promote_dead_end,
+)
+
+spec = MetricSpec(metric_key="recall_at_10", comparator=">=", target=0.8)
+
+# An experiment prints `__RESULT__ {"recall_at_10": 0.83}` on stdout:
+metrics = parse_metrics_line(stdout)        # -> {"recall_at_10": 0.83}
+verdict = measure(spec, ExperimentResult(metrics=metrics, exit_code=0))
+
+verdict.verdict          # "supported" | "refuted" | "inconclusive"  (deterministic)
+verdict.evidence_level   # "deterministic"
+should_promote_dead_end(verdict)            # True only for a deterministic refutation
+```
+
+## What it owns (and what it doesn't)
+
+**Owns — the decision discipline:**
+- `MetricSpec` + the `__RESULT__` result contract (`parse_metrics_line`, `validate_metric_spec`)
+- `DeterministicVerdict` / `measure` (metric vs target → supported / refuted / inconclusive)
+- failure classification (`classify_run_failure` → `H2` / `H3` / `H4`)
+- gates (`resolve_gates`, `check_gate`)
+- policy (`decide`, `detect_plateau`, `should_promote_dead_end`)
+- promotion record shapes (`DeadEndRecord`, `KnowhowRecord`, `approach_hash`, `should_skip`)
+
+**Doesn't own — bind these via `ports.py` `Protocol`s to your own infra:**
+`Spawn`, `Retriever`, `KnowledgeGraph`, `ExperimentRunner`, `Store`.
+
+## Verdict authority
+
+`DeterministicVerdict` is the default and the reason this package exists. Other
+strategies (an LLM judge, an exit-code check) can be plugged in via the
+`VerdictStrategy` protocol, but **only a deterministic refutation auto-promotes a
+dead-end** — non-deterministic verdicts are advisory. Every verdict records its
+`strategy` and `evidence_level`, so the decision trail stays auditable.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q --cov=autoresearch_core
+```
+
+## License
+
+MIT © Cameleon X — see [LICENSE](LICENSE).

autoresearch_core-0.1.1/autoresearch_core/__init__.py

@@ -0,0 +1,31 @@
+"""autoresearch-core: pure-Python decision contracts for autoresearch loops."""
+
+__version__ = "0.1.1"
+
+from .types import (
+    Comparator, EvidenceLevel, ExperimentResult, FailureClass, GateCheck, GateState,
+    Hypothesis, MetricSpec, Takeaway, Verdict, VerdictRecord,
+)
+from .contract import parse_metrics_line, validate_metric_spec
+from .failures import classify_run_failure
+from .verdict import compare, DeterministicVerdict, VerdictStrategy
+from .gates import resolve_gates, check_gate
+from .policy import (
+    decide_branch, should_terminate, detect_plateau, should_promote_dead_end,
+    measure, decide,
+)
+from .promote import (
+    DeadEndRecord, KnowhowRecord, approach_hash, build_dead_end_record, should_skip,
+)
+from .ports import Spawn, Retriever, KnowledgeGraph, ExperimentRunner, Store
+
+__all__ = [
+    "Comparator", "EvidenceLevel", "ExperimentResult", "FailureClass", "GateCheck", "GateState",
+    "Hypothesis", "MetricSpec", "Takeaway", "Verdict", "VerdictRecord",
+    "parse_metrics_line", "validate_metric_spec", "classify_run_failure",
+    "compare", "DeterministicVerdict", "VerdictStrategy", "resolve_gates", "check_gate",
+    "decide_branch", "should_terminate", "detect_plateau", "should_promote_dead_end",
+    "measure", "decide",
+    "DeadEndRecord", "KnowhowRecord", "approach_hash", "build_dead_end_record", "should_skip",
+    "Spawn", "Retriever", "KnowledgeGraph", "ExperimentRunner", "Store",
+]

autoresearch_core-0.1.1/autoresearch_core/contract.py

@@ -0,0 +1,52 @@
+"""The machine-readable experiment-result contract. Parity with GRD runner.ts."""
+from __future__ import annotations
+
+import json
+import math
+import re
+
+from .types import Comparator, MetricSpec
+
+_RESULT_RE = re.compile(r"__RESULT__\s*(\{.*\})")
+_COMPARATORS: tuple[Comparator, ...] = (">=", "<=", ">", "<", "==")
+
+
+def _reject_constant(token: str) -> float:
+    # GRD parity: JS JSON.parse rejects NaN/Infinity/-Infinity. Mirror that.
+    raise ValueError(f"non-JSON constant: {token}")
+
+
+def parse_metrics_line(stdout: str) -> dict[str, float]:
+    """Extract {metric: number} from the first `__RESULT__ {json}` occurrence.
+
+    Mirrors GRD: non-numeric values are dropped. Python `bool` is an `int`
+    subclass, so booleans are excluded explicitly.
+    """
+    match = _RESULT_RE.search(stdout)
+    if not match:
+        return {}
+    try:
+        obj = json.loads(match.group(1), parse_constant=_reject_constant)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(obj, dict):
+        return {}
+    out: dict[str, float] = {}
+    for key, value in obj.items():
+        if isinstance(value, bool):
+            continue
+        if isinstance(value, (int, float)) and math.isfinite(value):
+            out[str(key)] = float(value)
+    return out
+
+
+def validate_metric_spec(spec: MetricSpec) -> None:
+    """Raise ValueError if the spec cannot drive a deterministic verdict."""
+    if not isinstance(spec.metric_key, str) or not spec.metric_key:
+        raise ValueError("MetricSpec.metric_key must be a non-empty string")
+    if spec.comparator not in _COMPARATORS:
+        raise ValueError(f"MetricSpec.comparator must be one of {_COMPARATORS}")
+    if not isinstance(spec.target, (int, float)) or isinstance(spec.target, bool):
+        raise ValueError("MetricSpec.target must be numeric")
+    if not math.isfinite(spec.target):
+        raise ValueError("MetricSpec.target must be finite")

autoresearch_core-0.1.1/autoresearch_core/failures.py

@@ -0,0 +1,26 @@
+"""Failure classification. Parity with GRD runner.ts classifyRunFailure."""
+from __future__ import annotations
+
+import re
+
+from .types import FailureClass
+
+_H2_RE = re.compile(
+    r"command not found|not found:|ModuleNotFoundError|ImportError", re.IGNORECASE
+)
+_H3_RE = re.compile(
+    r"No such file or directory|ENOENT|permission denied", re.IGNORECASE
+)
+
+
+def classify_run_failure(stderr: str, timed_out: bool) -> FailureClass:
+    """H4=timeout/other-runtime, H2=missing dep, H3=missing file/permission, none=empty."""
+    if timed_out:
+        return "H4"
+    if _H2_RE.search(stderr):
+        return "H2"
+    if _H3_RE.search(stderr):
+        return "H3"
+    if not stderr:
+        return "none"
+    return "H4"

autoresearch_core-0.1.1/autoresearch_core/gates.py

@@ -0,0 +1,33 @@
+"""Gate model. Parity with GRD gates.ts.
+
+The config sub-key is `experiment_execution` (NOT `execute`); it controls the
+runtime gate named `execute`. Any value other than literal False leaves it on.
+"""
+from __future__ import annotations
+
+from typing import Any, Literal, Mapping
+
+from .types import GateCheck, GateState
+
+
+def resolve_gates(config: Mapping[str, Any], no_gates: bool) -> GateState:
+    if no_gates:
+        return GateState(execute=False, kg_write=False)
+    _rg = config.get("research_gates")
+    rg: dict[str, object] = _rg if isinstance(_rg, dict) else {}
+    return GateState(
+        execute=rg.get("experiment_execution") is not False,
+        kg_write=rg.get("kg_write") is not False,
+    )
+
+
+def check_gate(gates: GateState, gate: Literal["execute", "kg_write"], approved: bool) -> GateCheck:
+    """Decide whether to proceed or pause at `gate`. Parity with GRD checkGate
+    (which also sets thread.status='paused'/pendingGate — the caller does that).
+    Unknown gate names raise ValueError (fail-fast; GRD would silently proceed)."""
+    current = getattr(gates, gate, None)
+    if current is None:
+        raise ValueError(f"unknown gate: {gate!r}")
+    if (not current) or approved:
+        return GateCheck(proceed=True, pending_gate=None)
+    return GateCheck(proceed=False, pending_gate=gate)

autoresearch_core-0.1.1/autoresearch_core/policy.py

@@ -0,0 +1,45 @@
+"""Pure decision policy + facades. Parity with GRD verdict.ts + promotion-authority rule."""
+from __future__ import annotations
+
+from .types import ExperimentResult, MetricSpec, Verdict, VerdictRecord
+from .verdict import DeterministicVerdict, VerdictStrategy
+
+
+def decide_branch(verdict: Verdict) -> str:
+    """'finalize' if supported, else 'revise'."""
+    return "finalize" if verdict == "supported" else "revise"
+
+
+def should_terminate(iteration: int, max_iterations: int, last_verdict: Verdict) -> tuple[bool, str]:
+    """Return (done, status). supported -> supported; budget hit -> exhausted; else active."""
+    if last_verdict == "supported":
+        return True, "supported"
+    if iteration >= max_iterations:
+        return True, "exhausted"
+    return False, "active"
+
+
+def detect_plateau(verdicts: list[Verdict], window: int = 3) -> bool:
+    """True when the last `window` verdicts are all non-supported."""
+    if len(verdicts) < window:
+        return False
+    return all(v != "supported" for v in verdicts[-window:])
+
+
+def should_promote_dead_end(record: VerdictRecord) -> bool:
+    """Codex rule: only a DETERMINISTIC refutation may auto-promote a dead-end."""
+    return record.verdict == "refuted" and record.evidence_level == "deterministic"
+
+
+def measure(
+    spec: MetricSpec, result: ExperimentResult, strategy: VerdictStrategy | None = None
+) -> VerdictRecord:
+    """Facade: evaluate a result under a verdict strategy (deterministic by default)."""
+    return (strategy or DeterministicVerdict()).evaluate(spec, result)
+
+
+def decide(iteration: int, max_iterations: int, verdict: Verdict) -> tuple[str, bool, str]:
+    """Facade: (branch, done, status) from a verdict. branch in {finalize, revise}."""
+    branch = decide_branch(verdict)
+    done, status = should_terminate(iteration, max_iterations, verdict)
+    return branch, done, status

autoresearch_core-0.1.1/autoresearch_core/ports.py

@@ -0,0 +1,34 @@
+"""Adapter protocols. Each project binds these to its own infra (no impl here)."""
+from __future__ import annotations
+
+from typing import Any, Protocol, Sequence, runtime_checkable
+
+from .types import ExperimentResult
+
+
+@runtime_checkable
+class Spawn(Protocol):
+    async def __call__(self, prompt: str) -> str: ...
+
+
+@runtime_checkable
+class Retriever(Protocol):
+    async def retrieve(self, query: str, k: int = 8) -> Sequence[dict[str, Any]]: ...
+
+
+@runtime_checkable
+class KnowledgeGraph(Protocol):
+    async def prior_findings(self, query: str) -> Sequence[dict[str, Any]]: ...
+    async def write_finding(self, finding: dict[str, Any]) -> None: ...
+
+
+@runtime_checkable
+class ExperimentRunner(Protocol):
+    def run(self, plan: dict[str, Any], workdir: str) -> ExperimentResult: ...
+
+
+@runtime_checkable
+class Store(Protocol):
+    def save_verdict(self, thread_id: str, record: Any) -> None: ...
+    def load_dead_end_hashes(self, scope: str) -> set[str]: ...
+    def save_dead_end(self, scope: str, record: Any) -> None: ...

autoresearch_core-0.1.1/autoresearch_core/promote.py

@@ -0,0 +1,48 @@
+"""Promotion record shapes (KNOWHOW / DEAD-ENDS). Shape only; projects persist."""
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass
+
+from .policy import should_promote_dead_end
+from .types import Hypothesis, VerdictRecord
+
+
+@dataclass(frozen=True)
+class DeadEndRecord:
+    approach_hash: str
+    statement: str
+    reason: str
+    iteration: int
+    evidence_level: str
+
+
+@dataclass(frozen=True)
+class KnowhowRecord:
+    statement: str
+    content: str
+    iteration: int
+
+
+def approach_hash(statement: str) -> str:
+    """Stable, case/space-insensitive hash used to dedupe approaches."""
+    normalized = re.sub(r"\s+", " ", statement.strip().lower())
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
+
+
+def build_dead_end_record(hypothesis: Hypothesis, record: VerdictRecord) -> DeadEndRecord:
+    if not should_promote_dead_end(record):
+        raise ValueError("build_dead_end_record requires a deterministic refutation")
+    return DeadEndRecord(
+        approach_hash=approach_hash(hypothesis.statement),
+        statement=hypothesis.statement,
+        reason=record.detail,
+        iteration=hypothesis.iteration,
+        evidence_level=record.evidence_level,
+    )
+
+
+def should_skip(statement: str, dead_end_hashes: set[str]) -> bool:
+    """Don't re-propose an approach already in the dead-ends set."""
+    return approach_hash(statement) in dead_end_hashes

autoresearch_core-0.1.1/autoresearch_core/py.typed

@@ -0,0 +1 @@
+# PEP 561 marker: autoresearch-core ships inline type annotations.

autoresearch_core-0.1.1/autoresearch_core/types.py

@@ -0,0 +1,79 @@
+"""Core data definitions for autoresearch-core. Pure data, no logic, no I/O."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+Verdict = Literal["supported", "refuted", "inconclusive"]
+Comparator = Literal[">=", "<=", ">", "<", "=="]
+FailureClass = Literal["H2", "H3", "H4", "none"]
+EvidenceLevel = Literal["deterministic", "exit_code", "llm"]
+HypothesisStatus = Literal[
+    "open", "testing", "supported", "refuted", "inconclusive", "superseded"
+]
+TakeawayKind = Literal[
+    "success_pattern", "failure_root_cause", "constraint", "domain_fact", "tool_pattern"
+]
+
+
+@dataclass(frozen=True)
+class MetricSpec:
+    """The machine-readable verdict contract a hypothesis must carry."""
+    metric_key: str
+    comparator: Comparator
+    target: float
+
+
+@dataclass(frozen=True)
+class ExperimentResult:
+    metrics: dict[str, float]
+    exit_code: int
+    failure_class: FailureClass = "none"
+    runner: str = "subprocess"
+    duration_ms: int = 0
+    stdout_excerpt: str = ""
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "metrics", dict(self.metrics))
+
+
+@dataclass(frozen=True)
+class VerdictRecord:
+    verdict: Verdict
+    strategy: str
+    evidence_level: EvidenceLevel
+    detail: str
+    raw_evidence_ref: str | None = None
+
+
+@dataclass(frozen=True)
+class Hypothesis:
+    id: str
+    iteration: int
+    statement: str
+    predicted_outcome: str
+    status: HypothesisStatus = "open"
+    parent_id: str | None = None
+    verdict: Verdict | None = None
+
+
+@dataclass(frozen=True)
+class Takeaway:
+    kind: TakeawayKind
+    content: str
+    confidence: float
+    evidence: str
+    failure_class: FailureClass
+    iteration: int
+
+
+@dataclass(frozen=True)
+class GateState:
+    execute: bool = True
+    kg_write: bool = True
+
+
+@dataclass(frozen=True)
+class GateCheck:
+    proceed: bool
+    pending_gate: str | None = None

autoresearch_core-0.1.1/autoresearch_core/verdict.py

@@ -0,0 +1,64 @@
+"""Deterministic verdict. Parity with GRD verdict.ts (compare + evaluateVerdict)."""
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from .types import Comparator, ExperimentResult, MetricSpec, VerdictRecord
+
+
+def compare(value: float, comparator: Comparator, target: float) -> bool:
+    if comparator == ">=":
+        return value >= target
+    if comparator == "<=":
+        return value <= target
+    if comparator == ">":
+        return value > target
+    if comparator == "<":
+        return value < target
+    if comparator == "==":
+        return value == target
+    return False
+
+
+@runtime_checkable
+class VerdictStrategy(Protocol):
+    name: str
+
+    def evaluate(self, spec: MetricSpec, result: ExperimentResult) -> VerdictRecord: ...
+
+
+class DeterministicVerdict:
+    """Authoritative strategy: numeric metric vs target. evidence_level='deterministic'."""
+
+    name = "deterministic"
+
+    def evaluate(self, spec: MetricSpec, result: ExperimentResult) -> VerdictRecord:
+        if result.exit_code != 0:
+            return VerdictRecord(
+                verdict="inconclusive",
+                strategy=self.name,
+                evidence_level="deterministic",
+                detail=f"experiment run failed ({result.failure_class})",
+            )
+        if spec.metric_key not in result.metrics:
+            return VerdictRecord(
+                verdict="inconclusive",
+                strategy=self.name,
+                evidence_level="deterministic",
+                detail=f'metric "{spec.metric_key}" not reported',
+            )
+        value = result.metrics[spec.metric_key]
+        passed = compare(value, spec.comparator, spec.target)
+        return VerdictRecord(
+            verdict="supported" if passed else "refuted",
+            strategy=self.name,
+            evidence_level="deterministic",
+            detail=f"{spec.metric_key}={_fmt(value)} {spec.comparator} {_fmt(spec.target)} "
+            f"→ {'pass' if passed else 'fail'}",
+        )
+
+
+def _fmt(n: float) -> str:
+    """Render 5 not 5.0; 0.9 stays 0.9. The `detail` string is human-readable and
+    NOT a byte-for-byte parity guarantee with GRD — only the verdict OUTCOME is."""
+    return str(int(n)) if isinstance(n, float) and n.is_integer() else str(n)

autoresearch_core-0.1.1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "autoresearch-core"
+version = "0.1.1"
+description = "Decision-contracts library: deterministic verdict/gate/failure/promotion logic for autoresearch loops."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Cameleon X", email = "ca1773130n@gmail.com" }]
+keywords = ["autoresearch", "decision-contracts", "verdict", "research-loop", "deterministic", "agent"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/ca1773130n/autoresearch-core"
+Repository = "https://github.com/ca1773130n/autoresearch-core"
+Issues = "https://github.com/ca1773130n/autoresearch-core/issues"
+Changelog = "https://github.com/ca1773130n/autoresearch-core/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "pytest-cov>=5.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["autoresearch_core"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

autoresearch_core-0.1.1/tests/test_contract.py

@@ -0,0 +1,71 @@
+import pytest
+from autoresearch_core.contract import parse_metrics_line, validate_metric_spec
+from autoresearch_core.types import MetricSpec
+
+
+def test_parses_first_result_line_numeric_only():
+    assert parse_metrics_line('noise\n__RESULT__ {"latency_ms": 180, "ok": "yes"}\nmore') == {
+        "latency_ms": 180.0
+    }
+
+
+def test_excludes_bool_values():
+    # bool is a subclass of int in Python; must not leak in as 1.0/0.0
+    assert parse_metrics_line('__RESULT__ {"passed": true, "n": 3}') == {"n": 3.0}
+
+
+def test_missing_marker_or_bad_json_returns_empty():
+    assert parse_metrics_line("no marker here") == {}
+    assert parse_metrics_line("__RESULT__ {not json}") == {}
+
+
+def test_rejects_nan_and_infinity_like_js():
+    # JS JSON.parse rejects these tokens; GRD returns {} — match that.
+    assert parse_metrics_line('__RESULT__ {"x": NaN}') == {}
+    assert parse_metrics_line('__RESULT__ {"x": Infinity}') == {}
+
+
+def test_first_of_multiple_result_lines():
+    assert parse_metrics_line('__RESULT__ {"a": 1}\n__RESULT__ {"a": 2}') == {"a": 1.0}
+
+
+def test_validate_metric_spec():
+    validate_metric_spec(MetricSpec("recall", ">=", 0.8))  # no raise
+    with pytest.raises(ValueError):
+        validate_metric_spec(MetricSpec("", ">=", 0.8))
+    with pytest.raises(ValueError):
+        validate_metric_spec(MetricSpec("x", "!=", 0.8))  # type: ignore[arg-type]
+
+
+def test_greedy_regex_drops_line_with_trailing_junk_grd_parity():
+    # INTENTIONAL: GRD's runner.ts regex is greedy (\{.*\}), so a line with
+    # trailing JSON-shaped junk captures the whole span, JSON.parse fails, and
+    # the result is dropped. We MATCH that behavior on purpose. Do not "fix" to
+    # non-greedy — that would diverge from GRD. The __RESULT__ contract is one
+    # clean `{json}` per line.
+    assert parse_metrics_line('__RESULT__ {"a": 1} junk {"b": 2}') == {}
+
+
+def test_validate_metric_spec_rejects_bool_target():
+    with pytest.raises(ValueError):
+        validate_metric_spec(MetricSpec("x", ">=", True))  # type: ignore[arg-type]
+
+
+def test_parse_metrics_drops_overflow_to_inf():
+    # 1e999 overflows to float('inf') in Python JSON; must be dropped (non-finite guard).
+    assert parse_metrics_line('__RESULT__ {"x": 1e999}') == {}
+
+
+def test_parse_metrics_drops_neg_inf():
+    # -1e999 overflows to float('-inf'); must also be dropped.
+    assert parse_metrics_line('__RESULT__ {"x": -1e999}') == {}
+
+
+def test_validate_metric_spec_rejects_inf_target():
+    with pytest.raises(ValueError):
+        validate_metric_spec(MetricSpec("x", ">=", float("inf")))
+
+
+def test_validate_metric_spec_rejects_nan_target():
+    with pytest.raises(ValueError):
+        validate_metric_spec(MetricSpec("x", ">=", float("nan")))

autoresearch_core-0.1.1/tests/test_failures.py

@@ -0,0 +1,18 @@
+from autoresearch_core.failures import classify_run_failure
+
+
+def test_classify():
+    assert classify_run_failure("", True) == "H4"                       # timeout wins
+    assert classify_run_failure("ModuleNotFoundError: x", False) == "H2"
+    assert classify_run_failure("ImportError: bad", False) == "H2"
+    assert classify_run_failure("bash: foo: command not found", False) == "H2"
+    assert classify_run_failure("not found: foo", False) == "H2"
+    assert classify_run_failure("ENOENT: no such file", False) == "H3"
+    assert classify_run_failure("permission denied", False) == "H3"
+    assert classify_run_failure("", False) == "none"                    # empty stderr
+    assert classify_run_failure("segfault boom", False) == "H4"         # other runtime
+
+
+def test_h2_takes_precedence_over_h3_when_both_present():
+    # GRD checks H2 before H3
+    assert classify_run_failure("ImportError and No such file or directory", False) == "H2"

autoresearch_core-0.1.1/tests/test_gates.py

@@ -0,0 +1,43 @@
+from autoresearch_core.gates import resolve_gates, check_gate
+from autoresearch_core.types import GateState
+
+
+def test_resolve_defaults_on():
+    g = resolve_gates({}, no_gates=False)
+    assert g.execute is True and g.kg_write is True
+
+
+def test_resolve_disable_execute_via_experiment_execution_key():
+    g = resolve_gates({"research_gates": {"experiment_execution": False}}, no_gates=False)
+    assert g.execute is False and g.kg_write is True
+
+
+def test_no_gates_disables_all():
+    g = resolve_gates({"research_gates": {"experiment_execution": True}}, no_gates=True)
+    assert g.execute is False and g.kg_write is False
+
+
+def test_check_gate_pause_vs_proceed():
+    gates = GateState(execute=True, kg_write=True)
+    paused = check_gate(gates, "execute", approved=False)
+    assert paused.proceed is False and paused.pending_gate == "execute"
+    assert check_gate(gates, "execute", approved=True).proceed is True
+    assert check_gate(GateState(execute=False), "execute", approved=False).proceed is True
+
+
+def test_check_gate_unknown_gate_raises():
+    import pytest
+    with pytest.raises(ValueError):
+        check_gate(GateState(), "nope", approved=False)  # type: ignore[arg-type]
+
+
+def test_resolve_gates_non_dict_research_gates_treated_as_empty():
+    # When research_gates is a non-dict (e.g. True), fall back to defaults (both on).
+    g = resolve_gates({"research_gates": True}, no_gates=False)
+    assert g.execute is True and g.kg_write is True
+
+    g2 = resolve_gates({"research_gates": 1}, no_gates=False)
+    assert g2.execute is True and g2.kg_write is True
+
+    g3 = resolve_gates({"research_gates": "yes"}, no_gates=False)
+    assert g3.execute is True and g3.kg_write is True

autoresearch_core-0.1.1/tests/test_parity.py

@@ -0,0 +1,58 @@
+# tests/test_parity.py
+"""Vectors transcribed from GRD lib/research/{verdict.ts,runner.ts,gates.ts}.
+If GRD changes these behaviors, update here deliberately — do not loosen."""
+import autoresearch_core as ac
+from autoresearch_core.types import MetricSpec, ExperimentResult
+
+
+def test_public_surface_exports():
+    for name in [
+        "MetricSpec", "ExperimentResult", "VerdictRecord", "GateState", "GateCheck",
+        "parse_metrics_line", "classify_run_failure", "compare",
+        "DeterministicVerdict", "resolve_gates", "check_gate",
+        "decide_branch", "should_terminate", "detect_plateau",
+        "should_promote_dead_end", "measure", "decide",
+        "approach_hash", "build_dead_end_record",
+    ]:
+        assert hasattr(ac, name), f"missing public export: {name}"
+
+
+def test_end_to_end_supported_path():
+    spec = MetricSpec("recall_at_10", ">=", 0.8)
+    stdout = 'log line\n__RESULT__ {"recall_at_10": 0.83}\n'
+    metrics = ac.parse_metrics_line(stdout)
+    result = ExperimentResult(metrics=metrics, exit_code=0)
+    rec = ac.DeterministicVerdict().evaluate(spec, result)
+    assert rec.verdict == "supported"
+    assert ac.decide_branch(rec.verdict) == "finalize"
+    assert ac.should_promote_dead_end(rec) is False
+
+
+def test_end_to_end_refuted_then_promote():
+    spec = MetricSpec("latency_ms", "<", 200)
+    result = ExperimentResult(metrics={"latency_ms": 300.0}, exit_code=0)
+    rec = ac.DeterministicVerdict().evaluate(spec, result)
+    assert rec.verdict == "refuted"
+    assert ac.decide_branch(rec.verdict) == "revise"
+    assert ac.should_promote_dead_end(rec) is True
+
+
+def test_end_to_end_failed_run_is_inconclusive():
+    spec = MetricSpec("x", ">=", 1)
+    err = ExperimentResult(metrics={}, exit_code=127, failure_class="H2")
+    rec = ac.DeterministicVerdict().evaluate(spec, err)
+    assert rec.verdict == "inconclusive"
+    assert ac.should_promote_dead_end(rec) is False  # inconclusive never promotes
+
+
+def test_invalid_comparator_returns_false():
+    assert ac.compare(1, "!=", 1) is False  # type: ignore[arg-type]
+
+
+def test_exit_code_precedence_over_metrics():
+    # non-zero exit -> inconclusive even when a metric is present
+    spec = MetricSpec("x", ">=", 1)
+    rec = ac.DeterministicVerdict().evaluate(
+        spec, ExperimentResult(metrics={"x": 5.0}, exit_code=1, failure_class="H4")
+    )
+    assert rec.verdict == "inconclusive"

autoresearch_core-0.1.1/tests/test_policy.py

@@ -0,0 +1,40 @@
+from autoresearch_core.policy import (
+    decide_branch, should_terminate, detect_plateau, should_promote_dead_end,
+    measure, decide,
+)
+from autoresearch_core.types import MetricSpec, ExperimentResult, VerdictRecord
+
+
+def test_decide_branch():
+    assert decide_branch("supported") == "finalize"
+    assert decide_branch("refuted") == "revise"
+    assert decide_branch("inconclusive") == "revise"
+
+
+def test_should_terminate():
+    assert should_terminate(2, 8, "supported") == (True, "supported")
+    assert should_terminate(8, 8, "refuted") == (True, "exhausted")
+    assert should_terminate(3, 8, "refuted") == (False, "active")
+
+
+def test_detect_plateau():
+    assert detect_plateau(["refuted", "refuted"], window=3) is False       # too few
+    assert detect_plateau(["refuted", "inconclusive", "refuted"]) is True
+    assert detect_plateau(["refuted", "supported", "refuted"]) is False
+
+
+def test_promotion_authority_deterministic_only():
+    det = VerdictRecord("refuted", "deterministic", "deterministic", "x<y")
+    llm = VerdictRecord("refuted", "reviewer", "llm", "looks wrong")
+    ok = VerdictRecord("supported", "deterministic", "deterministic", "x>=y")
+    assert should_promote_dead_end(det) is True
+    assert should_promote_dead_end(llm) is False    # advisory only
+    assert should_promote_dead_end(ok) is False      # supported never promotes
+
+
+def test_measure_and_decide_facades():
+    spec = MetricSpec("recall", ">=", 0.8)
+    rec = measure(spec, ExperimentResult(metrics={"recall": 0.9}, exit_code=0))
+    assert rec.verdict == "supported" and rec.evidence_level == "deterministic"
+    assert decide(2, 8, rec.verdict) == ("finalize", True, "supported")
+    assert decide(3, 8, "refuted") == ("revise", False, "active")

autoresearch_core-0.1.1/tests/test_ports.py

@@ -0,0 +1,26 @@
+from autoresearch_core.ports import ExperimentRunner, Store
+from autoresearch_core.types import ExperimentResult
+
+
+class FakeRunner:
+    def run(self, plan: dict, workdir: str) -> ExperimentResult:
+        return ExperimentResult(metrics={"x": 1.0}, exit_code=0)
+
+
+class FakeStore:
+    def __init__(self):
+        self.dead_ends: dict[str, list] = {}
+
+    def save_verdict(self, thread_id: str, record) -> None:
+        pass
+
+    def load_dead_end_hashes(self, scope: str) -> set[str]:
+        return set()
+
+    def save_dead_end(self, scope: str, record) -> None:
+        self.dead_ends.setdefault(scope, []).append(record)
+
+
+def test_fakes_satisfy_protocols():
+    assert isinstance(FakeRunner(), ExperimentRunner)
+    assert isinstance(FakeStore(), Store)

autoresearch_core-0.1.1/tests/test_promote.py

@@ -0,0 +1,47 @@
+import pytest
+from autoresearch_core.promote import (
+    approach_hash, build_dead_end_record, should_skip, DeadEndRecord,
+)
+from autoresearch_core.types import Hypothesis, VerdictRecord
+
+
+def test_approach_hash_is_normalized_and_stable():
+    a = approach_hash("  Memoize The Tokenizer  ")
+    b = approach_hash("memoize the tokenizer")
+    assert a == b and len(a) == 16
+
+
+def test_build_dead_end_record():
+    h = Hypothesis(id="h1", iteration=2, statement="cache embeddings",
+                   predicted_outcome="faster")
+    rec = VerdictRecord("refuted", "deterministic", "deterministic", "latency=300 < 200 -> fail")
+    de = build_dead_end_record(h, rec)
+    assert isinstance(de, DeadEndRecord)
+    assert de.statement == "cache embeddings" and de.iteration == 2
+    assert de.evidence_level == "deterministic" and de.reason.endswith("fail")
+
+
+def test_should_skip_against_known_hashes():
+    seen = {approach_hash("cache embeddings")}
+    assert should_skip("Cache Embeddings", seen) is True
+    assert should_skip("use a bloom filter", seen) is False
+
+
+def test_approach_hash_whitespace_normalization():
+    # Internal runs of whitespace must collapse to a single space.
+    assert approach_hash("cache   embeddings") == approach_hash("cache embeddings")
+    assert approach_hash("cache\t\tembeddings") == approach_hash("cache embeddings")
+    assert approach_hash("cache\n embeddings") == approach_hash("cache embeddings")
+
+
+def test_build_dead_end_record_raises_on_non_deterministic_refutation():
+    h = Hypothesis(id="h2", iteration=1, statement="use llm scoring",
+                   predicted_outcome="better")
+    # supported + llm — neither condition of should_promote_dead_end is met
+    rec_supported = VerdictRecord("supported", "deterministic", "deterministic", "ok")
+    with pytest.raises(ValueError, match="deterministic refutation"):
+        build_dead_end_record(h, rec_supported)
+    # refuted but evidence_level=llm — not deterministic
+    rec_llm = VerdictRecord("refuted", "deterministic", "llm", "llm said no")
+    with pytest.raises(ValueError, match="deterministic refutation"):
+        build_dead_end_record(h, rec_llm)

autoresearch_core-0.1.1/tests/test_types.py

@@ -0,0 +1,35 @@
+import dataclasses
+import pytest
+from autoresearch_core.types import (
+    MetricSpec, ExperimentResult, VerdictRecord, Hypothesis, Takeaway, GateState,
+)
+
+def test_dataclasses_construct_and_are_frozen():
+    spec = MetricSpec(metric_key="recall", comparator=">=", target=0.8)
+    assert spec.metric_key == "recall" and spec.comparator == ">=" and spec.target == 0.8
+    res = ExperimentResult(metrics={"recall": 0.9}, exit_code=0)
+    assert res.failure_class == "none" and res.runner == "subprocess"
+    rec = VerdictRecord(verdict="supported", strategy="deterministic",
+                        evidence_level="deterministic", detail="ok")
+    assert rec.raw_evidence_ref is None
+    gates = GateState()
+    assert gates.execute is True and gates.kg_write is True
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        spec.target = 0.5  # type: ignore[misc]
+
+
+def test_experiment_result_defensive_copy():
+    # Mutating the source dict after construction must not alter .metrics.
+    src = {"recall": 0.9, "latency_ms": 120.0}
+    res = ExperimentResult(metrics=src, exit_code=0)
+    src["recall"] = 0.0
+    src["new_key"] = 999.0
+    assert res.metrics["recall"] == 0.9
+    assert "new_key" not in res.metrics
+
+
+def test_experiment_result_metrics_is_still_frozen():
+    # The defensive copy must not make metrics itself mutable via setattr.
+    res = ExperimentResult(metrics={"x": 1.0}, exit_code=0)
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        res.metrics = {}  # type: ignore[misc]

autoresearch_core-0.1.1/tests/test_verdict.py

@@ -0,0 +1,29 @@
+from autoresearch_core.verdict import compare, DeterministicVerdict
+from autoresearch_core.types import MetricSpec, ExperimentResult
+
+
+def test_compare_all_operators():
+    assert compare(0.8, ">=", 0.8) is True
+    assert compare(199, "<", 200) is True
+    assert compare(5, "==", 5) is True
+    assert compare(5, ">", 5) is False
+    assert compare(5, "<=", 4) is False
+
+
+def test_deterministic_supported_and_refuted():
+    strat = DeterministicVerdict()
+    spec = MetricSpec("recall", ">=", 0.8)
+    rec = strat.evaluate(spec, ExperimentResult(metrics={"recall": 0.9}, exit_code=0))
+    assert rec.verdict == "supported" and rec.evidence_level == "deterministic"
+    assert rec.detail == "recall=0.9 >= 0.8 → pass"
+    rec2 = strat.evaluate(spec, ExperimentResult(metrics={"recall": 0.5}, exit_code=0))
+    assert rec2.verdict == "refuted"
+
+
+def test_deterministic_inconclusive_paths():
+    strat = DeterministicVerdict()
+    spec = MetricSpec("recall", ">=", 0.8)
+    bad = strat.evaluate(spec, ExperimentResult(metrics={}, exit_code=1, failure_class="H2"))
+    assert bad.verdict == "inconclusive" and "H2" in bad.detail
+    missing = strat.evaluate(spec, ExperimentResult(metrics={"other": 1.0}, exit_code=0))
+    assert missing.verdict == "inconclusive" and "not reported" in missing.detail