Provenance SDK (Python)

Python SDK for the Provenance platform — queue-based ingestion and full async REST API client.

Installation

pip install provenance-sdk

Quick Start

from provenance_sdk import create
import uuid

provenance = await create(api_key="your-api-key", origin="my-service")

# Queue-based ingestion
await provenance.log(
    resource_type="user",
    resource_id="user-123",
    action="login",
    uow_id=str(uuid.uuid4()),
    interaction={"email": "user@example.com"},
)

# REST API client
api = await provenance.api()
actions = await api.actions.list()
trace = await api.traces.get("user-123")

REST API Client

api = await provenance.api()

# CRUD
action = await api.actions.create({"title": "Deploy", "mnemonic": "DEPLOY"})
await api.actions.update(action["id"], {"title": "Deploy v2"})
await api.actions.delete(action["id"])

# Search & Analytics
results = await api.activity.search({"filters": {"action": "CREATE"}})
data = await api.analytics.query({
    "metrics": ["count"],
    "dimensions": ["action"],
    "timeRange": {"type": "relative", "value": "7d"},
})

# Auto-pagination
async for action in api.actions.list_all():
    print(action["title"])

Context Layering

scoped = provenance.add_context(resource_type="order", user_id="user-456")

await scoped.log(
    resource_id="order-789",
    action="create",
    uow_id=str(uuid.uuid4()),
    interaction={"total": 99.99},
)

Span Hierarchy

log() returns the generated spanId (a string). Pass it as parent_span_id to link child interactions:

parent_span_id = await provenance.log(
    resource_type="order",
    resource_id="order-789",
    action="create",
    uow_id=uow_id,
    interaction={"total": 99.99},
)

await provenance.log(
    resource_type="payment",
    resource_id="payment-456",
    action="process",
    uow_id=uow_id,
    parent_span_id=parent_span_id,
    interaction={"method": "card"},
)

You can also propagate parent_span_id via context:

child = provenance.add_context(parent_span_id=parent_span_id)
await child.log(resource_id="item-1", action="reserve", ...)

See the full docs for more details.

Configuration

Resilience

• Lazy resolution — Config fetched on first use, not at create() time
• Retry with backoff — 429/5xx retried up to 3× with exponential backoff
• Auto-refresh — On 401/403, credentials force-refreshed and retried
• 5-minute cache — Platform config cached per API key
• Single dependency — Only requires httpx

License

Proprietary — STDIO Labs