Metadata-Version: 2.4
Name: openadtrace-sdk
Version: 0.1.0
Summary: Python client SDK for OpenAdTrace MCP server — advertising audit trails for agentic AI
Author: OpenAdTrace Contributors
License: Apache-2.0
Project-URL: Homepage, https://github.com/Samrajtheailyceum/open-ad-trace
Project-URL: Repository, https://github.com/Samrajtheailyceum/open-ad-trace
Keywords: openadtrace,mcp,advertising,adtech,audit,trace,agentic
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# OpenAdTrace Python SDK

Python client for the [OpenAdTrace](https://github.com/Samrajtheailyceum/open-ad-trace) MCP server -- advertising audit trails for agentic AI.

Zero external dependencies. Works with Python 3.9+.

## Installation

```bash
pip install openadtrace-sdk
```

## Quick Start (Synchronous)

```python
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)

```python
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:

```python
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:

```python
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:

```python
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

```python
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.

```python
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](https://github.com/Samrajtheailyceum/open-ad-trace) for details.
