Metadata-Version: 2.4
Name: provenarium-client
Version: 0.1.2
Summary: Thin Python client for the Provenarium extraction API.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx<1.0.0,>=0.28.0
Requires-Dist: pydantic<3.0.0,>=2.6.0

# Provenarium Python Client

`provenarium_client` is a thin Python wrapper around the public Provenarium API.

It is intentionally focused on the main data-team workflow:

- list, create, and rotate machine API keys
- create or reuse schemas
- submit extraction jobs
- poll for results
- request hosted review for completed work
- manage webhook destinations

Full guide: [docs.provenarium.com/python-client](https://docs.provenarium.com/python-client)

## Install

If the client is being distributed through PyPI for your environment:

```bash
pip install provenarium-client
```

Otherwise install it from the wheel, source checkout, or private package path provided for your environment.

The client defaults to `https://api.provenarium.com`. Only override `base_url` when pointing at a local or non-default hosted environment.

## Quickstart

```python
from provenarium_client import SchemaField, ProvenariumClient

with ProvenariumClient(
    api_key="pk_live_...",
) as client:
    schema = client.create_schema(
        name="Quality Packet",
        description="Fields to pull from quality packets.",
        fields=[
            SchemaField(
                name="document_id",
                display_name="Document ID",
                description="Internal document identifier.",
                group="document_info",
                path="document_info.document_id",
                field_type="String",
            ),
            SchemaField(
                name="record_id",
                display_name="Record ID",
                description="Operational record identifier.",
                group="record_context",
                path="record_context.record_id",
                field_type="String",
            ),
        ],
    )

    job = client.submit_job(
        file_path="packet.pdf",
        schema_id=schema.id,
    )

    result = client.wait_for_result(
        job.id,
        poll_interval_seconds=2.0,
        timeout_seconds=120.0,
    )

    print(result.summary.field_count)
    print(result.fields[0].value)
```

## Hosted Review

Route a completed job into hosted review later:

```python
from provenarium_client import ProvenariumClient

with ProvenariumClient(api_key="pk_live_...") as client:
    reviewed_job = client.request_review(
        "job_123",
        reviewer_email="reviewer@example.com",
        reviewer_team="qa-team",
    )
    print(reviewed_job.review.status)
    print(reviewed_job.reviewer_notification)
```

If review should be part of the job from the start, pass `requires_review=True` and reviewer details directly to `submit_job(...)`.

## API Keys

The client can also wrap the public API-key routes for scripted key rotation:

```python
from provenarium_client import ProvenariumClient

with ProvenariumClient(api_key="pk_admin_...") as client:
    created = client.create_api_key(
        name="ingestion-bot",
        role="member",
    )
    print(created.token)

    for key in client.list_api_keys():
        print(key.name, key.role, key.is_active)

    client.delete_api_key(created.id)
```

## Notes

- this client wraps the public `/api/v1/*` surface only
- API key management calls require an `owner` or `admin` team API key
- use the docs app and API reference for the canonical integration guide and exact wire payloads
- the package is intentionally a lightweight convenience layer, not a heavy SDK

## Tests

```bash
uv run pytest -q
```
