API Reference

The AP3 SDK provides a comprehensive API for building privacy-preserving multi-agent applications.

Core Modules

Types

Pydantic models for commitments, directives, and protocol data structures.

• CommitmentMetadata - Data structure commitments
• PrivacyIntentDirective - Operation proposals
• PrivacyResultDirective - Computation results
• DataStructure, DataFormat, DataFreshness - Enumerations

Operations

AP3 defines a minimal Operation contract in the core SDK. Concrete protocol implementations live in external packages (this repo includes ap3operations).

• ap3.Operation - Base class for protocol implementations (session lifecycle + wire shape)
• ap3operations.PSIOperation - Private Set Intersection (PSI) sanction-check example protocol

Services

High-level services for commitment management and discovery.

• CommitmentMetadataSystem - Create and manage commitments
• CommitmentCompatibilityChecker - Score and validate compatibility between two agents' AP3 parameters
• RemoteAgentDiscoveryService - Discover and check compatibility with remote agents

Exceptions

Error handling and protocol-specific exceptions.

• ProtocolError - Protocol execution errors (operations layer)
• BinaryNotFoundError - Required native binary not found
• BinaryLoadError - Native binary failed to load
• PlatformNotSupportedError - OS/arch not supported by available binaries

Quick Navigation

Module	Description	Common Use
ap3.types.core	Core data structures	Define commitments
ap3.types.directive	Privacy directives	Propose operations
ap3.services	High-level APIs	Commitment management
ap3.core.operation	Operation contract	Implement protocols
ap3operations.psi.operations	PSI protocol implementation	Run PSI

Import Patterns

# Types
from ap3.types.core import CommitmentMetadata, DataStructure, DataSchema, DataFormat
from ap3.types.directive import PrivacyIntentDirective, PrivacyResultDirective

# Services
from ap3.services import CommitmentMetadataSystem, CommitmentCompatibilityChecker, RemoteAgentDiscoveryService

# Operations
from ap3operations import PSIOperation

# Exceptions
from ap3operations.exceptions import ProtocolError

Architecture

graph TD
    A[Your Agent] --> B[AP3 SDK]
    B --> C[Operations Layer]
    B --> D[Services Layer]
    B --> E[Types Layer]
    C --> F[PSI Protocol]
    D --> G[Commitment System]
    E --> H[Pydantic Models]
    F --> I[Rust Binaries]

Commitment Creation

from ap3.services import CommitmentMetadataSystem
from ap3.types.core import DataSchema, DataStructure, DataFormat

system = CommitmentMetadataSystem()
commitment = system.create_commitment(
    agent_id="agent_01",
    data_schema=DataSchema(
        structure=DataStructure.CUSTOMER_LIST,
        format=DataFormat.STRUCTURED,
        fields=["name", "id", "address"],
    ),
    entry_count=5000,
    data_hash="sha256:abc123...",  # required
)

API Conventions

Naming Patterns

• Classes: PascalCase (e.g., PSIOperation, CommitmentMetadataSystem)
• Functions: snake_case (e.g., start(), receive(), process())
• Constants: UPPER_SNAKE_CASE (e.g., DATA_STRUCTURE)

Return Types

• Operation.start(), receive(), process() return dicts with keys: session_id, operation, done, metadata, outgoing, result
• Services return Pydantic models for structured data
• Utilities return bytes or primitives

For multi-round protocols, Operation stores per-session state internally:

• start(...): creates a new session (or uses the provided session_id) and calls on_start(...)
• receive(...): responder-side entrypoint for the first inbound message (calls on_process(...) with empty state and context.is_first_message=True)
• process(session_id, message, ...): continues an existing session (raises KeyError if unknown), and automatically clears session state when done=True

Error Handling

All protocol operations may raise:

• ProtocolError - Protocol execution failures
• ValueError - Configuration errors

from ap3operations.exceptions import ProtocolError
from ap3operations import PSIOperation

psi = PSIOperation()
try:
    result = psi.start(role="initiator", inputs={"customer_data": "John Doe,ID123,123 Main St"})
except ProtocolError as e:
    print(f"Protocol failed: {e}")

PSI wire shape (current PSIOperation)

PSIOperation is a 2-message protocol with explicit phases:

• Initiator start(...) returns outgoing={"phase": "msg1", "protocol_session": "...", "message": "..."}
• Receiver receive(...) expects phase="msg1" and returns outgoing={"phase": "msg2", "message": "..."}
• Initiator process(session_id, ...) expects phase="msg2" and returns result={"is_match": bool} with done=True

Version Compatibility

This documentation covers AP3 SDK v1.0.0.