interhumanai 1.3.0__tar.gz → 1.3.2__tar.gz

{interhumanai-1.3.0 → interhumanai-1.3.2}/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `interhumanai` are documented here. The package follows
 the TypeScript SDK (`@interhumanai/sdk`): both packages always carry the same
 version and release together.
 
+## 1.3.2
+
+- ``Scope.UPLOAD`` and ``Scope.STREAM`` now cover every model their endpoint
+  serves. The connect-rejection hint of a v2 stream session names the stream
+  scope whichever model the session opens on.
+- Documented the Inter-2 Audio model: ``UploadModel.INTER_2_AUDIO``,
+  ``StreamModel.INTER_2_AUDIO``, ``update_config(audio_format=...)``
+  (``RawAudioFormat``) and ``send_audio`` are part of the generated reference,
+  with the file types each model accepts and the signal subset the audio
+  model reports. No behavior change.
+
+## 1.3.1
+
+- Revised the package quickstart docstring, the README and the examples to lead
+  with the Inter-2 endpoints and an API key passed as ``access_token``. The
+  stream example selects ``api_version="v2"`` explicitly and forwards each
+  chunk its recorder (ffmpeg) writes, instead of cutting a file into fixed-size
+  slices. The ``auth.py`` example is removed. Documentation only; no behavior
+  change.
+
 ## 1.3.0
 
 - Added the whole-file signal list to upload jobs. ``submit(include=...)``

