interhumanai 2.0.0__tar.gz → 3.2.1__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.
Files changed (21) hide show
  1. {interhumanai-2.0.0 → interhumanai-3.2.1}/CHANGELOG.md +43 -0
  2. {interhumanai-2.0.0 → interhumanai-3.2.1}/PKG-INFO +14 -5
  3. {interhumanai-2.0.0 → interhumanai-3.2.1}/README.md +13 -4
  4. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/__init__.py +22 -0
  5. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_version.py +1 -1
  6. interhumanai-3.2.1/src/interhumanai/types.py +710 -0
  7. interhumanai-2.0.0/src/interhumanai/types.py +0 -407
  8. {interhumanai-2.0.0 → interhumanai-3.2.1}/.gitignore +0 -0
  9. {interhumanai-2.0.0 → interhumanai-3.2.1}/LICENSE +0 -0
  10. {interhumanai-2.0.0 → interhumanai-3.2.1}/pyproject.toml +0 -0
  11. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_http.py +0 -0
  12. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_sdk_metadata.py +0 -0
  13. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_session_socket.py +0 -0
  14. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/auth.py +0 -0
  15. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/client.py +0 -0
  16. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/config.py +0 -0
  17. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/errors.py +0 -0
  18. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/py.typed +0 -0
  19. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/realtime.py +0 -0
  20. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/stream.py +0 -0
  21. {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/upload.py +0 -0
@@ -5,6 +5,49 @@ 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
+ ## 3.2.1
9
+
10
+ - Documentation only: when no speaker could be identified as on camera, the
11
+ lexical and speech cues of an ``UploadModel.INTER_2_DEEP`` job cover every
12
+ speaker, with ``speaker_role`` as ``None``, rather than the block being
13
+ ``FAILED``.
14
+
15
+ ## 3.2.0
16
+
17
+ - Added three ``UploadJobIncludeFlag`` values for ``UploadModel.INTER_2_DEEP``
18
+ jobs, with their result types: ``VISUAL_CUES``
19
+ (``UploadJobResult.visual_cues``, behaviors seen on camera), ``LEXICAL_CUES``
20
+ (``UploadJobResult.lexical_cues``, features of how the words were chosen) and
21
+ ``SPEECH_CUES`` (``UploadJobResult.speech_cues``, changes in how a speaker
22
+ sounds). Each block carries its own ``status``, so cues that could not be
23
+ produced do not fail the job. These sections are defined ahead of being
24
+ served: until a deployment serves one, a submit that names its flag is
25
+ refused with ``ih1003``.
26
+
27
+ ## 3.1.0
28
+
29
+ - Added ``UploadJobIncludeFlag.TRANSCRIPT`` and ``UploadJobResult.transcript``.
30
+ A ``UploadModel.INTER_2_DEEP`` job submitted with the flag carries a
31
+ transcript of the whole file: every word with its times and speaker
32
+ (``UploadJobTranscriptWord``), and who spoke when
33
+ (``UploadJobTranscriptSegment``). ``UploadJobTranscript.status`` tells a
34
+ transcribed file, even one with no speech, from a transcript that could not
35
+ be produced; the second carries ``error`` and does not fail the job. The API
36
+ refuses the flag for any other model.
37
+
38
+ ## 3.0.0
39
+
40
+ - **Breaking:** renamed the five section fields of ``UploadJobReasoning`` to
41
+ match the sections Inter-2 Deep now reasons in. They are, in order,
42
+ ``baseline_context``, ``observable_evidence``, ``appraisal_inference``,
43
+ ``mental_state_hypothesis`` and ``signal_conclusion``; they replace
44
+ ``perceptual_cues``, ``mental_state_hypothesis``, ``cognitive_execution``,
45
+ ``relational_stance`` and ``synthesis``. ``mental_state_hypothesis`` keeps
46
+ its name but is now the fourth section, and ``signal_conclusion``, which names
47
+ the signals and the evidence for each, is the closest counterpart to
48
+ ``synthesis``. ``trace`` is unchanged, and the
49
+ sections are still ``None`` when the reasoning could not be split into them.
50
+
8
51
  ## 2.0.0
9
52
 
10
53
  - **Breaking:** removed the four legacy per-model scopes from ``Scope``:
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: interhumanai
3
- Version: 2.0.0
3
+ Version: 3.2.1
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
@@ -167,7 +167,16 @@ else:
167
167
  named. `SIGNALS` adds `signals`: every window's signals as one chronological
168
168
  list, same-type signals in adjacent windows merged into one span with the
169
169
  highest probability and its rationale, and no `modality` (an empty list when
170
- nothing was detected). Without a flag the result has no such section.
170
+ nothing was detected). `TRANSCRIPT`, which `UploadModel.INTER_2_DEEP` jobs
171
+ accept, adds `transcript`: an `UploadJobTranscript` with every spoken word
172
+ (`text`, `start`, `end`, `speaker`, `speaker_role`) and the speaker
173
+ segments. Check `transcript.status` first: `FAILED` means no transcript
174
+ could be produced, carries `error`, and leaves the job completed.
175
+ `VISUAL_CUES`, `LEXICAL_CUES` and `SPEECH_CUES` add `visual_cues`,
176
+ `lexical_cues` and `speech_cues`: timestamped cue lists, each with its own
177
+ `status`. The API defines them ahead of serving them, so a submit that names
178
+ one is refused with `ih1003` until the deployment serves it. Without a flag
179
+ the result has no such section.
171
180
  - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
172
181
  `error_id` `ih4021` once the job has expired (`job.expires_at`).
173
182
  - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -190,8 +199,8 @@ else:
190
199
  before it answers: each window carries `reasoning` whenever the model wrote
191
200
  it, an
192
201
  `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
202
+ (`baseline_context`, `observable_evidence`, `appraisal_inference`,
203
+ `mental_state_hypothesis`, `signal_conclusion`) and in full as `trace`. The sections are
195
204
  `None` when the reasoning could not be split into them; `trace` is always
196
205
  set. It needs `Scope.UPLOAD_INTER_2_DEEP`, which `Scope.UPLOAD` does not
197
206
  cover, and is served on upload jobs only. A window can take a minute or
@@ -201,7 +210,7 @@ else:
201
210
  job = await client.upload.submit("pitch.mp4", model=UploadModel.INTER_2_DEEP)
202
211
  job = await client.upload.wait_for_job(job, timeout=3600)
203
212
  for window in job.result.windows:
204
- print(window.start_seconds, window.reasoning.synthesis or window.reasoning.trace)
213
+ print(window.start_seconds, window.reasoning.signal_conclusion or window.reasoning.trace)
205
214
  ```
206
215
 
207
216
  ### Inter-1 upload (V1, compatibility)
@@ -141,7 +141,16 @@ else:
141
141
  named. `SIGNALS` adds `signals`: every window's signals as one chronological
