SDK 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 - Enumerations

Operations

Privacy-preserving cryptographic protocols.

SanctionCheck - Private Set Intersection (PSI)
DotProduct - Secure Multi-party Computation (MPC)

Services

High-level services for commitment management and discovery.

StructuredCommitmentSystem - Create and manage commitments
CommitmentDiscoveryService - Find compatible partners

Exceptions

Error handling and protocol-specific exceptions.

ProtocolError - Protocol execution errors
ValidationError - Data validation errors

Module	Description	Common Use
`ap3.types.core`	Core data structures	Define commitments
`ap3.types.directive`	Privacy directives	Propose operations
`ap3.operations.psi`	PSI protocol	Sanction checks
`ap3.operations.sfe`	Dot product	Score computation
`ap3.services`	High-level APIs	Commitment management

Import Patterns

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

# Operations
from ap3.operations.psi import SanctionCheck
from ap3.operations.sfe import DotProduct

# Services
from ap3.services import StructuredCommitmentSystem, CommitmentDiscoveryService

# Exceptions
from ap3.operations.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[Privacy-Preserving Protocols]
    D --> G[Commitment System]
    E --> H[Pydantic Models]
    F --> I[Protocol Binaries]

Usage Examples

Private Set Intersection

from ap3.operations.psi import SanctionCheck

# Initiator side
psi = SanctionCheck(side="initiator")
session_id, state, msg1 = psi.initiate("John Doe,ID123,123 Main St")

# Receiver side
receiver = SanctionCheck(side="receiver")
msg2 = receiver.initiate_receiver(session_id, msg1, sanction_list)

# Finalize
is_match = psi.finalize(state, msg2)

Secure Dot Product

from ap3.operations.sfe import DotProduct

# Opening party
with DotProduct(side="OB") as dp:
    session_id, msg1, state, shares, triples = dp.initiate([5, 3])
    # ... exchange messages ...
    result = dp.finalize(ob_share, cb_share)

Commitment Creation

from ap3.services import StructuredCommitmentSystem
from ap3.types.core import DataSchema, DataStructure

system = StructuredCommitmentSystem()
commitment = system.create_structured_commitment(
    agent_id="agent_01",
    data_schema=DataSchema(structure=DataStructure.CUSTOMER_LIST),
    entry_count=5000
)

API Conventions

Naming Patterns

Classes: PascalCase (e.g., SanctionCheck, DotProduct)
Functions: snake_case (e.g., initiate(), process_round())
Constants: UPPER_SNAKE_CASE (e.g., DATA_STRUCTURE)

Return Types

Operations return tuples for multi-value returns
Services return Pydantic models for structured data
Utilities return bytes or primitives

Error Handling

All protocol operations may raise:

ProtocolError - Protocol execution failures
ValidationError - Invalid input data
ValueError - Configuration errors

from ap3.operations.exceptions import ProtocolError

try:
    session_id, state, msg1 = psi.initiate(customer_data)
except ProtocolError as e:
    print(f"Protocol failed at round {e.round_num}: {e.message}")

Version Compatibility

This documentation covers AP3 SDK v0.1.0.

Semantic Versioning

AP3 follows semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Breaking API changes
MINOR: New features, backwards compatible
PATCH: Bug fixes

Deprecation Policy

Deprecated features are marked with warnings
Deprecated code remains for 2 minor versions
Migration guides provided for breaking changes