primate-intelligence 0.1.0__tar.gz

primate_intelligence-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/

primate_intelligence-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+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` |

primate_intelligence-0.1.0/README.md

@@ -0,0 +1,87 @@
+# 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` |

primate_intelligence-0.1.0/primate_intelligence/__init__.py

@@ -0,0 +1,82 @@
+"""primate-intelligence — official Python SDK for the Primate Vision API.
+
+    from primate_intelligence import Primate
+
+    client = Primate()  # reads PRIMATE_API_KEY
+    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"])
+
+Docs: https://primateintelligence.ai/docs
+Spec: https://api.primateintelligence.ai/v1/openapi.json
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._client import HttpClient
+from ._errors import PrimateError, PrimateTimeoutError, registry_flags
+from ._resources import (
+    Analyses,
+    ClientTokens,
+    Errors,
+    Models,
+    Streams,
+    TestFixtures,
+    Usage,
+    Videos,
+    WebhookEndpoints,
+)
+from .webhooks import verify_webhook, verify_webhook_request
+
+__version__ = "0.1.0"
+__all__ = [
+    "Primate",
+    "PrimateError",
+    "PrimateTimeoutError",
+    "registry_flags",
+    "verify_webhook",
+    "verify_webhook_request",
+]
+
+
+class Primate:
+    """Entry point. All options optional — PRIMATE_API_KEY env var is the default auth."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        max_retries: int = 3,
+        timeout_s: float = 60.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        self.http = HttpClient(
+            api_key=api_key,
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout_s=timeout_s,
+            transport=transport,
+        )
+        self.videos = Videos(self.http)
+        self.analyses = Analyses(self.http)
+        self.streams = Streams(self.http)
+        self.client_tokens = ClientTokens(self.http)
+        self.models = Models(self.http)
+        self.usage = Usage(self.http)
+        self.errors = Errors(self.http)
+        self.webhook_endpoints = WebhookEndpoints(self.http)
+        self.test_fixtures = TestFixtures(self.http)
+
+    def close(self) -> None:
+        self.http.close()
+
+    def __enter__(self) -> "Primate":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

primate_intelligence-0.1.0/primate_intelligence/_client.py