142
142
  list, same-type signals in adjacent windows merged into one span with the
143
143
  highest probability and its rationale, and no `modality` (an empty list when
144
- nothing was detected). Without a flag the result has no such section.
144
+ nothing was detected). `TRANSCRIPT`, which `UploadModel.INTER_2_DEEP` jobs
145
+ accept, adds `transcript`: an `UploadJobTranscript` with every spoken word
146
+ (`text`, `start`, `end`, `speaker`, `speaker_role`) and the speaker
147
+ segments. Check `transcript.status` first: `FAILED` means no transcript
148
+ could be produced, carries `error`, and leaves the job completed.
149
+ `VISUAL_CUES`, `LEXICAL_CUES` and `SPEECH_CUES` add `visual_cues`,
150
+ `lexical_cues` and `speech_cues`: timestamped cue lists, each with its own
151
+ `status`. The API defines them ahead of serving them, so a submit that names
152
+ one is refused with `ih1003` until the deployment serves it. Without a flag
153
+ the result has no such section.
145
154
  - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
146
155
  `error_id` `ih4021` once the job has expired (`job.expires_at`).
147
156
  - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -164,8 +173,8 @@ else:
164
173
  before it answers: each window carries `reasoning` whenever the model wrote
165
174
  it, an
166
175
  `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
176
+ (`baseline_context`, `observable_evidence`, `appraisal_inference`,
177
+ `mental_state_hypothesis`, `signal_conclusion`) and in full as `trace`. The sections are
169
178
  `None` when the reasoning could not be split into them; `trace` is always
170
179
  set. It needs `Scope.UPLOAD_INTER_2_DEEP`, which `Scope.UPLOAD` does not
171
180
  cover, and is served on upload jobs only. A window can take a minute or
@@ -175,7 +184,7 @@ else:
175
184
  job = await client.upload.submit("pitch.mp4", model=UploadModel.INTER_2_DEEP)
176
185
  job = await client.upload.wait_for_job(job, timeout=3600)
177
186
  for window in job.result.windows:
178
- print(window.start_seconds, window.reasoning.synthesis or window.reasoning.trace)
187
+ print(window.start_seconds, window.reasoning.signal_conclusion or window.reasoning.trace)
179
188
  ```
180
189
 
181
190
  ### Inter-1 upload (V1, compatibility)
@@ -124,12 +124,23 @@ from .types import (
124
124
  StreamModel,
125
125
  UploadJob,
126
126
  UploadJobConversationQuality,
127
+ UploadJobCuesStatus,
127
128
  UploadJobError,
128
129
  UploadJobIncludeFlag,
130
+ UploadJobLexicalCue,
131
+ UploadJobLexicalCues,
129
132
  UploadJobReasoning,
130
133
  UploadJobResult,
131
134
  UploadJobSignal,
135
+ UploadJobSpeechCue,
136
+ UploadJobSpeechCues,
132
137
  UploadJobStatus,
138
+ UploadJobTranscript,
139
+ UploadJobTranscriptSegment,
140
+ UploadJobTranscriptStatus,
141
+ UploadJobTranscriptWord,
142
+ UploadJobVisualCue,
143
+ UploadJobVisualCues,
133
144
  UploadJobWindow,
134
145
  UploadModel,
135
146
  )
