AP3 - Commitments

Commitments allow agents to commit to providing data of a specific structure, format, and count without revealing the actual data content. This enables informed decision-making about privacy-preserving computations while maintaining complete data confidentiality.

The Data Disclosure Dilemma

Companies need to make informed decisions about whether to engage in privacy-preserving computations, but they don't want to reveal their actual data. Traditional approaches either:

Reveal too much: Share actual data samples (privacy violation)
Reveal too little: No information for decision-making (blind engagement)

Solution: Commitments

Commitments provide a middle ground by revealing:

Data structure and format
Entry count and estimated size
Data freshness and coverage
Industry and purpose

Note

No actual data content, individual entries, sensitive information are revealed in commitments.

Data Structures and Formats

Supported Data Structures

Structure	Purpose	Typical Fields
BLACKLIST	Fraud prevention	person_id, name, phone, reason, date_added
CUSTOMER_LIST	Customer analytics	customer_id, name, email, segment, signup_date
TRANSACTION_LOG	Financial analysis	transaction_id, amount, date, merchant, type
PRODUCT_CATALOG	Product matching	product_id, name, category, price, availability
SUPPLY_CHAIN_DATA	Supply optimization	supplier_id, product, cost, delivery_time, quality
FINANCIAL_RECORDS	Financial compliance	record_id, amount, date, account, type
USER_PROFILES	User analytics	user_id, name, age, preferences, activity
INVENTORY_DATA	Inventory management	item_id, name, quantity, location, status

Data Formats

Format	Description	Use Case
STRUCTURED	JSON, CSV, database records	Blacklists, customer lists
UNSTRUCTURED	Free text, documents	Reports, descriptions
SEMI_STRUCTURED	Mixed format	Logs, mixed data sources
BINARY	Binary data, images	Media, encoded data

How it Works

Let's take an example of XYZ Agent who wants to commit to a blacklist of 10000 entries with 5 fields and ABC agent who wants to find suitable partners for a blacklist of 5000 entries with 5 fields.

1. Creating Commitments - XYZ agent

Use CommitmentMetadataSystem.create_commitment() — it handles signing automatically.

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

system = CommitmentMetadataSystem()

xyz_data_commitment = system.create_commitment(
    agent_id="xyz_agent",
    data_schema=DataSchema(
        structure=DataStructure.BLACKLIST,
        format=DataFormat.STRUCTURED,
        fields=["person_id", "name", "phone", "reason", "date_added"],
    ),
    entry_count=10000,
    data_hash="sha256:abc123...",
)

2. Sign the commitment - XYZ agent

Signing is handled automatically by create_commitment(). The returned CommitmentMetadata object includes a signature field:

{
  "commitment_id": "commit_...",
  "signature": "xyz_signature_12345"
}

3. Public Metadata - XYZ agent

The commitment creates public metadata that can be safely shared:

{
  "commitment_id": "commit_...",
  "agent_id": "xyz_agent",
  "data_structure": "blacklist",
  "data_format": "structured",
  "entry_count": 10000,
  "field_count": 5,
  "estimated_size_mb": 4.8,
  "last_updated": "2025-01-20T10:00:00Z",
  "data_freshness": "daily",
  "coverage_area": "global",
  "industry": "food_delivery",
  "signature": "xyz_signature_12345"
}

4. Discovery - ABC agent

Discover and evaluate commitments without seeing their own data:

from ap3.services import CommitmentMetadataSystem
from ap3.types.core import DataStructure

system = CommitmentMetadataSystem()

# Search for commitments matching the desired criteria
suitable_partners = system.search_commitments(
    data_structure=DataStructure.BLACKLIST,
    min_entry_count=5000,
)

# Evaluate each partner
for partner in suitable_partners:
    evaluation = evaluate_partner(partner)
    print(f"Agent: {partner.agent_id}")
    print(f"Entry Count: {partner.entry_count:,}")

5. Evaluation and Scoring - ABC agent

def evaluate_partner(partner_metadata):
    score = 0.0

    # Entry count score
    if partner_metadata.entry_count >= min_required:
        score += 50.0

    # Data freshness score
    freshness_scores = {
        "real_time": 30.0,
        "daily": 25.0,
        "weekly": 15.0
    }
    score += freshness_scores.get(partner_metadata.data_freshness, 0.0)

    # Size efficiency score
    if partner_metadata.estimated_size_mb <= 100:
        score += 15.0

    return min(score, 100.0)

Roadmap

Commitments can evolve into a trusted registry of commitments that can be used to find suitable partners for privacy-preserving computations.
Automated scoring and evaluation of commitments can be added to the protocol.
Enforcement and reward system can be added to the protocol to encourage agents to commit to more suitable commitments.