aar-ref-lib-py

Python reference implementation of the Agent Acknowledgment Record (AAR) — the append-only, hash-chained ledger that stores and aggregates AAP acknowledgment events, with Merkle checkpoints and the normative §9 default reputation algorithm.

Install

pip install aar-manifest

What's in the box

Usage

from aar_manifest import InMemoryLedger

ledger = InMemoryLedger("did:tutus:0xagg")

ev = {
    "id": "urn:uuid:…",
    "type": "ENDORSEMENT",
    "issued_at": "2026-05-20T14:32:00Z",
    "issuer": {"did": "did:web:alice"},
    "subject": {"did": "did:web:bob"},
}

ledger.accept(ev)                      # chained Record Entry; raises on duplicate id (§4.1.2)
valid, errors = ledger.verify(recompute_hashes=True)
rep = ledger.reputation("did:web:bob", settlement_verified=lambda e: False)

The wrapped event is a plain dict (snake_case keys, as on the wire) so the package takes no hard dependency on aap-manifest.

The default aggregation (spec §9)

weight(a) = type_weight × issuer_trust × value_weight × witness_factor
          × time_decay × (0 if withdrawn else 1) × settlement_factor

• value_weight = 1 + log10(1 + usd) applies only when settlement is verified (§6.3).
• settlement_factor = 0.5 when a value is claimed but unverified (T2/T10), else 1.
• The issuer-diversity penalty (§9.5) scales the aggregate by diversity / 0.3 when Simpson diversity over distinct issuers/controllers is below 0.3.
• Recursive issuer trust is bounded at depth 2 with an attestation fallback (§9.4); pass issuer_trust= or attestation= to drive it.

aggregate_reputation returns the full ReputationResult (the AAR §8 ReputationSource shape ADP consumes).

Hash chaining & checkpoints

compute_entry_hash hashes the immutable content (everything except entry_hash and the mutable status fields withdrawn / withdrawal_ref), so a withdrawal can flip those fields without breaking chain continuity (§3.2, §4.2, §7.4). build_checkpoint produces a signed, prev-chained Merkle commitment; build_inclusion_proof / verify_inclusion_proof give single-entry inclusion proofs (§5.4).

How It Composes

aap-manifest   constructs and weights acknowledgment events
aar-manifest   stores, chains, federates, and aggregates them   (this library)
aar-validate   audits a ledger's chain, sequencing, and replay

Test

pip install -e ".[dev]"
pytest

License

Apache-2.0 — see LICENSE and NOTICE.