Metadata-Version: 2.4
Name: primate-intelligence
Version: 0.1.0
Summary: Official Python SDK for the Primate Vision API (Primate Intelligence). Video scene understanding: upload, analyze, stream.
Project-URL: Homepage, https://primateintelligence.ai/docs
Project-URL: Repository, https://github.com/Primate-Intelligence/primate-intelligence-api
Author: Primate Intelligence
License: MIT
Keywords: ai,primate-intelligence,video,video-understanding,vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# primate-intelligence

Official Python SDK for the [Primate Vision API](https://primateintelligence.ai/docs) by Primate Intelligence — video scene understanding: upload a video, ask a question, get a deterministic answer with confidence and clip timestamps.

> **Status:** built in-repo from the OpenAPI spec (`GET /v1/openapi.json`). Not yet published to PyPI — install from the repo until the first public release.

## Install

```bash
pip install primate-intelligence
```

Requires Python 3.10+.

## Quickstart

```python
from primate_intelligence import Primate

client = Primate()  # reads PRIMATE_API_KEY from the environment

video = client.videos.create(url="https://example.com/clip.mp4")
analysis = client.analyses.create_and_wait(
    video_id=video["id"],
    prompt="Is there a person in this video?",
)
print(analysis["result"]["answer"], analysis["result"]["confidence"])
```

Get a free test key with no signup:

```bash
curl -X POST https://api.primateintelligence.ai/v1/sandbox
```

## Features

- **Typed resource namespaces** for the full `/v1` surface: `videos`, `analyses`, `streams`, `client_tokens`, `models`, `usage`, `errors`, `webhook_endpoints`.
- **Automatic retries** driven by the [error registry](https://primateintelligence.ai/docs/errors) `retryable` flags + `Retry-After`.
- **Auto idempotency keys** (UUIDv4) on all create calls.
- **`create_and_wait()`** — create an analysis and block until a terminal state (uses `Prefer: wait` server-side, then polls).
- **`videos.upload()`** — create + presigned S3 PUT + complete, in one call.
- **Pagination iterators** — `for video in client.videos.iter(): …`.
- **Webhook verification** — `verify_webhook()` implements [Standard Webhooks](https://www.standardwebhooks.com) with constant-time compare + replay-window checks.

## Error handling

```python
from primate_intelligence import Primate, PrimateError

client = Primate()
try:
    client.analyses.create(video_id="video_x", prompt="hi")
except PrimateError as err:
    print(err.code, err.status, err.request_id, err.docs_url)
    if err.code == "insufficient_credits":
        usage = client.usage.retrieve()
        # → prompt the account owner to top up or enable auto-refill
```

Every error carries `code`, `status`, `request_id`, and a `docs_url` anchor into the error registry. Retryable codes are retried automatically before the exception reaches you.

## Webhooks

```python
from primate_intelligence import verify_webhook_request

@app.post("/webhooks/primate")
async def receive(request: Request):
    raw = await request.body()
    verify_webhook_request(
        secret=os.environ["PRIMATE_WEBHOOK_SECRET"],  # whsec_…
        headers=dict(request.headers),
        raw_body=raw,
    )  # raises ValueError on bad signature / stale timestamp
    # dedupe on the webhook-id header — delivery is at-least-once
    return Response(status_code=204)
```

## Configuration

| Kwarg | Env var | Default |
|---|---|---|
| `api_key` | `PRIMATE_API_KEY` | — (required) |
| `base_url` | `PRIMATE_BASE_URL` | `https://api.primateintelligence.ai` |
| `max_retries` | — | `3` |
| `timeout_s` | — | `60.0` |
