interhumanai 3.0.0__tar.gz → 3.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,47 @@ 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.3.0
9
+
10
+ - Added the ``language`` argument to ``UploadClient.submit``: the spoken
11
+ language as an ISO 639 code such as ``"en"``. An ``UploadModel.INTER_2_DEEP``
12
+ job's transcript is then made in that language rather than a detected one.
13
+ Any other model raises ``ih4005``.
14
+ - Added ``UploadJobTranscript.language_source`` (``"requested"`` or
15
+ ``"detected"``) and ``UploadJobTranscript.language_probability`` (the
16
+ recognizer's 0–1 confidence in a detected language, where it reports one).
17
+ A detected ``language`` is best-effort.
18
+
19
+ ## 3.2.1
20
+
21
+ - Documentation only: when no speaker could be identified as on camera, the
22
+ lexical and speech cues of an ``UploadModel.INTER_2_DEEP`` job cover every
23
+ speaker, with ``speaker_role`` as ``None``, rather than the block being
24
+ ``FAILED``.
25
+
26
+ ## 3.2.0
27
+
28
+ - Added three ``UploadJobIncludeFlag`` values for ``UploadModel.INTER_2_DEEP``
29
+ jobs, with their result types: ``VISUAL_CUES``
30
+ (``UploadJobResult.visual_cues``, behaviors seen on camera), ``LEXICAL_CUES``
31
+ (``UploadJobResult.lexical_cues``, features of how the words were chosen) and
32
+ ``SPEECH_CUES`` (``UploadJobResult.speech_cues``, changes in how a speaker
33
+ sounds). Each block carries its own ``status``, so cues that could not be
34
+ produced do not fail the job. These sections are defined ahead of being
35
+ served: until a deployment serves one, a submit that names its flag is
36
+ refused with ``ih1003``.
37
+
38
+ ## 3.1.0
39
+
40
+ - Added ``UploadJobIncludeFlag.TRANSCRIPT`` and ``UploadJobResult.transcript``.
41
+ A ``UploadModel.INTER_2_DEEP`` job submitted with the flag carries a
42
+ transcript of the whole file: every word with its times and speaker
43
+ (``UploadJobTranscriptWord``), and who spoke when
44
+ (``UploadJobTranscriptSegment``). ``UploadJobTranscript.status`` tells a
45
+ transcribed file, even one with no speech, from a transcript that could not
46
+ be produced; the second carries ``error`` and does not fail the job. The API
47
+ refuses the flag for any other model.
48
+
8
49
  ## 3.0.0
9
50
 
10
51
  - **Breaking:** renamed the five section fields of ``UploadJobReasoning`` to
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: interhumanai
3
- Version: 3.0.0
3
+ Version: 3.3.0
4
4
  Summary: First-party Python SDK for the Interhuman API: upload and stream social-signal analysis.
5
5
  Project-URL: Homepage, https://docs.interhuman.ai
6
6
  Project-URL: Repository, https://github.com/interhuman-core/interhuman-api
@@ -167,7 +167,20 @@ 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
+ `transcript.language_source` says whether `language` is the one you named
176
+ (`"requested"`) or the recognizer's guess (`"detected"`), which is
177
+ best-effort: pass `language="en"` (any ISO 639 code) to `submit` wherever
178
+ you know the spoken language. Only `INTER_2_DEEP` takes it.
179
+ `VISUAL_CUES`, `LEXICAL_CUES` and `SPEECH_CUES` add `visual_cues`,
180
+ `lexical_cues` and `speech_cues`: timestamped cue lists, each with its own
181
+ `status`. A deployment serves each list only where it is enabled; a submit
182
+ that names a list the deployment does not serve is refused with `ih1003`. Without a flag the result has no
183
+ such section.
171
184
  - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
172
185
  `error_id` `ih4021` once the job has expired (`job.expires_at`).
173
186
  - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -141,7 +141,20 @@ 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
+ `transcript.language_source` says whether `language` is the one you named
150
+ (`"requested"`) or the recognizer's guess (`"detected"`), which is
151
+ best-effort: pass `language="en"` (any ISO 639 code) to `submit` wherever
152
+ you know the spoken language. Only `INTER_2_DEEP` takes it.
153
+ `VISUAL_CUES`, `LEXICAL_CUES` and `SPEECH_CUES` add `visual_cues`,
154
+ `lexical_cues` and `speech_cues`: timestamped cue lists, each with its own
155
+ `status`. A deployment serves each list only where it is enabled; a submit
156
+ that names a list the deployment does not serve is refused with `ih1003`. Without a flag the result has no
157
+ such section.
145
158
  - `get_job(job_id)` — one status read. Raises `InterhumanAPIError` with
146
159
  `error_id` `ih4021` once the job has expired (`job.expires_at`).
147
160
  - `wait_for_job(job_id, timeout=None, poll_interval=2.0)` — returns the
@@ -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__ = "3.0.0"
3
+ __version__ = "3.3.0"
@@ -250,13 +250,26 @@ class UploadJobIncludeFlag(str, enum.Enum):
250
250
 
251
251
  The two :class:`IncludeFlag` Conversation Quality Index sections, plus
252
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.
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``.
255
264
  """
256
265
 
257
266
  CONVERSATION_QUALITY_OVERALL = "conversation_quality_overall"
258
267
  CONVERSATION_QUALITY_TIMELINE = "conversation_quality_timeline"
259
268
  SIGNALS = "signals"
269
+ TRANSCRIPT = "transcript"
270
+ VISUAL_CUES = "visual_cues"
271
+ LEXICAL_CUES = "lexical_cues"
272
+ SPEECH_CUES = "speech_cues"
260
273
 
261
274
 
262
275
  class UploadJobStatus(str, enum.Enum):
@@ -358,6 +371,296 @@ class UploadJobConversationQuality(BaseModel):
358
371
  timeline: list[ConversationQualityTimelineEntry] | None = None
359
372
 
360
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 the speech was transcribed in, as an ISO 639
448
+ code. When ``language_source`` is ``"detected"`` it is the speech
449
+ recognizer's own guess, which is best-effort and can be wrong:
450
+ pass ``language`` to :meth:`UploadClient.submit` where you know it.
451
+ language_source: Where ``language`` came from: ``"requested"``, the
452
+ language the submit named, or ``"detected"``, the recognizer's
453
+ own guess. ``None`` when ``language`` is, or when the speech
454
+ service did not report it.
455
+ language_probability: The recognizer's confidence, from 0 to 1, in a
456
+ detected language. ``None`` for a requested language and wherever
457
+ the recognizer reports no confidence.
458
+ speaker_roles_status: Whether the speakers could be told apart as on
459
+ camera or off it: ``"mapped"`` when at least one speaker has a
460
+ role, ``"unmapped"`` when none could be told, ``"no_face"`` when no
461
+ face was found in the picture, ``"failed"`` when the step itself
462
+ failed. Only ``speaker_role`` is affected; the words and segments
463
+ are complete in every case. Treat a value not listed here as
464
+ ``"unmapped"``: later versions of the API may add one.
465
+ word_timing: How the word times were measured. ``"asr"`` means they
466
+ are the speech recognizer's own estimates.
467
+ words: Every spoken word, in the order spoken.
468
+ segments: Who spoke when: one entry per stretch of speech, in order.
469
+ error: Why no transcript could be produced. Set only when ``status``
470
+ is ``FAILED``.
471
+ """
472
+
473
+ status: UploadJobTranscriptStatus
474
+ language: str | None = None
475
+ language_source: str | None = None
476
+ language_probability: float | None = None
477
+ speaker_roles_status: str | None = None
478
+ word_timing: str | None = None
479
+ words: list[UploadJobTranscriptWord] = Field(default_factory=list)
480
+ segments: list[UploadJobTranscriptSegment] = Field(default_factory=list)
481
+ error: UploadJobError | None = None
482
+
483
+
484
+ class UploadJobCuesStatus(str, enum.Enum):
485
+ """How one family of cues of an upload job ended.
486
+
487
+ ``COMPLETED`` means the stage ran over the whole file, including when it
488
+ found no cue and the list is empty. ``FAILED`` means the stage could not
489
+ produce its cues; the job's windows and its other sections are unaffected.
490
+ """
491
+
492
+ COMPLETED = "completed"
493
+ FAILED = "failed"
494
+
495
+
496
+ class UploadJobVisualCue(BaseModel):
497
+ """One observable behavior of a person on camera.
498
+
499
+ Attributes:
500
+ label: A short name for the behavior, in lower case. The vocabulary is
501
+ open: the same movement can arrive under more than one name.
502
+ start: Where the behavior starts, in seconds from the start of the file.
503
+ end: Where the behavior ends, in seconds from the start of the file.
504
+ description: One sentence describing what was seen.
505
+ visible_participant: Which person on camera the behavior belongs to,
506
+ as ``"P1"``, ``"P2"`` and so on. It names a body in the picture,
507
+ which is not the transcript's ``speaker`` number.
508
+ context_speaker: Who was speaking while the behavior happened:
509
+ ``"fg_speaker"`` for the person on camera, ``"bg_speaker"`` for a
510
+ voice from off camera, or ``None`` when nobody was speaking or the
511
+ role could not be told.
512
+ """
513
+
514
+ label: str
515
+ start: float
516
+ end: float
517
+ description: str | None = None
518
+ visible_participant: str | None = None
519
+ context_speaker: Literal["fg_speaker", "bg_speaker"] | None = None
520
+
521
+
522
+ class UploadJobLexicalCue(BaseModel):
523
+ """One feature of how a speaker chose and built their words.
524
+
525
+ Attributes:
526
+ label: A short name for what was said, in lower case, such as
527
+ ``"repetition"``, ``"false start"``, ``"hedge"`` or
528
+ ``"filled pause"``. The vocabulary is open: it covers
529
+ disfluencies and also hedges, intensifiers, vague language,
530
+ discourse markers, questions and laughter.
531
+ start: Where the cue starts, in seconds from the start of the file.
532
+ end: Where the cue ends, in seconds from the start of the file.
533
+ quote: The words the cue covers, as spoken.
534
+ core_quote: The fragment the label names, inside ``quote``.
535
+ description: One sentence describing the cue.
536
+ speaker: The speaker, as the number the transcript's segments use.
537
+ speaker_role: ``"fg_speaker"`` for the person on camera,
538
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
539
+ role could not be told.
540
+ word_start: Position of the cue's first word in the
541
+ ``transcript.words`` list of this same result, counting from 0.
542
+ ``None`` when the result carries no completed transcript.
543
+ word_end: Position of the cue's last word in that list, inclusive.
544
+ ``None`` under the same condition.
545
+ """
546
+
547
+ label: str
548
+ start: float
549
+ end: float
550
+ quote: str
551
+ core_quote: str | None = None
552
+ description: str | None = None
553
+ speaker: int | None = None
554
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
555
+ word_start: int | None = None
556
+ word_end: int | None = None
557
+
558
+
559
+ class UploadJobSpeechCue(BaseModel):
560
+ """One change in how a speaker sounds, or one turn-taking event.
561
+
562
+ Attributes:
563
+ label: What was heard, in lower case, such as ``"faster than usual"``,
564
+ ``"higher pitch than usual"`` or ``"backchannel"``.
565
+ feature: What was measured: ``"speech_rate"``, ``"pitch_level"``,
566
+ ``"pitch_range"``, ``"pitch_slope"``, ``"loudness"``,
567
+ ``"response_latency"``, ``"reply_length"``,
568
+ ``"disfluency_rate"``, ``"interruption"`` or ``"backchannel"``.
569
+ Treat a value not listed here as unknown: later versions of the
570
+ API may add one.
571
+ start: Where the cue starts, in seconds from the start of the file.
572
+ end: Where the cue ends, in seconds from the start of the file.
573
+ value: The measurement, in the unit of its ``feature``: syllables
574
+ per second for ``speech_rate``; semitones (12 times the base-2
575
+ logarithm of the frequency in hertz) for ``pitch_level``;
576
+ semitones between the low and the high of the pitch for
577
+ ``pitch_range``; semitones per second for ``pitch_slope``;
578
+ decibels for ``loudness``; seconds before the reply for
579
+ ``response_latency``; words for ``reply_length``; hesitations per
580
+ 100 words for ``disfluency_rate``; seconds of overlap for
581
+ ``interruption``. ``None`` for a ``backchannel``.
582
+ z: How unusual the measurement is, in standard deviations from the
583
+ rest of the analyzed speech in this file. For ``reply_length`` it
584
+ is taken on a logarithmic scale. ``None`` for a ``backchannel``
585
+ or an ``interruption``, which are not compared with a baseline.
586
+ description: One sentence describing the cue.
587
+ quote: The words spoken during the cue, when it covers words.
588
+ speaker: The speaker, as the number the transcript's segments use.
589
+ speaker_role: ``"fg_speaker"`` for the person on camera,
590
+ ``"bg_speaker"`` for a voice from off camera, or ``None`` when the
591
+ role could not be told.
592
+ word_start: Position of the cue's first word in the
593
+ ``transcript.words`` list of this same result, counting from 0.
594
+ ``None`` when the cue covers no words or the result carries no
595
+ completed transcript.
596
+ word_end: Position of the cue's last word in that list, inclusive.
597
+ ``None`` under the same conditions.
598
+ """
599
+
600
+ label: str
601
+ feature: str
602
+ start: float
603
+ end: float
604
+ value: float | None = None
605
+ z: float | None = None
606
+ description: str | None = None
607
+ quote: str | None = None
608
+ speaker: int | None = None
609
+ speaker_role: Literal["fg_speaker", "bg_speaker"] | None = None
610
+ word_start: int | None = None
611
+ word_end: int | None = None
612
+
613
+
614
+ class UploadJobVisualCues(BaseModel):
615
+ """The visual cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
616
+
617
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
618
+ was seen. ``FAILED`` carries ``error`` and no cues. Either way the job
619
+ itself completed.
620
+ """
621
+
622
+ status: UploadJobCuesStatus
623
+ cues: list[UploadJobVisualCue] = Field(default_factory=list)
624
+ error: UploadJobError | None = None
625
+
626
+
627
+ class UploadJobLexicalCues(BaseModel):
628
+ """The lexical cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
629
+
630
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
631
+ stood out. ``FAILED`` carries ``error`` and no cues. Either way the job
632
+ itself completed.
633
+
634
+ The cues cover the speech of the person on camera. An off-camera speaker
635
+ is not analyzed. When no speaker could be identified as on camera, every
636
+ speaker is analyzed and each cue's ``speaker_role`` is ``None``.
637
+ """
638
+
639
+ status: UploadJobCuesStatus
640
+ cues: list[UploadJobLexicalCue] = Field(default_factory=list)
641
+ error: UploadJobError | None = None
642
+
643
+
644
+ class UploadJobSpeechCues(BaseModel):
645
+ """The speech cues of a completed ``UploadModel.INTER_2_DEEP`` job that asked for them.
646
+
647
+ Read ``status`` first. ``COMPLETED`` carries ``cues``, empty when nothing
648
+ stood out or the file holds too little speech to judge a speaker against
649
+ themselves. ``FAILED`` carries ``error`` and no cues. Either way the job
650
+ itself completed.
651
+
652
+ The cues cover the speech of the person on camera, judged against the rest
653
+ of that person's speech in the file. An off-camera speaker is not
654
+ analyzed. When no speaker could be identified as on camera, every speaker
655
+ is analyzed, each against the rest of the speech in the file, and each
656
+ cue's ``speaker_role`` is ``None``.
657
+ """
658
+
659
+ status: UploadJobCuesStatus
660
+ cues: list[UploadJobSpeechCue] = Field(default_factory=list)
661
+ error: UploadJobError | None = None
662
+
663
+
361
664
  class UploadJobResult(BaseModel):
362
665
  """The result of a completed upload job: one entry per analyzed window.
363
666
 
@@ -371,6 +674,17 @@ class UploadJobResult(BaseModel):
371
674
 
372
675
  ``conversation_quality`` is present only when the submit passed at least one
373
676
  Conversation Quality Index flag, and carries the sections those flags named.
677
+
678
+ ``transcript`` is a transcript of the whole file with speakers and word
679
+ times. It is set only when the submit passed
680
+ :attr:`UploadJobIncludeFlag.TRANSCRIPT`, which ``UploadModel.INTER_2_DEEP``
681
+ jobs accept. A transcript that could not be produced is still set, with
682
+ ``status`` ``FAILED``, and does not fail the job.
683
+
684
+ ``visual_cues``, ``lexical_cues`` and ``speech_cues`` are timestamped cue
685
+ lists, each set only when the submit passed the matching
686
+ :class:`UploadJobIncludeFlag`. Each carries its own ``status``, so one
687
+ family that could not be produced does not fail the job or the others.
374
688
  """
375
689
 
376
690
  duration_seconds: float
@@ -378,15 +692,10 @@ class UploadJobResult(BaseModel):
378
692
  windows: list[UploadJobWindow] = Field(default_factory=list)
379
693
  signals: list[UploadJobSignal] | None = None
380
694
  conversation_quality: UploadJobConversationQuality | None = None
381
-
382
-
383
- class UploadJobError(BaseModel):
384
- """Why an upload job failed, in the API's standard error-body shape."""
385
-
386
- error_id: str
387
- correlation_id: str | None = None
388
- link: str | None = None
389
- message: str | None = None
695
+ transcript: UploadJobTranscript | None = None
696
+ visual_cues: UploadJobVisualCues | None = None
697
+ lexical_cues: UploadJobLexicalCues | None = None
698
+ speech_cues: UploadJobSpeechCues | None = None
390
699
 
391
700
 
392
701
  class UploadJob(BaseModel):
@@ -127,6 +127,7 @@ class UploadClient:
127
127
  model: UploadModel | str,
128
128
  wait_seconds: int = 0,
129
129
  include: Sequence[UploadJobIncludeFlag | IncludeFlag | str] | None = None,
130
+ language: str | None = None,
130
131
  filename: str | None = None,
131
132
  content_type: str | None = None,
132
133
  ) -> UploadJob:
@@ -174,6 +175,12 @@ class UploadClient:
174
175
  :meth:`analyze` takes, so :class:`IncludeFlag` members work
175
176
  too) for the quality block, and ``SIGNALS`` for the signal
176
177
  list. Omit a flag for no such section.
178
+ language: The language spoken in the file, as a two- or
179
+ three-letter ISO 639 code such as ``"en"``.
180
+ ``UploadModel.INTER_2_DEEP`` accepts it, and its transcript is
181
+ then made in that language. Without it the speech recognizer
182
+ detects the language, which is best-effort. Any other model
183
+ raises ``ih4005``.
177
184
  filename: Filename reported to the API. Defaults to the path or
178
185
  file object's name, else ``video``.
179
186
  content_type: MIME type of the file (e.g. ``video/mp4``).
@@ -194,6 +201,8 @@ class UploadClient:
194
201
  flag.value if isinstance(flag, (IncludeFlag, UploadJobIncludeFlag)) else flag
195
202
  for flag in include
196
203
  ]
204
+ if language:
205
+ data["language"] = language
197
206
  headers = {"Authorization": f"Bearer {token}"}
198
207
  url = self._base_url + "/v2/upload/analyze"
199
208
  payload = await self._request(
File without changes
File without changes