primate-intelligence 0.1.0__tar.gz → 0.3.0__tar.gz

primate_intelligence-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog — primate-intelligence (Python SDK)
+
+## 0.3.0 — 2026-07-31
+
+Parity release with the PRI-496 private→public API parity program. Behavior verified against the live dev API on 2026-07-31 (recorded stream with narrative + status events + mid-stream update_prompt). Dict-based responses — fully additive.
+
+### Added
+
+- `client.streams.recording(stream_id)` — `GET /v1/streams/{id}/recording`: signed 1h playback URL for the server-side session recording (create the stream with `recording=True`; raw H.264 Annex-B — `ffmpeg -i in.h264 -c copy out.mp4`).
+- `client.videos.list_analyses(video_id, status=, limit=, starting_after=)` — `GET /v1/videos/{id}/analyses`: per-video analysis history, newest first.
+- `client.analyses.rerun(analysis_id)` — `POST /v1/analyses/{id}/rerun`: free re-run of an eligible failed analysis (`rerun_eligible: true`; never billed).
+
+### Documentation (docstrings)
+
+- `streams.create`: full signaling protocol summary incl. mid-stream `update_prompt` → `prompt_updated`, the narrative opt-in (`options={"narrative": True}` → `narrative_update {t_s, text}` on result detections + `status` events `prompt_context | combined_prompt | recalculating`), and the `recording=True` opt-in.
+- `analyses.create`: the narrative opt-in and the async `narrative {status, entries}` object on completed analyses.
+- `videos.retrieve`: the `media {url, expires_at}` signed source-playback field (sign-on-read, 1h TTL).
+
+## 0.2.0 — 2026-07-28
+
+Parity release with the 2026-07-22 → 2026-07-28 API changes (PRI-480/482 rounds + streaming DX). Behavior verified against the live OpenAPI document and recorded live responses. Dict-based responses mean no breaking type changes — this release is additive.
+
+### Added
+
+- `client.credits.retrieve(limit=, before=)` — `GET /v1/credits`: balance in billable seconds + paginated transaction ledger (each debit carries its analysis/stream `source_id`). Check before submitting work to avoid a 402.
+- `client.credit_pricing.retrieve()` — `GET /v1/credit-pricing` (public): `price_per_second_cents`, grants, purchase presets.
+- `client.analyses.validate_only(video_id=, prompt=)` — dry-run (`validate_only: true`): returns an `analysis_preview` with `assessable`, `estimated_seconds`, `estimated_cost_usd`. Costs nothing.
+- `client.analyses.create_batch(video_id=, prompts=[...])` — `POST /v1/analyses/batch`: 2–10 prompts, first full price, each additional at 50%. Returns `analysis_batch` with all analyses + pricing summary.
+- `client.analyses.validate_batch(...)` — batch dry-run returning `analysis_batch_preview` with per-prompt `discount_pct` (0 or 50) and estimates.
+- Auto `Idempotency-Key` now also covers `POST /v1/analyses/batch`.
+
+### Documentation (docstrings — dict responses, no code change needed)
+
+- `create_and_wait` / `create`: documents `result.detected_count` (count-intent queries; 0 = nothing found), `result.indeterminate_reason` (`low_confidence | nothing_detected | unsupported_query_form | duration_mismatch`), nullable `result.video_duration_s`, and the real `usage` shape `{billed_seconds, credit_balance_after}` (immutable post-settlement snapshot).
+- `streams.end`: documents the honest `end_reason` vocabulary (`completed | canceled | insufficient_credits | error | timeout | ice_failed | media_timeout`), `results_summary.result_frames` (the `frames` alias is removed ~2026-08-28), `failure_diagnostic`, and the metering-tick field `session_remaining_s` (the `balance_s` alias is removed ~2026-08-28).
+
+## 0.1.0
+
+Initial release.

