interhumanai 1.2.3__tar.gz → 1.3.2__tar.gz

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

@@ -5,6 +5,37 @@ 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=...)``
+  now takes ``UploadJobIncludeFlag``: the two ``IncludeFlag`` Conversation
+  Quality Index values plus ``SIGNALS`` (``IncludeFlag`` members still work).
+  With ``SIGNALS``, a completed job's ``UploadJobResult.signals`` carries every
+  window's signals as one chronological list, same-type signals in adjacent
+  windows merged into one span that keeps the highest probability and its
+  rationale, with no ``modality``. ``None`` without the flag; an empty list
+  when requested and nothing was detected. The ``windows`` are unchanged.
+
 ## 1.2.3
 
 - Revised the reference documentation for authentication. Documentation only;

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: interhumanai
-Version: 1.2.3
+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,40 +128,19 @@ 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 IncludeFlag, UploadModel
+from interhumanai import UploadJobIncludeFlag, UploadModel
 
 job = await client.upload.submit(
     "meeting.mp4",
     model=UploadModel.INTER_2,
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional quality scores
+    # optional whole-file views: quality scores and the merged signal list
+    include=[UploadJobIncludeFlag.CONVERSATION_QUALITY_OVERALL, UploadJobIncludeFlag.SIGNALS],
 )
 print(job.job_id, job.status.value)          # queued
 
@@ -158,6 +149,8 @@ if job.status.value == "completed":
     for window in job.result.windows:
         names = ", ".join(signal.type.value for signal in window.signals)
         print(f"{window.start_seconds:5.1f}s {window.engagement_status.value:11} {names}")
+    for signal in job.result.signals:
+        print(signal.type.value, signal.start, signal.end)
     print(job.result.conversation_quality.overall.quality_index)
 else:
     print(job.error.error_id, job.error.message)
@@ -166,11 +159,15 @@ else:
 - `submit(file, model=..., wait_seconds=0, include=None)` — pass `wait_seconds`
   to let the API hold the request open for up to that long and return the
   finished job inline when it completes in time; otherwise it returns the
-  queued envelope. Pass `include` with the same `IncludeFlag` values `analyze`
-  takes to have the result carry `conversation_quality`, an
-  `UploadJobConversationQuality` scored over the whole file with `overall`
-  and/or `timeline` set for the flags you named; without it the result has no
-  quality block.
+  queued envelope. Pass `include` with `UploadJobIncludeFlag` values to have
+  the result carry whole-file views. The two Conversation Quality Index values
+  (the same ones `analyze` takes as `IncludeFlag`, whose members also work
+  here) add `conversation_quality`, an `UploadJobConversationQuality` scored
+  over the whole file with `overall` and/or `timeline` set for the flags you
+  named. `SIGNALS` adds `signals`: every window's signals as one chronological
+  list, same-type signals in adjacent windows merged into one span with the
+  highest probability and its rationale, and no `modality` (an empty list when
+  nothing was detected). Without a flag the result has no such section.
 - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
   `error_id` `ih4021` once the job has expired (`job.expires_at`).
 - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -183,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
@@ -209,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.
 
@@ -244,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:
@@ -287,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.2.3 → 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,40 +102,19 @@ 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 IncludeFlag, UploadModel
+from interhumanai import UploadJobIncludeFlag, UploadModel
 
 job = await client.upload.submit(
     "meeting.mp4",
     model=UploadModel.INTER_2,
-    include=[IncludeFlag.CONVERSATION_QUALITY_OVERALL],   # optional quality scores
+    # optional whole-file views: quality scores and the merged signal list
+    include=[UploadJobIncludeFlag.CONVERSATION_QUALITY_OVERALL, UploadJobIncludeFlag.SIGNALS],
 )
 print(job.job_id, job.status.value)          # queued
 
@@ -132,6 +123,8 @@ if job.status.value == "completed":
     for window in job.result.windows:
         names = ", ".join(signal.type.value for signal in window.signals)
         print(f"{window.start_seconds:5.1f}s {window.engagement_status.value:11} {names}")
