Skip to main content

autoresearch-core

CI PyPI Python License: MIT

A tiny, pure-Python decision-contracts library for autoresearch / agentic loops: a deterministic verdict (metric / comparator / target), failure classification, gates, promotion record shapes, and — since 0.4.3 — life-harness round contracts (evidence-driven self-improvement policy) — 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 Protocols and call measure / decide / should_promote_dead_end at your decision points. The verdict logic is parity-tested against the GRD autoresearch loop.

Why

Agentic research loops fail in a predictable way: the model grades its own homework. An LLM proposes a hypothesis, runs an experiment, then judges whether the result supports the hypothesis — and judgment drifts. autoresearch-core removes the judge from the control path:

  1. Every hypothesis must carry a machine-readable contract (MetricSpec: which metric, which comparator, which target).
  2. Experiments report results through a machine-readable line (__RESULT__ {"accuracy": 0.93} on stdout).
  3. The verdict is computed, not judged: metric vs target → supported / refuted / inconclusive.
  4. Only a deterministic refutation may auto-promote a dead-end. Anything judged by an LLM or inferred from an exit code is advisory.

Install

pip install autoresearch-core

Requires Python 3.11+. No runtime dependencies. Fully typed (py.typed).

Quickstart

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

Documentation

  • QUICKSTART — zero to a working deterministic verdict in five minutes, with a complete runnable script.
  • TUTORIAL — build a full hypothesis → experiment → measure → learn loop on top of the library: contracts, failure classes, gates, dead-end promotion, infrastructure ports, and custom verdict strategies.
  • RELEASING — ownership, versioning policy, release procedure, and the shared parity-vector contract with GRD.
  • CHANGELOG

What it owns (and what it doesn't)

Owns — the decision discipline:

Module Public surface Job
types MetricSpec, ExperimentResult, VerdictRecord, Hypothesis, Takeaway, GateState, GateCheck Frozen dataclasses; pure data, no logic
contract parse_metrics_line, validate_metric_spec The __RESULT__ {json} experiment-result contract
verdict compare, DeterministicVerdict, VerdictStrategy Metric vs target → supported / refuted / inconclusive
failures classify_run_failure stderr → H2 (missing dep) / H3 (missing file / permission) / H4 (timeout / runtime) / none
gates resolve_gates, check_gate Approval gates (execute, kg_write) resolved from config
policy measure, decide, decide_branch, should_terminate, detect_plateau, should_promote_dead_end The loop's branch / terminate / promote decisions
promote DeadEndRecord, KnowhowRecord, approach_hash, build_dead_end_record, should_skip Promotion record shapes + approach dedupe
rounds resolve_autonomy, select_evidence, validate_round_patch, patch_hash, should_apply, decide_round (+ Finding, PatchEntry, RoundPatch, EvalReport, AutonomyState, RoundRecord in types) Life-harness rounds: the policy for patching a harness's own primitives from session evidence

Doesn't own — bind these via ports.py Protocols to your own infra: Spawn (LLM call), Retriever, KnowledgeGraph, ExperimentRunner, Store, and for rounds: FindingsSource, PatchProposer, RoundEvaluator, Applier, RoundStore. No implementations ship in this package; the tutorial shows minimal bindings.

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.

Life-harness rounds (0.4.3)

The same discipline, pointed at the harness itself: a round turns session evidence (e.g. Tesserae-compiled takeaways) into one eval-gated, reversible patch to the host's own primitives. The kernel owns the decisions — evidence selection, patch validation (path guards + a self-protection deny-list: a round can never patch its own driver or autonomy config), dedupe, and the apply gate (kill switch > eval > review-mode > confidence). Hosts bind the I/O through five protocols and keep the forge in git: one commit per round, revert = git revert.

from autoresearch_core import (
    AutonomyState, EvalCheck, EvalReport, PatchEntry, RoundPatch, decide_round,
)

patch = RoundPatch(round_id="r1", entries=(
    PatchEntry(path="commands/execute-phase.md", kind="markdown", op="modify",
               content="...", rationale="executor keeps forgetting to commit"),
), summary="commit reminder in executor prompt", confidence=0.9)

decide_round(patch, AutonomyState(), set(), EvalReport(checks=(EvalCheck("lint", 0),)))
# ('evaluated', 'awaiting review (harness_review)')   — review mode is the default

Reference host: GRD's gd harness round. Design: life-harness rounds spec. Note: the package version is locked to GRD's version line from 0.4.3 onward (see RELEASING).

Development

pip install -e ".[dev]"
pytest -q --cov=autoresearch_core

The test suite includes a parity suite (tests/test_parity.py) that pins behaviour to the GRD TypeScript implementation.

License

MIT © Cameleon X — see LICENSE.

Metadata

Release files for autoresearch-core 0.4.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for autoresearch-core 0.4.4
File Size Uploaded Provenance Actions
autoresearch_core-0.4.4.tar.gz 44.6 kB With provenance Details for autoresearch_core-0.4.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for autoresearch-core 0.4.4
File Interpreter ABI Platform Actions
autoresearch_core-0.4.4-py3-none-any.whl Python 3 none any Details for autoresearch_core-0.4.4-py3-none-any.whl

Total release size: 61.1 kB

Release files / autoresearch_core-0.4.4.tar.gz

Download URL autoresearch_core-0.4.4.tar.gz
Size 44.6 kB
Tags Source
SHA-256 checksum
How to use checksums
942f4e045797112ffc0595123d7e68b94132cb5688997743e530e7ceecb1aaf0
BLAKE2b-256 checksum
How to use checksums
0ecdfa54caf8e453623688265997feccf77649b6f6fb03150ad53b6e25c41bbd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 8, 2026.

Transparency log

Release files / autoresearch_core-0.4.4-py3-none-any.whl

Download URL autoresearch_core-0.4.4-py3-none-any.whl
Size 16.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f3b763acc371198b572ccbfb86db7a4e1783c3ae5c75682a42b94a0072802db3
BLAKE2b-256 checksum
How to use checksums
218e09a6c3478f4486bb4551e2bf1ac2363b7c392cec62019ffb7d9bdd80898f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 8, 2026.

Transparency log

Security for autoresearch-core 0.4.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for autoresearch_core-0.4.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jun 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page