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

primate_intelligence-0.2.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog — primate-intelligence (Python SDK)
+
+## 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.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primate-intelligence
-Version: 0.1.0
+Version: 0.2.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.2.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.2.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.2.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.2.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,
@@ -225,6 +232,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 +253,20 @@
       "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"
+    },
+    "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 +274,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.1.0 → primate_intelligence-0.2.0}/primate_intelligence/_resources.py

@@ -70,9 +70,59 @@ class Analyses:
         self._http = http
 
     def create(self, **params: Any) -> dict[str, Any]:
-        """POST /v1/analyses."""
+        """POST /v1/analyses.
+
+        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}")
 
@@ -96,6 +146,15 @@ class Analyses:
 
         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
@@ -130,7 +189,27 @@ class Streams:
         return self._http.paginate("/v1/streams", params=params)
 
     def end(self, stream_id: str) -> dict[str, Any]:
-        """POST /v1/streams/{id}/end (idempotent)."""
+        """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")
 
 
@@ -156,10 +235,57 @@ class Usage:
         self._http = http
 
     def retrieve(self) -> dict[str, Any]:
-        """GET /v1/usage — credit balance + period meters."""
+        """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

{primate_intelligence-0.1.0 → primate_intelligence-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "primate-intelligence"
-version = "0.1.0"
+version = "0.2.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.2.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