interhumanai 1.3.4__tar.gz → 2.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,34 @@ All notable changes to `interhumanai` are documented here. The package follows
5
5
  the TypeScript SDK (`@interhumanai/sdk`): both packages always carry the same
6
6
  version and release together.
7
7
 
8
+ ## 2.0.0
9
+
10
+ - **Breaking:** removed the four legacy per-model scopes from ``Scope``:
11
+ ``Scope.UPLOAD_INTER_2`` (``interhumanai.upload.inter-2``),
12
+ ``Scope.UPLOAD_INTER_2_AUDIO`` (``interhumanai.upload.inter-2-audio``),
13
+ ``Scope.STREAM_INTER_2`` (``interhumanai.stream.inter-2``) and
14
+ ``Scope.STREAM_INTER_2_AUDIO`` (``interhumanai.stream.inter-2-audio``). They
15
+ were aliases of the endpoint scopes, and the API no longer accepts them: a
16
+ request that still names one of those strings is refused as an unknown
17
+ scope. ``Scope.UPLOAD`` and ``Scope.STREAM`` are the grants for the
18
+ ``inter-2`` and ``inter-2-audio`` models on their routes.
19
+ ``Scope.UPLOAD_INTER_2_DEEP`` is unchanged.
20
+
21
+ ## 1.4.0
22
+
23
+ - Added the Inter-2 Deep upload model. ``UploadModel.INTER_2_DEEP`` and
24
+ ``Scope.UPLOAD_INTER_2_DEEP`` are now part of the generated reference: the
25
+ model reads the same video files as ``UploadModel.INTER_2`` and needs its own
26
+ scope, which ``Scope.UPLOAD`` does not cover.
27
+ - Added ``UploadJobReasoning`` and ``UploadJobWindow.reasoning``: each window
28
+ of an ``inter-2-deep`` job carries the model's reasoning, whenever the model
29
+ wrote it, in five sections (``perceptual_cues``, ``mental_state_hypothesis``,
30
+ ``cognitive_execution``, ``relational_stance``, ``synthesis``) and in full as
31
+ ``trace``. The field is ``None`` on the other models' windows and on a Deep
32
+ window whose reply carried no reasoning.
33
+ - The ``upload_job.py`` example takes an optional model argument and prints
34
+ each Deep window's reasoning.
35
+
8
36
  ## 1.3.4
9
37
 
10
38
  - The package's Repository and Changelog URLs point at
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: interhumanai
3
- Version: 1.3.4
3
+ Version: 2.0.0
4
4
  Summary: First-party Python SDK for the Interhuman API: upload and stream social-signal analysis.
5
5
  Project-URL: Homepage, https://docs.interhuman.ai
6
6
  Project-URL: Repository, https://github.com/interhuman-core/interhuman-api
@@ -185,6 +185,24 @@ else:
185
185
  It reports the same result shape, with a subset of the signals
186
186
  `UploadModel.INTER_2` reports: agreement, confidence, frustration,
187
187
  hesitation, interest and uncertainty. The same `Scope.UPLOAD` covers it.
188
+ - `UploadModel.INTER_2_DEEP` reads the same video files as
189
+ `UploadModel.INTER_2`, at most two minutes long by default, and reasons
190
+ before it answers: each window carries `reasoning` whenever the model wrote
191
+ it, an
192
+ `UploadJobReasoning` with the model's reasoning in five sections
193
+ (`perceptual_cues`, `mental_state_hypothesis`, `cognitive_execution`,
194
+ `relational_stance`, `synthesis`) and in full as `trace`. The sections are
195
+ `None` when the reasoning could not be split into them; `trace` is always
196
+ set. It needs `Scope.UPLOAD_INTER_2_DEEP`, which `Scope.UPLOAD` does not
197
+ cover, and is served on upload jobs only. A window can take a minute or
198
+ more, so submit without `wait_seconds` and use `wait_for_job`:
199
+
200
+ ```python
201
+ job = await client.upload.submit("pitch.mp4", model=UploadModel.INTER_2_DEEP)
202
+ job = await client.upload.wait_for_job(job, timeout=3600)
203
+ for window in job.result.windows:
204
+ print(window.start_seconds, window.reasoning.synthesis or window.reasoning.trace)
205
+ ```
188
206
 
189
207
  ### Inter-1 upload (V1, compatibility)
190
208
 
@@ -159,6 +159,24 @@ else:
159
159
  It reports the same result shape, with a subset of the signals
160
160
  `UploadModel.INTER_2` reports: agreement, confidence, frustration,
161
161
  hesitation, interest and uncertainty. The same `Scope.UPLOAD` covers it.
