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

{primate_intelligence-0.2.0 → primate_intelligence-0.3.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: primate-intelligence
-Version: 0.2.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

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

@@ -204,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,
@@ -260,6 +267,27 @@
       "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,

{primate_intelligence-0.2.0 → primate_intelligence-0.3.0}/primate_intelligence/_resources.py

@@ -27,6 +27,15 @@ class Videos:
         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]:
@@ -42,6 +51,18 @@ class Videos:
         """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,
@@ -72,6 +93,14 @@ class Analyses:
     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
@@ -135,6 +164,18 @@ class Analyses:
     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,
         *,
@@ -177,6 +218,29 @@ class Streams:
         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]:
@@ -212,6 +276,25 @@ class Streams:
         """
         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:

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

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