{interhumanai-1.3.0 → interhumanai-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: interhumanai
-Version: 1.3.0
+Version: 1.3.2
 Summary: First-party Python SDK for the Interhuman API: upload and stream social-signal analysis.
 Project-URL: Homepage, https://docs.interhuman.ai
 Project-URL: Repository, https://github.com/interhumanai/interhuman-api
@@ -49,31 +49,43 @@ inherently event-driven, so a single async API keeps every surface consistent
 
 ```python
 import asyncio
-from interhumanai import InterhumanClient
+import os
+
+from interhumanai import InterhumanClient, UploadJobIncludeFlag, UploadJobStatus, UploadModel
 
 async def main() -> None:
-    client = InterhumanClient(key_id="...", key_secret="...")
-    result = await client.upload.analyze("meeting.mp4")
-    for signal in result.signals:
-        print(signal.type.value, signal.start, signal.end)
+    client = InterhumanClient(access_token=os.environ["INTERHUMAN_API_KEY"])
+    job = await client.upload.submit(
+        "meeting.mp4", model=UploadModel.INTER_2, include=[UploadJobIncludeFlag.SIGNALS]
+    )
+    job = await client.upload.wait_for_job(job)
+    if job.status is UploadJobStatus.COMPLETED:
+        for signal in job.result.signals:
+            print(signal.type.value, signal.start, signal.end)
+    else:
+        print(job.error.error_id, job.error.message)
 
 asyncio.run(main())
 ```
 
+For a live feed, open `client.stream(api_version="v2")` (see [Stream API](#stream-api)).
+Pass `api_version` explicitly: the default is `"v1"`.
+
 ## Authentication
 
-Two ways to authenticate:
+Pass a credential as `access_token`; the client sends it as-is:
 
-- **API key credentials** (`key_id` + `key_secret`): the client authenticates
-  with them and renews its session automatically.
-- **A client token** (see below) or your API key, passed as `access_token` and
-  used as-is.
+- **Your API key**, on your server.
+- **A client token** (see below) on an untrusted client such as a browser,
+  which must never see the API key.
 
 ```python
-from interhumanai import InterhumanClient, Scope
+import os
 
-# Managed credentials (recommended for servers)
-client = InterhumanClient(key_id="...", key_secret="...", scopes=[Scope.UPLOAD, Scope.STREAM])
+from interhumanai import InterhumanClient
+
+# On your server
+client = InterhumanClient(access_token=os.environ["INTERHUMAN_API_KEY"])
 
 # A client token minted by your backend
 client = InterhumanClient(access_token=client_token)
@@ -86,13 +98,13 @@ custom credential source into the lower-level clients.
 Scopes name one endpoint family, on every API version that serves it:
 
 - `Scope.UPLOAD` (`interhumanai.upload`) — `POST /v1/upload/analyze`, and
-  `POST /v2/upload/analyze` with `model="inter-2"`; also reads the account's
-  jobs.
+  `POST /v2/upload/analyze` with every model it serves; also reads the
+  account's jobs.
 - `Scope.STREAM` (`interhumanai.stream`) — `WS /v1/stream/analyze`, and
-  `WS /v2/stream/analyze` with `model="inter-2"`.
+  `WS /v2/stream/analyze` with every model it serves.
 
-Holding one scope never implies another, so request every scope the client
-needs.
+A scope covers its endpoint on every API version and every model. Holding one
+scope never implies another, so request every scope the client needs.
 
 ## Client tokens (browser / untrusted clients)
 
@@ -116,32 +128,10 @@ await auth.revoke_client_token(api_key="ih_...", token=token.access_token)
 
 ## Upload API
 
-Analyze a complete video file (mp4, avi, mov, mkv, mpeg-ts, or webm; at least
-3 seconds, at most 32 MB):
-
-```python
-from interhumanai import GoalDimension, IncludeFlag
-
-result = await client.upload.analyze(
-    "meeting.mp4",                                        # path, bytes, or file object
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional sections
-    goal_dimensions=[GoalDimension.CLARITY],              # enables feedback
-)
-```
-
-The typed `AnalysisResult` carries `signals`, `engagement_state`, and — when
-requested — `feedback` and `conversation_quality`.
-
-Every v1 `Signal` carries a `modality` naming the analysis modalities that
-detected it. When several tracks detect the same signal, every contributing
-modality is included, e.g. `["audio", "visual"]`. The Inter-2 (v2) routes send
-no `modality`: the model you choose names the evidence.
-
-### Upload jobs with Inter-2 (`POST /v2/upload/analyze`)
-
-The v2 upload route analyzes a file with an Inter-2 model as an **asynchronous
-job**: the API validates the file, answers with a job envelope, and analyzes
-the file afterwards. Poll the job until it is `completed` or `failed`:
+`client.upload.submit()` sends a file to `POST /v2/upload/analyze`, which
+analyzes it with an Inter-2 model as an **asynchronous job**: the API validates
+the file, answers with a job envelope, and analyzes the file afterwards. Poll
+the job until it is `completed` or `failed`:
 
 ```python
 from interhumanai import UploadJobIncludeFlag, UploadModel
@@ -190,17 +180,50 @@ else:
   `UploadJobWindow` per fixed-length window, each with its span, an
   `engagement_status` and the `signals` read over it. Each signal is an
   `UploadJobSignal`: the v1 `Signal` without `modality`.
+- `UploadModel.INTER_2_AUDIO` reads the audio alone: a wav, flac, mp3, m4a or
+  ogg file, or a webm or mp4 carrying an audio track, under the same limits.
+  It reports the same result shape, with a subset of the signals
+  `UploadModel.INTER_2` reports: agreement, confidence, frustration,
+  hesitation, interest and uncertainty. The same `Scope.UPLOAD` covers it.
+
+### Inter-1 upload (V1, compatibility)
+
+`client.upload.analyze()` calls `POST /v1/upload/analyze`, which analyzes the
+file with Inter-1 and answers synchronously. Use it only to keep an existing
+V1 integration running; see
+[Migrate from V1 to V2](https://docs.interhuman.ai/api-reference/migrate-v1-to-v2).
+It takes a complete video file (mp4, avi, mov, mkv, mpeg-ts, or webm; at least
+3 seconds, at most 32 MB):
+
+```python
+from interhumanai import GoalDimension, IncludeFlag
+
+result = await client.upload.analyze(
+    "meeting.mp4",                                        # path, bytes, or file object
+    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional sections
+    goal_dimensions=[GoalDimension.CLARITY],              # enables feedback
+)
+```
+
+The typed `AnalysisResult` carries `signals`, `engagement_state`, and — when
+requested — `feedback` and `conversation_quality`.
+
+Every v1 `Signal` carries a `modality` naming the analysis modalities that
+detected it. When several tracks detect the same signal, every contributing
+modality is included, e.g. `["audio", "visual"]`. The Inter-2 (v2) routes send
+no `modality`: the model you choose names the evidence.
 
 ## Stream API
 
-One `StreamClient` handles one live session against `WS /v1/stream/analyze`.
-Send binary WebM or fragmented-MP4 chunks and consume typed events with
-`async for`:
+One `StreamClient` handles one live session. Pass `api_version="v2"` to open
+`WS /v2/stream/analyze`, analyzed by Inter-2. Send binary WebM or
+fragmented-MP4 chunks as your recorder produces them, and consume typed events
+with `async for`:
 
 ```python
 from interhumanai import IncludeFlag, SignalDetectedEvent
 
-async with client.stream() as session:
+async with client.stream(api_version="v2") as session:
     await session.wait_for_session_ready()
     await session.update_config(include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL])
     await session.send_video(first_chunk)   # first chunk carries the container header
@@ -216,31 +239,26 @@ close code and reason. Event types this SDK version does not know arrive as
 
 ### Choosing the model: v1 and v2
 
-`client.stream()` opens `WS /v1/stream/analyze`, analyzed by the Inter-1
-model. Pass `api_version="v2"` to open `WS /v2/stream/analyze` and have the
-same session analyzed by the Inter-2 model:
-
-```python
-async with client.stream(api_version="v2") as session:
-    ...
-```
-
-Everything else is identical — the `session.ready` limits, session config, the
-video you send, the events you receive and their order, the same `Scope.STREAM`
-scope for the default model, and the graceful close — so the code above works
-unchanged, except that
-v2 signal events carry no `modality` (`event.data.modality` is `None`). One
-more thing differs: how the client names itself: errors raised for a v2 session say "Inter-2
-stream" where a v1 session says "Stream", so a message names the endpoint the
-session actually opened. If a deployment has no Inter-2 backend configured, a
-v2 session is refused right after the handshake with an `ErrorEvent`
-(`ih1003`) and close code 1013.
+`client.stream()` without `api_version` opens `WS /v1/stream/analyze`,
+analyzed by the Inter-1 model, so always pass `api_version="v2"` for Inter-2.
+Use V1 only to keep an existing integration running.
+
+Apart from the endpoint and the model, V1 and V2 sessions are identical: the
+`session.ready` limits, session config, the video you send, the events you
+receive and their order, the same `Scope.STREAM` scope for every model, and
+the graceful close. Code written for V1 therefore works on V2 unchanged,
+except that v2 signal events carry no `modality` (`event.data.modality` is
+`None`). Errors raised for a v2 session also say "Inter-2 stream" where a v1
+session says "Stream", so a message names the endpoint the session actually
+opened. If a deployment has no Inter-2 backend configured, a v2 session is
+refused right after the handshake with an `ErrorEvent` (`ih1003`) and close
+code 1013.
 
 ### Choosing the Inter-2 model
 
 On `api_version="v2"` the `model` argument names the model the session opens
-on. It defaults to `StreamModel.INTER_2`, which reads the video and which
-`Scope.STREAM` covers. `session.ready` lists the models the deployment serves
+on. It defaults to `StreamModel.INTER_2`, which reads the video;
+`Scope.STREAM` covers every model. `session.ready` lists the models the deployment serves
 that your credential may select under `supported_session_config_options.model`,
 and `session.updated` echoes the one in force.
 
@@ -251,6 +269,23 @@ async with client.stream(api_version="v2", model=StreamModel.INTER_2) as session
     await session.wait_for_session_ready()
 ```
 
+`StreamModel.INTER_2_AUDIO` hears the audio alone and reports a subset of the
+signals `StreamModel.INTER_2` reports (agreement, confidence, frustration,
+hesitation, interest, uncertainty). It takes the same WebM or fragmented-MP4
+clips through `send_video`, with or without a video track, so an audio-only
+recording works as-is. To send raw audio instead, declare the format once in
+the session config and then send samples with `send_audio`: signed 16-bit
+little-endian mono PCM at 16000 or 24000 Hz, cut at any byte boundary.
+
+```python
+from interhumanai import RawAudioFormat, StreamModel
+
+async with client.stream(api_version="v2", model=StreamModel.INTER_2_AUDIO) as session:
+    await session.wait_for_session_ready()
+    await session.update_config(audio_format=RawAudioFormat(sample_rate=16000))
+    await session.send_audio(pcm_frame)
+```
+
 ## Errors
 
 Three surfaces, mirroring the API:
@@ -294,17 +329,18 @@ want to inspect exactly what is sent.
 ## Environments
 
 ```python
-InterhumanClient(key_id=..., key_secret=...)                          # production (default): api.interhuman.ai
-InterhumanClient(key_id=..., key_secret=..., environment="staging")   # staging-api.interhuman.ai
-InterhumanClient(key_id=..., key_secret=..., base_url="http://localhost:8080")  # local override
+InterhumanClient(access_token=api_key)                                   # production (default): api.interhuman.ai
+InterhumanClient(access_token=api_key, environment="staging")            # staging-api.interhuman.ai
+InterhumanClient(access_token=api_key, base_url="http://localhost:8080") # local override
 ```
 
 WebSocket URLs are derived automatically (`https://` → `wss://`).
 
 ## Examples
 
-Runnable scripts for every flow live in [`examples/`](examples/): `auth.py`,
-`client_tokens.py`, `upload.py`, `upload_job.py`, and `stream.py`.
+Runnable scripts for every flow live in [`examples/`](examples/):
+`upload_job.py` (Inter-2 upload), `stream.py` (Inter-2 stream),
+`client_tokens.py`, and `upload.py` (V1 compatibility).
 
 ## Development
 

{interhumanai-1.3.0 → interhumanai-1.3.2}/README.md

@@ -23,31 +23,43 @@ inherently event-driven, so a single async API keeps every surface consistent
 
 ```python
 import asyncio
-from interhumanai import InterhumanClient
+import os
+
+from interhumanai import InterhumanClient, UploadJobIncludeFlag, UploadJobStatus, UploadModel
 
 async def main() -> None:
-    client = InterhumanClient(key_id="...", key_secret="...")
-    result = await client.upload.analyze("meeting.mp4")
-    for signal in result.signals:
-        print(signal.type.value, signal.start, signal.end)
+    client = InterhumanClient(access_token=os.environ["INTERHUMAN_API_KEY"])
+    job = await client.upload.submit(
+        "meeting.mp4", model=UploadModel.INTER_2, include=[UploadJobIncludeFlag.SIGNALS]
+    )
+    job = await client.upload.wait_for_job(job)
+    if job.status is UploadJobStatus.COMPLETED:
+        for signal in job.result.signals:
+            print(signal.type.value, signal.start, signal.end)
+    else:
+        print(job.error.error_id, job.error.message)
 
 asyncio.run(main())
 ```
 
+For a live feed, open `client.stream(api_version="v2")` (see [Stream API](#stream-api)).
+Pass `api_version` explicitly: the default is `"v1"`.
+
 ## Authentication
 
-Two ways to authenticate:
+Pass a credential as `access_token`; the client sends it as-is:
 
-- **API key credentials** (`key_id` + `key_secret`): the client authenticates
-  with them and renews its session automatically.
-- **A client token** (see below) or your API key, passed as `access_token` and
-  used as-is.
+- **Your API key**, on your server.
+- **A client token** (see below) on an untrusted client such as a browser,
+  which must never see the API key.
 
 ```python
-from interhumanai import InterhumanClient, Scope
+import os
 
-# Managed credentials (recommended for servers)
-client = InterhumanClient(key_id="...", key_secret="...", scopes=[Scope.UPLOAD, Scope.STREAM])
+from interhumanai import InterhumanClient
+
+# On your server
+client = InterhumanClient(access_token=os.environ["INTERHUMAN_API_KEY"])
 
 # A client token minted by your backend
 client = InterhumanClient(access_token=client_token)
@@ -60,13 +72,13 @@ custom credential source into the lower-level clients.
 Scopes name one endpoint family, on every API version that serves it:
 
 - `Scope.UPLOAD` (`interhumanai.upload`) — `POST /v1/upload/analyze`, and
-  `POST /v2/upload/analyze` with `model="inter-2"`; also reads the account's
-  jobs.
+  `POST /v2/upload/analyze` with every model it serves; also reads the
+  account's jobs.
 - `Scope.STREAM` (`interhumanai.stream`) — `WS /v1/stream/analyze`, and
-  `WS /v2/stream/analyze` with `model="inter-2"`.
+  `WS /v2/stream/analyze` with every model it serves.
 
-Holding one scope never implies another, so request every scope the client
-needs.
+A scope covers its endpoint on every API version and every model. Holding one
+scope never implies another, so request every scope the client needs.
 
 ## Client tokens (browser / untrusted clients)
 
@@ -90,32 +102,10 @@ await auth.revoke_client_token(api_key="ih_...", token=token.access_token)
 
 ## Upload API
 
-Analyze a complete video file (mp4, avi, mov, mkv, mpeg-ts, or webm; at least
-3 seconds, at most 32 MB):
-
-```python
-from interhumanai import GoalDimension, IncludeFlag
-
-result = await client.upload.analyze(
-    "meeting.mp4",                                        # path, bytes, or file object
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional sections
-    goal_dimensions=[GoalDimension.CLARITY],              # enables feedback
-)
-```
-
-The typed `AnalysisResult` carries `signals`, `engagement_state`, and — when
-requested — `feedback` and `conversation_quality`.
-
-Every v1 `Signal` carries a `modality` naming the analysis modalities that
-detected it. When several tracks detect the same signal, every contributing
-modality is included, e.g. `["audio", "visual"]`. The Inter-2 (v2) routes send
-no `modality`: the model you choose names the evidence.
-
-### Upload jobs with Inter-2 (`POST /v2/upload/analyze`)
-
-The v2 upload route analyzes a file with an Inter-2 model as an **asynchronous
-job**: the API validates the file, answers with a job envelope, and analyzes
-the file afterwards. Poll the job until it is `completed` or `failed`:
+`client.upload.submit()` sends a file to `POST /v2/upload/analyze`, which
+analyzes it with an Inter-2 model as an **asynchronous job**: the API validates
+the file, answers with a job envelope, and analyzes the file afterwards. Poll
+the job until it is `completed` or `failed`:
 
 ```python
 from interhumanai import UploadJobIncludeFlag, UploadModel
@@ -164,17 +154,50 @@ else:
   `UploadJobWindow` per fixed-length window, each with its span, an
   `engagement_status` and the `signals` read over it. Each signal is an
   `UploadJobSignal`: the v1 `Signal` without `modality`.
+- `UploadModel.INTER_2_AUDIO` reads the audio alone: a wav, flac, mp3, m4a or
+  ogg file, or a webm or mp4 carrying an audio track, under the same limits.
+  It reports the same result shape, with a subset of the signals
+  `UploadModel.INTER_2` reports: agreement, confidence, frustration,
+  hesitation, interest and uncertainty. The same `Scope.UPLOAD` covers it.
+
+### Inter-1 upload (V1, compatibility)
+
+`client.upload.analyze()` calls `POST /v1/upload/analyze`, which analyzes the
+file with Inter-1 and answers synchronously. Use it only to keep an existing
+V1 integration running; see
+[Migrate from V1 to V2](https://docs.interhuman.ai/api-reference/migrate-v1-to-v2).
+It takes a complete video file (mp4, avi, mov, mkv, mpeg-ts, or webm; at least
+3 seconds, at most 32 MB):
+
+```python
+from interhumanai import GoalDimension, IncludeFlag
+
+result = await client.upload.analyze(
+    "meeting.mp4",                                        # path, bytes, or file object
+    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional sections
+    goal_dimensions=[GoalDimension.CLARITY],              # enables feedback
+)
+```
+
+The typed `AnalysisResult` carries `signals`, `engagement_state`, and — when
+requested — `feedback` and `conversation_quality`.
+
+Every v1 `Signal` carries a `modality` naming the analysis modalities that
+detected it. When several tracks detect the same signal, every contributing
+modality is included, e.g. `["audio", "visual"]`. The Inter-2 (v2) routes send
+no `modality`: the model you choose names the evidence.
 
 ## Stream API
 
-One `StreamClient` handles one live session against `WS /v1/stream/analyze`.
-Send binary WebM or fragmented-MP4 chunks and consume typed events with
-`async for`:
+One `StreamClient` handles one live session. Pass `api_version="v2"` to open
+`WS /v2/stream/analyze`, analyzed by Inter-2. Send binary WebM or
+fragmented-MP4 chunks as your recorder produces them, and consume typed events
+with `async for`:
 
 ```python
 from interhumanai import IncludeFlag, SignalDetectedEvent
 
-async with client.stream() as session:
+async with client.stream(api_version="v2") as session:
     await session.wait_for_session_ready()
     await session.update_config(include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL])
     await session.send_video(first_chunk)   # first chunk carries the container header
@@ -190,31 +213,26 @@ close code and reason. Event types this SDK version does not know arrive as
 
 ### Choosing the model: v1 and v2
 
-`client.stream()` opens `WS /v1/stream/analyze`, analyzed by the Inter-1
-model. Pass `api_version="v2"` to open `WS /v2/stream/analyze` and have the
-same session analyzed by the Inter-2 model:
-
-```python
-async with client.stream(api_version="v2") as session:
-    ...
-```
-
-Everything else is identical — the `session.ready` limits, session config, the
-video you send, the events you receive and their order, the same `Scope.STREAM`
-scope for the default model, and the graceful close — so the code above works
-unchanged, except that
-v2 signal events carry no `modality` (`event.data.modality` is `None`). One
-more thing differs: how the client names itself: errors raised for a v2 session say "Inter-2
-stream" where a v1 session says "Stream", so a message names the endpoint the
-session actually opened. If a deployment has no Inter-2 backend configured, a
-v2 session is refused right after the handshake with an `ErrorEvent`
-(`ih1003`) and close code 1013.
+`client.stream()` without `api_version` opens `WS /v1/stream/analyze`,
+analyzed by the Inter-1 model, so always pass `api_version="v2"` for Inter-2.
+Use V1 only to keep an existing integration running.
+
+Apart from the endpoint and the model, V1 and V2 sessions are identical: the
+`session.ready` limits, session config, the video you send, the events you
+receive and their order, the same `Scope.STREAM` scope for every model, and
+the graceful close. Code written for V1 therefore works on V2 unchanged,
+except that v2 signal events carry no `modality` (`event.data.modality` is
+`None`). Errors raised for a v2 session also say "Inter-2 stream" where a v1
+session says "Stream", so a message names the endpoint the session actually
+opened. If a deployment has no Inter-2 backend configured, a v2 session is
+refused right after the handshake with an `ErrorEvent` (`ih1003`) and close
+code 1013.
 
 ### Choosing the Inter-2 model
 
 On `api_version="v2"` the `model` argument names the model the session opens
-on. It defaults to `StreamModel.INTER_2`, which reads the video and which
-`Scope.STREAM` covers. `session.ready` lists the models the deployment serves
+on. It defaults to `StreamModel.INTER_2`, which reads the video;
+`Scope.STREAM` covers every model. `session.ready` lists the models the deployment serves
 that your credential may select under `supported_session_config_options.model`,
 and `session.updated` echoes the one in force.
 
@@ -225,6 +243,23 @@ async with client.stream(api_version="v2", model=StreamModel.INTER_2) as session
     await session.wait_for_session_ready()
 ```
 
+`StreamModel.INTER_2_AUDIO` hears the audio alone and reports a subset of the
+signals `StreamModel.INTER_2` reports (agreement, confidence, frustration,
+hesitation, interest, uncertainty). It takes the same WebM or fragmented-MP4
+clips through `send_video`, with or without a video track, so an audio-only
+recording works as-is. To send raw audio instead, declare the format once in
+the session config and then send samples with `send_audio`: signed 16-bit
+little-endian mono PCM at 16000 or 24000 Hz, cut at any byte boundary.
+
+```python
+from interhumanai import RawAudioFormat, StreamModel
+
+async with client.stream(api_version="v2", model=StreamModel.INTER_2_AUDIO) as session:
+    await session.wait_for_session_ready()
+    await session.update_config(audio_format=RawAudioFormat(sample_rate=16000))
+    await session.send_audio(pcm_frame)
+```
+
 ## Errors
 
 Three surfaces, mirroring the API:
@@ -268,17 +303,18 @@ want to inspect exactly what is sent.
 ## Environments
 
 ```python
-InterhumanClient(key_id=..., key_secret=...)                          # production (default): api.interhuman.ai
-InterhumanClient(key_id=..., key_secret=..., environment="staging")   # staging-api.interhuman.ai
-InterhumanClient(key_id=..., key_secret=..., base_url="http://localhost:8080")  # local override
+InterhumanClient(access_token=api_key)                                   # production (default): api.interhuman.ai
+InterhumanClient(access_token=api_key, environment="staging")            # staging-api.interhuman.ai
+InterhumanClient(access_token=api_key, base_url="http://localhost:8080") # local override
 ```
 
 WebSocket URLs are derived automatically (`https://` → `wss://`).
 
 ## Examples
 
-Runnable scripts for every flow live in [`examples/`](examples/): `auth.py`,
-`client_tokens.py`, `upload.py`, `upload_job.py`, and `stream.py`.
+Runnable scripts for every flow live in [`examples/`](examples/):
+`upload_job.py` (Inter-2 upload), `stream.py` (Inter-2 stream),
+`client_tokens.py`, and `upload.py` (V1 compatibility).
 
 ## Development
 

{interhumanai-1.3.0 → interhumanai-1.3.2}/src/interhumanai/__init__.py

@@ -3,15 +3,27 @@
 Quickstart::
 
     import asyncio
-    from interhumanai import InterhumanClient
+    import os
+
+    from interhumanai import InterhumanClient, UploadJobIncludeFlag, UploadJobStatus, UploadModel
 
     async def main() -> None:
-        client = InterhumanClient(key_id="...", key_secret="...")
-        result = await client.upload.analyze("meeting.mp4")
-        for signal in result.signals:
-            print(signal.type.value, signal.start, signal.end)
+        client = InterhumanClient(access_token=os.environ["INTERHUMAN_API_KEY"])
+        job = await client.upload.submit(
+            "meeting.mp4", model=UploadModel.INTER_2, include=[UploadJobIncludeFlag.SIGNALS]
+        )
+        job = await client.upload.wait_for_job(job)
+        if job.status is UploadJobStatus.COMPLETED:
+            for signal in job.result.signals:
+                print(signal.type.value, signal.start, signal.end)
+        else:
+            print(job.error.error_id, job.error.message)
 
     asyncio.run(main())
+
+For a live feed, ``client.stream(api_version="v2")`` opens
+``WS /v2/stream/analyze``. Pass ``api_version`` explicitly: the default is
+``"v1"``.
 """
 
 from ._sdk_metadata import SDK_HEADER_NAME, SDK_NAME, sdk_header_value

{interhumanai-1.3.0 → interhumanai-1.3.2}/src/interhumanai/_version.py

@@ -1,3 +1,3 @@
 """Package version (single source of truth, read by hatchling at build time)."""
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"

{interhumanai-1.3.0 → interhumanai-1.3.2}/src/interhumanai/client.py

@@ -23,10 +23,10 @@ from .upload import UploadClient
 class InterhumanClient:
     """High-level client for the Interhuman API.
 
-    Authenticate either with API key credentials (``key_id`` + ``key_secret``,
-    exchanged for short-lived bearer tokens that are refreshed automatically)
-    or with a pre-issued ``access_token`` used as-is. Exactly one of the two
-    must be provided.
+    Authenticate with ``access_token``: your API key, or a client token your
+    server minted, used as-is. Alternatively pass API key credentials
+    (``key_id`` + ``key_secret``), exchanged for short-lived bearer tokens that
+    are refreshed automatically. Exactly one of the two must be provided.
 
     The client exposes every public surface: :attr:`auth` for token endpoints,
     :attr:`upload` for complete files, and :meth:`stream` for live WebSocket
@@ -35,7 +35,7 @@ class InterhumanClient:
     Args:
         key_id: API key id (paired with ``key_secret``).
         key_secret: API key secret.
-        access_token: A client token, or your API key, used as-is.
+        access_token: Your API key, or a client token, used as-is.
         scopes: Scopes requested when exchanging credentials. Defaults to
             upload + stream. Ignored when ``access_token`` is used.
         environment: Named environment to call. Defaults to ``production``.

{interhumanai-1.3.0 → interhumanai-1.3.2}/src/interhumanai/stream.py

@@ -18,7 +18,6 @@ from .types import (
     IncludeFlag,
     Probability,
     RawAudioFormat,
-    Scope,
     SignalType,
     StreamModel,
 )
@@ -403,7 +402,7 @@ class StreamClient(SessionSocketClient[StreamEvent]):
 
     ``api_version`` selects the endpoint: ``"v1"`` (the default) is analyzed by
     the Inter-1 model; ``"v2"`` is analyzed by an Inter-2 model. Both require
-    the ``interhumanai.stream`` scope for the default model. The session
+    the ``interhumanai.stream`` scope, which covers every model. The session
     protocol and the events are identical on both, and each names the endpoint
     it actually opened in the errors it raises: a v2 session reports the
     Inter-2 stream, a v1 session the Stream.
@@ -462,14 +461,9 @@ class StreamClient(SessionSocketClient[StreamEvent]):
         self._model = model_value
         if model_value is not None:
             self._handshake_query["model"] = model_value
-        # The audio model is authorized by its own scope, so the hint names it.
-        if api_version == "v2" and model_value == StreamModel.INTER_2_AUDIO.value:
-            self._scope_hint = (
-                "The credentials may be invalid or lack the "
-                f"{Scope.STREAM_INTER_2_AUDIO.value} scope."
-            )
-        else:
-            self._scope_hint = "The credentials may be invalid or lack the stream scope."
+        # One stream scope covers both endpoints and every model, so the hint
+        # never names a model.
+        self._scope_hint = "The credentials may be invalid or lack the stream scope."
 
     @property
     def api_version(self) -> StreamApiVersion:
@@ -512,9 +506,14 @@ class StreamClient(SessionSocketClient[StreamEvent]):
             goal_dimensions: Goal dimensions that enable feedback generation.
             model: The Inter-2 model to analyze the session with, on
                 ``api_version="v2"`` only. ``StreamModel.INTER_2`` (the
-                default) reads the video.
-            audio_format: Session state like ``model``. Not used by
-                ``StreamModel.INTER_2`` sessions; leave it unset.
+                default) reads the video; ``StreamModel.INTER_2_AUDIO`` hears
+                the audio alone.
+            audio_format: Declares that the session's binary frames are raw
+                PCM audio rather than container media, on
+                ``StreamModel.INTER_2_AUDIO`` sessions only. Session state
+                like ``model``: omitted keeps the format in force, and it is
+                fixed once the first audio frame has been accepted. Leave it
+                unset to send WebM or MP4 clips.
         """
         config: dict[str, Any] = {}
         if include is not None:
@@ -534,9 +533,10 @@ class StreamClient(SessionSocketClient[StreamEvent]):
     async def send_audio(self, frame: bytes | bytearray | memoryview) -> None:
         """Send one frame of raw PCM audio.
 
-        Only meaningful on ``api_version="v2"`` after :meth:`update_config`
-        declared an ``audio_format`` on a model that accepts raw audio; the
-        server then reads every binary frame as signed 16-bit mono PCM at the
+        Only meaningful on ``api_version="v2"`` with
+        ``model=StreamModel.INTER_2_AUDIO``, after :meth:`update_config`
+        declared an ``audio_format``; the server then reads every binary frame
+        as signed 16-bit mono PCM at the
         declared sample rate. Frames can be any size and cut at any byte
         boundary. Without that declaration a binary frame is container media,
         which :meth:`send_video` names.

{interhumanai-1.3.0 → interhumanai-1.3.2}/src/interhumanai/types.py

@@ -12,20 +12,23 @@ class Scope(str, enum.Enum):
 
     A scope names one endpoint family across every API version. ``UPLOAD``
     covers ``POST /v1/upload/analyze`` and ``POST /v2/upload/analyze`` with
-    ``model="inter-2"``, and reads the account's jobs at
+    every model it serves, and reads the account's jobs at
     ``GET /v2/upload/jobs/{job_id}``; ``STREAM`` covers ``WS /v1/stream/analyze``
-    and ``WS /v2/stream/analyze`` with ``model="inter-2"``. No scope implies
+    and ``WS /v2/stream/analyze`` with every model it serves. No scope implies
     another. The token response's ``scope`` is authoritative.
     """
 
     UPLOAD = "interhumanai.upload"
     STREAM = "interhumanai.stream"
     REALTIME = "interhumanai.realtime"
-    UPLOAD_INTER_2_AUDIO = "interhumanai.upload.inter-2-audio"
     UPLOAD_INTER_2_DEEP = "interhumanai.upload.inter-2-deep"
-    STREAM_INTER_2_AUDIO = "interhumanai.stream.inter-2-audio"
+    # Legacy names of UPLOAD and STREAM, accepted during the cooling-off
+    # period and issued as the endpoint scope. The two audio members were
+    # program scopes before the audio model moved under the endpoint scopes.
     UPLOAD_INTER_2 = "interhumanai.upload.inter-2"
+    UPLOAD_INTER_2_AUDIO = "interhumanai.upload.inter-2-audio"
     STREAM_INTER_2 = "interhumanai.stream.inter-2"
+    STREAM_INTER_2_AUDIO = "interhumanai.stream.inter-2-audio"
 
 
 class SignalType(str, enum.Enum):
@@ -185,8 +188,13 @@ class AnalysisResult(BaseModel):
 class StreamModel(str, enum.Enum):
     """Inter-2 models a ``WS /v2/stream/analyze`` session can select.
 
-    ``INTER_2`` (the default) reads the video. ``WS /v1/stream/analyze``
-    offers no selection and rejects any value.
+    ``INTER_2`` (the default) reads the video. ``INTER_2_AUDIO`` hears the
+    audio alone: it accepts the same WebM and fragmented MP4 clips, with or
+    without a video track, and raw PCM frames once the session config declares
+    an :class:`RawAudioFormat`, and reports a subset of the signals
+    ``INTER_2`` reports (agreement, confidence, frustration, hesitation,
+    interest, uncertainty). ``WS /v1/stream/analyze`` offers no selection and
+    rejects any value.
     """
 
     INTER_2 = "inter-2"
@@ -202,7 +210,8 @@ class RawAudioFormat(BaseModel):
     """Declares that a session's binary frames are raw audio, not container media.
 
     Signed 16-bit little-endian PCM at ``sample_rate``, mono, with no header;
-    frames may be cut at any byte boundary.
+    frames may be cut at any byte boundary. Accepted on
+    ``StreamModel.INTER_2_AUDIO`` sessions only.
 
     Attributes:
         encoding: Always ``pcm_s16le``.
@@ -218,7 +227,12 @@ class RawAudioFormat(BaseModel):
 class UploadModel(str, enum.Enum):
     """Inter-2 models a ``POST /v2/upload/analyze`` job can name.
 
-    ``INTER_2`` reads a video (picture and sound together).
+    ``INTER_2`` reads a video (picture and sound together): an mp4, mov, avi,
+    mkv, webm or mpeg-ts file carrying both a video and an audio track.
+    ``INTER_2_AUDIO`` reads the audio alone: a wav, flac, mp3, m4a or ogg
+    file, or a webm or mp4 carrying an audio track. It reports a subset of the
+    signals ``INTER_2`` reports (agreement, confidence, frustration,
+    hesitation, interest, uncertainty).
     """
 
     INTER_2 = "inter-2"