{primate_intelligence-0.1.0 → primate_intelligence-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primate-intelligence
-Version: 0.1.0
+Version: 0.3.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
@@ -57,12 +57,15 @@ 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`.
+- **Typed resource namespaces** for the full `/v1` surface: `videos`, `analyses`, `streams`, `client_tokens`, `models`, `usage`, `credits`, `credit_pricing`, `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(): …`.
+- **`analyses.validate_only()`** — dry-run a prompt: compiled query + `assessable` + cost estimate, without creating an analysis or spending credits.
+- **`analyses.create_batch()` / `validate_batch()`** — 2–10 prompts against one video; first full price, each additional at 50%.
+- **`credits.retrieve()`** — balance + per-analysis transaction ledger (`GET /v1/credits`); **`credit_pricing.retrieve()`** — public pricing config.
 - **Webhook verification** — `verify_webhook()` implements [Standard Webhooks](https://www.standardwebhooks.com) with constant-time compare + replay-window checks.
 
 ## Error handling
@@ -76,7 +79,7 @@ try:
 except PrimateError as err:
     print(err.code, err.status, err.request_id, err.docs_url)
     if err.code == "insufficient_credits":
-        usage = client.usage.retrieve()
+        credits = client.credits.retrieve()  # balance_seconds + transaction ledger
         # → prompt the account owner to top up or enable auto-refill
 ```
 

{primate_intelligence-0.1.0 → primate_intelligence-0.3.0}/README.md

@@ -35,12 +35,15 @@ 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`.
+- **Typed resource namespaces** for the full `/v1` surface: `videos`, `analyses`, `streams`, `client_tokens`, `models`, `usage`, `credits`, `credit_pricing`, `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(): …`.
+- **`analyses.validate_only()`** — dry-run a prompt: compiled query + `assessable` + cost estimate, without creating an analysis or spending credits.
+- **`analyses.create_batch()` / `validate_batch()`** — 2–10 prompts against one video; first full price, each additional at 50%.
+- **`credits.retrieve()`** — balance + per-analysis transaction ledger (`GET /v1/credits`); **`credit_pricing.retrieve()`** — public pricing config.
 - **Webhook verification** — `verify_webhook()` implements [Standard Webhooks](https://www.standardwebhooks.com) with constant-time compare + replay-window checks.
 
 ## Error handling
@@ -54,7 +57,7 @@ try:
 except PrimateError as err:
     print(err.code, err.status, err.request_id, err.docs_url)
     if err.code == "insufficient_credits":
-        usage = client.usage.retrieve()
+        credits = client.credits.retrieve()  # balance_seconds + transaction ledger
         # → prompt the account owner to top up or enable auto-refill
 ```
 

{primate_intelligence-0.1.0 → primate_intelligence-0.3.0}/primate_intelligence/__init__.py

@@ -23,6 +23,8 @@ from ._errors import PrimateError, PrimateTimeoutError, registry_flags
 from ._resources import (
     Analyses,
     ClientTokens,
+    CreditPricing,
+    Credits,
     Errors,
     Models,
     Streams,
@@ -33,7 +35,7 @@ from ._resources import (
 )
 from .webhooks import verify_webhook, verify_webhook_request
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "Primate",
     "PrimateError",
@@ -68,6 +70,8 @@ class Primate:
         self.client_tokens = ClientTokens(self.http)
         self.models = Models(self.http)
         self.usage = Usage(self.http)
+        self.credits = Credits(self.http)
+        self.credit_pricing = CreditPricing(self.http)
         self.errors = Errors(self.http)
         self.webhook_endpoints = WebhookEndpoints(self.http)
         self.test_fixtures = TestFixtures(self.http)

{primate_intelligence-0.1.0 → primate_intelligence-0.3.0}/primate_intelligence/_client.py

@@ -17,8 +17,8 @@ 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"
+_IDEMPOTENT_CREATE_PATHS = ("/v1/videos", "/v1/analyses", "/v1/analyses/batch", "/v1/webhook_endpoints")
+_USER_AGENT = "primate-intelligence-sdk-py/0.2.0"
 
 
 class HttpClient:

{primate_intelligence-0.1.0 → primate_intelligence-0.3.0}/primate_intelligence/_error_registry.json

@@ -50,6 +50,13 @@
       "idem": false,
       "docs_url": "https://primateintelligence.ai/docs/errors#test_mode_only"
     },
+    "test_key_fixture_only": {
+      "kind": "http",
+      "status": 403,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#test_key_fixture_only"
+    },
     "validation_failed": {
       "kind": "http",
       "status": 400,
@@ -197,6 +204,13 @@
       "idem": false,
       "docs_url": "https://primateintelligence.ai/docs/errors#analysis_not_cancelable"
     },
+    "rerun_not_eligible": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#rerun_not_eligible"
+    },
     "rate_limit_exceeded": {
       "kind": "http",
       "status": 429,
@@ -225,6 +239,13 @@
       "idem": false,
       "docs_url": "https://primateintelligence.ai/docs/errors#insufficient_credits"
     },
