Extension interfaces and submodules

Implement model, human, journal, and tracing seams, then reach into tier-2 modules only when required.

Everyday applications should start with import agentsparty as ap. Extend the library at one of four explicit seams when a built-in adapter does not fit.

Interface	Required operation	Use it for
`HumanIo`	`async choose(offer)`	Web, chat, or external approval input
`Journal`	`bind`, `append`, `script`	Durable decision storage
`Tracer`	`record(event)`	Logs, metrics, or telemetry export
`LanguageModel`	`async complete(request)`	A provider or inference endpoint

HumanIo

choose returns one message class from offer.messages. notify, recall, and cancel have default implementations; override them only when the host must present deliveries, restore a prior decision, or announce cancellation.

# requires: custom-human-io
import agentsparty as ap


class WebApprovalIo(ap.HumanIo):
    async def choose(self, offer: ap.Offer) -> ap.Message:
        return await receive_operator_message(offer.messages)

The adapter must not invent a class outside the offer. Use Desk when an in-process queue and later submit call already match the host.

Journal

bind(protocol_id) establishes or checks protocol identity. append(decision) must durably commit one decision before delivery. script() returns the recorded sequence for replay.

# requires: custom-journal
import agentsparty as ap
from agentsparty.journal.types import Decision, ProtocolId, Script


class DatabaseJournal(ap.Journal):
    def bind(self, protocol_id: ProtocolId) -> None:
        check_protocol_id(protocol_id)

    def append(self, decision: Decision) -> None:
        save_decision(decision)

    def script(self) -> Script:
        return Script.of(load_decisions())

The application owns transactions, connection lifetime, retention, and any version conversion. Raise ProtocolMismatch rather than reading decisions under a different protocol shape.

Tracer

record(event) receives structured signals. It must not mutate event data, alter routing, or raise into session execution. Put slow network exporters behind a queue.

# requires: custom-tracer
import agentsparty as ap
from agentsparty.tracing.types import Event


class LoggingTracer(ap.Tracer):
    def record(self, event: Event) -> None:
        logger.info(type(event.signal).__name__)

LanguageModel

complete(request) receives a StructuredRequest containing instructions, turns, schema name, JSON Schema, and requested effort. It returns an Answer whose raw JSON matches that schema; Agent performs message decoding and bounded correction.

# requires: custom-language-model
import agentsparty as ap
from agentsparty.llm.types import Answer, StructuredRequest


class ProviderModel(ap.LanguageModel):
    async def complete(self, request: StructuredRequest) -> Answer:
        return await call_provider(request)

Keep authentication, transport, provider fields, and usage extraction in this adapter. Keep role instructions in Agent and route decisions in Protocol.

Tier-2 submodules

Use a tier-2 import when implementing one of these seams or inspecting protocol internals. Root functions remain the default application surface.

Module	Contains	Typical reason to import it
`agentsparty.protocol`	codecs, projection, graph analysis, rendering	Custom codecs or static protocol analysis
`agentsparty.journal`	decisions, scripts, ids, tracks, step indices	A journal backend or version tool
`agentsparty.tracing`	signal types, scopes, facets, descriptions	Filtering or exporting specific events
`agentsparty.llm`	requests, turns, answers, usage, model ids	A provider adapter

Do not reach into these modules for ordinary step construction, built-in journals, common tracers, or model wrappers; the root ap. surface already exports those operations.

Built-in storage and tracing adapters

Root API	Contract
`MemoryJournal`	Keeps decisions in process for deterministic tests and replay.
`SqliteJournal`	Persists decisions in SQLite for durable local sessions.
`SessionId`	Names one journalled session independently of its protocol.
`MemoryTracer`	Retains structured events in process for later inspection.
`QueueTracer`	Sends structured events to a `watching` consumer.
`patterns`	Provides named protocol shapes without hiding their roles or steps.

Use MemoryJournal and MemoryTracer for local observation. Use SqliteJournal when a session must survive process restarts. A QueueTracer paired with watching exposes live progress, while SessionId keeps stored runs distinct. The patterns namespace remains a convenience layer over the same explicit protocol operations.

Roles, participants, and models: use the built-in seams first.
Journals, replay, and tracing: understand journal and tracer semantics.
API reference: inspect exact signatures and public types.