behavioralsignals 1.0.0__tar.gz → 1.2.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.
Files changed (35) hide show
  1. {behavioralsignals-1.0.0/src/behavioralsignals.egg-info → behavioralsignals-1.2.0}/PKG-INFO +29 -5
  2. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/README.md +28 -4
  3. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/pyproject.toml +1 -1
  4. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/__init__.py +5 -2
  5. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/base.py +66 -4
  6. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/behavioral.py +41 -31
  7. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/deepfakes.py +29 -26
  8. behavioralsignals-1.2.0/src/behavioralsignals/generated/api_pb2.py +52 -0
  9. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/generated/api_pb2.pyi +10 -4
  10. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/mcp_server.py +10 -1
  11. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/models.py +17 -2
  12. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0/src/behavioralsignals.egg-info}/PKG-INFO +29 -5
  13. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_client.py +17 -0
  14. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_mcp_server.py +29 -0
  15. behavioralsignals-1.2.0/tests/test_streaming.py +406 -0
  16. behavioralsignals-1.0.0/src/behavioralsignals/generated/api_pb2.py +0 -52
  17. behavioralsignals-1.0.0/tests/test_streaming.py +0 -151
  18. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/LICENSE +0 -0
  19. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/setup.cfg +0 -0
  20. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/client.py +0 -0
  21. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/configuration.py +0 -0
  22. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/generated/__init__.py +0 -0
  23. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/generated/api_pb2_grpc.py +0 -0
  24. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/py.typed +0 -0
  25. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals/utils.py +0 -0
  26. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals.egg-info/SOURCES.txt +0 -0
  27. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals.egg-info/dependency_links.txt +0 -0
  28. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals.egg-info/entry_points.txt +0 -0
  29. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals.egg-info/requires.txt +0 -0
  30. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/src/behavioralsignals.egg-info/top_level.txt +0 -0
  31. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_examples.py +0 -0
  32. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_models.py +0 -0
  33. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_package.py +0 -0
  34. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_utils.py +0 -0
  35. {behavioralsignals-1.0.0 → behavioralsignals-1.2.0}/tests/test_wait_for_result.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: behavioralsignals
3
- Version: 1.0.0
3
+ Version: 1.2.0
4
4
  Summary: Official Python SDK for the Behavioral Signals API: voice emotion/behavior analysis and audio/video deepfake detection
5
5
  Author: Behavioral Signal Technologies
6
6
  License: Apache License
@@ -421,6 +421,8 @@ for item in result.results:
421
421
  print(item.st, "arousal", scores["strong"] - scores["weak"])
422
422
  ```
423
423
 
424
+ The API can also return a valence and an arousal score directly: see [Continuous valence and arousal](#continuous-valence-and-arousal).
425
+
424
426
  All probabilities are model estimates: use them to compare utterances and follow trends, not as exact measurements.
425
427
 
426
428
  See [Definition of behaviors](https://behavioralsignals.readme.io/docs/definition-of-behaviors) for what each signal means.
@@ -528,6 +530,10 @@ for result in client.behavioral.stream_audio(
528
530
 
529
531
  `stream_audio()` can also accept your own `Iterator[bytes]`, for example from a microphone or live call.
530
532
 
533
+ If you know when the caller's turn has ended, for example from your voice agent's turn detector, yield `END_OF_TURN` (from `behavioralsignals`) from the iterator at that point. The SDK sends it as its own message, with no audio, to tell the server that the turn has ended. Yield it once per turn, and only for a final end of turn, never for a guess. It is sent when your iterator yields it, so an iterator that waits for audio must be woken up to yield it.
534
+
535
+ To stop a stream early, call `cancel()` on what `stream_audio()` returns. You can call it from another thread; the loop over the results then ends, with no error.
536
+
531
537
  For real-time deepfake detection, use the same interface:
532
538
 
533
539
  ```python
@@ -559,6 +565,24 @@ Each flag is a result with `task="focus"` and `finalLabel="suspected_<label>"`,
559
565
 
560
566
  A stream's focus results are saved with its results: `get_result` returns them, and replaces them if you pass `focus`.
561
567
 
568
+ ## Continuous valence and arousal
569
+
570
+ Ask for `continuous` values to get a valence and an arousal score for every utterance (and, in streaming, every segment), from -1 to 1. Unlike Focus there is no threshold: every utterance with behavioral results gets a value. It is available in the Behavioral API, for batch and streaming.
571
+
572
+ ```python
573
+ # Batch
574
+ result = client.behavioral.wait_for_result(pid=process.pid, continuous=["valence", "arousal"])
575
+
576
+ # Streaming
577
+ options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM", continuous=["valence", "arousal"])
578
+
579
+ for item in result.results:
580
+ if item.task in ("continuous_valence", "continuous_arousal"):
581
+ print(item.st, item.task, float(item.prediction[0].score))
582
+ ```
583
+
584
+ Each value is a result with `task="continuous_valence"` or `"continuous_arousal"` and the value in `score`, with the same time span as its utterance or segment. It can be combined with `focus`.
585
+
562
586
  ## Available Methods
563
587
 
564
588
  `client.behavioral` and `client.deepfakes` expose the same methods for audio. Video methods are available only on `client.deepfakes`.
