adj-manifest

A Python reference implementation of the Agent Deliberation Journal (ADJ) specification — the append-only journal format that records every step of a multi-agent deliberation: when it opened, what proposals were emitted, what falsifications happened, when it closed, and what outcome was eventually observed.

This library is one of several reference implementations (C#, TypeScript) of the same spec. The spec itself is at adp-manifest.dev and is the source of truth; this library implements what the spec says.

Zero runtime dependencies. Requires Python 3.10+.

Install

pip install adj-manifest

Or from source:

git clone https://github.com/ai-manifests/adj-ref-lib-py.git
cd adj-ref-lib-py
pip install -e .

Quick example

from datetime import datetime, timezone
from adj_manifest import (
    InMemoryJournalStore,
    DeliberationOpened,
    ActionDescriptor,
    DeliberationConfig,
    BrierScorer,
)

store = InMemoryJournalStore()

store.append(DeliberationOpened(
    entry_id="adj_01HMX",
    deliberation_id="dlb_42",
    timestamp=datetime.now(timezone.utc),
    prior_entry_hash=None,
    action=ActionDescriptor(kind="code.merge", tier="auto", blast_radius="team-scope"),
    config=DeliberationConfig(min_agents=3, timeout_seconds=300),
))

# ... append proposals, round events, deliberation close, outcome ...

score = BrierScorer.compute_calibration(scoring_pairs)
# score.value is the Brier-scored calibration score in [0, 1]

API

All public symbols are exported from the adj_manifest package root.

Entry types

JournalEntry, DeliberationOpened, ProposalEmitted, RoundEvent, DeliberationClosed, OutcomeObserved

Value types

ActionDescriptor, DeliberationConfig, TallyRecord, ProposalData, ConditionRecord, CalibrationScore, ScoringPair, ConditionQualityMetrics

Scorers

• BrierScorer — compute_calibration(pairs) returns a calibration score from (confidence, outcome) pairs. update(score, pair) folds a new observation into an existing score.
• ConditionQualityScorer — compute(entries) returns per-condition quality metrics (how often each dissent condition was falsified, how often it was load-bearing, etc.)

Store

• InMemoryJournalStore — thread-safe in-memory journal store suitable for tests and prototypes. Implements the store contract from the spec.

Testing

pip install -e .[dev]
pytest

Spec

This library implements the Agent Deliberation Journal specification. Read the spec at adp-manifest.dev. If the spec and this library disagree, the spec is correct and this is a bug.

License

Apache-2.0 — see LICENSE for the full license text and NOTICE for attribution.