@@ -0,0 +1,157 @@
+"""Core HTTP client for the Primate Vision API.
+
+- Auth: PRIMATE_API_KEY env var by default (design §5.3).
+- Retry: registry ``retryable`` flags + ``Retry-After`` (design §15/§16.2).
+- Idempotency: auto UUIDv4 ``Idempotency-Key`` on create calls (§16.1).
+"""
+from __future__ import annotations
+
+import os
+import random
+import time
+import uuid
+from typing import Any, Iterator, Optional
+
+import httpx
+
+from ._errors import PrimateError
+
+DEFAULT_BASE_URL = "https://api.primateintelligence.ai"
+_IDEMPOTENT_CREATE_PATHS = ("/v1/videos", "/v1/analyses", "/v1/webhook_endpoints")
+_USER_AGENT = "primate-intelligence-sdk-py/0.1.0"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        max_retries: int = 3,
+        timeout_s: float = 60.0,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        key = api_key or os.environ.get("PRIMATE_API_KEY")
+        if not key:
+            raise ValueError(
+                "Missing API key. Set the PRIMATE_API_KEY environment variable or pass api_key= — "
+                "get a free test key: curl -X POST https://api.primateintelligence.ai/v1/sandbox"
+            )
+        self._api_key = key
+        self.base_url = (base_url or os.environ.get("PRIMATE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._http = httpx.Client(
+            timeout=timeout_s,
+            transport=transport,
+            headers={"Authorization": f"Bearer {key}", "User-Agent": _USER_AGENT},
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "HttpClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # ── Core request with registry-driven retry ──────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[dict[str, Any]] = None,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+        max_retries: Optional[int] = None,
+    ) -> Any:
+        url = self.base_url + path
+        hdrs = dict(headers or {})
+
+        # §16.1 — auto idempotency keys on create calls.
+        if method == "POST" and path in _IDEMPOTENT_CREATE_PATHS:
+            hdrs["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        elif idempotency_key:
+            hdrs["Idempotency-Key"] = idempotency_key
+
+        retries = self.max_retries if max_retries is None else max_retries
+        last_exc: Optional[Exception] = None
+
+        for attempt in range(retries + 1):
+            try:
+                res = self._http.request(method, url, json=json_body, params=params, headers=hdrs)
+            except httpx.TransportError as exc:  # network-level: retry
+                last_exc = exc
+                if attempt < retries:
+                    time.sleep(_backoff_s(None, attempt))
+                    continue
+                raise
+
+            if res.is_success:
+                if res.status_code == 204 or not res.content:
+                    return None
+                return res.json()
+
+            err = _to_primate_error(res)
+            if err.retryable and attempt < retries:
+                time.sleep(_backoff_s(res, attempt))
+                last_exc = err
+                continue
+            raise err
+
+        raise last_exc  # pragma: no cover — loop always returns or raises
+
+    def get(self, path: str, params: Optional[dict[str, Any]] = None, **kw: Any) -> Any:
+        return self.request("GET", path, params=params, **kw)
+
+    def post(self, path: str, json_body: Optional[dict[str, Any]] = None, **kw: Any) -> Any:
+        return self.request("POST", path, json_body=json_body, **kw)
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    # ── Pagination (§13.4: starting_after + has_more) ─────────────────────────
+
+    def paginate(self, path: str, params: Optional[dict[str, Any]] = None) -> Iterator[dict[str, Any]]:
+        params = dict(params or {})
+        while True:
+            page = self.get(path, params=params)
+            data = page.get("data", [])
+            yield from data
+            if not page.get("has_more") or not data:
+                return
+            params["starting_after"] = data[-1]["id"]
+
+
+def _to_primate_error(res: httpx.Response) -> PrimateError:
+    try:
+        e = res.json().get("error", {})
+    except Exception:
+        e = {}
+    return PrimateError(
+        code=e.get("code", "internal_error"),
+        message=e.get("message", f"HTTP {res.status_code}"),
+        status=res.status_code,
+        param=e.get("param"),
+        docs_url=e.get("docs_url"),
+        request_id=e.get("request_id"),
+        errors=e.get("errors"),
+        details=e.get("details"),
+    )
+
+
+def _backoff_s(res: Optional[httpx.Response], attempt: int) -> float:
+    """Exponential backoff with full jitter; honors Retry-After when present."""
+    if res is not None:
+        retry_after = res.headers.get("Retry-After")
+        if retry_after:
+            try:
+                s = int(retry_after)
+                if s > 0:
+                    return float(s)
+            except ValueError:
+                pass
+    base = min(1.0 * (2**attempt), 8.0)
+    return base * (0.5 + random.random())

primate_intelligence-0.1.0/primate_intelligence/_error_registry.json

@@ -0,0 +1,285 @@
+{
+  "_generated": "scripts/generate-sdk-artifacts.ts — do not hand-edit",
+  "codes": {
+    "invalid_api_key": {
+      "kind": "http",
+      "status": 401,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#invalid_api_key"
+    },
+    "key_revoked": {
+      "kind": "http",
+      "status": 401,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#key_revoked"
+    },
+    "key_expired": {
+      "kind": "http",
+      "status": 401,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#key_expired"
+    },
+    "token_expired": {
+      "kind": "http",
+      "status": 401,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#token_expired"
+    },
+    "insufficient_scope": {
+      "kind": "http",
+      "status": 403,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#insufficient_scope"
+    },
+    "account_restricted": {
+      "kind": "http",
+      "status": 403,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#account_restricted"
+    },
+    "test_mode_only": {
+      "kind": "http",
+      "status": 403,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#test_mode_only"
+    },
+    "validation_failed": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#validation_failed"
+    },
+    "unsupported_media_type": {
+      "kind": "http",
+      "status": 415,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#unsupported_media_type"
+    },
+    "payload_too_large": {
+      "kind": "http",
+      "status": 413,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#payload_too_large"
+    },
+    "resource_not_found": {
+      "kind": "http",
+      "status": 404,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#resource_not_found"
+    },
+    "resource_conflict": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#resource_conflict"
+    },
+    "idempotency_key_reused": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#idempotency_key_reused"
+    },
+    "idempotency_unavailable": {
+      "kind": "http",
+      "status": 409,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#idempotency_unavailable"
+    },
+    "stream_already_active": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#stream_already_active"
+    },
+    "upload_incomplete": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#upload_incomplete"
+    },
+    "video_unreadable": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#video_unreadable"
+    },
+    "video_too_large": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#video_too_large"
+    },
+    "video_too_long": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#video_too_long"
+    },
+    "url_fetch_failed": {
+      "kind": "http",
+      "status": 400,
+      "retryable": true,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#url_fetch_failed"
+    },
+    "url_forbidden": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#url_forbidden"
+    },
+    "prompt_empty": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#prompt_empty"
+    },
+    "prompt_too_long": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#prompt_too_long"
+    },
+    "query_invalid": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#query_invalid"
+    },
+    "parse_failed": {
+      "kind": "http",
+      "status": 422,
+      "retryable": true,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#parse_failed"
+    },
+    "model_not_found": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#model_not_found"
+    },
+    "model_deprecated": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#model_deprecated"
+    },
+    "analysis_not_cancelable": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#analysis_not_cancelable"
+    },
+    "rate_limit_exceeded": {
+      "kind": "http",
+      "status": 429,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#rate_limit_exceeded"
+    },
+    "concurrency_limit_exceeded": {
+      "kind": "http",
+      "status": 429,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#concurrency_limit_exceeded"
+    },
+    "quota_exceeded": {
+      "kind": "http",
+      "status": 429,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#quota_exceeded"
+    },
+    "insufficient_credits": {
+      "kind": "http",
+      "status": 402,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#insufficient_credits"
+    },
+    "capacity_exhausted": {
+      "kind": "http",
+      "status": 503,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#capacity_exhausted"
+    },
+    "sandbox_limit_exceeded": {
+      "kind": "http",
+      "status": 429,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#sandbox_limit_exceeded"
+    },
+    "inference_unavailable": {
+      "kind": "http",
+      "status": 503,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#inference_unavailable"
+    },
+    "db_unavailable": {
+      "kind": "http",
+      "status": 503,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#db_unavailable"
+    },
+    "internal_error": {
+      "kind": "http",
+      "status": 500,
+      "retryable": true,
+      "idem": true,
+      "docs_url": "https://primateintelligence.ai/docs/errors#internal_error"
+    },
+    "webhook_endpoint_limit": {
+      "kind": "http",
+      "status": 400,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#webhook_endpoint_limit"
+    },
+    "inference_error": {
+      "kind": "resource",
+      "status": 0,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#inference_error"
+    },
+    "stuck_timeout": {
+      "kind": "resource",
+      "status": 0,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#stuck_timeout"
+    }
+  }
+}