162
+ - `UploadModel.INTER_2_DEEP` reads the same video files as
163
+ `UploadModel.INTER_2`, at most two minutes long by default, and reasons
164
+ before it answers: each window carries `reasoning` whenever the model wrote
165
+ it, an
166
+ `UploadJobReasoning` with the model's reasoning in five sections
167
+ (`perceptual_cues`, `mental_state_hypothesis`, `cognitive_execution`,
168
+ `relational_stance`, `synthesis`) and in full as `trace`. The sections are
169
+ `None` when the reasoning could not be split into them; `trace` is always
170
+ set. It needs `Scope.UPLOAD_INTER_2_DEEP`, which `Scope.UPLOAD` does not
171
+ cover, and is served on upload jobs only. A window can take a minute or
172
+ more, so submit without `wait_seconds` and use `wait_for_job`:
173
+
174
+ ```python
175
+ job = await client.upload.submit("pitch.mp4", model=UploadModel.INTER_2_DEEP)
176
+ job = await client.upload.wait_for_job(job, timeout=3600)
177
+ for window in job.result.windows:
178
+ print(window.start_seconds, window.reasoning.synthesis or window.reasoning.trace)
179
+ ```
162
180
 
163
181
  ### Inter-1 upload (V1, compatibility)
164
182
 