@@ -567,11 +591,11 @@ A stream's focus results are saved with its results: `get_result` returns them,
567
591
  |---|---|
568
592
  | `upload_audio(file_path, ...)` | Uploads an audio file and returns the process, including its `pid` |
569
593
  | `upload_s3_presigned_url(url, ...)` | Submits audio using an S3 presigned URL |
570
- | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results. Behavioral also takes `focus` and `sensitivity` (see [Focus](#focus)) |
571
- | `get_result(pid)` | Returns the results of a finished process. Behavioral also takes `focus` and `sensitivity` |
594
+ | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results. Behavioral also takes `focus` and `sensitivity` (see [Focus](#focus)), and `continuous` (see [Continuous valence and arousal](#continuous-valence-and-arousal)) |
595
+ | `get_result(pid)` | Returns the results of a finished process. Behavioral also takes `focus`, `sensitivity` and `continuous` |
572
596
  | `get_process(pid)` | Returns a process and its current status |
573
597
  | `list_processes(...)` | Lists audio processes |
574
- | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive |
598
+ | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive. The iterator can also yield `END_OF_TURN` when the caller's turn has ended (see [Streaming](#streaming)). Call `cancel()` on what it returns to stop the stream |
575
599
  | `upload_video(file_path, ...)` | Deepfakes only: uploads a video file |
576
600
  | `upload_s3_presigned_video_url(url, ...)` | Deepfakes only: submits video using an S3 presigned URL |
577
601
  | `wait_for_video_result(pid, timeout=None)` | Deepfakes only: waits for a video process to finish and returns its results |
@@ -706,7 +730,7 @@ The server exposes four tools:
706
730
  |---|---|
707
731
  | `analyze_behavior` | Uploads an audio file or S3 presigned URL for behavioral analysis and returns the results |
708
732
  | `detect_deepfake` | Uploads an audio or video file, or an S3 presigned URL, for deepfake detection (video is experimental) and returns the results |
709
- | `get_result` | Returns the results of a process, in pages, optionally filtered to specific tasks. Each row has the final label and the probability of every label. Behavioral results can also include [Focus](#focus) rows, with `focus` and `sensitivity` |
733
+ | `get_result` | Returns the results of a process, in pages, optionally filtered to specific tasks. Each row has the final label and the probability of every label. Behavioral results can also include [Focus](#focus) rows, with `focus` and `sensitivity`, and [continuous valence and arousal](#continuous-valence-and-arousal) rows, with `continuous` |
710
734
  | `list_processes` | Lists processes, newest first, including the failure reason when available |
711
735
 
712
736
  Notes:
@@ -175,6 +175,8 @@ for item in result.results:
175
175
  print(item.st, "arousal", scores["strong"] - scores["weak"])
176
176
  ```
177
177
 
178
+ The API can also return a valence and an arousal score directly: see [Continuous valence and arousal](#continuous-valence-and-arousal).
179
+
178
180
  All probabilities are model estimates: use them to compare utterances and follow trends, not as exact measurements.
179
181
 
180
182
  See [Definition of behaviors](https://behavioralsignals.readme.io/docs/definition-of-behaviors) for what each signal means.
@@ -282,6 +284,10 @@ for result in client.behavioral.stream_audio(
282
284
 
283
285
  `stream_audio()` can also accept your own `Iterator[bytes]`, for example from a microphone or live call.
284
286
 
287
+ If you know when the caller's turn has ended, for example from your voice agent's turn detector, yield `END_OF_TURN` (from `behavioralsignals`) from the iterator at that point. The SDK sends it as its own message, with no audio, to tell the server that the turn has ended. Yield it once per turn, and only for a final end of turn, never for a guess. It is sent when your iterator yields it, so an iterator that waits for audio must be woken up to yield it.
288
+
289
+ To stop a stream early, call `cancel()` on what `stream_audio()` returns. You can call it from another thread; the loop over the results then ends, with no error.
290
+
285
291
  For real-time deepfake detection, use the same interface:
286
292
 
287
293
  ```python
@@ -313,6 +319,24 @@ Each flag is a result with `task="focus"` and `finalLabel="suspected_<label>"`,
313
319
 
314
320
  A stream's focus results are saved with its results: `get_result` returns them, and replaces them if you pass `focus`.
315
321
 
322
+ ## Continuous valence and arousal
323
+
324
+ Ask for `continuous` values to get a valence and an arousal score for every utterance (and, in streaming, every segment), from -1 to 1. Unlike Focus there is no threshold: every utterance with behavioral results gets a value. It is available in the Behavioral API, for batch and streaming.
325
+
326
+ ```python
327
+ # Batch
328
+ result = client.behavioral.wait_for_result(pid=process.pid, continuous=["valence", "arousal"])
329
+
330
+ # Streaming
331
+ options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM", continuous=["valence", "arousal"])
332
+
333
+ for item in result.results:
334
+ if item.task in ("continuous_valence", "continuous_arousal"):
335
+ print(item.st, item.task, float(item.prediction[0].score))
336
+ ```
337
+
338
+ Each value is a result with `task="continuous_valence"` or `"continuous_arousal"` and the value in `score`, with the same time span as its utterance or segment. It can be combined with `focus`.
339
+
316
340
  ## Available Methods
317
341
 
318
342
  `client.behavioral` and `client.deepfakes` expose the same methods for audio. Video methods are available only on `client.deepfakes`.
@@ -321,11 +345,11 @@ A stream's focus results are saved with its results: `get_result` returns them,
321
345
  |---|---|
322
346
  | `upload_audio(file_path, ...)` | Uploads an audio file and returns the process, including its `pid` |
323
347
  | `upload_s3_presigned_url(url, ...)` | Submits audio using an S3 presigned URL |
324
- | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results. Behavioral also takes `focus` and `sensitivity` (see [Focus](#focus)) |
325
- | `get_result(pid)` | Returns the results of a finished process. Behavioral also takes `focus` and `sensitivity` |
348
+ | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results. Behavioral also takes `focus` and `sensitivity` (see [Focus](#focus)), and `continuous` (see [Continuous valence and arousal](#continuous-valence-and-arousal)) |
349
+ | `get_result(pid)` | Returns the results of a finished process. Behavioral also takes `focus`, `sensitivity` and `continuous` |
326
350
  | `get_process(pid)` | Returns a process and its current status |
327
351
  | `list_processes(...)` | Lists audio processes |
328
- | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive |
352
+ | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive. The iterator can also yield `END_OF_TURN` when the caller's turn has ended (see [Streaming](#streaming)). Call `cancel()` on what it returns to stop the stream |
329
353
  | `upload_video(file_path, ...)` | Deepfakes only: uploads a video file |
330
354
  | `upload_s3_presigned_video_url(url, ...)` | Deepfakes only: submits video using an S3 presigned URL |
331
355
  | `wait_for_video_result(pid, timeout=None)` | Deepfakes only: waits for a video process to finish and returns its results |
@@ -460,7 +484,7 @@ The server exposes four tools:
460
484
  |---|---|
461
485
  | `analyze_behavior` | Uploads an audio file or S3 presigned URL for behavioral analysis and returns the results |
462
486
  | `detect_deepfake` | Uploads an audio or video file, or an S3 presigned URL, for deepfake detection (video is experimental) and returns the results |
463
- | `get_result` | Returns the results of a process, in pages, optionally filtered to specific tasks. Each row has the final label and the probability of every label. Behavioral results can also include [Focus](#focus) rows, with `focus` and `sensitivity` |
487
+ | `get_result` | Returns the results of a process, in pages, optionally filtered to specific tasks. Each row has the final label and the probability of every label. Behavioral results can also include [Focus](#focus) rows, with `focus` and `sensitivity`, and [continuous valence and arousal](#continuous-valence-and-arousal) rows, with `continuous` |
464
488
  | `list_processes` | Lists processes, newest first, including the failure reason when available |
465
489
 
466
490
  Notes:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "behavioralsignals"
3
- version = "1.0.0"
3
+ version = "1.2.0"
4
4
  description = "Official Python SDK for the Behavioral Signals API: voice emotion/behavior analysis and audio/video deepfake detection"
5
5
  readme = "README.md"
6
6
  authors = [{ name = "Behavioral Signal Technologies" }]
@@ -1,8 +1,8 @@
1
1
  from importlib.metadata import PackageNotFoundError, version
2
2
 
3
- from .base import BehavioralSignalsError
3
+ from .base import StreamingResults, BehavioralSignalsError
4
4
  from .client import Client
5
- from .models import StreamingOptions, VideoResultResponse
5
+ from .models import END_OF_TURN, EndOfTurn, StreamingOptions, VideoResultResponse
6
6
  from .deepfakes import Deepfakes
7
7
  from .behavioral import Behavioral
8
8
 
@@ -13,10 +13,13 @@ except PackageNotFoundError: # running from source without installing
13
13
  __version__ = "unknown"
14
14
 
15
15
  __all__ = [
16
+ "END_OF_TURN",
16
17
  "Behavioral",
17
18
  "BehavioralSignalsError",
18
19
  "Client",
19
20
  "Deepfakes",
21
+ "EndOfTurn",
20
22
  "StreamingOptions",
23
+ "StreamingResults",
21
24
  "VideoResultResponse",
22
25
  ]
@@ -1,15 +1,22 @@
1
1
  import os
2
2
  import time
3
- from collections.abc import Callable
3
+ import threading
4
+ from typing import Any
5
+ from collections.abc import Callable, Iterator, Generator
4
6
 
5
7
  import grpc
6
8
  import requests
9
+ from google.protobuf.json_format import MessageToDict
7
10
 
8
- from .models import APIError, ProcessItem, ProcessStatus
11
+ from .models import APIError, ProcessItem, ProcessStatus, StreamingResultResponse
9
12
  from .configuration import DEFAULT_TIMEOUT, DEFAULT_UPLOAD_TIMEOUT, TimeoutType, Configuration
10
13
 
11
14
 
12
15
  POLL_INTERVAL_SECONDS = 1.0
16
+ # A stream pings the API this often, and fails if a ping gets no answer in time. Without this, a
17
+ # network that drops without closing the connection leaves the stream waiting for minutes.
18
+ KEEPALIVE_TIME_MS = 20_000
19
+ KEEPALIVE_TIMEOUT_MS = 10_000
13
20
 
14
21
 
15
22
  class BehavioralSignalsError(Exception):
@@ -20,6 +27,53 @@ class BehavioralSignalsError(Exception):
20
27
  self.status_code = status_code
21
28
 
22
29
 
30
+ class StreamingResults(Iterator[StreamingResultResponse]):
31
+ """The results of a stream, as they arrive. The stream opens on the first `next()`.
32
+
33
+ Call `cancel()`, from any thread, to stop the stream: the loop over the results ends.
34
+ """
35
+
36
+ def __init__(self, open_channel: Callable, start_call: Callable[[grpc.Channel], Any]):
37
+ self._cancelled = threading.Event()
38
+ # The gRPC call, once started: an iterator of responses, with cancel()
39
+ self._calls: list[Any] = []
40
+ # A plain function, not a method: the generator must not hold `self`, or the stream
41
+ # stays open after the caller drops the results without reading them to the end
42
+ self._results = _stream(open_channel, start_call, self._cancelled, self._calls)
43
+
44
+ def __next__(self) -> StreamingResultResponse:
45
+ return next(self._results)
46
+
47
+ def cancel(self) -> None:
48
+ """Stop the stream. The loop over the results ends, with no error."""
49
+ self._cancelled.set()
50
+ for call in self._calls:
51
+ call.cancel()
52
+
53
+ def close(self) -> None:
54
+ """Stop the stream from the thread that reads it, like a generator's `close()`."""
55
+ self._results.close()
56
+
57
+
58
+ def _stream(
59
+ open_channel: Callable, start_call: Callable, cancelled: threading.Event, calls: list
60
+ ) -> Generator[StreamingResultResponse, None, None]:
61
+ if cancelled.is_set():
62
+ return
63
+ with open_channel() as channel:
64
+ call = start_call(channel)
65
+ calls.append(call)
66
+ if cancelled.is_set(): # cancelled while the call started
67
+ call.cancel()
68
+ try:
69
+ for response in call:
70
+ resp_dict = MessageToDict(response, always_print_fields_with_no_presence=True)
71
+ yield StreamingResultResponse(**resp_dict)
72
+ except grpc.RpcError:
73
+ if not cancelled.is_set():
74
+ raise
75
+
76
+
23
77
  def _value_or_env(value: str | int | None, arg_name: str, env_var: str) -> str:
24
78
  """Returns the value, or the environment variable if the value is not given."""
25
79
  if value is None:
@@ -167,8 +221,16 @@ class BaseClient:
167
221
 
168
222
  def _get_channel_context(self):
169
223
  """Returns the channel context for gRPC connections."""
224
+ options = [
225
+ ("grpc.keepalive_time_ms", KEEPALIVE_TIME_MS),
226
+ ("grpc.keepalive_timeout_ms", KEEPALIVE_TIMEOUT_MS),
227
+ # A keepalive can wait on gRPC's own ping instead, which waits 60 s for an answer by default
228
+ ("grpc.http2.ping_timeout_ms", KEEPALIVE_TIMEOUT_MS),
229
+ ]
170
230
  if self.config.use_ssl:
171
231
  credentials = grpc.ssl_channel_credentials()
172
- return grpc.secure_channel(self.config.streaming_api_url, credentials=credentials)
232
+ return grpc.secure_channel(
233
+ self.config.streaming_api_url, credentials=credentials, options=options
234
+ )
173
235
  else:
174
- return grpc.insecure_channel(self.config.streaming_api_url)
236
+ return grpc.insecure_channel(self.config.streaming_api_url, options=options)
@@ -2,10 +2,9 @@ from typing import Literal
2
2
  from pathlib import Path
3
3
  from collections.abc import Iterator
4
4
 
5
- from google.protobuf.json_format import MessageToDict
6
-
7
- from .base import BaseClient
5
+ from .base import BaseClient, StreamingResults
8
6
  from .models import (
7
+ EndOfTurn,
9
8
  ProcessItem,
10
9
  ResultResponse,
11
10
  StreamingOptions,
@@ -13,7 +12,6 @@ from .models import (
13
12
  ProcessListParams,
14
13
  S3UrlUploadParams,
15
14
  ProcessListResponse,
16
- StreamingResultResponse,
17
15
  )
18
16
  from .generated import api_pb2 as pb
19
17
  from .generated import api_pb2_grpc as pb_grpc
@@ -151,6 +149,7 @@ class Behavioral(BaseClient):
151
149
  pid: int,
152
150
  focus: list[str] | None = None,
153
151
  sensitivity: Literal["low", "default", "high"] = "default",
152
+ continuous: list[str] | None = None,
154
153
  ) -> ResultResponse:
155
154
  """Retrieves the result of a completed process by its ID.
156
155
 
@@ -159,16 +158,20 @@ class Behavioral(BaseClient):
159
158
  focus (list[str], optional): Labels to focus on, e.g. ["angry", "low_confidence"].
160
159
  Adds a "focus" result when a label is likely but not the predicted one.
161
160
  sensitivity (str, optional): Focus sensitivity: "low", "default" or "high".
161
+ continuous (list[str], optional): Continuous values, e.g. ["valence", "arousal"].
162
+ Adds a "continuous_<name>" result with a score in [-1, 1].
162
163
  Returns:
163
164
  ResultResponse: The result response containing the results of the specified process.
164
165
  """
165
- params = (
166
- {"focus": ",".join(focus), "sensitivity": sensitivity} if focus is not None else None
167
- )
166
+ params: dict[str, str] = {}
167
+ if focus is not None:
168
+ params.update(focus=",".join(focus), sensitivity=sensitivity)
169
+ if continuous is not None:
170
+ params["continuous"] = ",".join(continuous)
168
171
  data = self._send_request(
169
172
  path=f"clients/{self.config.cid}/processes/{pid}/results",
170
173
  method="GET",
171
- data=params,
174
+ data=params or None,
172
175
  )
173
176
  return ResultResponse(**data)
174
177
 
@@ -178,6 +181,7 @@ class Behavioral(BaseClient):
178
181
  timeout: float | None = None,
179
182
  focus: list[str] | None = None,
180
183
  sensitivity: Literal["low", "default", "high"] = "default",
184
+ continuous: list[str] | None = None,
181
185
  ) -> ResultResponse:
182
186
  """Waits for a process to finish and returns its result.
183
187
 
@@ -188,6 +192,7 @@ class Behavioral(BaseClient):
188
192
  timeout (float, optional): Maximum seconds to wait. Defaults to None (no limit).
189
193
  focus (list[str], optional): Labels to focus on (see `get_result`).
190
194
  sensitivity (str, optional): Focus sensitivity: "low", "default" or "high".
195
+ continuous (list[str], optional): Continuous values (see `get_result`).
191
196
  Returns:
192
197
  ResultResponse: The result response containing the results of the specified process.
193
198
  Raises:
@@ -197,34 +202,39 @@ class Behavioral(BaseClient):
197
202
  retried until `timeout` runs out.
198
203
  """
199
204
  self._wait_for_process(self.get_process, pid, timeout)
200
- return self.get_result(pid, focus, sensitivity)
205
+ return self.get_result(pid, focus, sensitivity, continuous)
201
206
 
202
207
  def stream_audio(
203
- self, audio_stream: Iterator[bytes], options: StreamingOptions
204
- ) -> Iterator[StreamingResultResponse]:
205
- with self._get_channel_context() as channel:
206
- stub = pb_grpc.BehavioralStreamingApiStub(channel)
207
-
208
- def _request_generator() -> Iterator[pb.AudioStream]:
209
- # Streaming API always requires the first message to contain
210
- # the audio configuration and authentication details
211
- audio_config = options.to_pb_config()
212
- req = pb.AudioStream(
213
- cid=int(self.config.cid),
214
- x_auth_token=self.config.api_key,
215
- config=audio_config,
216
- )
217
- yield req
208
+ self, audio_stream: Iterator[bytes | EndOfTurn], options: StreamingOptions
209
+ ) -> StreamingResults:
210
+ def _request_generator() -> Iterator[pb.AudioStream]:
211
+ # Streaming API always requires the first message to contain
212
+ # the audio configuration and authentication details
213
+ audio_config = options.to_pb_config()
214
+ req = pb.AudioStream(
215
+ cid=int(self.config.cid),
216
+ x_auth_token=self.config.api_key,
217
+ config=audio_config,
218
+ )
219
+ yield req
218
220
 
219
- for chunk in audio_stream:
221
+ for chunk in audio_stream:
222
+ if isinstance(chunk, EndOfTurn):
220
223
  yield pb.AudioStream(
221
224
  cid=int(self.config.cid),
222
225
  x_auth_token=self.config.api_key,
223
- audio_content=chunk,
226
+ end_of_turn=True,
224
227
  )
228
+ continue
229
+ yield pb.AudioStream(
230
+ cid=int(self.config.cid),
231
+ x_auth_token=self.config.api_key,
232
+ audio_content=chunk,
233
+ )
225
234
 
226
- response_stream = stub.StreamAudio(_request_generator())
227
- for response in response_stream:
228
- resp_dict = MessageToDict(response, always_print_fields_with_no_presence=True)
229
- response_data = StreamingResultResponse(**resp_dict)
230
- yield response_data
235
+ return StreamingResults(
236
+ self._get_channel_context,
237
+ lambda channel: pb_grpc.BehavioralStreamingApiStub(channel).StreamAudio(
238
+ _request_generator()
239
+ ),
240
+ )
@@ -2,17 +2,15 @@ from typing import Literal
2
2
  from pathlib import Path
3
3
  from collections.abc import Iterator
4
4
 
5
- from google.protobuf.json_format import MessageToDict
6
-
7
- from .base import BaseClient
5
+ from .base import BaseClient, StreamingResults
8
6
  from .models import (
7
+ EndOfTurn,
9
8
  ProcessItem,
10
9
  ResultResponse,
11
10
  StreamingOptions,
12
11
  ProcessListParams,
13
12
  ProcessListResponse,
14
13
  VideoResultResponse,
15
- StreamingResultResponse,
16
14
  DeepfakeAudioUploadParams,
17
15
  DeepfakeS3UrlUploadParams,
18
16
  )
@@ -393,31 +391,36 @@ class Deepfakes(BaseClient):
393
391
  return self.get_video_result(pid)
394
392
 
395
393
  def stream_audio(
396
- self, audio_stream: Iterator[bytes], options: StreamingOptions
397
- ) -> Iterator[StreamingResultResponse]:
398
- with self._get_channel_context() as channel:
399
- stub = pb_grpc.BehavioralStreamingApiStub(channel)
400
-
401
- def _request_generator() -> Iterator[pb.AudioStream]:
402
- # Streaming API always requires the first message to contain
403
- # the audio configuration and authentication details
404
- audio_config = options.to_pb_config()
405
- req = pb.AudioStream(
406
- cid=int(self.config.cid),
407
- x_auth_token=self.config.api_key,
408
- config=audio_config,
409
- )
410
- yield req
394
+ self, audio_stream: Iterator[bytes | EndOfTurn], options: StreamingOptions
395
+ ) -> StreamingResults:
396
+ def _request_generator() -> Iterator[pb.AudioStream]:
397
+ # Streaming API always requires the first message to contain
398
+ # the audio configuration and authentication details
399
+ audio_config = options.to_pb_config()
400
+ req = pb.AudioStream(
401
+ cid=int(self.config.cid),
402
+ x_auth_token=self.config.api_key,
403
+ config=audio_config,
404
+ )
405
+ yield req
411
406
 
412
- for chunk in audio_stream:
407
+ for chunk in audio_stream:
408
+ if isinstance(chunk, EndOfTurn):
413
409
  yield pb.AudioStream(
414
410
  cid=int(self.config.cid),
415
411
  x_auth_token=self.config.api_key,
416
- audio_content=chunk,
412
+ end_of_turn=True,
417
413
  )
414
+ continue
415
+ yield pb.AudioStream(
416
+ cid=int(self.config.cid),
417
+ x_auth_token=self.config.api_key,
418
+ audio_content=chunk,
419
+ )
418
420
 
419
- response_stream = stub.DeepfakeDetection(_request_generator())
420
- for response in response_stream:
421
- resp_dict = MessageToDict(response, always_print_fields_with_no_presence=True)
422
- response_data = StreamingResultResponse(**resp_dict)
423
- yield response_data
421
+ return StreamingResults(
422
+ self._get_channel_context,
423
+ lambda channel: pb_grpc.BehavioralStreamingApiStub(channel).DeepfakeDetection(
424
+ _request_generator()
425
+ ),
426
+ )
@@ -0,0 +1,52 @@
1
+ # -*- coding: utf-8 -*-
2
+ # Generated by the protocol buffer compiler. DO NOT EDIT!
3
+ # NO CHECKED-IN PROTOBUF GENCODE
4
+ # source: api.proto
5
+ # Protobuf Python Version: 6.31.0
6
+ """Generated protocol buffer code."""
7
+ from google.protobuf import descriptor as _descriptor
8
+ from google.protobuf import descriptor_pool as _descriptor_pool
9
+ from google.protobuf import runtime_version as _runtime_version
10
+ from google.protobuf import symbol_database as _symbol_database
11
+ from google.protobuf.internal import builder as _builder
12
+ _runtime_version.ValidateProtobufRuntimeVersion(
13
+ _runtime_version.Domain.PUBLIC,
14
+ 6,
15
+ 31,
16
+ 0,
17
+ '',
18
+ 'api.proto'
19
+ )
20
+ # @@protoc_insertion_point(imports)
21
+
22
+ _sym_db = _symbol_database.Default()
23
+
24
+
25
+
26
+
27
+ DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\tapi.proto\x12\x16\x62\x65havioral_api.grpc.v1\"\xcb\x02\n\x0b\x41udioConfig\x12\x37\n\x08\x65ncoding\x18\x01 \x01(\x0e\x32%.behavioral_api.grpc.v1.AudioEncoding\x12\x19\n\x11sample_rate_hertz\x18\x02 \x01(\x05\x12\x31\n\x05level\x18\x03 \x01(\x0e\x32\x1d.behavioral_api.grpc.v1.LevelH\x00\x88\x01\x01\x12\x13\n\x06logits\x18\x04 \x01(\x08H\x01\x88\x01\x01\x12\x1e\n\x11\x66\x65\x61ture_embedding\x18\x05 \x01(\x08H\x02\x88\x01\x01\x12\x37\n\x05\x66ocus\x18\x06 \x01(\x0b\x32#.behavioral_api.grpc.v1.FocusConfigH\x03\x88\x01\x01\x12\x12\n\ncontinuous\x18\x07 \x03(\tB\x08\n\x06_levelB\t\n\x07_logitsB\x14\n\x12_feature_embeddingB\x08\n\x06_focus\"2\n\x0b\x46ocusConfig\x12\x0e\n\x06labels\x18\x01 \x03(\t\x12\x13\n\x0bsensitivity\x18\x02 \x01(\t\"\xb1\x01\n\x0b\x41udioStream\x12\x0b\n\x03\x63id\x18\x01 \x01(\x03\x12\x14\n\x0cx_auth_token\x18\x02 \x01(\t\x12\x33\n\x06\x63onfig\x18\x03 \x01(\x0b\x32#.behavioral_api.grpc.v1.AudioConfig\x12\x15\n\raudio_content\x18\x04 \x01(\x0c\x12\x13\n\x06\x61pp_id\x18\x05 \x01(\tH\x00\x88\x01\x01\x12\x13\n\x0b\x65nd_of_turn\x18\x06 \x01(\x08\x42\t\n\x07_app_id\"}\n\nPrediction\x12\r\n\x05label\x18\x01 \x01(\t\x12\x16\n\tposterior\x18\x02 \x01(\tH\x00\x88\x01\x01\x12\x12\n\x05logit\x18\x03 \x01(\tH\x01\x88\x01\x01\x12\x12\n\x05score\x18\x04 \x01(\tH\x02\x88\x01\x01\x42\x0c\n\n_posteriorB\x08\n\x06_logitB\x08\n\x06_score\"\x81\x02\n\x0fInferenceResult\x12\n\n\x02id\x18\x01 \x01(\t\x12\x12\n\nstart_time\x18\x02 \x01(\t\x12\x10\n\x08\x65nd_time\x18\x03 \x01(\t\x12\x0c\n\x04task\x18\x04 \x01(\t\x12\x36\n\nprediction\x18\x05 \x03(\x0b\x32\".behavioral_api.grpc.v1.Prediction\x12\x13\n\x0b\x66inal_label\x18\x06 \x01(\t\x12\x16\n\tembedding\x18\x07 \x01(\tH\x00\x88\x01\x01\x12\x31\n\x05level\x18\x08 \x01(\x0e\x32\x1d.behavioral_api.grpc.v1.LevelH\x01\x88\x01\x01\x42\x0c\n\n_embeddingB\x08\n\x06_level\"u\n\x0cStreamResult\x12\x0b\n\x03\x63id\x18\x01 \x01(\x03\x12\x0b\n\x03pid\x18\x02 \x01(\x03\x12\x12\n\nmessage_id\x18\x03 \x01(\x05\x12\x37\n\x06result\x18\x04 \x03(\x0b\x32\'.behavioral_api.grpc.v1.InferenceResult*\x1f\n\rAudioEncoding\x12\x0e\n\nLINEAR_PCM\x10\x00*#\n\x05Level\x12\x0b\n\x07segment\x10\x00\x12\r\n\tutterance\x10\x01\x32\xde\x01\n\x16\x42\x65havioralStreamingApi\x12^\n\x0bStreamAudio\x12#.behavioral_api.grpc.v1.AudioStream\x1a$.behavioral_api.grpc.v1.StreamResult\"\x00(\x01\x30\x01\x12\x64\n\x11\x44\x65\x65pfakeDetection\x12#.behavioral_api.grpc.v1.AudioStream\x1a$.behavioral_api.grpc.v1.StreamResult\"\x00(\x01\x30\x01\x62\x06proto3')
28
+
29
+ _globals = globals()
30
+ _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
31
+ _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'api_pb2', _globals)
32
+ if not _descriptor._USE_C_DESCRIPTORS:
33
+ DESCRIPTOR._loaded_options = None
34
+ _globals['_AUDIOENCODING']._serialized_start=1109
35
+ _globals['_AUDIOENCODING']._serialized_end=1140
36
+ _globals['_LEVEL']._serialized_start=1142
37
+ _globals['_LEVEL']._serialized_end=1177
38
+ _globals['_AUDIOCONFIG']._serialized_start=38
39
+ _globals['_AUDIOCONFIG']._serialized_end=369
40
+ _globals['_FOCUSCONFIG']._serialized_start=371
41
+ _globals['_FOCUSCONFIG']._serialized_end=421
42
+ _globals['_AUDIOSTREAM']._serialized_start=424
43
+ _globals['_AUDIOSTREAM']._serialized_end=601
44
+ _globals['_PREDICTION']._serialized_start=603
45
+ _globals['_PREDICTION']._serialized_end=728
46
+ _globals['_INFERENCERESULT']._serialized_start=731
47
+ _globals['_INFERENCERESULT']._serialized_end=988
48
+ _globals['_STREAMRESULT']._serialized_start=990
49
+ _globals['_STREAMRESULT']._serialized_end=1107
50
+ _globals['_BEHAVIORALSTREAMINGAPI']._serialized_start=1180
51
+ _globals['_BEHAVIORALSTREAMINGAPI']._serialized_end=1402
52
+ # @@protoc_insertion_point(module_scope)
@@ -20,20 +20,22 @@ segment: Level
20
20
  utterance: Level
21
21
 
22
22
  class AudioConfig(_message.Message):
23
- __slots__ = ("encoding", "sample_rate_hertz", "level", "logits", "feature_embedding", "focus")
23
+ __slots__ = ("encoding", "sample_rate_hertz", "level", "logits", "feature_embedding", "focus", "continuous")
24
24
  ENCODING_FIELD_NUMBER: _ClassVar[int]
25
25
  SAMPLE_RATE_HERTZ_FIELD_NUMBER: _ClassVar[int]
26
26
  LEVEL_FIELD_NUMBER: _ClassVar[int]
27
27
  LOGITS_FIELD_NUMBER: _ClassVar[int]
28
28
  FEATURE_EMBEDDING_FIELD_NUMBER: _ClassVar[int]
29
29
  FOCUS_FIELD_NUMBER: _ClassVar[int]
30
+ CONTINUOUS_FIELD_NUMBER: _ClassVar[int]
30
31
  encoding: AudioEncoding
31
32
  sample_rate_hertz: int
32
33
  level: Level
33
34
  logits: bool
34
35
  feature_embedding: bool
35
36
  focus: FocusConfig
36
- def __init__(self, encoding: _Optional[_Union[AudioEncoding, str]] = ..., sample_rate_hertz: _Optional[int] = ..., level: _Optional[_Union[Level, str]] = ..., logits: bool = ..., feature_embedding: bool = ..., focus: _Optional[_Union[FocusConfig, _Mapping]] = ...) -> None: ...
37
+ continuous: _containers.RepeatedScalarFieldContainer[str]
38
+ def __init__(self, encoding: _Optional[_Union[AudioEncoding, str]] = ..., sample_rate_hertz: _Optional[int] = ..., level: _Optional[_Union[Level, str]] = ..., logits: bool = ..., feature_embedding: bool = ..., focus: _Optional[_Union[FocusConfig, _Mapping]] = ..., continuous: _Optional[_Iterable[str]] = ...) -> None: ...
37
39
 
38
40
  class FocusConfig(_message.Message):
39
41
  __slots__ = ("labels", "sensitivity")
@@ -44,16 +46,20 @@ class FocusConfig(_message.Message):
44
46
  def __init__(self, labels: _Optional[_Iterable[str]] = ..., sensitivity: _Optional[str] = ...) -> None: ...
45
47
 
46
48
  class AudioStream(_message.Message):
47
- __slots__ = ("cid", "x_auth_token", "config", "audio_content")
49
+ __slots__ = ("cid", "x_auth_token", "config", "audio_content", "app_id", "end_of_turn")
48
50
  CID_FIELD_NUMBER: _ClassVar[int]
49
51
  X_AUTH_TOKEN_FIELD_NUMBER: _ClassVar[int]
50
52
  CONFIG_FIELD_NUMBER: _ClassVar[int]
51
53
  AUDIO_CONTENT_FIELD_NUMBER: _ClassVar[int]
54
+ APP_ID_FIELD_NUMBER: _ClassVar[int]
55
+ END_OF_TURN_FIELD_NUMBER: _ClassVar[int]
52
56
  cid: int
53
57
  x_auth_token: str
54
58
  config: AudioConfig
55
59
  audio_content: bytes
56
- def __init__(self, cid: _Optional[int] = ..., x_auth_token: _Optional[str] = ..., config: _Optional[_Union[AudioConfig, _Mapping]] = ..., audio_content: _Optional[bytes] = ...) -> None: ...
60
+ app_id: str
61
+ end_of_turn: bool
62
+ def __init__(self, cid: _Optional[int] = ..., x_auth_token: _Optional[str] = ..., config: _Optional[_Union[AudioConfig, _Mapping]] = ..., audio_content: _Optional[bytes] = ..., app_id: _Optional[str] = ..., end_of_turn: bool = ...) -> None: ...
57
63
 
58
64
  class Prediction(_message.Message):
59
65
  __slots__ = ("label", "posterior", "logit", "score")
@@ -97,6 +97,7 @@ def get_result(
97
97
  wait_seconds: WaitSeconds = DEFAULT_WAIT,
98
98
  focus: list[str] | None = None,
99
99
  sensitivity: Literal["low", "default", "high"] = "default",
100
+ continuous: list[str] | None = None,
100
101
  ) -> str:
101
102
  """Returns the results of a job, waiting up to wait_seconds if it is still processing.
102
103
 
@@ -110,12 +111,17 @@ def get_result(
110
111
  `focus` (behavioral only) adds "focus" rows where a label is likely but is not the final
111
112
  label, e.g. ["angry", "low_confidence"]. Labels: angry, happy, negative, positive, slow, fast,
112
113
  high_stress, low_confidence, negative_tone. `sensitivity` "high" flags more rows, "low" fewer.
114
+
115
+ `continuous` (behavioral only) adds a "continuous_valence" and/or "continuous_arousal" row to
116
+ every utterance, e.g. ["valence", "arousal"], with a score from -1 to 1 as its label.
113
117
  """
114
118
  if focus is not None and analysis != "behavioral":
115
119
  raise ToolError("focus is only available for behavioral results.")
120
+ if continuous is not None and analysis != "behavioral":
121
+ raise ToolError("continuous is only available for behavioral results.")
116
122
  with _tool_errors(), _api(analysis) as api:
117
123
  return _result_text(
118
- api, analysis, pid, wait_seconds, tasks, offset, limit, focus, sensitivity
124
+ api, analysis, pid, wait_seconds, tasks, offset, limit, focus, sensitivity, continuous
119
125
  )
120
126
 
121
127
 
@@ -220,12 +226,15 @@ def _result_text(
220
226
  limit: int,
221
227
  focus: list[str] | None = None,
222
228
  sensitivity: str = "default",
229
+ continuous: list[str] | None = None,
223
230
  ) -> str:
224
231
  """Waits up to wait_seconds for the result and formats one page of it."""
225
232
  wait = api.wait_for_video_result if analysis == "deepfake_video" else api.wait_for_result # type: ignore[union-attr]
226
233
  focus_args: dict[str, Any] = (
227
234
  {} if focus is None else {"focus": focus, "sensitivity": sensitivity}
228
235
  )
236
+ if continuous is not None:
237
+ focus_args["continuous"] = continuous
229
238
  try:
230
239
  result = wait(pid=pid, timeout=wait_seconds, **focus_args)
231
240
  except TimeoutError: