API Walkthrough

View on GitHub

examples/01_api_walkthrough/

Every API method demonstrated in sequence: assert, query, get, validate. Runs in a temporary directory with no external dependencies. Trust reads off the derived axes graph.proposition_status(prop) returns: status per content_id (the answer) and question_status per frame_id (the question). Steps 5 and 6 below exercise the stored support_level ladder, the legacy per-claim axis whose REPLICATED / ESTABLISHED public labels are deprecated for v0.4.0; the walkthrough keeps them because they are still functional this release.

What it covers

Open: zero setup, no init required
Assert: INFERRED, ANALYTICAL, DERIVED classifications
Query: text filter, min_support, classification, limit
Idempotency: retry-safe writes
REPLICATED: automatic when two claims under distinct signing keys share upstream evidence
ESTABLISHED: human validation only, requires REPLICATED first
Operational surfaces: health(), classify_supports()
Anti-patterns: what silently corrupts the epistemic model

Run

cd examples/01_api_walkthrough
python 01_api_walkthrough.py

No external dependencies. Uses a temporary directory, safe to run anywhere.

Key snippet

import tempfile, mareforma
from mareforma import signing

with tempfile.TemporaryDirectory() as tmp:
    # Two distinct signing keys: REPLICATED keys on distinct asserter keyids,
    # and the shared upstream must be ESTABLISHED (a seed claim).
    ka, kb = f"{tmp}/a.key", f"{tmp}/b.key"
    signing.bootstrap_key(ka); signing.bootstrap_key(kb)
    signer_b = signing.load_private_key(kb)
    with mareforma.open(tmp, key_path=ka) as graph:
        graph.enroll_validator(
            signing.public_key_to_pem(signer_b.public_key()), identity="b"
        )
        prior_id = graph.assert_claim(
            "upstream reference", generated_by="seed", seed=True
        )
        id_a = graph.assert_claim(
            "finding A", supports=[prior_id], generated_by="agent/a"
        )
        id_b = graph.assert_claim(
            "finding B", supports=[prior_id], generated_by="agent/b",
            signer=signer_b,
        )
        assert graph.get_claim(id_a)["support_level"] == "REPLICATED"

Introduction

Concepts

For agents

Reference

Examples

View on GitHub

What it covers

Run

Key snippet

View on GitHub

​What it covers

​Run

​Key snippet

What it covers

Run

Key snippet