+    "grant_exhausted": {
+      "kind": "http",
+      "status": 402,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#grant_exhausted"
+    },
     "capacity_exhausted": {
       "kind": "http",
       "status": 503,
@@ -239,6 +260,41 @@
       "idem": true,
       "docs_url": "https://primateintelligence.ai/docs/errors#sandbox_limit_exceeded"
     },
+    "upgrade_limit_exceeded": {
+      "kind": "http",
+      "status": 429,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#upgrade_limit_exceeded"
+    },
+    "github_verification_required": {
+      "kind": "http",
+      "status": 403,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#github_verification_required"
+    },
+    "github_token_invalid": {
+      "kind": "http",
+      "status": 401,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#github_token_invalid"
+    },
+    "github_account_already_used": {
+      "kind": "http",
+      "status": 409,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#github_account_already_used"
+    },
+    "device_code_expired": {
+      "kind": "http",
+      "status": 410,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#device_code_expired"
+    },
     "inference_unavailable": {
       "kind": "http",
       "status": 503,
@@ -246,6 +302,13 @@
       "idem": true,
       "docs_url": "https://primateintelligence.ai/docs/errors#inference_unavailable"
     },
+    "upstream_error": {
+      "kind": "http",
+      "status": 502,
+      "retryable": false,
+      "idem": false,
+      "docs_url": "https://primateintelligence.ai/docs/errors#upstream_error"
+    },
     "db_unavailable": {
       "kind": "http",
       "status": 503,

primate_intelligence-0.3.0/primate_intelligence/_resources.py

@@ -0,0 +1,419 @@
+"""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]:
+        """GET /v1/videos/{id}.
+
+        Ready videos carry ``media: {url, expires_at} | None`` — a signed
+        playback URL for the original source video, generated FRESH on every
+        read with a 1-hour TTL (sign-on-read). Re-fetch the video for a new
+        URL after expiry; old videos always stay playable. ``media`` is None
+        for non-ready videos and rows without a stored source object (e.g.
+        sandbox fixture videos).
+        """
+        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 list_analyses(self, video_id: str, **params: Any) -> dict[str, Any]:
+        """GET /v1/videos/{id}/analyses — per-video analysis history.
+
+        Every analysis run against this video, newest first. Same list
+        envelope + filters (``status``, ``limit``, ``starting_after``) as
+        GET /v1/analyses — the resource-nested spelling of
+        ``analyses.list(video_id=...)``. Combine with ``Video.media`` (signed
+        source playback) and ``Analysis.artifacts`` (annotated result video)
+        for full video-library semantics: list, replay, per-video history.
+        """
+        return self._http.get(f"/v1/videos/{video_id}/analyses", params=params)
+
+    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.
+
+        Pass ``options={"narrative": True}`` to generate a timestamped
+        narrative (event sentences) for the video: the completed analysis
+        then carries ``narrative: {status: "generating" | "ready" | "failed",
+        entries: [{t_s, text}]}``. Generation runs asynchronously AFTER
+        completion — the first completed read may show ``generating`` with
+        empty entries; keep polling the GET until ``ready``. No surcharge.
+        Without the opt-in, ``narrative`` is always None.
+
+        Pass ``validate_only=True`` for a dry run: compiles the prompt, reports
+        whether the query is assessable, and estimates duration/cost — WITHOUT
+        creating an analysis or spending credits. The response is then an
+        ``analysis_preview`` object (``{object, query, parse_mode, assessable,
+        video_duration_s, estimated_seconds, estimated_cost_usd}``), not an
+        analysis. Prefer :meth:`validate_only` which reads more clearly.
+        """
+        return self._http.post("/v1/analyses", json_body=params)
+
+    def validate_only(self, **params: Any) -> dict[str, Any]:
+        """Dry-run a prompt (POST /v1/analyses with ``validate_only: true``).
+
+        Costs nothing: no analysis is created, no credits spent. Returns an
+        ``analysis_preview`` dict::
+
+            {object: "analysis_preview", query, parse_mode: "llm"|"heuristic"|"client",
+             assessable: bool, video_duration_s: float|None,
+             estimated_seconds: int|None, estimated_cost_usd: float|None}
+
+        Estimates are None when the video duration is not yet known.
+        """
+        params["validate_only"] = True
+        return self._http.post("/v1/analyses", json_body=params)
+
+    def create_batch(self, **params: Any) -> dict[str, Any]:
+        """POST /v1/analyses/batch — 2–10 prompts against the same video.
+
+        First prompt is billed at full price; each additional prompt at 50%.
+        Required: ``video_id`` and ``prompts`` (list of 2–10 strings).
+        Returns an ``analysis_batch``::
+
+            {object: "analysis_batch", id, video_id, analyses: […], pricing:
+             {full_price_prompts, discounted_prompts, discount_pct,
+              estimated_total_seconds, estimated_total_cost_usd}}
+
+        Poll each returned analysis id individually. Pass ``validate_only=True``
+        (or use :meth:`validate_batch`) for a cost-estimate dry-run that returns
+        an ``analysis_batch_preview`` with per-prompt ``discount_pct`` (0 or 50)
+        and estimates — no credits reserved, no jobs created.
+        """
+        return self._http.post("/v1/analyses/batch", json_body=params)
+
+    def validate_batch(self, **params: Any) -> dict[str, Any]:
+        """Dry-run a batch (POST /v1/analyses/batch with ``validate_only: true``).
+
+        Parses all prompts and returns an ``analysis_batch_preview`` with
+        per-prompt estimates. No credits reserved, no jobs created.
+        """
+        params["validate_only"] = True
+        return self._http.post("/v1/analyses/batch", 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 rerun(self, analysis_id: str) -> dict[str, Any]:
+        """POST /v1/analyses/{id}/rerun — free re-run of an eligible failed analysis.
+
+        Failed analyses carry ``rerun_eligible: bool`` (present ONLY on
+        failed status) — true when the failure occurred during a declared
+        platform incident or was flagged by ops. Creates a FRESH analysis at
+        no charge (same video, prompt/query, model, options; new id; usage
+        stays None — never billed). One free re-run per failed analysis;
+        ineligible → 409 ``rerun_not_eligible``.
+        """
+        return self._http.post(f"/v1/analyses/{analysis_id}/rerun")
+
+    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``.
+
+        On completion, ``result`` carries ``answer`` (yes|no|indeterminate),
+        ``confidence``, ``clips``, ``video_duration_s`` (may be None), and —
+        when relevant — ``detected_count`` (count-intent queries; 0 = nothing
+        found) and ``indeterminate_reason`` (low_confidence |
+        nothing_detected | unsupported_query_form | duration_mismatch).
+        ``usage`` (terminal only) is ``{billed_seconds, credit_balance_after}``
+        — an immutable snapshot of the balance after THIS analysis settled.
+        Do not pass ``validate_only`` here — use :meth:`validate_only`.
+        """
+        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]:
+        """POST /v1/streams — create a real-time WebRTC analysis stream.
+
+        Returns ``signaling.url`` + ``ice_servers`` + ``limits``. Signaling
+        protocol v1 over the WS (auth: ``?token=`` with a pvct\\_ client token,
+        never a secret key): join → ready|queued → offer/answer/ice → live →
+        result frames; 5s metering ticks; ``end {reason}``. Mid-stream, send
+        ``{"type": "update_prompt", "prompt": "..."}`` (≤2000 chars) to change
+        the question without reconnecting — the server confirms with
+        ``{"type": "prompt_updated"}`` and subsequent frames echo the new
+        prompt.
+
+        Opt-ins:
+
+        - ``options={"narrative": True}`` — live narrative. Result-frame
+          detections then carry ``narrative_update: {t_s, text}`` whenever the
+          engine emits a new sentence (event-driven, absent otherwise), and
+          the WS additionally delivers ``status`` events
+          (``{"type": "status", "status": "prompt_context" |
+          "combined_prompt" | "recalculating", "message": ...}`` — closed
+          vocabulary) for ordering/annotating narrative entries. No surcharge.
+        - ``recording=True`` — server-side session recording; retrieve the
+          playback URL after the stream ends via :meth:`recording`.
+        """
+        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).
+
+        The terminal stream resource carries:
+
+        - ``end_reason``: completed | canceled | insufficient_credits | error |
+          timeout | ice_failed | media_timeout. A stream that never went live
+          is never "completed"; ice_failed/media_timeout/canceled bill 0.
+        - ``results_summary``: ``{result_frames, frames (deprecated alias,
+          removed ~2026-08-28 — read result_frames), last_detections}``.
+          result_frames counts result EVENTS emitted (sampled, not per-frame).
+        - ``failure_diagnostic``: on ice_failed (and some media_timeout cases),
+          ``{local_candidates, hint}`` — the server-side ICE candidate summary.
+        - ``usage``: ``{billed_seconds, credit_balance_after}`` — live-clock
+          seconds; join/negotiation free.
+
+        While live, the signaling WS sends 5s metering ticks
+        ``{elapsed_s, billed_s, session_remaining_s}`` (``balance_s`` is a
+        deprecated alias of session_remaining_s, removed ~2026-08-28) and may
+        push a ``warning`` with ``code: "no_media_frames"`` when transport
+        connected but no decodable frames arrived.
+        """
+        return self._http.post(f"/v1/streams/{stream_id}/end")
+
+    def recording(self, stream_id: str) -> dict[str, Any]:
+        """GET /v1/streams/{id}/recording — signed session-recording URL.
+
+        Requires the stream to have been created with ``recording=True`` and
+        ended with a stored recording (``stream["recording"]["status"] ==
+        "available"``). Returns::
+
+            {object: "stream_recording", stream_id, url, expires_at,
+             content_type: "video/h264", container: "h264-annex-b"}
+
+        The URL is signed FRESH on every call (1h TTL) — re-fetch for a new
+        one. The recording is a raw H.264 Annex-B elementary stream (the
+        exact annotated frames the client saw); lossless remux to MP4:
+        ``ffmpeg -i recording.h264 -c copy recording.mp4``.
+        404 when recording wasn't enabled; 409 while the stream is active,
+        when capture failed, or when nothing was stored.
+        """
+        return self._http.get(f"/v1/streams/{stream_id}/recording")
+
+
+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.
+
+        For the per-analysis transaction ledger, use :class:`Credits`
+        (``client.credits.retrieve()``).
+        """
+        return self._http.get("/v1/usage")
+
+
+class Credits:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def retrieve(self, *, limit: Optional[int] = None, before: Optional[str] = None) -> dict[str, Any]:
+        """GET /v1/credits — balance + paginated transaction ledger.
+
+        Agent-facing billing truth: check this before submitting work to avoid
+        a 402. Returns::
+
+            {object: "credits", balance_seconds, grant_seconds, used_seconds,
+             transactions: [{id, kind, seconds_delta, balance_after_seconds,
+                             source_type, source_id, created_at}],
+             has_more: bool}
+
+        Each debit carries the analysis/stream id it came from in
+        ``source_id`` (``source_type: "analysis"``). ``limit`` is 1–100
+        (default 20); ``before`` is a cursor returning transactions older
+        than that id.
+        """
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        if before is not None:
+            params["before"] = before
+        return self._http.get("/v1/credits", params=params or None)
+
+
+class CreditPricing:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def retrieve(self) -> dict[str, Any]:
+        """GET /v1/credit-pricing — current pricing config (public, no auth).
+
+        Returns ``{price_per_second_cents, signup_grant_seconds,
+        card_grant_seconds, auto_refill_threshold_seconds,
+        allowed_purchase_cents, custom_purchase_enabled, min_purchase_cents}``.
+        Cost of an analysis = ``usage.billed_seconds × price_per_second_cents``.
+        """
+        return self._http.get("/v1/credit-pricing")
+
+
+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-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "primate-intelligence"
-version = "0.1.0"
+version = "0.3.0"
 description = "Official Python SDK for the Primate Vision API (Primate Intelligence). Video scene understanding: upload, analyze, stream."
 readme = "README.md"
 license = { text = "MIT" }

primate_intelligence-0.3.0/tests/test_parity.py

@@ -0,0 +1,156 @@
+"""PRI-480 parity tests — new resources exercised against RECORDED LIVE API
+responses (captured 2026-07-28 from https://api.primateintelligence.ai with a
+sandbox key), never invented shapes. Offline via httpx MockTransport."""
+from __future__ import annotations
+
+import json
+
+import httpx
+
+from primate_intelligence import Primate
+
+# ── Recorded live fixtures (2026-07-28) ──────────────────────────────────────
+
+LIVE_CREDITS = {
+    "object": "credits",
+    "balance_seconds": 6000,
+    "grant_seconds": 6000,
+    "used_seconds": 0,
+    "transactions": [
+        {
+            "id": "09b1463b-a461-4eba-864b-1a7fd46c6844",
+            "kind": "signup_grant",
+            "seconds_delta": 6000,
+            "balance_after_seconds": 6000,
+            "source_type": None,
+            "source_id": None,
+            "created_at": "2026-07-28T19:59:13.406703+00:00",
+        }
+    ],
+    "has_more": False,
+}
+
+LIVE_PRICING = {
+    "price_per_second_cents": 1,
+    "signup_grant_seconds": 6000,
+    "card_grant_seconds": 6000,
+    "auto_refill_threshold_seconds": 600,
+    "allowed_purchase_cents": [1000, 2500, 5000, 10000],
+    "custom_purchase_enabled": True,
+    "min_purchase_cents": 1000,
+}
+
+LIVE_PREVIEW = {
+    "object": "analysis_preview",
+    "query": {"query_type": "object", "search_terms": ["forklift"]},
+    "parse_mode": "llm",
+    "assessable": True,
+    "video_duration_s": 22.967,
+    "estimated_seconds": 23,
+    "estimated_cost_usd": 0.23,
+}
+
+LIVE_BATCH_PREVIEW = {
+    "object": "analysis_batch_preview",
+    "video_id": "video_01KYN50SNEJMXBAY56VP0RVYR4",
+    "prompts": [
+        {"index": 0, "query": {}, "parse_mode": "llm", "assessable": True,
+         "estimated_seconds": None, "estimated_cost_usd": None, "discount_pct": 0},
+        {"index": 1, "query": {}, "parse_mode": "llm", "assessable": True,
+         "estimated_seconds": None, "estimated_cost_usd": None, "discount_pct": 50},
+    ],
+    "pricing": {
+        "full_price_prompts": 1,
+        "discounted_prompts": 1,
+        "discount_pct": 50,
+        "estimated_total_seconds": None,
+        "estimated_total_cost_usd": None,
+    },
+}
+
+
+def _client(handler) -> Primate:
+    return Primate(api_key="pv_test_k", transport=httpx.MockTransport(handler))
+
+
+def test_credits_retrieve_hits_v1_credits():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json=LIVE_CREDITS)
+
+    out = _client(handler).credits.retrieve()
+    assert seen["path"] == "/v1/credits"
+    assert seen["query"] == {}
+    assert out["object"] == "credits"
+    assert out["balance_seconds"] == 6000
+    assert out["transactions"][0]["kind"] == "signup_grant"
+    assert out["transactions"][0]["source_id"] is None
+
+
+def test_credits_retrieve_pagination_params():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json=LIVE_CREDITS)
+
+    _client(handler).credits.retrieve(limit=5, before="txn_x")
+    assert seen["query"] == {"limit": "5", "before": "txn_x"}
+
+
+def test_credit_pricing_retrieve():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/v1/credit-pricing"
+        return httpx.Response(200, json=LIVE_PRICING)
+
+    out = _client(handler).credit_pricing.retrieve()
+    assert out["price_per_second_cents"] == 1
+    assert out["allowed_purchase_cents"] == [1000, 2500, 5000, 10000]
+
+
+def test_validate_only_sends_flag_and_returns_preview():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(200, json=LIVE_PREVIEW)
+
+    out = _client(handler).analyses.validate_only(video_id="video_x", prompt="Is there a forklift?")
+    assert seen["body"]["validate_only"] is True
+    assert out["object"] == "analysis_preview"
+    assert out["assessable"] is True
+    assert out["estimated_seconds"] == 23
+
+
+def test_create_batch_posts_and_auto_idempotency_key():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(202, json={"object": "analysis_batch", "id": "ab_x",
+                                         "video_id": "video_x", "analyses": [],
+                                         "pricing": LIVE_BATCH_PREVIEW["pricing"]})
+
+    out = _client(handler).analyses.create_batch(video_id="video_x", prompts=["a?", "b?"])
+    assert seen["path"] == "/v1/analyses/batch"
+    assert seen["idem"] and len(seen["idem"]) == 36
+    assert "validate_only" not in seen["body"]
+    assert out["object"] == "analysis_batch"
+
+
+def test_validate_batch_returns_live_preview_shape():
+    def handler(request: httpx.Request) -> httpx.Response:
+        body = json.loads(request.content)
+        assert body["validate_only"] is True
+        return httpx.Response(200, json=LIVE_BATCH_PREVIEW)
+
+    out = _client(handler).analyses.validate_batch(video_id="video_x", prompts=["a?", "b?"])
+    assert out["object"] == "analysis_batch_preview"
+    assert out["prompts"][0]["discount_pct"] == 0
+    assert out["prompts"][1]["discount_pct"] == 50
+    assert out["pricing"]["discount_pct"] == 50

primate_intelligence-0.1.0/primate_intelligence/_resources.py

@@ -1,210 +0,0 @@
-"""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")