+    for signal in job.result.signals:
+        print(signal.type.value, signal.start, signal.end)
     print(job.result.conversation_quality.overall.quality_index)
 else:
     print(job.error.error_id, job.error.message)
@@ -140,11 +133,15 @@ else:
 - `submit(file, model=..., wait_seconds=0, include=None)` — pass `wait_seconds`
   to let the API hold the request open for up to that long and return the
   finished job inline when it completes in time; otherwise it returns the
-  queued envelope. Pass `include` with the same `IncludeFlag` values `analyze`
-  takes to have the result carry `conversation_quality`, an
-  `UploadJobConversationQuality` scored over the whole file with `overall`
-  and/or `timeline` set for the flags you named; without it the result has no
-  quality block.
+  queued envelope. Pass `include` with `UploadJobIncludeFlag` values to have
+  the result carry whole-file views. The two Conversation Quality Index values
+  (the same ones `analyze` takes as `IncludeFlag`, whose members also work
+  here) add `conversation_quality`, an `UploadJobConversationQuality` scored
+  over the whole file with `overall` and/or `timeline` set for the flags you
+  named. `SIGNALS` adds `signals`: every window's signals as one chronological
+  list, same-type signals in adjacent windows merged into one span with the
+  highest probability and its rationale, and no `modality` (an empty list when
+  nothing was detected). Without a flag the result has no such section.
 - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
   `error_id` `ih4021` once the job has expired (`job.expires_at`).
 - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -157,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
@@ -183,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.
 
