Metadata-Version: 2.4
Name: provenance-sdk
Version: 1.2.0
Summary: Python SDK for the Provenance platform — queue ingestion and full REST API client
Project-URL: Homepage, https://www.stdiolabs.dev
Project-URL: Repository, https://github.com/stdiolabs/provenance-sdk-python
Project-URL: Issues, https://github.com/stdiolabs/provenance-sdk-python/issues
Author-email: STDIO Labs <hello@stdiolabs.dev>
License: Copyright (c) 2025 STDIO Labs
        
        All rights reserved.
        
        This software and associated documentation files (the "Software") are the
        proprietary property of STDIO Labs. The Software is provided for use with
        the Provenance platform only.
        
        Redistribution, modification, or use of this Software outside of the
        Provenance platform is not permitted without prior written consent from
        STDIO Labs.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: analytics,api-client,audit,provenance,tracking
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://www.stdiolabs.dev/images/stdio-logo-white-font.png" alt="STDIO Labs" height="32" />
</p>

<h1 align="center">Provenance SDK (Python)</h1>

<p align="center">
  Python SDK for the <a href="https://provenance.dev">Provenance</a> platform — queue-based ingestion and full async REST API client.
</p>

<p align="center">
  <a href="https://pypi.org/project/provenance-sdk/"><img src="https://img.shields.io/pypi/v/provenance-sdk" alt="PyPI version" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
  <a href="https://www.python.org"><img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python Version" /></a>
</p>

---

## Installation

```bash
pip install provenance-sdk
```

## Quick Start

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

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

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

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

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

See the [full docs](https://provenance.dev/docs/core-concepts/unit-of-work#span-hierarchy) for more details.

## Configuration

| Option         | Required | Description                                               |
| -------------- | -------- | --------------------------------------------------------- |
| `api_key`      | Yes      | Your Provenance API key                                   |
| `origin`       | Yes      | Name of the source system                                 |
| `platform_url` | No       | Platform URL (default: `https://platform.provenance.dev`) |
| `api_url`      | No       | Override API URL (resolved from platform by default)      |

## 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](https://www.stdiolabs.dev)
