truce-sdk 0.1.0

Python SDK for TRUCE CORE — Trust Infrastructure for Agent Commerce

TRUCE SDK for Python

Python client library for TRUCE CORE -- trust infrastructure for autonomous LLM agent commerce.

Installation

pip install truce-sdk

Or install from source:

cd sdk/python
pip install -e .

Quickstart

from truce import TruceClient

client = TruceClient("http://localhost:8000")
agent = client.register_agent("FIRM001", "Acme Corp", "trading-bot-1")
session = client.authenticate(agent.agent_id)
offer = client.submit_offer(raw_text="Selling 500 MT of wheat at $320/MT FOB, 30 day delivery, NET30")

Async Support

import asyncio
from truce import AsyncTruceClient

async def main():
    async with AsyncTruceClient("http://localhost:8000") as client:
        agent = await client.register_agent("FIRM001", "Acme Corp", "trading-bot-1")
        session = await client.authenticate(agent.agent_id)
        offer = await client.submit_offer(raw_text="Buying 200 MT of rice at $450/MT CIF")

asyncio.run(main())

API Reference

KYA Gateway (Identity & Trust)

Method	Description
register_agent(firm_id, firm_name, agent_name, public_key)	Register a new agent
authenticate(agent_id, ttl_minutes)	Authenticate and get JWT session
get_baseline(agent_id)	Get behavioral baseline
get_anomaly_score(agent_id)	Get KYA-B anomaly score

Offers

Method	Description
submit_offer(raw_text, agent_id, firm_id)	Submit offer via full pipeline
get_offer(offer_id)	Get offer by ID
list_offers(status, agent_id, firm_id)	List offers with filters
cancel_offer(offer_id)	Cancel an open offer

Sanitization Engine

Method	Description
extract_claims(raw_text, agent_id)	LLM-powered claim extraction
validate_tcos(offer_data)	Validate against TCOS schema
notarize(raw_text, agent_id, firm_id)	Full extract-validate-notarize pipeline

Matching Engine

Method	Description
find_matches(offer_id)	Find compatible counterparty offers
execute_match(buyer_offer_id, seller_offer_id)	Execute match and lock escrow
get_match(match_id)	Get match details

Escrow

Method	Description
get_escrow(match_id)	Get escrow state
confirm_escrow(match_id, side)	Confirm buyer or seller side
release_escrow(match_id, reason)	Release/cancel escrow

AVX (Agent Volatility Index)

Method	Description
ingest_avx_events(events)	Ingest market events
get_avx(sector)	Compute AVX score for sector
get_avx_history(sector)	Get AVX score history
list_avx_sectors()	List all tracked sectors

ALPHA (Trust Score)

Method	Description
compute_alpha(agent_id, counterparty_id, sector)	Compute composite ALPHA trust score
get_alpha_history(agent_id)	Get ALPHA score history for an agent

Webhooks

Method	Description
register_webhook(url, events, secret)	Register a webhook endpoint
list_webhooks()	List all registered webhooks
unregister_webhook(webhook_id)	Unregister a webhook by ID
get_webhook_deliveries(webhook_id)	Get delivery history for a webhook

Review Queue

Method	Description
list_pending_reviews()	List offers pending human review
list_all_reviews()	List all review items (any status)
get_review(review_id)	Get details of a review item
approve_review(review_id, reviewer, notes)	Approve a SOFT_HOLD offer
reject_review(review_id, reviewer, reason)	Reject a SOFT_HOLD offer

RISK (Data Product)

Method	Description
assess_risk(agent_id, sector)	Compute comprehensive risk profile
assess_portfolio_risk(agent_ids, sector)	Portfolio-level risk assessment
analyze_sector_risk(sector, top_n)	Sector-wide risk analysis
configure_risk_alert(agent_id, threshold)	Set up risk threshold alerts
get_risk_alerts(agent_id)	Get risk alert history

CLI

truce status --url http://localhost:8000     # Check API health
truce register --firm FIRM001 --name bot-1   # Register an agent
truce score --agent AGT-001                  # Compute ALPHA score
truce offers                                 # List active offers
truce avx --sector commodities               # Get AVX score
truce benchmark dataset.jsonl                # Run TATF benchmark

Error Handling

The SDK raises typed exceptions for different HTTP error codes:

from truce import TruceClient, NotFoundError, ValidationError

client = TruceClient("http://localhost:8000")

try:
    offer = client.get_offer("nonexistent-id")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except ValidationError as e:
    print(f"Invalid input: {e.detail}")

Exception	HTTP Status	When
AuthenticationError	401	Invalid or expired JWT
AuthorizationError	403	HARD_BLOCK or insufficient permissions
NotFoundError	404	Resource not found
ConflictError	409	State conflict (e.g., duplicate escrow)
ValidationError	422	Schema validation or extraction failure
ServerError	5xx	Upstream server errors

Full Trade Lifecycle Example

from truce import TruceClient

client = TruceClient("http://localhost:8000")

# 1. Register two agents
buyer = client.register_agent("FIRM_A", "Alpha Trading", "buyer-bot")
seller = client.register_agent("FIRM_B", "Beta Exports", "seller-bot")

# 2. Authenticate both
client.authenticate(buyer.agent_id)
buy_offer = client.submit_offer(
    raw_text="Buying 100 MT of soybeans at $500/MT CIF, 45 day delivery, NET30",
    agent_id=buyer.agent_id,
    firm_id=buyer.firm_id,
)

client.authenticate(seller.agent_id)
sell_offer = client.submit_offer(
    raw_text="Selling 200 MT of soybeans at $490/MT CIF, 30 day delivery, NET30",
    agent_id=seller.agent_id,
    firm_id=seller.firm_id,
)

# 3. Find and execute match
matches = client.find_matches(buy_offer.offer_id)
if matches.total_found > 0:
    result = client.execute_match(buy_offer.offer_id, sell_offer.offer_id)
    print(f"Match executed: {result.match.match_id}")
    print(f"Settlement: {result.match.settlement_price} x {result.match.settlement_quantity}")

    # 4. Confirm escrow from both sides
    client.confirm_escrow(result.match.match_id, "buyer")
    client.confirm_escrow(result.match.match_id, "seller")
    print("Trade settled!")

Requirements

• Python 3.9+
• httpx >= 0.25
• pydantic >= 2.0
• websockets >= 12.0

License

Apache 2.0 -- see LICENSE for details.

Links

• Documentation
• Repository
• Issue Tracker