openadtrace-sdk 0.1.0

Python client SDK for OpenAdTrace MCP server — advertising audit trails for agentic AI

OpenAdTrace Python SDK

Python client for the OpenAdTrace MCP server -- advertising audit trails for agentic AI.

Zero external dependencies. Works with Python 3.9+.

Installation

pip install openadtrace-sdk

Quick Start (Synchronous)

from openadtrace_sdk import OpenAdTraceClient, Protocol, Layer, Status

with OpenAdTraceClient("http://localhost:3001/mcp") as client:
    result = client.trace_event(
        protocol=Protocol.OPENRTB,
        layer=Layer.BID_REQUEST,
        actor_role="dsp",
        actor_id="dsp-42",
        event_type="bid",
        action="submit",
        status=Status.SUCCESS,
        latency_ms=12,
    )
    print(f"Recorded: trace_id={result.trace_id}, span_id={result.span_id}")

Quick Start (Async)

import asyncio
from openadtrace_sdk import AsyncOpenAdTraceClient, Protocol, Layer, Status

async def main():
    async with AsyncOpenAdTraceClient("http://localhost:3001/mcp") as client:
        result = await client.trace_event(
            protocol=Protocol.OPENRTB,
            layer=Layer.BID_REQUEST,
            actor_role="dsp",
            actor_id="dsp-42",
            event_type="bid",
            action="submit",
            status=Status.SUCCESS,
        )
        print(result.trace_id)

asyncio.run(main())

Authentication

Pass a Bearer token to the client constructor:

client = OpenAdTraceClient("http://localhost:3001/mcp", token="your-api-key")

Methods

The SDK wraps all 11 tools exposed by the OpenAdTrace MCP server:

Method	Description
trace_event(...)	Record an advertising audit trail event
validate_event(...)	Validate an event without recording it
query_traces(...)	Query stored trace events with filters
analyse_traces(...)	Analyse trace data for insights and quality scores
redact_event(...)	Redact sensitive fields from a trace event
scan_protocols(...)	Scan trace data for protocol usage and conformance
verify_supply_chain(...)	Verify supply-chain transparency (ads.txt / sellers.json)
trust_score(...)	Compute a trust score for an actor
correlate_traces(...)	Correlate events across a shared key (campaign, deal, etc.)
compliance_check(...)	Check compliance against a protocol specification
risk_signals(...)	Detect risk signals in trace data

Builder Pattern

Use TraceEventBuilder for a fluent API when constructing complex events:

from openadtrace_sdk import TraceEventBuilder, Protocol, Layer, Status

event = (
    TraceEventBuilder()
    .protocol(Protocol.OPENRTB)
    .layer(Layer.BID_DECISION)
    .actor("dsp", "dsp-42")
    .event("bid", "evaluate")
    .status(Status.SUCCESS)
    .with_campaign("camp-123")
    .with_auction("auc-456")
    .latency(8)
    .bid_price(4.50)
    .bid_floor(2.00)
    .rationale("CPM within target range and brand-safe context")
    .risk_flags(["new_publisher"])
    .build()
)

with OpenAdTraceClient("http://localhost:3001/mcp") as client:
    result = client.trace_event(**event)

Batch Requests

Send up to 20 tool calls in a single HTTP request:

with OpenAdTraceClient("http://localhost:3001/mcp") as client:
    results = (
        client.batch()
        .trace_event(
            protocol="openrtb", layer="bid_request",
            actor_role="dsp", actor_id="dsp-42",
            event_type="bid", action="submit", status="success",
        )
        .trust_score(actor_id="dsp-42")
        .risk_signals(actor_id="dsp-42", period_days=7)
        .execute()
    )

    trace_result, trust_result, risk_result = results
    print(f"Trust score: {trust_result.trust_score}")

Error Handling

from openadtrace_sdk import (
    OpenAdTraceClient,
    OpenAdTraceError,
    AuthenticationError,
    RateLimitError,
    NetworkError,
    ToolError,
)

try:
    with OpenAdTraceClient("http://localhost:3001/mcp", token="key") as client:
        result = client.trust_score(actor_id="dsp-42")
except AuthenticationError:
    print("Invalid API token")
except RateLimitError as e:
    print(f"Rate limited -- retry after {e.retry_after_seconds}s")
except NetworkError as e:
    print(f"Connection problem: {e}")
except ToolError as e:
    print(f"Tool '{e.tool_name}' failed: {e}")
except OpenAdTraceError as e:
    print(f"SDK error: {e}")

Enums

The SDK provides enums for type-safe protocol, layer, and status values. You can also pass plain strings -- enums are optional.

from openadtrace_sdk import Protocol, Layer, Status, AampPillar

# Using enums
client.trace_event(protocol=Protocol.OPENRTB, layer=Layer.BID_REQUEST, status=Status.SUCCESS, ...)

# Using strings (equivalent)
client.trace_event(protocol="openrtb", layer="bid_request", status="success", ...)

Requirements

• Python 3.9+
• No external dependencies (stdlib only)

License

Apache-2.0. See the main repository for details.