primate_intelligence-0.1.0/primate_intelligence/_errors.py

@@ -0,0 +1,62 @@
+"""Error types + registry-driven retry flags (design §15).
+
+The registry JSON is generated from the API's single source of truth
+(scripts/generate-sdk-artifacts.ts) — never hand-edit it.
+"""
+from __future__ import annotations
+
+import json
+from importlib import resources
+from typing import Any, Optional
+
+
+def _load_registry() -> dict[str, dict[str, Any]]:
+    with resources.files(__package__).joinpath("_error_registry.json").open() as f:
+        return json.load(f)["codes"]
+
+
+_REGISTRY: dict[str, dict[str, Any]] = _load_registry()
+
+
+def registry_flags(code: str) -> Optional[dict[str, Any]]:
+    """Return {kind, status, retryable, idem, docs_url} for an error code."""
+    return _REGISTRY.get(code)
+
+
+class PrimateError(Exception):
+    """Raised for every non-2xx API response.
+
+    Attributes mirror the error envelope (design §4.4):
+    code, status, message, param, docs_url, request_id, errors, details.
+    ``retryable`` derives from the error registry.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status: int,
+        *,
+        param: Optional[str] = None,
+        docs_url: Optional[str] = None,
+        request_id: Optional[str] = None,
+        errors: Optional[list[dict[str, str]]] = None,
+        details: Optional[dict[str, Any]] = None,
+    ) -> None:
+        suffix = f" (request_id: {request_id})" if request_id else ""
+        super().__init__(f"{code}: {message}{suffix}")
+        self.code = code
+        self.message = message
+        self.status = status
+        self.param = param
+        self.docs_url = docs_url
+        self.request_id = request_id
+        self.errors = errors
+        self.details = details
+        flags = registry_flags(code)
+        self.retryable: bool = bool(flags["retryable"]) if flags else False
+        self.idem: bool = bool(flags["idem"]) if flags else False
+
+
+class PrimateTimeoutError(Exception):
+    """Raised by create_and_wait when the wait budget is exhausted."""

primate_intelligence-0.1.0/primate_intelligence/_resources.py

@@ -0,0 +1,210 @@
+"""Typed resource namespaces — mirror the /v1 surface 1:1.
+
+Responses are returned as dicts matching the OpenAPI schemas
+(https://api.primateintelligence.ai/v1/openapi.json). Structured so a
+Stainless-generated client can replace this module without changing the
+public import surface (A6 fallback path, PRI-438).
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Iterator, Optional
+
+import httpx
+
+from ._client import HttpClient
+from ._errors import PrimateTimeoutError
+
+_TERMINAL = {"completed", "failed", "canceled"}
+
+
+class Videos:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        """POST /v1/videos — presigned-upload create or URL-ingest create."""
+        return self._http.post("/v1/videos", json_body=params)
+
+    def retrieve(self, video_id: str) -> dict[str, Any]:
+        return self._http.get(f"/v1/videos/{video_id}")
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._http.get("/v1/videos", params=params)
+
+    def iter(self, **params: Any) -> Iterator[dict[str, Any]]:
+        return self._http.paginate("/v1/videos", params=params)
+
+    def delete(self, video_id: str) -> dict[str, Any]:
+        return self._http.delete(f"/v1/videos/{video_id}")
+
+    def complete(self, video_id: str) -> dict[str, Any]:
+        """POST /v1/videos/{id}/complete — after the presigned S3 PUT."""
+        return self._http.post(f"/v1/videos/{video_id}/complete")
+
+    def upload(
+        self,
+        file: bytes,
+        *,
+        filename: str,
+        content_type: str = "video/mp4",
+        metadata: Optional[dict[str, str]] = None,
+    ) -> dict[str, Any]:
+        """Create + presigned S3 PUT + complete, in one call."""
+        video = self.create(
+            filename=filename,
+            content_type=content_type,
+            size_bytes=len(file),
+            **({"metadata": metadata} if metadata else {}),
+        )
+        upload = video.get("upload")
+        if not upload:
+            raise RuntimeError("API did not return presigned upload details")
+        res = httpx.put(upload["url"], content=file, headers=upload.get("headers", {}), timeout=600)
+        res.raise_for_status()
+        return self.complete(video["id"])
+
+
+class Analyses:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        """POST /v1/analyses."""
+        return self._http.post("/v1/analyses", json_body=params)
+
+    def retrieve(self, analysis_id: str) -> dict[str, Any]:
+        return self._http.get(f"/v1/analyses/{analysis_id}")
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._http.get("/v1/analyses", params=params)
+
+    def iter(self, **params: Any) -> Iterator[dict[str, Any]]:
+        return self._http.paginate("/v1/analyses", params=params)
+
+    def cancel(self, analysis_id: str) -> dict[str, Any]:
+        return self._http.post(f"/v1/analyses/{analysis_id}/cancel")
+
+    def create_and_wait(
+        self,
+        *,
+        timeout_s: float = 600.0,
+        poll_interval_s: float = 2.0,
+        **params: Any,
+    ) -> dict[str, Any]:
+        """Create an analysis and block until a terminal state (design §7.2).
+
+        Uses ``Prefer: wait`` server-side sync sugar for the first leg
+        (cap 120s), then polls with the given interval until ``timeout_s``.
+        """
+        prefer_wait = min(int(timeout_s), 120)
+        deadline = time.monotonic() + timeout_s
+        analysis = self._http.post(
+            "/v1/analyses", json_body=params, headers={"Prefer": f"wait={prefer_wait}"}
+        )
+        while analysis["status"] not in _TERMINAL:
+            if time.monotonic() > deadline:
+                raise PrimateTimeoutError(
+                    f"Analysis {analysis['id']} still {analysis['status']} after {timeout_s}s — "
+                    f"poll client.analyses.retrieve('{analysis['id']}') or use webhooks."
+                )
+            time.sleep(poll_interval_s)
+            analysis = self.retrieve(analysis["id"])
+        return analysis
+
+
+class Streams:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        return self._http.post("/v1/streams", json_body=params or {})
+
+    def retrieve(self, stream_id: str) -> dict[str, Any]:
+        return self._http.get(f"/v1/streams/{stream_id}")
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._http.get("/v1/streams", params=params)
+
+    def iter(self, **params: Any) -> Iterator[dict[str, Any]]:
+        return self._http.paginate("/v1/streams", params=params)
+
+    def end(self, stream_id: str) -> dict[str, Any]:
+        """POST /v1/streams/{id}/end (idempotent)."""
+        return self._http.post(f"/v1/streams/{stream_id}/end")
+
+
+class ClientTokens:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        """POST /v1/client_tokens — mint an ephemeral browser-safe pvct_ token."""
+        return self._http.post("/v1/client_tokens", json_body=params)
+
+
+class Models:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> dict[str, Any]:
+        return self._http.get("/v1/models")
+
+
+class Usage:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def retrieve(self) -> dict[str, Any]:
+        """GET /v1/usage — credit balance + period meters."""
+        return self._http.get("/v1/usage")
+
+
+class Errors:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> dict[str, Any]:
+        """GET /v1/errors — the machine-readable error registry."""
+        return self._http.get("/v1/errors")
+
+
+class WebhookEndpoints:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def create(self, **params: Any) -> dict[str, Any]:
+        """POST /v1/webhook_endpoints — response carries the one-time whsec_ secret."""
+        return self._http.post("/v1/webhook_endpoints", json_body=params)
+
+    def retrieve(self, endpoint_id: str) -> dict[str, Any]:
+        return self._http.get(f"/v1/webhook_endpoints/{endpoint_id}")
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._http.get("/v1/webhook_endpoints", params=params)
+
+    def delete(self, endpoint_id: str) -> dict[str, Any]:
+        return self._http.delete(f"/v1/webhook_endpoints/{endpoint_id}")
+
+    def rotate_secret(self, endpoint_id: str) -> dict[str, Any]:
+        return self._http.post(f"/v1/webhook_endpoints/{endpoint_id}/rotate_secret")
+
+    def enable(self, endpoint_id: str) -> dict[str, Any]:
+        return self._http.post(f"/v1/webhook_endpoints/{endpoint_id}/enable")
+
+    def list_deliveries(self, endpoint_id: str, **params: Any) -> dict[str, Any]:
+        return self._http.get(f"/v1/webhook_endpoints/{endpoint_id}/deliveries", params=params)
+
+    def redeliver(self, endpoint_id: str, delivery_id: str) -> dict[str, Any]:
+        return self._http.post(
+            f"/v1/webhook_endpoints/{endpoint_id}/deliveries/{delivery_id}/redeliver"
+        )
+
+
+class TestFixtures:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def retrieve(self) -> dict[str, Any]:
+        """GET /v1/test-fixture — stable fixture for CI self-verification (§5.5)."""
+        return self._http.get("/v1/test-fixture")

primate_intelligence-0.1.0/primate_intelligence/webhooks.py

@@ -0,0 +1,72 @@
+"""Standard Webhooks signature verification (design §16.3).
+
+Signed content: ``{id}.{timestamp}.{payload}`` where payload is the RAW
+request body. HMAC key = base64-decoded portion of the whsec_ secret.
+Rejects timestamp skew > 5 minutes; constant-time compare; accepts any
+matching signature during the 24h dual-secret rotation overlap.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import time
+from typing import Mapping, Optional, Union
+
+TOLERANCE_S = 300
+
+
+def verify_webhook(
+    *,
+    secret: str,
+    id: str,
+    timestamp: str,
+    signature: str,
+    payload: Union[str, bytes],
+    now_s: Optional[int] = None,
+) -> bool:
+    """Return True when the delivery is authentic and inside the replay window."""
+    now = now_s if now_s is not None else int(time.time())
+    try:
+        ts = int(timestamp)
+    except (TypeError, ValueError):
+        return False
+    if abs(now - ts) > TOLERANCE_S:
+        return False
+
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    body = payload.encode() if isinstance(payload, str) else payload
+    expected = hmac.new(key, f"{id}.{timestamp}.".encode() + body, hashlib.sha256).digest()
+
+    for part in signature.split(" "):
+        version, _, sig = part.partition(",")
+        if version != "v1" or not sig:
+            continue
+        try:
+            candidate = base64.b64decode(sig)
+        except Exception:
+            continue
+        if hmac.compare_digest(candidate, expected):
+            return True
+    return False
+
+
+def verify_webhook_request(
+    *,
+    secret: str,
+    headers: Mapping[str, str],
+    raw_body: Union[str, bytes],
+    now_s: Optional[int] = None,
+) -> None:
+    """Verify from a headers mapping + raw body. Raises ValueError on failure."""
+    lower = {k.lower(): v for k, v in headers.items()}
+    ok = verify_webhook(
+        secret=secret,
+        id=lower.get("webhook-id", ""),
+        timestamp=lower.get("webhook-timestamp", ""),
+        signature=lower.get("webhook-signature", ""),
+        payload=raw_body,
+        now_s=now_s,
+    )
+    if not ok:
+        raise ValueError("Webhook signature verification failed")

primate_intelligence-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "primate-intelligence"
+version = "0.1.0"
+description = "Official Python SDK for the Primate Vision API (Primate Intelligence). Video scene understanding: upload, analyze, stream."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Primate Intelligence" }]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.25,<1"]
+keywords = ["video", "vision", "ai", "video-understanding", "primate-intelligence"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://primateintelligence.ai/docs"
+Repository = "https://github.com/Primate-Intelligence/primate-intelligence-api"
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "respx>=0.21"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["primate_intelligence"]

primate_intelligence-0.1.0/tests/test_sdk.py

@@ -0,0 +1,198 @@
+"""Unit tests for the primate-intelligence Python SDK (offline, httpx MockTransport)."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+
+import httpx
+import pytest
+
+from primate_intelligence import Primate, PrimateError, PrimateTimeoutError, registry_flags
+from primate_intelligence.webhooks import verify_webhook, verify_webhook_request
+
+SECRET = "whsec_" + base64.b64encode(b"test-secret-32-bytes-aaaaaaaaaaa").decode()
+
+
+def _client(handler) -> Primate:
+    return Primate(api_key="pv_test_k", transport=httpx.MockTransport(handler), max_retries=3)
+
+
+def _err(code: str, status: int, **extra) -> httpx.Response:
+    return httpx.Response(
+        status,
+        json={"error": {"code": code, "message": f"msg {code}", "status": status, "request_id": "req_t", **extra}},
+    )
+
+
+# ── Auth / construction ─────────────────────────────────────────────────────────
+
+
+def test_requires_api_key(monkeypatch):
+    monkeypatch.delenv("PRIMATE_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="PRIMATE_API_KEY"):
+        Primate()
+
+
+def test_sends_bearer_and_auto_idempotency_key():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["auth"] = request.headers.get("Authorization")
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(200, json={"id": "video_x", "object": "video"})
+
+    c = _client(handler)
+    c.videos.create(url="https://example.com/v.mp4")
+    assert seen["auth"] == "Bearer pv_test_k"
+    assert seen["idem"] and len(seen["idem"]) == 36  # UUIDv4
+
+
+def test_no_auto_key_on_cancel():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(200, json={"id": "an_x", "object": "analysis", "status": "canceled"})
+
+    _client(handler).analyses.cancel("an_x")
+    assert seen["idem"] is None
+
+
+# ── Retry policy (registry-driven) ───────────────────────────────────────────────
+
+
+def test_retries_retryable_then_succeeds():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        if calls["n"] == 1:
+            return _err("inference_unavailable", 503, docs_url="x")
+        return httpx.Response(200, json={"object": "list", "data": [], "has_more": False})
+
+    out = _client(handler).models.list()
+    assert out["object"] == "list"
+    assert calls["n"] == 2
+
+
+def test_does_not_retry_non_retryable():
+    calls = {"n": 0}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls["n"] += 1
+        return _err("invalid_api_key", 401)
+
+    with pytest.raises(PrimateError) as ei:
+        _client(handler).models.list()
+    assert calls["n"] == 1
+    assert ei.value.code == "invalid_api_key"
+    assert ei.value.retryable is False
+    assert ei.value.request_id == "req_t"
+
+
+def test_registry_flags():
+    assert registry_flags("rate_limit_exceeded")["retryable"] is True
+    assert registry_flags("capacity_exhausted")["idem"] is True
+    assert registry_flags("validation_failed")["retryable"] is False
+
+
+# ── create_and_wait ─────────────────────────────────────────────────────────────
+
+
+def test_create_and_wait_prefers_wait_and_polls():
+    calls = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append((request.method, request.url.path, request.headers.get("Prefer")))
+        if request.method == "POST":
+            return httpx.Response(200, json={"id": "an_1", "object": "analysis", "status": "queued"})
+        n = len([c for c in calls if c[0] == "GET"])
+        status = "completed" if n >= 2 else "analyzing"
+        return httpx.Response(200, json={"id": "an_1", "object": "analysis", "status": status})
+
+    a = _client(handler).analyses.create_and_wait(
+        video_id="video_x", prompt="p", poll_interval_s=0.001
+    )
+    assert a["status"] == "completed"
+    assert calls[0][2] == "wait=120"  # Prefer header on the create
+
+
+def test_create_and_wait_timeout():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, json={"id": "an_1", "object": "analysis", "status": "analyzing"})
+
+    with pytest.raises(PrimateTimeoutError):
+        _client(handler).analyses.create_and_wait(
+            video_id="video_x", prompt="p", timeout_s=0.01, poll_interval_s=0.001
+        )
+
+
+# ── Pagination ──────────────────────────────────────────────────────────────────
+
+
+def test_paginate_cursors():
+    def handler(request: httpx.Request) -> httpx.Response:
+        after = request.url.params.get("starting_after")
+        if after is None:
+            return httpx.Response(
+                200, json={"object": "list", "data": [{"id": "v_1"}, {"id": "v_2"}], "has_more": True}
+            )
+        assert after == "v_2"
+        return httpx.Response(200, json={"object": "list", "data": [{"id": "v_3"}], "has_more": False})
+
+    ids = [v["id"] for v in _client(handler).videos.iter()]
+    assert ids == ["v_1", "v_2", "v_3"]
+
+
+# ── Webhook verification (§16.3 test vectors) ───────────────────────────────────
+
+
+def _sign(id_: str, ts: str, payload: str, secret: str = SECRET) -> str:
+    key = base64.b64decode(secret.removeprefix("whsec_"))
+    mac = hmac.new(key, f"{id_}.{ts}.{payload}".encode(), hashlib.sha256).digest()
+    return "v1," + base64.b64encode(mac).decode()
+
+
+NOW = 1_751_980_800
+EVT = "evt_01TESTTESTTESTTESTTESTTEST"
+PAYLOAD = json.dumps({"id": EVT, "type": "analysis.completed"})
+
+
+def test_webhook_valid():
+    assert verify_webhook(
+        secret=SECRET, id=EVT, timestamp=str(NOW), signature=_sign(EVT, str(NOW), PAYLOAD),
+        payload=PAYLOAD, now_s=NOW,
+    )
+
+
+def test_webhook_tampered_payload():
+    assert not verify_webhook(
+        secret=SECRET, id=EVT, timestamp=str(NOW), signature=_sign(EVT, str(NOW), PAYLOAD),
+        payload=PAYLOAD + "x", now_s=NOW,
+    )
+
+
+def test_webhook_replay_window():
+    assert not verify_webhook(
+        secret=SECRET, id=EVT, timestamp=str(NOW), signature=_sign(EVT, str(NOW), PAYLOAD),
+        payload=PAYLOAD, now_s=NOW + 301,
+    )
+
+
+def test_webhook_rotation_any_match():
+    sig = "v1,AAAA " + _sign(EVT, str(NOW), PAYLOAD)
+    assert verify_webhook(
+        secret=SECRET, id=EVT, timestamp=str(NOW), signature=sig, payload=PAYLOAD, now_s=NOW
+    )
+
+
+def test_webhook_request_helper_raises():
+    with pytest.raises(ValueError, match="verification failed"):
+        verify_webhook_request(
+            secret=SECRET,
+            headers={"Webhook-Id": EVT, "Webhook-Timestamp": str(NOW), "Webhook-Signature": "v1,AAAA"},
+            raw_body=PAYLOAD,
+            now_s=NOW,
+        )