Mareforma

Verify your AI scientists' findings the way science verifies itself
signed provenance · independent replication · human validation · local-first

Quickstart  ·  Docs  ·  Examples

PyPI Python Tests License: MIT

Mareforma is a local-first library where AI scientists record their findings as claims. Each claim cites the claims it builds on and can contradict others, forming a knowledge graph. Trust is read from that graph, not from the agents' self-reported confidence.

The silent failure it catches

The most dangerous result an AI scientist returns is the one that looks right but never touched the data. A step fails quietly, the model fills the gap from memory, and the answer is indistinguishable from a real one.

graph.assert_claim(
    finding_text,
    # The one line that breaks the symmetry: classification records
    # whether real data reached the result, or the model filled the gap.
    classification="ANALYTICAL" if data_ran else "INFERRED",
    generated_by="agent/lab-a",
    source_name=dataset_id if data_loaded else None,
)

Ask for grounded, replicated claims and the fabricated one drops out: still recorded and traceable, never trusted. Example 05 runs this against a real research agent.

Install

uv add mareforma
mareforma bootstrap   # optional: sign your claims and enable the public log

Capabilities

What you get What it does
Signed claims Each claim shows who stands behind it and cannot be altered unnoticed.
Grounding check Records whether a finding actually rests on data it read, or on the model's memory.
Trust map mareforma map <claim> places every trust property (grounding, independence, contestation, witnessing) at its tier, and states plainly what it does not evaluate.
Audit-grade verify mareforma verify <claim> re-checks signatures, the grounding-to-citation binding, and support level, with stable exit codes for CI (0 verified, 1 tampered, 2 unverifiable).
Diagnose a run mareforma diagnose -- python run.py runs a target under the observer and reports what data actually flowed, and where a silent fallback hid.
Optional public log Publish a claim to a public, append-only log for an independent, timestamped record.
Local-first Runs on local SQLite. Network only for the optional log.

The trust ladder

A claim's support level is read from the graph, never self-reported. High-trust claims are re-checked against their signatures on every read, so a tampered claim in a shared graph is caught when you query, not served.

Level Meaning
PRELIMINARY One agent asserted it. No independent agreement yet.
REPLICATED Two agents signing with different keys converged on the same established finding. A convergence marker, not proof of independence: signing keys are operator-mintable, so distinct signatures are a weak prior.
ESTABLISHED A human reviewer signed off, listing the evidence they checked. When the optional public log is enabled, promotion also requires the claim to be witnessed there; without it, the transparency flag is set locally and no external witness is involved.

Independence is reported as its own axis, not folded into the ladder. mareforma map marks it UNVERIFIABLE whenever every validator traces to a single trust root. That is the honest reading when the same operator could mint every key. Operators who want data-distinctness as a hard promotion gate can open with strict_promotion=True, which requires distinct data on both sides before a pair converges.

Classification is a separate axis the agent declares: INFERRED (model reasoning), ANALYTICAL (analysis run against real data), DERIVED (built on higher-trust claims). Ask for both at once: graph.query(text, min_support="REPLICATED", classification="ANALYTICAL").

Examples

Example What it shows
01 API Walkthrough The full API in one runnable script
02 Compounding Agents Findings accumulate across agent runs
03 Documented Contestation An agent challenges established consensus
04 Private Data, Public Findings Two labs share provenance without sharing data
05 Drug Target Provenance A real research agent with honest evidence labels
06 Verify in CI mareforma verify as a GitHub Actions gate, keyed on exit codes

AGENTS.md: execution contract and adapters  ·  ARCHITECTURE.md: system design  ·  SECURITY.md: threat model  ·  CONTRIBUTING.md: dev workflow  ·  CHANGELOG.md: releases

Project links

Data verified by PyPI on Jul 9, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.3.13)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for felipeyanez from gravatar.com felipeyanez

GitHub Statistics

Data verified by PyPI on Jul 9, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

clawinstitute tooluniverse gemini dev test-heavy docs

Tags

epistemic-graph ai-scientists provenance reproducibility multi-agent research

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mareforma-0.3.9.tar.gz (645.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mareforma-0.3.9-py3-none-any.whl (385.7 kB view details)

Uploaded Python 3

File details

Details for the file mareforma-0.3.9.tar.gz.

File metadata

  • Download URL: mareforma-0.3.9.tar.gz
  • Upload date:
  • Size: 645.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for mareforma-0.3.9.tar.gz
Algorithm Hash digest
SHA256 04e1a59fe8db4f2c5180a30a1ac31d094c6561d720eae212276345ccca86faa1
MD5 93b489b89ce36a80855e6c0c0e265e63
BLAKE2b-256 1ef5494715ff0919af0c1d27b530ecee976575f443471b562756b5109acc420e

See more details on using hashes here.

Provenance

The following attestation bundles were made for mareforma-0.3.9.tar.gz:

Publisher: publish.yml on mareforma/mareforma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mareforma-0.3.9-py3-none-any.whl.

File metadata

  • Download URL: mareforma-0.3.9-py3-none-any.whl
  • Upload date:
  • Size: 385.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for mareforma-0.3.9-py3-none-any.whl
Algorithm Hash digest
SHA256 f8b657f8b38208ced1f4f9dfe6e21741f330d3180b6b50fdf8cf487df56cdfa7
MD5 d6f3a3aa091cbde0a34a53f75a075466
BLAKE2b-256 4cace33e60588446259bb0d0d16a1e29a488ed0ed969e1e73a15166d79f49a7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for mareforma-0.3.9-py3-none-any.whl:

Publisher: publish.yml on mareforma/mareforma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page