@@ -218,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:
@@ -261,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.2.3 → 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
@@ -113,6 +125,7 @@ from .types import (
     UploadJob,
     UploadJobConversationQuality,
     UploadJobError,
+    UploadJobIncludeFlag,
     UploadJobResult,
     UploadJobSignal,
     UploadJobStatus,
@@ -214,6 +227,7 @@ __all__ = [
     "UploadJob",
     "UploadJobConversationQuality",
     "UploadJobError",
+    "UploadJobIncludeFlag",
     "UploadJobResult",
     "UploadJobSignal",
     "UploadJobStatus",

{interhumanai-1.2.3 → 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.2.3"
+__version__ = "1.3.2"

{interhumanai-1.2.3 → 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.2.3 → 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.2.3 → 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"
@@ -226,6 +240,20 @@ class UploadModel(str, enum.Enum):
     INTER_2_DEEP = "inter-2-deep"
 
 
+class UploadJobIncludeFlag(str, enum.Enum):
+    """Whole-file sections a ``POST /v2/upload/analyze`` job's result can carry.
+
+    The two :class:`IncludeFlag` Conversation Quality Index sections, plus
+    ``SIGNALS`` for the whole-file signal list
+    (:attr:`UploadJobResult.signals`). ``SIGNALS`` is a v2 upload option only;
+    :meth:`~interhumanai.UploadClient.analyze` and the stream do not take it.
+    """
+
+    CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
+    CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
+    SIGNALS = "signals"
+
+
 class UploadJobStatus(str, enum.Enum):
     """Lifecycle of a ``POST /v2/upload/analyze`` job.
 
@@ -285,13 +313,22 @@ class UploadJobConversationQuality(BaseModel):
 class UploadJobResult(BaseModel):
     """The result of a completed upload job: one entry per analyzed window.
 
+    ``signals`` is every window's signals as one list over the whole file, in
+    chronological order, merged by the same rules as
+    :meth:`~interhumanai.UploadClient.analyze` and with no ``modality``:
+    signals of the same type in adjacent windows become one span, which keeps
+    the highest probability and that signal's rationale. It is set only when the submit
+    passed :attr:`UploadJobIncludeFlag.SIGNALS`, and is then an empty list when
+    nothing was detected; ``windows`` are unchanged either way.
+
     ``conversation_quality`` is present only when the submit passed at least one
-    :class:`IncludeFlag`, and carries the sections those flags named.
+    Conversation Quality Index flag, and carries the sections those flags named.
     """
 
     duration_seconds: float
     window_seconds: float
     windows: list[UploadJobWindow] = Field(default_factory=list)
+    signals: list[UploadJobSignal] | None = None
     conversation_quality: UploadJobConversationQuality | None = None
 
 

{interhumanai-1.2.3 → interhumanai-1.3.2}/src/interhumanai/upload.py

@@ -13,7 +13,14 @@ from ._http import request_json
 from .auth import TokenProvider
 from .config import Environment, resolve_http_base_url
 from .errors import UploadJobTimeoutError
-from .types import AnalysisResult, GoalDimension, IncludeFlag, UploadJob, UploadModel
+from .types import (
+    AnalysisResult,
+    GoalDimension,
+    IncludeFlag,
+    UploadJob,
+    UploadJobIncludeFlag,
+    UploadModel,
+)
 
 DEFAULT_JOB_POLL_INTERVAL_SECONDS = 2.0
 """How often :meth:`UploadClient.wait_for_job` reads the job status by default."""
@@ -119,7 +126,7 @@ class UploadClient:
         *,
         model: UploadModel | str,
         wait_seconds: int = 0,
-        include: Sequence[IncludeFlag | str] | None = None,
+        include: Sequence[UploadJobIncludeFlag | IncludeFlag | str] | None = None,
         filename: str | None = None,
         content_type: str | None = None,
     ) -> UploadJob:
@@ -132,10 +139,11 @@ class UploadClient:
         it comes back ``queued`` or ``running`` and :meth:`wait_for_job` or
         :meth:`get_job` reads it later.
 
-        Pass ``include`` to have the completed job's result carry the
-        Conversation Quality Index over the whole file, in the sections the
-        flags name (:attr:`UploadJobResult.conversation_quality`). Without it
-        the result carries no such block.
+        Pass ``include`` to have the completed job's result carry whole-file
+        views: the Conversation Quality Index in the sections the CQI flags
+        name (:attr:`UploadJobResult.conversation_quality`), and the merged
+        signal list for ``SIGNALS`` (:attr:`UploadJobResult.signals`). Without
+        a flag the result carries no such section.
 
         For ``UploadModel.INTER_2`` the file is an mp4, mov, avi, mkv, webm or
         mpeg-ts video carrying both a video and an audio track (``ih5001``
@@ -151,10 +159,13 @@ class UploadClient:
             wait_seconds: How long the API may hold the request waiting for
                 the job to finish. ``0`` (the default) answers at once. The
                 deployment bounds it; a larger value raises ``ih4005``.
-            include: Conversation Quality Index sections the result should
-                carry: ``IncludeFlag.CONVERSATION_QUALITY_OVERALL`` and/or
-                ``IncludeFlag.CONVERSATION_QUALITY_TIMELINE``, the same flags
-                :meth:`analyze` takes. Omit it for no quality block.
+            include: Whole-file sections the result should carry, as
+                :class:`UploadJobIncludeFlag` values:
+                ``CONVERSATION_QUALITY_OVERALL`` and/or
+                ``CONVERSATION_QUALITY_TIMELINE`` (the same values
+                :meth:`analyze` takes, so :class:`IncludeFlag` members work
+                too) for the quality block, and ``SIGNALS`` for the signal
+                list. Omit a flag for no such section.
             filename: Filename reported to the API. Defaults to the path or
                 file object's name, else ``video``.
             content_type: MIME type of the file (e.g. ``video/mp4``).
@@ -172,7 +183,8 @@ class UploadClient:
             data["wait_seconds"] = str(wait_seconds)
         if include:
             data["include[]"] = [
-                flag.value if isinstance(flag, IncludeFlag) else flag for flag in include
+                flag.value if isinstance(flag, (IncludeFlag, UploadJobIncludeFlag)) else flag
+                for flag in include
             ]
         headers = {"Authorization": f"Bearer {token}"}
         url = self._base_url + "/v2/upload/analyze"