@@ -126,6 +126,7 @@ from .types import (
126
126
  UploadJobConversationQuality,
127
127
  UploadJobError,
128
128
  UploadJobIncludeFlag,
129
+ UploadJobReasoning,
129
130
  UploadJobResult,
130
131
  UploadJobSignal,
131
132
  UploadJobStatus,
@@ -228,6 +229,7 @@ __all__ = [
228
229
  "UploadJobConversationQuality",
229
230
  "UploadJobError",
230
231
  "UploadJobIncludeFlag",
232
+ "UploadJobReasoning",
231
233
  "UploadJobResult",
232
234
  "UploadJobSignal",
233
235
  "UploadJobStatus",
@@ -1,3 +1,3 @@
1
1
  """Package version (single source of truth, read by hatchling at build time)."""
2
2
 
3
- __version__ = "1.3.4"
3
+ __version__ = "2.0.0"
@@ -12,23 +12,21 @@ class Scope(str, enum.Enum):
12
12
 
13
13
  A scope names one endpoint family across every API version. ``UPLOAD``
14
14
  covers ``POST /v1/upload/analyze`` and ``POST /v2/upload/analyze`` with
15
- every model it serves, and reads the account's jobs at
16
- ``GET /v2/upload/jobs/{job_id}``; ``STREAM`` covers ``WS /v1/stream/analyze``
17
- and ``WS /v2/stream/analyze`` with every model it serves. No scope implies
18
- another. The token response's ``scope`` is authoritative.
15
+ every model it serves except ``inter-2-deep``, and reads the account's
16
+ jobs at ``GET /v2/upload/jobs/{job_id}``; ``STREAM`` covers
17
+ ``WS /v1/stream/analyze`` and ``WS /v2/stream/analyze`` with every model it
18
+ serves. ``UPLOAD_INTER_2_DEEP`` covers ``POST /v2/upload/analyze`` with
19
+ ``UploadModel.INTER_2_DEEP``, which no other scope grants, and also reads
20
+ the account's jobs; it is enabled per account. No scope implies another,
21
+ and these are the only scope names the API accepts: a request naming any
22
+ other string, the former per-model names included, is refused as an
23
+ unknown scope. The token response's ``scope`` is authoritative.
19
24
  """
20
25
 
21
26
  UPLOAD = "interhumanai.upload"
22
27
  STREAM = "interhumanai.stream"
23
28
  REALTIME = "interhumanai.realtime"
24
29
  UPLOAD_INTER_2_DEEP = "interhumanai.upload.inter-2-deep"
25
- # Legacy names of UPLOAD and STREAM, accepted during the cooling-off
26
- # period and issued as the endpoint scope. The two audio members were
27
- # program scopes before the audio model moved under the endpoint scopes.
28
- UPLOAD_INTER_2 = "interhumanai.upload.inter-2"
29
- UPLOAD_INTER_2_AUDIO = "interhumanai.upload.inter-2-audio"
30
- STREAM_INTER_2 = "interhumanai.stream.inter-2"
31
- STREAM_INTER_2_AUDIO = "interhumanai.stream.inter-2-audio"
32
30
 
33
31
 
34
32
  class SignalType(str, enum.Enum):
@@ -199,6 +197,8 @@ class StreamModel(str, enum.Enum):
199
197
 
200
198
  INTER_2 = "inter-2"
201
199
  INTER_2_AUDIO = "inter-2-audio"
200
+ # An upload model, declared so a stream naming it is refused with a clear
201
+ # error; the client refuses it before connecting.
202
202
  INTER_2_DEEP = "inter-2-deep"
203
203
 
204
204
 
@@ -232,7 +232,12 @@ class UploadModel(str, enum.Enum):
232
232
  ``INTER_2_AUDIO`` reads the audio alone: a wav, flac, mp3, m4a or ogg
233
233
  file, or a webm or mp4 carrying an audio track. It reports a subset of the
234
234
  signals ``INTER_2`` reports (agreement, confidence, frustration,
235
- hesitation, interest, uncertainty).
235
+ hesitation, interest, uncertainty). ``INTER_2_DEEP`` reads the same video
236
+ files as ``INTER_2`` and reasons before it answers: every window of its
237
+ result carries :attr:`UploadJobWindow.reasoning`. It needs
238
+ ``Scope.UPLOAD_INTER_2_DEEP``, which ``Scope.UPLOAD`` does not cover,
239
+ accepts files up to two minutes long by default, and is served on upload
240
+ jobs only.
236
241
  """
237
242
 
238
243
  INTER_2 = "inter-2"
@@ -285,10 +290,43 @@ class UploadJobSignal(BaseModel):
285
290
  rationale: str | None = None
286
291
 
287
292
 
293
+ class UploadJobReasoning(BaseModel):
294
+ """How an ``UploadModel.INTER_2_DEEP`` window's result was reached.
295
+
296
+ The model writes its reasoning in five numbered sections before it
297
+ answers. Each section field holds one section's text; all five are
298
+ ``None`` when the reasoning could not be split into exactly those
299
+ sections, and ``trace`` then still carries all of it.
300
+
301
+ Attributes:
302
+ perceptual_cues: The visual, verbal and vocal evidence the model
303
+ observed.
304
+ mental_state_hypothesis: What the person appears to believe, intend,
305
+ attend to or doubt.
306
+ cognitive_execution: The person's internal state: friction or flow,
307
+ such as hesitation, confusion, fluency or self-assurance.
308
+ relational_stance: The person's stance toward the partner, task or
309
+ topic, such as interest, agreement, skepticism or withdrawal.
310
+ synthesis: Why the evidence points to the reported result, and the
311
+ closest alternative it rules out.
312
+ trace: The whole reasoning, exactly as the model wrote it.
313
+ """
314
+
315
+ perceptual_cues: str | None = None
316
+ mental_state_hypothesis: str | None = None
317
+ cognitive_execution: str | None = None
318
+ relational_stance: str | None = None
319
+ synthesis: str | None = None
320
+ trace: str
321
+
322
+
288
323
  class UploadJobWindow(BaseModel):
289
324
  """The analysis of one fixed-length window of an upload job's file.
290
325
 
291
326
  ``signals`` carry the window's span as their ``start`` and ``end``.
327
+ ``reasoning`` is set on every ``UploadModel.INTER_2_DEEP`` window whose
328
+ reply carried the model's reasoning, and is ``None`` on the other models'
329
+ windows.
292
330
  """
293
331
 
294
332
  index: int
@@ -296,6 +334,7 @@ class UploadJobWindow(BaseModel):
296
334
  end_seconds: float
297
335
  engagement_status: EngagementLevel
298
336
  signals: list[UploadJobSignal] = Field(default_factory=list)
337
+ reasoning: UploadJobReasoning | None = None
299
338
 
300
339
 
301
340
  class UploadJobConversationQuality(BaseModel):
@@ -152,6 +152,14 @@ class UploadClient:
152
152
  duration (30 minutes by default; a longer file raises ``ih4004``). The
153
153
  job cuts it into fixed windows and analyzes each one.
154
154
 
155
+ ``UploadModel.INTER_2_DEEP`` takes the same video files, at most two
156
+ minutes long by default, and needs a credential holding
157
+ ``Scope.UPLOAD_INTER_2_DEEP`` (``ih2003`` otherwise; ``Scope.UPLOAD``
158
+ does not cover it). Every window of its result carries the model's
159
+ reasoning as :attr:`UploadJobWindow.reasoning`. A window can take a
160
+ minute or more, so submit without ``wait_seconds`` and read the job
161
+ back with :meth:`wait_for_job`.
162
+
155
163
  Args:
156
164
  file: The file to analyze - raw bytes, an open binary file object,
157
165
  or a filesystem path.
File without changes
File without changes