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.
- {interhumanai-2.0.0 → interhumanai-3.2.1}/CHANGELOG.md +43 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/PKG-INFO +14 -5
- {interhumanai-2.0.0 → interhumanai-3.2.1}/README.md +13 -4
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/__init__.py +22 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_version.py +1 -1
- interhumanai-3.2.1/src/interhumanai/types.py +710 -0
- interhumanai-2.0.0/src/interhumanai/types.py +0 -407
- {interhumanai-2.0.0 → interhumanai-3.2.1}/.gitignore +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/LICENSE +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/pyproject.toml +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_http.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_sdk_metadata.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/_session_socket.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/auth.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/client.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/config.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/errors.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/py.typed +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/realtime.py +0 -0
- {interhumanai-2.0.0 → interhumanai-3.2.1}/src/interhumanai/stream.py +0 -0
- {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.
|
|
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).
|
|
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
|
-
(`
|
|
194
|
-
`
|
|
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.
|
|
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).
|
|
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
|
-
(`
|
|
168
|
-
`
|
|
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.
|
|
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",
|
|
@@ -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
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|