@@ -227,13 +238,24 @@ __all__ = [
227
238
  "UploadClient",
228
239
  "UploadJob",
229
240
  "UploadJobConversationQuality",
241
+ "UploadJobCuesStatus",
230
242
  "UploadJobError",
231
243
  "UploadJobIncludeFlag",
244
+ "UploadJobLexicalCue",
245
+ "UploadJobLexicalCues",
232
246
  "UploadJobReasoning",
233
247
  "UploadJobResult",
234
248
  "UploadJobSignal",
249
+ "UploadJobSpeechCue",
250
+ "UploadJobSpeechCues",
235
251
  "UploadJobStatus",
236
252
  "UploadJobTimeoutError",
253
+ "UploadJobTranscript",
254
+ "UploadJobTranscriptSegment",
255
+ "UploadJobTranscriptStatus",
256
+ "UploadJobTranscriptWord",
257
+ "UploadJobVisualCue",
258
+ "UploadJobVisualCues",
237
259
  "UploadJobWindow",
238
260
  "UploadModel",
239
261
  "VideoInput",
@@ -1,3 +1,3 @@
1
1
  """Package version (single source of truth, read by hatchling at build time)."""
2
2
 
3
- __version__ = "2.0.0"
3
+ __version__ = "3.2.1"
@@ -0,0 +1,710 @@
1
+ """Public enums and analysis models shared across the Interhuman API surfaces."""
2
+
3
+ import enum
4
+ from datetime import datetime
5
+ from typing import Annotated, Literal
6
+
7
+ from pydantic import BaseModel, Field
8
+
9
+
10
+ class Scope(str, enum.Enum):
11
+ """OAuth-style scopes accepted by the Interhuman API.
12
+
13
+ A scope names one endpoint family across every API version. ``UPLOAD``
14
+ covers ``POST /v1/upload/analyze`` and ``POST /v2/upload/analyze`` with
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.
24
+ """
25
+
26
+ UPLOAD = "interhumanai.upload"
27
+ STREAM = "interhumanai.stream"
28
+ REALTIME = "interhumanai.realtime"
29
+ UPLOAD_INTER_2_DEEP = "interhumanai.upload.inter-2-deep"
30
+
31
+
32
+ class SignalType(str, enum.Enum):
33
+ """Social signals the Interhuman API can detect."""
34
+
35
+ AGREEMENT = "agreement"
36
+ CONFIDENCE = "confidence"
37
+ CONFUSION = "confusion"
38
+ DISAGREEMENT = "disagreement"
39
+ DISENGAGEMENT = "disengagement"
40
+ ENGAGEMENT = "engagement"
41
+ FRUSTRATION = "frustration"
42
+ HESITATION = "hesitation"
43
+ INTEREST = "interest"
44
+ SKEPTICISM = "skepticism"
45
+ STRESS = "stress"
46
+ TENSION = "tension"
47
+ UNCERTAINTY = "uncertainty"
48
+
49
+
50
+ class Probability(str, enum.Enum):
51
+ """Confidence band attached to a detected signal."""
52
+
53
+ HIGH = "high"
54
+ MEDIUM = "medium"
55
+ LOW = "low"
56
+
57
+
58
+ class EngagementLevel(str, enum.Enum):
59
+ """Coarse engagement state of the analyzed subject."""
60
+
61
+ ENGAGED = "engaged"
62
+ NEUTRAL = "neutral"
63
+ DISENGAGED = "disengaged"
64
+
65
+
66
+ class GoalDimension(str, enum.Enum):
67
+ """Interaction-goal dimensions used for feedback and conversation quality."""
68
+
69
+ CLARITY = "clarity"
70
+ AUTHORITY = "authority"
71
+ ENERGY = "energy"
72
+ RAPPORT = "rapport"
73
+ LEARNING = "learning"
74
+
75
+
76
+ class IncludeFlag(str, enum.Enum):
77
+ """Optional response sections selectable on upload and stream analysis."""
78
+
79
+ CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
80
+ CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
81
+
82
+
83
+ class AnalysisGroup(str, enum.Enum):
84
+ """Analysis track groups selectable on the realtime API."""
85
+
86
+ VISUAL = "visual"
87
+ AUDIO = "audio"
88
+
89
+
90
+ class RealtimeRecommendationFrequency(str, enum.Enum):
91
+ """How often the realtime API generates feedback output.
92
+
93
+ ``HIGH`` is roughly every 10 seconds of analyzed video, ``MEDIUM`` every
94
+ 20 seconds, and ``LOW`` every 30 seconds.
95
+ """
96
+
97
+ HIGH = "high"
98
+ MEDIUM = "medium"
99
+ LOW = "low"
100
+
101
+
102
+ class Signal(BaseModel):
103
+ """A detected social signal over a time range.
104
+
105
+ ``modality`` names the analysis modalities that detected this signal. When
106
+ several tracks detect the same signal, every contributing modality is
107
+ included.
108
+ """
109
+
110
+ type: SignalType
111
+ start: float
112
+ end: float
113
+ probability: Probability | None = None
114
+ rationale: str | None = None
115
+ modality: list[str] = Field(default_factory=list)
116
+
117
+
118
+ class EngagementStateEntry(BaseModel):
119
+ """An engagement state over a time range."""
120
+
121
+ state: EngagementLevel
122
+ start: float
123
+ end: float
124
+
125
+
126
+ class ConversationQualityValues(BaseModel):
127
+ """Conversation-quality scores (0-100; 50 means no evidence either way)."""
128
+
129
+ quality_index: float
130
+ clarity: float
131
+ authority: float
132
+ energy: float
133
+ rapport: float
134
+ learning: float
135
+
136
+
137
+ class ConversationQualityTimelineEntry(BaseModel):
138
+ """Conversation-quality scores for one slice of the video."""
139
+
140
+ start: float
141
+ end: float
142
+ values: ConversationQualityValues
143
+
144
+
145
+ class ConversationQuality(BaseModel):
146
+ """Conversation-quality section of an analysis result."""
147
+
148
+ overall: ConversationQualityValues
149
+ timeline: list[ConversationQualityTimelineEntry] = Field(default_factory=list)
150
+
151
+
152
+ class Feedback(BaseModel):
153
+ """Actionable interaction feedback generated from the analysis."""
154
+
155
+ type: Literal["feedback"] = "feedback"
156
+ message: str
157
+ active_dimensions: list[GoalDimension] = Field(default_factory=list)
158
+ primary_signal: SignalType | None = None
159
+
160
+
161
+ class NoFeedback(BaseModel):
162
+ """Explicit indication that no feedback was warranted, with the reason."""
163
+
164
+ type: Literal["no_feedback"] = "no_feedback"
165
+ reason: str
166
+
167
+
168
+ InteractionFeedback = Annotated[Feedback | NoFeedback, Field(discriminator="type")]
169
+ """Feedback section of an analysis result, discriminated on ``type``."""
170
+
171
+
172
+ class AnalysisResult(BaseModel):
173
+ """Response of ``POST /v1/upload/analyze``.
174
+
175
+ Optional sections are only present when requested: ``feedback`` when goal
176
+ dimensions or a conversation context were supplied, ``conversation_quality``
177
+ when requested via include flags.
178
+ """
179
+
180
+ signals: list[Signal] = Field(default_factory=list)
181
+ engagement_state: list[EngagementStateEntry] = Field(default_factory=list)
182
+ feedback: InteractionFeedback | None = None
183
+ conversation_quality: ConversationQuality | None = None
184
+
185
+
186
+ class StreamModel(str, enum.Enum):
187
+ """Inter-2 models a ``WS /v2/stream/analyze`` session can select.
188
+
189
+ ``INTER_2`` (the default) reads the video. ``INTER_2_AUDIO`` hears the
190
+ audio alone: it accepts the same WebM and fragmented MP4 clips, with or
191
+ without a video track, and raw PCM frames once the session config declares
192
+ an :class:`RawAudioFormat`, and reports a subset of the signals
193
+ ``INTER_2`` reports (agreement, confidence, frustration, hesitation,
194
+ interest, uncertainty). ``WS /v1/stream/analyze`` offers no selection and
195
+ rejects any value.
196
+ """
197
+
198
+ INTER_2 = "inter-2"
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
+ INTER_2_DEEP = "inter-2-deep"
203
+
204
+
205
+ PcmSampleRate = Literal[16000, 24000]
206
+ """Sample rates accepted for raw PCM frames."""
207
+
208
+
209
+ class RawAudioFormat(BaseModel):
210
+ """Declares that a session's binary frames are raw audio, not container media.
211
+
212
+ Signed 16-bit little-endian PCM at ``sample_rate``, mono, with no header;
213
+ frames may be cut at any byte boundary. Accepted on
214
+ ``StreamModel.INTER_2_AUDIO`` sessions only.
215
+
216
+ Attributes:
217
+ encoding: Always ``pcm_s16le``.
218
+ sample_rate: Samples per second, 16000 or 24000.
219
+ channels: Always ``1``.
220
+ """
221
+
222
+ encoding: Literal["pcm_s16le"] = "pcm_s16le"
223
+ sample_rate: PcmSampleRate = 16000
224
+ channels: Literal[1] = 1
225
+
226
+
227
+ class UploadModel(str, enum.Enum):
228
+ """Inter-2 models a ``POST /v2/upload/analyze`` job can name.
229
+
230
+ ``INTER_2`` reads a video (picture and sound together): an mp4, mov, avi,
231
+ mkv, webm or mpeg-ts file carrying both a video and an audio track.
232
+ ``INTER_2_AUDIO`` reads the audio alone: a wav, flac, mp3, m4a or ogg
233
+ file, or a webm or mp4 carrying an audio track. It reports a subset of the
234
+ signals ``INTER_2`` reports (agreement, confidence, frustration,
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.
241
+ """
242
+
243
+ INTER_2 = "inter-2"
244
+ INTER_2_AUDIO = "inter-2-audio"
245
+ INTER_2_DEEP = "inter-2-deep"
246
+
247
+
248
+ class UploadJobIncludeFlag(str, enum.Enum):
249
+ """Whole-file sections a ``POST /v2/upload/analyze`` job's result can carry.
250
+
251
+ The two :class:`IncludeFlag` Conversation Quality Index sections, plus
252
+ ``SIGNALS`` for the whole-file signal list
253
+ (:attr:`UploadJobResult.signals`) and ``TRANSCRIPT`` for a transcript of
254
+ the whole file (:attr:`UploadJobResult.transcript`). Both are v2 upload
255
+ options only; :meth:`~interhumanai.UploadClient.analyze` and the stream do
256
+ not take them. ``TRANSCRIPT`` is accepted with ``UploadModel.INTER_2_DEEP``
257
+ only; the API refuses it for any other model.
258
+
259
+ ``VISUAL_CUES``, ``LEXICAL_CUES`` and ``SPEECH_CUES`` ask for timestamped
260
+ cue lists (:attr:`UploadJobResult.visual_cues`,
261
+ :attr:`UploadJobResult.lexical_cues`, :attr:`UploadJobResult.speech_cues`).
262
+ They are ``UploadModel.INTER_2_DEEP`` options too. A deployment that does
263
+ not serve a section yet refuses a submit that names it with ``ih1003``.
264
+ """
265
+
266
+ CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
267
+ CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
268
+ SIGNALS = "signals"
269
+ TRANSCRIPT = "transcript"
270
+ VISUAL_CUES = "visual_cues"
271
+ LEXICAL_CUES = "lexical_cues"
272
+ SPEECH_CUES = "speech_cues"
273
+
274
+
275
+ class UploadJobStatus(str, enum.Enum):
276
+ """Lifecycle of a ``POST /v2/upload/analyze`` job.
277
+
278
+ ``QUEUED`` and ``RUNNING`` are transient; ``COMPLETED`` and ``FAILED`` are
279
+ terminal, and the job stays readable until its ``expires_at``.
280
+ """
281
+
282
+ QUEUED = "queued"
283
+ RUNNING = "running"
284
+ COMPLETED = "completed"
285
+ FAILED = "failed"
286
+
287
+
288
+ class UploadJobSignal(BaseModel):
289
+ """A social signal detected in one window of an upload job.
290
+
291
+ It carries the window's span as its ``start`` and ``end``. Unlike the v1
292
+ :class:`Signal`, it has no ``modality``: the job's ``model`` names the
293
+ evidence the model read. On a ``UploadModel.INTER_2_AUDIO`` job, the
294
+ ``type`` values are a subset of the ones ``UploadModel.INTER_2`` reports:
295
+ those it can hear (agreement, confidence, frustration, hesitation, interest
296
+ and uncertainty).
297
+ """
298
+
299
+ type: SignalType
300
+ start: float
301
+ end: float
302
+ probability: Probability | None = None
303
+ rationale: str | None = None
304
+
305
+
306
+ class UploadJobReasoning(BaseModel):
307
+ """How an ``UploadModel.INTER_2_DEEP`` window's result was reached.
308
+
309
+ The model writes its reasoning in five numbered sections before it
310
+ answers. Each section field holds one section's text; all five are
311
+ ``None`` when the reasoning could not be split into exactly those
312
+ sections, and ``trace`` then still carries all of it.
313
+
314
+ Attributes:
315
+ baseline_context: The interaction type, topic and social role the
316
+ model read, the baseline behavior it expects for that kind of
317
+ interaction, and what would count as a meaningful deviation.
318
+ observable_evidence: The concrete visual, verbal and vocal cues the
319
+ model observed, without interpretation, and which of them deviate
320
+ from the baseline.
321
+ appraisal_inference: The most probable appraisal behind a deviation,
322
+ such as incomplete understanding, a blocked goal, pressure,
323
+ motivated attention or stable self-assurance, or a note that the
324
+ behavior is within the baseline.
325
+ mental_state_hypothesis: What the person most probably believes,
326
+ intends, feels, attends to or resists given that appraisal, with
327
+ the model's confidence.
328
+ signal_conclusion: Every signal the evidence supports, with its
329
+ strongest grounded evidence, and the closest contrasting signal it
330
+ rules out; or a statement that no signal is supported.
331
+ trace: The whole reasoning, exactly as the model wrote it.
332
+ """
333
+
334
+ baseline_context: str | None = None
335
+ observable_evidence: str | None = None
336
+ appraisal_inference: str | None = None
337
+ mental_state_hypothesis: str | None = None
338
+ signal_conclusion: str | None = None
339
+ trace: str
340
+
341
+
342
+ class UploadJobWindow(BaseModel):
343
+ """The analysis of one fixed-length window of an upload job's file.
344
+
345
+ ``signals`` carry the window's span as their ``start`` and ``end``.
346
+ ``reasoning`` is set on every ``UploadModel.INTER_2_DEEP`` window whose
347
+ reply carried the model's reasoning, and is ``None`` on the other models'
348
+ windows.
349
+ """
350
+
351
+ index: int
352
+ start_seconds: float
353
+ end_seconds: float
354
+ engagement_status: EngagementLevel
355
+ signals: list[UploadJobSignal] = Field(default_factory=list)
356
+ reasoning: UploadJobReasoning | None = None
357
+
358
+
359
+ class UploadJobConversationQuality(BaseModel):
360
+ """The Conversation Quality Index of a completed upload job.
361
+
362
+ Scored once over the whole file from every window's signals and engagement.
363
+ Each section is set only when :meth:`~interhumanai.UploadClient.submit` asked
364
+ for it with the matching :class:`IncludeFlag`: ``overall`` for
365
+ ``CONVERSATION_QUALITY_OVERALL``, ``timeline`` for
366
+ ``CONVERSATION_QUALITY_TIMELINE``. A requested section is present even when
367
+ no signal was detected; every dimension then reads the neutral 50.
368
+ """
369
+
370
+ overall: ConversationQualityValues | None = None
371
+ timeline: list[ConversationQualityTimelineEntry] | None = None
372
+
373
+
374
+ class UploadJobError(BaseModel):
375
+ """Why an upload job failed, in the API's standard error-body shape."""
376
+
377
+ error_id: str
378
+ correlation_id: str | None = None
379
+ link: str | None = None
380
+ message: str | None = None
381
+
382
+
383
+ class UploadJobTranscriptStatus(str, enum.Enum):
384
+ """How the transcript of an upload job ended.
385
+
386
+ ``COMPLETED`` means the file was transcribed, including when nobody speaks
387
+ in it and the transcript is empty. ``FAILED`` means no transcript could be
388
+ produced; the job's windows are unaffected.
389
+ """
390
+
391
+ COMPLETED = "completed"
392
+ FAILED = "failed"
393
+
394
+
395
+ class UploadJobTranscriptWord(BaseModel):
396
+ """One spoken word of an upload job's file.
397
+
398
+ Attributes:
399
+ text: The word as it was spoken. The transcript is verbatim: fillers
400
+ and repeated words are kept.
401
+ start: Where the word starts, in seconds from the start of the file.
402
+ end: Where the word ends, in seconds from the start of the file.
403
+ speaker: The speaker who said the word, as the number the transcript's
404
+ segments use. ``None`` when the word falls outside every speaker
405
+ segment.
406
+ speaker_role: ``"fg_speaker"`` for the person on camera,
407
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
408
+ speaker's role could not be told.
409
+ """
410
+
411
+ text: str
412
+ start: float
413
+ end: float
414
+ speaker: int | None = None
415
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
416
+
417
+
418
+ class UploadJobTranscriptSegment(BaseModel):
419
+ """One stretch of speech by one speaker.
420
+
421
+ Attributes:
422
+ speaker: The speaker's number, unique within the file and starting at 0.
423
+ start: Where the segment starts, in seconds from the start of the file.
424
+ end: Where the segment ends, in seconds from the start of the file.
425
+ speaker_role: ``"fg_speaker"`` for the person on camera,
426
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
427
+ speaker's role could not be told.
428
+ """
429
+
430
+ speaker: int
431
+ start: float
432
+ end: float
433
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
434
+
435
+
436
+ class UploadJobTranscript(BaseModel):
437
+ """The transcript of a completed ``UploadModel.INTER_2_DEEP`` job that asked for one.
438
+
439
+ Read ``status`` first. ``COMPLETED`` carries ``words`` and ``segments``,
440
+ both empty when nobody speaks in the file. ``FAILED`` carries ``error`` and
441
+ no words: the transcript could not be produced, which is a different
442
+ outcome from a file without speech. Either way the job itself completed
443
+ and its windows are whole.
444
+
445
+ Attributes:
446
+ status: Whether the file was transcribed.
447
+ language: The language detected in the speech, as an ISO 639 code.
448
+ speaker_roles_status: Whether the speakers could be told apart as on
449
+ camera or off it: ``"mapped"`` when at least one speaker has a
450
+ role, ``"unmapped"`` when none could be told, ``"no_face"`` when no
451
+ face was found in the picture, ``"failed"`` when the step itself
452
+ failed. Only ``speaker_role`` is affected; the words and segments
453
+ are complete in every case. Treat a value not listed here as
454
+ ``"unmapped"``: later versions of the API may add one.
455
+ word_timing: How the word times were measured. ``"asr"`` means they
456
+ are the speech recognizer's own estimates.
457
+ words: Every spoken word, in the order spoken.
458
+ segments: Who spoke when: one entry per stretch of speech, in order.
459
+ error: Why no transcript could be produced. Set only when ``status``
460
+ is ``FAILED``.
461
+ """
462
+
463
+ status: UploadJobTranscriptStatus
464
+ language: str | None = None
465
+ speaker_roles_status: str | None = None
466
+ word_timing: str | None = None
467
+ words: list[UploadJobTranscriptWord] = Field(default_factory=list)
468
+ segments: list[UploadJobTranscriptSegment] = Field(default_factory=list)
469
+ error: UploadJobError | None = None
470
+
471
+
472
+ class UploadJobCuesStatus(str, enum.Enum):
473
+ """How one family of cues of an upload job ended.
474
+
475
+ ``COMPLETED`` means the stage ran over the whole file, including when it
476
+ found no cue and the list is empty. ``FAILED`` means the stage could not
477
+ produce its cues; the job's windows and its other sections are unaffected.
478
+ """
479
+
480
+ COMPLETED = "completed"
481
+ FAILED = "failed"
482
+
483
+
484
+ class UploadJobVisualCue(BaseModel):
485
+ """One observable behavior of a person on camera.
486
+
487
+ Attributes:
488
+ label: A short name for the behavior, in lower case. The vocabulary is
489
+ open: the same movement can arrive under more than one name.
490
+ start: Where the behavior starts, in seconds from the start of the file.
491
+ end: Where the behavior ends, in seconds from the start of the file.
492
+ description: One sentence describing what was seen.
493
+ visible_participant: Which person on camera the behavior belongs to,
494
+ as ``"P1"``, ``"P2"`` and so on. It names a body in the picture,
495
+ which is not the transcript's ``speaker`` number.
496
+ context_speaker: Who was speaking while the behavior happened:
497
+ ``"fg_speaker"`` for the person on camera, ``"bg_speaker"`` for a
498
+ voice from off camera, or ``None`` when nobody was speaking or the
499
+ role could not be told.
500
+ """
501
+
502
+ label: str
503
+ start: float
504
+ end: float
505
+ description: str | None = None
506
+ visible_participant: str | None = None
507
+ context_speaker: Literal["fg_speaker", "bg_speaker"] | None = None
508
+
509
+
510
+ class UploadJobLexicalCue(BaseModel):
511
+ """One feature of how a speaker chose and built their words.
512
+
513
+ Attributes:
514
+ label: A short name for what was said, in lower case, such as
515
+ ``"repetition"``, ``"false start"``, ``"hedge"`` or
516
+ ``"filled pause"``. The vocabulary is open: it covers
517
+ disfluencies and also hedges, intensifiers, vague language,
518
+ discourse markers, questions and laughter.
519
+ start: Where the cue starts, in seconds from the start of the file.
520
+ end: Where the cue ends, in seconds from the start of the file.
521
+ quote: The words the cue covers, as spoken.
522
+ core_quote: The fragment the label names, inside ``quote``.
523
+ description: One sentence describing the cue.
524
+ speaker: The speaker, as the number the transcript's segments use.
525
+ speaker_role: ``"fg_speaker"`` for the person on camera,
526
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
527
+ role could not be told.
528
+ word_start: Position of the cue's first word in the
529
+ ``transcript.words`` list of this same result, counting from 0.
530
+ ``None`` when the result carries no completed transcript.
531
+ word_end: Position of the cue's last word in that list, inclusive.
532
+ ``None`` under the same condition.
533
+ """
534
+
535
+ label: str
536
+ start: float
537
+ end: float
538
+ quote: str
539
+ core_quote: str | None = None
540
+ description: str | None = None
541
+ speaker: int | None = None
542
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
543
+ word_start: int | None = None
544
+ word_end: int | None = None
545
+
546
+
547
+ class UploadJobSpeechCue(BaseModel):
548
+ """One change in how a speaker sounds, or one turn-taking event.
549
+
550
+ Attributes:
551
+ label: What was heard, in lower case, such as ``"faster than usual"``,
552
+ ``"higher pitch than usual"`` or ``"backchannel"``.
553
+ feature: What was measured: ``"speech_rate"``, ``"pitch_level"``,
554
+ ``"pitch_range"``, ``"pitch_slope"``, ``"loudness"``,
555
+ ``"response_latency"``, ``"reply_length"``,
556
+ ``"disfluency_rate"``, ``"interruption"`` or ``"backchannel"``.
557
+ Treat a value not listed here as unknown: later versions of the
558
+ API may add one.
559
+ start: Where the cue starts, in seconds from the start of the file.
560
+ end: Where the cue ends, in seconds from the start of the file.
561
+ value: The measurement, in the unit of its ``feature``: syllables
562
+ per second for ``speech_rate``; semitones (12 times the base-2
563
+ logarithm of the frequency in hertz) for ``pitch_level``;
564
+ semitones between the low and the high of the pitch for
565
+ ``pitch_range``; semitones per second for ``pitch_slope``;
566
+ decibels for ``loudness``; seconds before the reply for
567
+ ``response_latency``; words for ``reply_length``; hesitations per
568
+ 100 words for ``disfluency_rate``; seconds of overlap for
569
+ ``interruption``. ``None`` for a ``backchannel``.
570
+ z: How unusual the measurement is, in standard deviations from the
571
+ rest of the analyzed speech in this file. For ``reply_length`` it
572
+ is taken on a logarithmic scale. ``None`` for a ``backchannel``
573
+ or an ``interruption``, which are not compared with a baseline.
574
+ description: One sentence describing the cue.
575
+ quote: The words spoken during the cue, when it covers words.
576
+ speaker: The speaker, as the number the transcript's segments use.
577
+ speaker_role: ``"fg_speaker"`` for the person on camera,
578
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
579
+ role could not be told.
580
+ word_start: Position of the cue's first word in the
581
+ ``transcript.words`` list of this same result, counting from 0.
582
+ ``None`` when the cue covers no words or the result carries no
583
+ completed transcript.
584
+ word_end: Position of the cue's last word in that list, inclusive.
585
+ ``None`` under the same conditions.
586
+ """
587
+
588
+ label: str
589
+ feature: str
590
+ start: float
591
+ end: float
592
+ value: float | None = None
593
+ z: float | None = None
594
+ description: str | None = None
595
+ quote: str | None = None
596
+ speaker: int | None = None
597
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
598
+ word_start: int | None = None
599
+ word_end: int | None = None
600
+
601
+
602
+ class UploadJobVisualCues(BaseModel):
603
+ """The visual cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
604
+
605
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
606
+ was seen. ``FAILED`` carries ``error`` and no cues. Either way the job
607
+ itself completed.
608
+ """
609
+
610
+ status: UploadJobCuesStatus
611
+ cues: list[UploadJobVisualCue] = Field(default_factory=list)
612
+ error: UploadJobError | None = None
613
+
614
+
615
+ class UploadJobLexicalCues(BaseModel):
616
+ """The lexical cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
617
+
618
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
619
+ stood out. ``FAILED`` carries ``error`` and no cues. Either way the job
620
+ itself completed.
621
+
622
+ The cues cover the speech of the person on camera. An off-camera speaker
623
+ is not analyzed. When no speaker could be identified as on camera, every
624
+ speaker is analyzed and each cue's ``speaker_role`` is ``None``.
625
+ """
626
+
627
+ status: UploadJobCuesStatus
628
+ cues: list[UploadJobLexicalCue] = Field(default_factory=list)
629
+ error: UploadJobError | None = None
630
+
631
+
632
+ class UploadJobSpeechCues(BaseModel):
633
+ """The speech cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
634
+
635
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
636
+ stood out or the file holds too little speech to judge a speaker against
637
+ themselves. ``FAILED`` carries ``error`` and no cues. Either way the job
638
+ itself completed.
639
+
640
+ The cues cover the speech of the person on camera, judged against the rest
641
+ of that person's speech in the file. An off-camera speaker is not
642
+ analyzed. When no speaker could be identified as on camera, every speaker
643
+ is analyzed, each against the rest of the speech in the file, and each
644
+ cue's ``speaker_role`` is ``None``.
645
+ """
646
+
647
+ status: UploadJobCuesStatus
648
+ cues: list[UploadJobSpeechCue] = Field(default_factory=list)
649
+ error: UploadJobError | None = None
650
+
651
+
652
+ class UploadJobResult(BaseModel):
653
+ """The result of a completed upload job: one entry per analyzed window.
654
+
655
+ ``signals`` is every window's signals as one list over the whole file, in
656
+ chronological order, merged by the same rules as
657
+ :meth:`~interhumanai.UploadClient.analyze` and with no ``modality``:
658
+ signals of the same type in adjacent windows become one span, which keeps
659
+ the highest probability and that signal's rationale. It is set only when the submit
660
+ passed :attr:`UploadJobIncludeFlag.SIGNALS`, and is then an empty list when
661
+ nothing was detected; ``windows`` are unchanged either way.
662
+
663
+ ``conversation_quality`` is present only when the submit passed at least one
664
+ Conversation Quality Index flag, and carries the sections those flags named.
665
+
666
+ ``transcript`` is a transcript of the whole file with speakers and word
667
+ times. It is set only when the submit passed
668
+ :attr:`UploadJobIncludeFlag.TRANSCRIPT`, which ``UploadModel.INTER_2_DEEP``
669
+ jobs accept. A transcript that could not be produced is still set, with
670
+ ``status`` ``FAILED``, and does not fail the job.
671
+
672
+ ``visual_cues``, ``lexical_cues`` and ``speech_cues`` are timestamped cue
673
+ lists, each set only when the submit passed the matching
674
+ :class:`UploadJobIncludeFlag`. Each carries its own ``status``, so one
675
+ family that could not be produced does not fail the job or the others.
676
+ """
677
+
678
+ duration_seconds: float
679
+ window_seconds: float
680
+ windows: list[UploadJobWindow] = Field(default_factory=list)
681
+ signals: list[UploadJobSignal] | None = None
682
+ conversation_quality: UploadJobConversationQuality | None = None
683
+ transcript: UploadJobTranscript | None = None
684
+ visual_cues: UploadJobVisualCues | None = None
685
+ lexical_cues: UploadJobLexicalCues | None = None
686
+ speech_cues: UploadJobSpeechCues | None = None
687
+
688
+
689
+ class UploadJob(BaseModel):
690
+ """The job envelope both v2 upload routes answer with.
691
+
692
+ Returned by ``POST /v2/upload/analyze`` and ``GET /v2/upload/jobs/{job_id}``
693
+ alike. ``result`` is set only when ``status`` is ``COMPLETED``; ``error`` only
694
+ when it is ``FAILED``. ``status_url`` is the status resource's path,
695
+ relative to the API base URL.
696
+ """
697
+
698
+ job_id: str
699
+ status: UploadJobStatus
700
+ model: UploadModel
701
+ created_at: datetime
702
+ expires_at: datetime
703
+ status_url: str
704
+ result: UploadJobResult | None = None
705
+ error: UploadJobError | None = None
706
+
707
+ @property
708
+ def is_terminal(self) -> bool:
709
+ """Whether the job has finished, successfully or not."""
710
+ return self.status in (UploadJobStatus.COMPLETED, UploadJobStatus.FAILED)
@@ -1,407 +0,0 @@
1
- """Public enums and analysis models shared across the Interhuman API surfaces."""
2
-
3
- import enum
4
- from datetime import datetime
5
- from typing import Annotated, Literal
6
-
7
- from pydantic import BaseModel, Field
8
-
9
-
10
- class Scope(str, enum.Enum):
11
- """OAuth-style scopes accepted by the Interhuman API.
12
-
13
- A scope names one endpoint family across every API version. ``UPLOAD``
14
- covers ``POST /v1/upload/analyze`` and ``POST /v2/upload/analyze`` with
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.
24
- """
25
-
26
- UPLOAD = "interhumanai.upload"
27
- STREAM = "interhumanai.stream"
28
- REALTIME = "interhumanai.realtime"
29
- UPLOAD_INTER_2_DEEP = "interhumanai.upload.inter-2-deep"
30
-
31
-
32
- class SignalType(str, enum.Enum):
33
- """Social signals the Interhuman API can detect."""
34
-
35
- AGREEMENT = "agreement"
36
- CONFIDENCE = "confidence"
37
- CONFUSION = "confusion"
38
- DISAGREEMENT = "disagreement"
39
- DISENGAGEMENT = "disengagement"
40
- ENGAGEMENT = "engagement"
41
- FRUSTRATION = "frustration"
42
- HESITATION = "hesitation"
43
- INTEREST = "interest"
44
- SKEPTICISM = "skepticism"
45
- STRESS = "stress"
46
- TENSION = "tension"
47
- UNCERTAINTY = "uncertainty"
48
-
49
-
50
- class Probability(str, enum.Enum):
51
- """Confidence band attached to a detected signal."""
52
-
53
- HIGH = "high"
54
- MEDIUM = "medium"
55
- LOW = "low"
56
-
57
-
58
- class EngagementLevel(str, enum.Enum):
59
- """Coarse engagement state of the analyzed subject."""
60
-
61
- ENGAGED = "engaged"
62
- NEUTRAL = "neutral"
63
- DISENGAGED = "disengaged"
64
-
65
-
66
- class GoalDimension(str, enum.Enum):
67
- """Interaction-goal dimensions used for feedback and conversation quality."""
68
-
69
- CLARITY = "clarity"
70
- AUTHORITY = "authority"
71
- ENERGY = "energy"
72
- RAPPORT = "rapport"
73
- LEARNING = "learning"
74
-
75
-
76
- class IncludeFlag(str, enum.Enum):
77
- """Optional response sections selectable on upload and stream analysis."""
78
-
79
- CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
80
- CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
81
-
82
-
83
- class AnalysisGroup(str, enum.Enum):
84
- """Analysis track groups selectable on the realtime API."""
85
-
86
- VISUAL = "visual"
87
- AUDIO = "audio"
88
-
89
-
90
- class RealtimeRecommendationFrequency(str, enum.Enum):
91
- """How often the realtime API generates feedback output.
92
-
93
- ``HIGH`` is roughly every 10 seconds of analyzed video, ``MEDIUM`` every
94
- 20 seconds, and ``LOW`` every 30 seconds.
95
- """
96
-
97
- HIGH = "high"
98
- MEDIUM = "medium"
99
- LOW = "low"
100
-
101
-
102
- class Signal(BaseModel):
103
- """A detected social signal over a time range.
104
-
105
- ``modality`` names the analysis modalities that detected this signal. When
106
- several tracks detect the same signal, every contributing modality is
107
- included.
108
- """
109
-
110
- type: SignalType
111
- start: float
112
- end: float
113
- probability: Probability | None = None
114
- rationale: str | None = None
115
- modality: list[str] = Field(default_factory=list)
116
-
117
-
118
- class EngagementStateEntry(BaseModel):
119
- """An engagement state over a time range."""
120
-
121
- state: EngagementLevel
122
- start: float
123
- end: float
124
-
125
-
126
- class ConversationQualityValues(BaseModel):
127
- """Conversation-quality scores (0-100; 50 means no evidence either way)."""
128
-
129
- quality_index: float
130
- clarity: float
131
- authority: float
132
- energy: float
133
- rapport: float
134
- learning: float
135
-
136
-
137
- class ConversationQualityTimelineEntry(BaseModel):
138
- """Conversation-quality scores for one slice of the video."""
139
-
140
- start: float
141
- end: float
142
- values: ConversationQualityValues
143
-
144
-
145
- class ConversationQuality(BaseModel):
146
- """Conversation-quality section of an analysis result."""
147
-
148
- overall: ConversationQualityValues
149
- timeline: list[ConversationQualityTimelineEntry] = Field(default_factory=list)
150
-
151
-
152
- class Feedback(BaseModel):
153
- """Actionable interaction feedback generated from the analysis."""
154
-
155
- type: Literal["feedback"] = "feedback"
156
- message: str
157
- active_dimensions: list[GoalDimension] = Field(default_factory=list)
158
- primary_signal: SignalType | None = None
159
-
160
-
161
- class NoFeedback(BaseModel):
162
- """Explicit indication that no feedback was warranted, with the reason."""
163
-
164
- type: Literal["no_feedback"] = "no_feedback"
165
- reason: str
166
-
167
-
168
- InteractionFeedback = Annotated[Feedback | NoFeedback, Field(discriminator="type")]
169
- """Feedback section of an analysis result, discriminated on ``type``."""
170
-
171
-
172
- class AnalysisResult(BaseModel):
173
- """Response of ``POST /v1/upload/analyze``.
174
-
175
- Optional sections are only present when requested: ``feedback`` when goal
176
- dimensions or a conversation context were supplied, ``conversation_quality``
177
- when requested via include flags.
178
- """
179
-
180
- signals: list[Signal] = Field(default_factory=list)
181
- engagement_state: list[EngagementStateEntry] = Field(default_factory=list)
182
- feedback: InteractionFeedback | None = None
183
- conversation_quality: ConversationQuality | None = None
184
-
185
-
186
- class StreamModel(str, enum.Enum):
187
- """Inter-2 models a ``WS /v2/stream/analyze`` session can select.
188
-
189
- ``INTER_2`` (the default) reads the video. ``INTER_2_AUDIO`` hears the
190
- audio alone: it accepts the same WebM and fragmented MP4 clips, with or
191
- without a video track, and raw PCM frames once the session config declares
192
- an :class:`RawAudioFormat`, and reports a subset of the signals
193
- ``INTER_2`` reports (agreement, confidence, frustration, hesitation,
194
- interest, uncertainty). ``WS /v1/stream/analyze`` offers no selection and
195
- rejects any value.
196
- """
197
-
198
- INTER_2 = "inter-2"
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
- INTER_2_DEEP = "inter-2-deep"
203
-
204
-
205
- PcmSampleRate = Literal[16000, 24000]
206
- """Sample rates accepted for raw PCM frames."""
207
-
208
-
209
- class RawAudioFormat(BaseModel):
210
- """Declares that a session's binary frames are raw audio, not container media.
211
-
212
- Signed 16-bit little-endian PCM at ``sample_rate``, mono, with no header;
213
- frames may be cut at any byte boundary. Accepted on
214
- ``StreamModel.INTER_2_AUDIO`` sessions only.
215
-
216
- Attributes:
217
- encoding: Always ``pcm_s16le``.
218
- sample_rate: Samples per second, 16000 or 24000.
219
- channels: Always ``1``.
220
- """
221
-
222
- encoding: Literal["pcm_s16le"] = "pcm_s16le"
223
- sample_rate: PcmSampleRate = 16000
224
- channels: Literal[1] = 1
225
-
226
-
227
- class UploadModel(str, enum.Enum):
228
- """Inter-2 models a ``POST /v2/upload/analyze`` job can name.
229
-
230
- ``INTER_2`` reads a video (picture and sound together): an mp4, mov, avi,
231
- mkv, webm or mpeg-ts file carrying both a video and an audio track.
232
- ``INTER_2_AUDIO`` reads the audio alone: a wav, flac, mp3, m4a or ogg
233
- file, or a webm or mp4 carrying an audio track. It reports a subset of the
234
- signals ``INTER_2`` reports (agreement, confidence, frustration,
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.
241
- """
242
-
243
- INTER_2 = "inter-2"
244
- INTER_2_AUDIO = "inter-2-audio"
245
- INTER_2_DEEP = "inter-2-deep"
246
-
247
-
248
- class UploadJobIncludeFlag(str, enum.Enum):
249
- """Whole-file sections a ``POST /v2/upload/analyze`` job's result can carry.
250
-
251
- The two :class:`IncludeFlag` Conversation Quality Index sections, plus
252
- ``SIGNALS`` for the whole-file signal list
253
- (:attr:`UploadJobResult.signals`). ``SIGNALS`` is a v2 upload option only;
254
- :meth:`~interhumanai.UploadClient.analyze` and the stream do not take it.
255
- """
256
-
257
- CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
258
- CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
259
- SIGNALS = "signals"
260
-
261
-
262
- class UploadJobStatus(str, enum.Enum):
263
- """Lifecycle of a ``POST /v2/upload/analyze`` job.
264
-
265
- ``QUEUED`` and ``RUNNING`` are transient; ``COMPLETED`` and ``FAILED`` are
266
- terminal, and the job stays readable until its ``expires_at``.
267
- """
268
-
269
- QUEUED = "queued"
270
- RUNNING = "running"
271
- COMPLETED = "completed"
272
- FAILED = "failed"
273
-
274
-
275
- class UploadJobSignal(BaseModel):
276
- """A social signal detected in one window of an upload job.
277
-
278
- It carries the window's span as its ``start`` and ``end``. Unlike the v1
279
- :class:`Signal`, it has no ``modality``: the job's ``model`` names the
280
- evidence the model read. On a ``UploadModel.INTER_2_AUDIO`` job, the
281
- ``type`` values are a subset of the ones ``UploadModel.INTER_2`` reports:
282
- those it can hear (agreement, confidence, frustration, hesitation, interest
283
- and uncertainty).
284
- """
285
-
286
- type: SignalType
287
- start: float
288
- end: float
289
- probability: Probability | None = None
290
- rationale: str | None = None
291
-
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
-
323
- class UploadJobWindow(BaseModel):
324
- """The analysis of one fixed-length window of an upload job's file.
325
-
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.
330
- """
331
-
332
- index: int
333
- start_seconds: float
334
- end_seconds: float
335
- engagement_status: EngagementLevel
336
- signals: list[UploadJobSignal] = Field(default_factory=list)
337
- reasoning: UploadJobReasoning | None = None
338
-
339
-
340
- class UploadJobConversationQuality(BaseModel):
341
- """The Conversation Quality Index of a completed upload job.
342
-
343
- Scored once over the whole file from every window's signals and engagement.
344
- Each section is set only when :meth:`~interhumanai.UploadClient.submit` asked
345
- for it with the matching :class:`IncludeFlag`: ``overall`` for
346
- ``CONVERSATION_QUALITY_OVERALL``, ``timeline`` for
347
- ``CONVERSATION_QUALITY_TIMELINE``. A requested section is present even when
348
- no signal was detected; every dimension then reads the neutral 50.
349
- """
350
-
351
- overall: ConversationQualityValues | None = None
352
- timeline: list[ConversationQualityTimelineEntry] | None = None
353
-
354
-
355
- class UploadJobResult(BaseModel):
356
- """The result of a completed upload job: one entry per analyzed window.
357
-
358
- ``signals`` is every window's signals as one list over the whole file, in
359
- chronological order, merged by the same rules as
360
- :meth:`~interhumanai.UploadClient.analyze` and with no ``modality``:
361
- signals of the same type in adjacent windows become one span, which keeps
362
- the highest probability and that signal's rationale. It is set only when the submit
363
- passed :attr:`UploadJobIncludeFlag.SIGNALS`, and is then an empty list when
364
- nothing was detected; ``windows`` are unchanged either way.
365
-
366
- ``conversation_quality`` is present only when the submit passed at least one
367
- Conversation Quality Index flag, and carries the sections those flags named.
368
- """
369
-
370
- duration_seconds: float
371
- window_seconds: float
372
- windows: list[UploadJobWindow] = Field(default_factory=list)
373
- signals: list[UploadJobSignal] | None = None
374
- conversation_quality: UploadJobConversationQuality | None = None
375
-
376
-
377
- class UploadJobError(BaseModel):
378
- """Why an upload job failed, in the API's standard error-body shape."""
379
-
380
- error_id: str
381
- correlation_id: str | None = None
382
- link: str | None = None
383
- message: str | None = None
384
-
385
-
386
- class UploadJob(BaseModel):
387
- """The job envelope both v2 upload routes answer with.
388
-
389
- Returned by ``POST /v2/upload/analyze`` and ``GET /v2/upload/jobs/{job_id}``
390
- alike. ``result`` is set only when ``status`` is ``COMPLETED``; ``error`` only
391
- when it is ``FAILED``. ``status_url`` is the status resource's path,
392
- relative to the API base URL.
393
- """
394
-
395
- job_id: str
396
- status: UploadJobStatus
397
- model: UploadModel
398
- created_at: datetime
399
- expires_at: datetime
400
- status_url: str
401
- result: UploadJobResult | None = None
402
- error: UploadJobError | None = None
403
-
404
- @property
405
- def is_terminal(self) -> bool:
406
- """Whether the job has finished, successfully or not."""
407
- return self.status in (UploadJobStatus.COMPLETED, UploadJobStatus.FAILED)
File without changes
File without changes