research-evidence-agent

research-evidence-agent is a local-first provenance and claim–evidence audit tool for computational and experimental research bundles.

It keeps four evidence layers explicit:

• raw experiment;
• reprocessed data;
• model output or inference; and
• synthetic illustration.

The deterministic core creates SHA-256 manifests, applies user-reviewable path rules, flags unclassified or sensitive-looking files, and checks whether a claim ledger cites evidence of a compatible type. It never interprets scientific values.

An optional OpenAI Agents SDK layer can review aggregate counts and issue codes. By default, the agent receives neither file contents nor individual filenames.

Quick start

python -m pip install -e ".[dev]"
research-evidence-agent demo --output-dir outputs/demo-bundle
pytest

Scan a real local bundle without uploading it:

research-evidence-agent scan ./my-study --output manifest.json
research-evidence-agent audit manifest.json claims.json

Claim ledger

{
  "claims": [
    {
      "id": "claim-1",
      "text": "A directly observed trend.",
      "claim_type": "observation",
      "evidence": ["ev-0123456789ab"]
    }
  ]
}

An observation without raw evidence fails. Model-only support cannot be silently rewritten as an observation. Warnings and errors are machine-readable so the tool can run in CI before a report or data package is released.

Optional OpenAI agent

python -m pip install -e ".[agent]"
export OPENAI_API_KEY="..."
export OPENAI_MODEL="gpt-5.6-terra"
research-evidence-agent agent ./my-study

The Agents SDK wraps one aggregate-only function tool. The model organizes the risk report; deterministic code owns hashing, classification and validation. See the agent boundary.

Scope boundary

This package helps prevent category errors and provenance loss. It does not prove that an experiment is correct, a model is valid, a paper claim is causal, or a dataset may legally be redistributed. Human domain review remains required.

BSD-3-Clause licensed.

AI × engineering × research portfolio

Companion repositories:

• tailaware-rve — tail-aware scientific surrogate diagnostics;
• engineering-run-agent — read-only solver and scheduler triage; and
• synthetic-gpa-agent — synthetic microscopy-method validation.