Metadata-Version: 2.4
Name: aar-manifest
Version: 1.0.0
Summary: Python reference implementation of the Agent Acknowledgment Record (AAR)
Author-email: "David H. Friedel Jr." <dev@ai-manifests.org>
Maintainer-email: MarketAlly Pte Ltd <dev@ai-manifests.org>
License-Expression: Apache-2.0
Project-URL: Homepage, https://aar-manifest.dev
Project-URL: Repository, https://github.com/ai-manifests/aar-ref-lib-py
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# aar-ref-lib-py

[![PyPI](https://img.shields.io/pypi/v/aar-manifest.svg)](https://pypi.org/project/aar-manifest/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Spec](https://img.shields.io/badge/spec-aar--manifest.dev-informational)](https://aar-manifest.dev)

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

## Install

```bash
pip install aar-manifest
```

## What's in the box

| Module | Spec | Purpose |
|--------|------|---------|
| `entries` | §3, §5, §8 | `RecordEntry`, `Checkpoint`, `ReputationResult` |
| `ledger` | §3, §4 | `canonicalize`, `compute_entry_hash`, `compute_commitment`, `build_genesis`, `append_event`, `verify_chain` |
| `checkpoint` | §5 | `merkle_root`, `build_inclusion_proof`, `verify_inclusion_proof`, `build_checkpoint` |
| `aggregation` | §9 | `aggregate_reputation` — the normative `default` algorithm |
| `store` | §3/§4/§8 | `InMemoryLedger` — accept, withdraw, query, verify, reputation |

## Usage

```python
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

```bash
pip install -e ".[dev]"
pytest
```

## License

Apache-2.0 — see [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).
