behavioralsignals 0.7.2__tar.gz → 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. {behavioralsignals-0.7.2/src/behavioralsignals.egg-info → behavioralsignals-1.0.0}/PKG-INFO +39 -9
  2. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/README.md +38 -8
  3. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/pyproject.toml +1 -1
  4. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/behavioral.py +23 -3
  5. behavioralsignals-1.0.0/src/behavioralsignals/generated/api_pb2.py +52 -0
  6. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/generated/api_pb2.pyi +12 -2
  7. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/mcp_server.py +33 -8
  8. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/models.py +29 -3
  9. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0/src/behavioralsignals.egg-info}/PKG-INFO +39 -9
  10. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals.egg-info/SOURCES.txt +1 -0
  11. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_client.py +24 -0
  12. behavioralsignals-1.0.0/tests/test_examples.py +112 -0
  13. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_mcp_server.py +51 -0
  14. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_streaming.py +40 -0
  15. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_wait_for_result.py +1 -1
  16. behavioralsignals-0.7.2/src/behavioralsignals/generated/api_pb2.py +0 -50
  17. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/LICENSE +0 -0
  18. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/setup.cfg +0 -0
  19. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/__init__.py +0 -0
  20. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/base.py +0 -0
  21. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/client.py +0 -0
  22. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/configuration.py +0 -0
  23. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/deepfakes.py +0 -0
  24. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/generated/__init__.py +0 -0
  25. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/generated/api_pb2_grpc.py +0 -0
  26. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/py.typed +0 -0
  27. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals/utils.py +0 -0
  28. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals.egg-info/dependency_links.txt +0 -0
  29. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals.egg-info/entry_points.txt +0 -0
  30. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals.egg-info/requires.txt +0 -0
  31. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/src/behavioralsignals.egg-info/top_level.txt +0 -0
  32. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_models.py +0 -0
  33. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_package.py +0 -0
  34. {behavioralsignals-0.7.2 → behavioralsignals-1.0.0}/tests/test_utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: behavioralsignals
3
- Version: 0.7.2
3
+ Version: 1.0.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
@@ -370,8 +370,8 @@ process = client.behavioral.upload_audio(
370
370
 
371
371
  ### Behavioral outputs
372
372
 
373
- The Behavioral API returns **24 signals** across 8 dimensions: 18 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
374
- All eight dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 4 = **5,184 possible profiles** per utterance.
373
+ The Behavioral API returns **28 signals** across 10 dimensions: 22 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
374
+ All ten dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 2 × 2 × 4 = **20,736 possible profiles** per utterance.
375
375
 
376
376
  | Task | What it measures | Labels | # |
377
377
  |---|---|---|---|
@@ -381,12 +381,16 @@ All eight dimensions are scored together on every utterance longer than 1 second
381
381
  | `speaking_rate` | How fast the speaker talks, compared to speakers in general, not to their own pace | `fast`, `slow`, `normal` | 3 |
382
382
  | `hesitation` | Signs of hesitation | `yes`, `no` | 2 |
383
383
  | `engagement` | Involved or detached tone | `engaged`, `withdrawn`, `neutral` | 3 |
384
+ | `whispering` | Whispered speech | `whispering`, `non-whispering` | 2 |
385
+ | `shouting` | Shouted speech | `shouting`, `non-shouting` | 2 |
384
386
  | `gender` | Sex of the speaker, estimated from the voice | `female`, `male` | 2 |
385
387
  | `age` | Age range of the speaker, estimated from the voice | `18 - 22`, `23 - 30`, `31 - 45`, `46 - 65` | 4 |
386
- | **Total** | | | **24** |
388
+ | **Total** | | | **28** |
387
389
 
388
- Plus `intensity`: how intense the emotion is, as one score between 0 and 1. It is not a score for any one emotion, even when `emotion` is `angry`. It has no labels and is not counted in the 24.
389
- In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all 24 signals and `intensity`, however short it is.
390
+ Plus four scores between 0 and 1, which have no labels and are not counted in the 28:
391
+ `intensity`, how intense the emotion is (not a score for any one emotion, even when `emotion` is `angry`), `breathiness`, how breathy the voice is, `monotony`, how monotone the delivery is (1 = monotone), and `fluency`, how fluent the speech sounds to a listener.
392
+ The quality of the recording comes as four more scores, named `signal_quality.<output>`: `signal_quality.snr` (background noise), `signal_quality.c50` (reverberation), `signal_quality.sdr` (clipping) and `signal_quality.overall`, from 0 to 1 where 1 is clean. `overall` is mostly the worst of the three.
393
+ In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all the signals and scores, however short it is.
390
394
  In batch results, `gender` and `age` are given per speaker: every utterance of a speaker longer than 1 second gets the same values, averaged over the file. When streaming, `gender` and `age` are estimated on each segment.
391
395
  The other tasks have open-ended values, not fixed labels: `diarization` (a speaker ID such as `SPEAKER_00`), `asr` (the transcript) and `language`. With `embeddings=True`, `features` holds the behavioral embedding.
392
396
  All results of one utterance share its `id`, `startTime` and `endTime`. To split results by speaker, use the `diarization` label of each utterance. Speaker IDs are generic: the API does not say who is the agent and who is the customer.
@@ -397,6 +401,13 @@ All results of one utterance share its `id`, `startTime` and `endTime`. To split
397
401
  When you need a score instead of a label, use the probabilities in `prediction`. They are strings, so convert them with `float()`.
398
402
  For each task in the table they add up to 1, so each label's probability is a score from 0 to 1 that you can track over time, average over a call, or compare against your own threshold.
399
403
  For example, the `angry` probability of `emotion` is a score for anger. `intensity` is not: it does not say which emotion is intense.
404
+ Scores have no `finalLabel`: their `prediction` holds a single `score`.
405
+
406
+ ```python
407
+ for item in result.results:
408
+ if item.task == "signal_quality.overall":
409
+ print(item.st, "signal quality:", float(item.prediction[0].score))
410
+ ```
400
411
 
401
412
  `positivity` is valence and `strength` is arousal, the two dimensions often used in emotion research. The API gives them as probabilities from 0 to 1. To put them on the usual scale from -1 to 1, subtract the probabilities of the two opposite labels:
402
413
 
@@ -529,6 +540,25 @@ for result in client.deepfakes.stream_audio(
529
540
 
530
541
  See the [streaming examples](examples/streaming/) and [streaming documentation](https://behavioralsignals.readme.io/docs/streaming-using-python-sdk) for more.
531
542
 
543
+ ## Focus
544
+
545
+ Focus flags behaviors that are likely but not the predicted label, for example anger in an utterance labeled neutral. It is available in the Behavioral API, for batch and streaming.
546
+
547
+ Labels: `angry`, `happy`, `negative`, `positive`, `slow`, `fast`, `high_stress`, `low_confidence`, `negative_tone`. Sensitivity: `low`, `default` or `high` (flags more).
548
+
549
+ ```python
550
+ # Batch
551
+ process = client.behavioral.upload_audio(file_path="audio.wav")
552
+ result = client.behavioral.wait_for_result(pid=process.pid, focus=["angry", "low_confidence"], sensitivity="high")
553
+
554
+ # Streaming
555
+ options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM", focus=["angry", "low_confidence"])
556
+ ```
557
+
558
+ Each flag is a result with `task="focus"` and `finalLabel="suspected_<label>"`, with the same time span as the utterance or segment it belongs to.
559
+
560
+ A stream's focus results are saved with its results: `get_result` returns them, and replaces them if you pass `focus`.
561
+
532
562
  ## Available Methods
533
563
 
534
564
  `client.behavioral` and `client.deepfakes` expose the same methods for audio. Video methods are available only on `client.deepfakes`.
@@ -537,8 +567,8 @@ See the [streaming examples](examples/streaming/) and [streaming documentation](
537
567
  |---|---|
538
568
  | `upload_audio(file_path, ...)` | Uploads an audio file and returns the process, including its `pid` |
539
569
  | `upload_s3_presigned_url(url, ...)` | Submits audio using an S3 presigned URL |
540
- | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results |
541
- | `get_result(pid)` | Returns the results of a finished process |
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` |
542
572
  | `get_process(pid)` | Returns a process and its current status |
543
573
  | `list_processes(...)` | Lists audio processes |
544
574
  | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive |
@@ -676,7 +706,7 @@ The server exposes four tools:
676
706
  |---|---|
677
707
  | `analyze_behavior` | Uploads an audio file or S3 presigned URL for behavioral analysis and returns the results |
678
708
  | `detect_deepfake` | Uploads an audio or video file, or an S3 presigned URL, for deepfake detection (video is experimental) and returns the results |
679
- | `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 |
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` |
680
710
  | `list_processes` | Lists processes, newest first, including the failure reason when available |
681
711
 
682
712
  Notes:
@@ -124,8 +124,8 @@ process = client.behavioral.upload_audio(
124
124
 
125
125
  ### Behavioral outputs
126
126
 
127
- The Behavioral API returns **24 signals** across 8 dimensions: 18 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
128
- All eight dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 4 = **5,184 possible profiles** per utterance.
127
+ The Behavioral API returns **28 signals** across 10 dimensions: 22 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
128
+ All ten dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 2 × 2 × 4 = **20,736 possible profiles** per utterance.
129
129
 
130
130
  | Task | What it measures | Labels | # |
131
131
  |---|---|---|---|
@@ -135,12 +135,16 @@ All eight dimensions are scored together on every utterance longer than 1 second
135
135
  | `speaking_rate` | How fast the speaker talks, compared to speakers in general, not to their own pace | `fast`, `slow`, `normal` | 3 |
136
136
  | `hesitation` | Signs of hesitation | `yes`, `no` | 2 |
137
137
  | `engagement` | Involved or detached tone | `engaged`, `withdrawn`, `neutral` | 3 |
138
+ | `whispering` | Whispered speech | `whispering`, `non-whispering` | 2 |
139
+ | `shouting` | Shouted speech | `shouting`, `non-shouting` | 2 |
138
140
  | `gender` | Sex of the speaker, estimated from the voice | `female`, `male` | 2 |
139
141
  | `age` | Age range of the speaker, estimated from the voice | `18 - 22`, `23 - 30`, `31 - 45`, `46 - 65` | 4 |
140
- | **Total** | | | **24** |
142
+ | **Total** | | | **28** |
141
143
 
142
- Plus `intensity`: how intense the emotion is, as one score between 0 and 1. It is not a score for any one emotion, even when `emotion` is `angry`. It has no labels and is not counted in the 24.
143
- In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all 24 signals and `intensity`, however short it is.
144
+ Plus four scores between 0 and 1, which have no labels and are not counted in the 28:
145
+ `intensity`, how intense the emotion is (not a score for any one emotion, even when `emotion` is `angry`), `breathiness`, how breathy the voice is, `monotony`, how monotone the delivery is (1 = monotone), and `fluency`, how fluent the speech sounds to a listener.
146
+ The quality of the recording comes as four more scores, named `signal_quality.<output>`: `signal_quality.snr` (background noise), `signal_quality.c50` (reverberation), `signal_quality.sdr` (clipping) and `signal_quality.overall`, from 0 to 1 where 1 is clean. `overall` is mostly the worst of the three.
147
+ In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all the signals and scores, however short it is.
144
148
  In batch results, `gender` and `age` are given per speaker: every utterance of a speaker longer than 1 second gets the same values, averaged over the file. When streaming, `gender` and `age` are estimated on each segment.
145
149
  The other tasks have open-ended values, not fixed labels: `diarization` (a speaker ID such as `SPEAKER_00`), `asr` (the transcript) and `language`. With `embeddings=True`, `features` holds the behavioral embedding.
146
150
  All results of one utterance share its `id`, `startTime` and `endTime`. To split results by speaker, use the `diarization` label of each utterance. Speaker IDs are generic: the API does not say who is the agent and who is the customer.
@@ -151,6 +155,13 @@ All results of one utterance share its `id`, `startTime` and `endTime`. To split
151
155
  When you need a score instead of a label, use the probabilities in `prediction`. They are strings, so convert them with `float()`.
152
156
  For each task in the table they add up to 1, so each label's probability is a score from 0 to 1 that you can track over time, average over a call, or compare against your own threshold.
153
157
  For example, the `angry` probability of `emotion` is a score for anger. `intensity` is not: it does not say which emotion is intense.
158
+ Scores have no `finalLabel`: their `prediction` holds a single `score`.
159
+
160
+ ```python
161
+ for item in result.results:
162
+ if item.task == "signal_quality.overall":
163
+ print(item.st, "signal quality:", float(item.prediction[0].score))
164
+ ```
154
165
 
155
166
  `positivity` is valence and `strength` is arousal, the two dimensions often used in emotion research. The API gives them as probabilities from 0 to 1. To put them on the usual scale from -1 to 1, subtract the probabilities of the two opposite labels:
156
167
 
@@ -283,6 +294,25 @@ for result in client.deepfakes.stream_audio(
283
294
 
284
295
  See the [streaming examples](examples/streaming/) and [streaming documentation](https://behavioralsignals.readme.io/docs/streaming-using-python-sdk) for more.
285
296
 
297
+ ## Focus
298
+
299
+ Focus flags behaviors that are likely but not the predicted label, for example anger in an utterance labeled neutral. It is available in the Behavioral API, for batch and streaming.
300
+
301
+ Labels: `angry`, `happy`, `negative`, `positive`, `slow`, `fast`, `high_stress`, `low_confidence`, `negative_tone`. Sensitivity: `low`, `default` or `high` (flags more).
302
+
303
+ ```python
304
+ # Batch
305
+ process = client.behavioral.upload_audio(file_path="audio.wav")
306
+ result = client.behavioral.wait_for_result(pid=process.pid, focus=["angry", "low_confidence"], sensitivity="high")
307
+
308
+ # Streaming
309
+ options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM", focus=["angry", "low_confidence"])
310
+ ```
311
+
312
+ Each flag is a result with `task="focus"` and `finalLabel="suspected_<label>"`, with the same time span as the utterance or segment it belongs to.
313
+
314
+ A stream's focus results are saved with its results: `get_result` returns them, and replaces them if you pass `focus`.
315
+
286
316
  ## Available Methods
287
317
 
288
318
  `client.behavioral` and `client.deepfakes` expose the same methods for audio. Video methods are available only on `client.deepfakes`.
@@ -291,8 +321,8 @@ See the [streaming examples](examples/streaming/) and [streaming documentation](
291
321
  |---|---|
292
322
  | `upload_audio(file_path, ...)` | Uploads an audio file and returns the process, including its `pid` |
293
323
  | `upload_s3_presigned_url(url, ...)` | Submits audio using an S3 presigned URL |
294
- | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results |
295
- | `get_result(pid)` | Returns the results of a finished process |
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` |
296
326
  | `get_process(pid)` | Returns a process and its current status |
297
327
  | `list_processes(...)` | Lists audio processes |
298
328
  | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive |
@@ -430,7 +460,7 @@ The server exposes four tools:
430
460
  |---|---|
431
461
  | `analyze_behavior` | Uploads an audio file or S3 presigned URL for behavioral analysis and returns the results |
432
462
  | `detect_deepfake` | Uploads an audio or video file, or an S3 presigned URL, for deepfake detection (video is experimental) and returns the results |
433
- | `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 |
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` |
434
464
  | `list_processes` | Lists processes, newest first, including the failure reason when available |
435
465
 
436
466
  Notes:
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "behavioralsignals"
3
- version = "0.7.2"
3
+ version = "1.0.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" }]
@@ -146,21 +146,39 @@ class Behavioral(BaseClient):
146
146
 
147
147
  return ProcessItem(**data)
148
148
 
149
- def get_result(self, pid: int) -> ResultResponse:
149
+ def get_result(
150
+ self,
151
+ pid: int,
152
+ focus: list[str] | None = None,
153
+ sensitivity: Literal["low", "default", "high"] = "default",
154
+ ) -> ResultResponse:
150
155
  """Retrieves the result of a completed process by its ID.
151
156
 
152
157
  Args:
153
158
  pid (int): The process ID for which to retrieve the result
159
+ focus (list[str], optional): Labels to focus on, e.g. ["angry", "low_confidence"].
160
+ Adds a "focus" result when a label is likely but not the predicted one.
161
+ sensitivity (str, optional): Focus sensitivity: "low", "default" or "high".
154
162
  Returns:
155
163
  ResultResponse: The result response containing the results of the specified process.
156
164
  """
165
+ params = (
166
+ {"focus": ",".join(focus), "sensitivity": sensitivity} if focus is not None else None
167
+ )
157
168
  data = self._send_request(
158
169
  path=f"clients/{self.config.cid}/processes/{pid}/results",
159
170
  method="GET",
171
+ data=params,
160
172
  )
161
173
  return ResultResponse(**data)
162
174
 
163
- def wait_for_result(self, pid: int, timeout: float | None = None) -> ResultResponse:
175
+ def wait_for_result(
176
+ self,
177
+ pid: int,
178
+ timeout: float | None = None,
179
+ focus: list[str] | None = None,
180
+ sensitivity: Literal["low", "default", "high"] = "default",
181
+ ) -> ResultResponse:
164
182
  """Waits for a process to finish and returns its result.
165
183
 
166
184
  Checks the process status until processing is complete, then returns the result.
@@ -168,6 +186,8 @@ class Behavioral(BaseClient):
168
186
  Args:
169
187
  pid (int): The process ID to wait for.
170
188
  timeout (float, optional): Maximum seconds to wait. Defaults to None (no limit).
189
+ focus (list[str], optional): Labels to focus on (see `get_result`).
190
+ sensitivity (str, optional): Focus sensitivity: "low", "default" or "high".
171
191
  Returns:
172
192
  ResultResponse: The result response containing the results of the specified process.
173
193
  Raises:
@@ -177,7 +197,7 @@ class Behavioral(BaseClient):
177
197
  retried until `timeout` runs out.
178
198
  """
179
199
  self._wait_for_process(self.get_process, pid, timeout)
180
- return self.get_result(pid)
200
+ return self.get_result(pid, focus, sensitivity)
181
201
 
182
202
  def stream_audio(
183
203
  self, audio_stream: Iterator[bytes], options: StreamingOptions
@@ -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\"\xb7\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\x42\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\"|\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\"}\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=1035
35
+ _globals['_AUDIOENCODING']._serialized_end=1066
36
+ _globals['_LEVEL']._serialized_start=1068
37
+ _globals['_LEVEL']._serialized_end=1103
38
+ _globals['_AUDIOCONFIG']._serialized_start=38
39
+ _globals['_AUDIOCONFIG']._serialized_end=349
40
+ _globals['_FOCUSCONFIG']._serialized_start=351
41
+ _globals['_FOCUSCONFIG']._serialized_end=401
42
+ _globals['_AUDIOSTREAM']._serialized_start=403
43
+ _globals['_AUDIOSTREAM']._serialized_end=527
44
+ _globals['_PREDICTION']._serialized_start=529
45
+ _globals['_PREDICTION']._serialized_end=654
46
+ _globals['_INFERENCERESULT']._serialized_start=657
47
+ _globals['_INFERENCERESULT']._serialized_end=914
48
+ _globals['_STREAMRESULT']._serialized_start=916
49
+ _globals['_STREAMRESULT']._serialized_end=1033
50
+ _globals['_BEHAVIORALSTREAMINGAPI']._serialized_start=1106
51
+ _globals['_BEHAVIORALSTREAMINGAPI']._serialized_end=1328
52
+ # @@protoc_insertion_point(module_scope)
@@ -20,18 +20,28 @@ segment: Level
20
20
  utterance: Level
21
21
 
22
22
  class AudioConfig(_message.Message):
23
- __slots__ = ("encoding", "sample_rate_hertz", "level", "logits", "feature_embedding")
23
+ __slots__ = ("encoding", "sample_rate_hertz", "level", "logits", "feature_embedding", "focus")
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
+ FOCUS_FIELD_NUMBER: _ClassVar[int]
29
30
  encoding: AudioEncoding
30
31
  sample_rate_hertz: int
31
32
  level: Level
32
33
  logits: bool
33
34
  feature_embedding: bool
34
- def __init__(self, encoding: _Optional[_Union[AudioEncoding, str]] = ..., sample_rate_hertz: _Optional[int] = ..., level: _Optional[_Union[Level, str]] = ..., logits: bool = ..., feature_embedding: bool = ...) -> None: ...
35
+ 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
+
38
+ class FocusConfig(_message.Message):
39
+ __slots__ = ("labels", "sensitivity")
40
+ LABELS_FIELD_NUMBER: _ClassVar[int]
41
+ SENSITIVITY_FIELD_NUMBER: _ClassVar[int]
42
+ labels: _containers.RepeatedScalarFieldContainer[str]
43
+ sensitivity: str
44
+ def __init__(self, labels: _Optional[_Iterable[str]] = ..., sensitivity: _Optional[str] = ...) -> None: ...
35
45
 
36
46
  class AudioStream(_message.Message):
37
47
  __slots__ = ("cid", "x_auth_token", "config", "audio_content")
@@ -7,7 +7,7 @@ over stdio, so it must never print to stdout.
7
7
  import os
8
8
  import json
9
9
  import time
10
- from typing import Literal, Annotated
10
+ from typing import Any, Literal, Annotated
11
11
  from contextlib import contextmanager
12
12
  from urllib.parse import unquote, urlparse
13
13
 
@@ -54,7 +54,8 @@ server = MCPServer(
54
54
  @server.tool(structured_output=False)
55
55
  def analyze_behavior(source: str, wait_seconds: WaitSeconds = DEFAULT_WAIT) -> str:
56
56
  """Analyzes speech in an audio file: transcript, speakers, language, gender, age, emotion,
57
- positivity, strength, speaking rate, hesitation, engagement and intensity.
57
+ positivity, strength, speaking rate, hesitation, engagement, intensity, speaking style (whispering,
58
+ shouting, breathiness, monotony, fluency) and signal quality.
58
59
 
59
60
  `source` is an absolute path to a local audio file, or an S3 presigned URL. Each call uploads
60
61
  the audio again and uses credits: to check a job you started, call get_result. If an upload
@@ -94,6 +95,8 @@ def get_result(
94
95
  offset: Annotated[int, Field(ge=0)] = 0,
95
96
  limit: Annotated[int, Field(ge=1, le=1000)] = DEFAULT_LIMIT,
96
97
  wait_seconds: WaitSeconds = DEFAULT_WAIT,
98
+ focus: list[str] | None = None,
99
+ sensitivity: Literal["low", "default", "high"] = "default",
97
100
  ) -> str:
98
101
  """Returns the results of a job, waiting up to wait_seconds if it is still processing.
99
102
 
@@ -103,9 +106,17 @@ def get_result(
103
106
  Each row has the final label and the probability of every label of the task. Use the
104
107
  probabilities as scores. positivity is valence and strength is arousal; for a scale from -1
105
108
  to 1, use P(positive) - P(negative) and P(strong) - P(weak).
109
+
110
+ `focus` (behavioral only) adds "focus" rows where a label is likely but is not the final
111
+ label, e.g. ["angry", "low_confidence"]. Labels: angry, happy, negative, positive, slow, fast,
112
+ high_stress, low_confidence, negative_tone. `sensitivity` "high" flags more rows, "low" fewer.
106
113
  """
114
+ if focus is not None and analysis != "behavioral":
115
+ raise ToolError("focus is only available for behavioral results.")
107
116
  with _tool_errors(), _api(analysis) as api:
108
- return _result_text(api, analysis, pid, wait_seconds, tasks, offset, limit)
117
+ return _result_text(
118
+ api, analysis, pid, wait_seconds, tasks, offset, limit, focus, sensitivity
119
+ )
109
120
 
110
121
 
111
122
  @server.tool(annotations=READ_ONLY, structured_output=False)
@@ -207,18 +218,24 @@ def _result_text(
207
218
  tasks: list[str] | None,
208
219
  offset: int,
209
220
  limit: int,
221
+ focus: list[str] | None = None,
222
+ sensitivity: str = "default",
210
223
  ) -> str:
211
224
  """Waits up to wait_seconds for the result and formats one page of it."""
212
225
  wait = api.wait_for_video_result if analysis == "deepfake_video" else api.wait_for_result # type: ignore[union-attr]
226
+ focus_args: dict[str, Any] = (
227
+ {} if focus is None else {"focus": focus, "sensitivity": sensitivity}
228
+ )
213
229
  try:
214
- result = wait(pid=pid, timeout=wait_seconds)
230
+ result = wait(pid=pid, timeout=wait_seconds, **focus_args)
215
231
  except TimeoutError:
216
- retry = _call("get_result", pid=pid, analysis=analysis)
232
+ retry = _call("get_result", pid=pid, analysis=analysis, **focus_args)
217
233
  return f"pid {pid} is still processing. Call {retry} to wait again."
218
234
  except RuntimeError as error:
219
235
  # The job failed. Keep the reason's first line; a long ffmpeg log can follow it.
220
236
  raise ToolError(str(error).splitlines()[0]) from error
221
- return _format_result(pid, analysis, _result_rows(result, analysis), tasks, offset, limit)
237
+ rows = _result_rows(result, analysis)
238
+ return _format_result(pid, analysis, rows, tasks, offset, limit, focus_args)
222
239
 
223
240
 
224
241
  def _result_rows(result, analysis: str) -> list[list[str]]:
@@ -259,13 +276,19 @@ def _format_result(
259
276
  tasks: list[str] | None,
260
277
  offset: int,
261
278
  limit: int,
279
+ focus_args: dict[str, Any],
262
280
  ) -> str:
263
281
  """Formats the rows of the tasks, `limit` rows from `offset`, as a tab-separated table."""
264
282
  columns = (["track"] if analysis == "deepfake_video" else []) + RESULT_COLUMNS
265
283
  task_index = columns.index("task")
266
284
  task_names = ", ".join(sorted({row[task_index] for row in rows}))
267
285
  if tasks:
268
- rows = [row for row in rows if row[task_index] in tasks]
286
+ # a group name keeps all its tasks, e.g. "signal_quality" keeps signal_quality.snr, ...
287
+ rows = [
288
+ row
289
+ for row in rows
290
+ if row[task_index] in tasks or row[task_index].split(".")[0] in tasks
291
+ ]
269
292
  total = len(rows)
270
293
  if total == 0:
271
294
  hint = f" Tasks: {task_names}" if tasks and task_names else ""
@@ -280,7 +303,9 @@ def _format_result(
280
303
  *(_tsv(row) for row in page),
281
304
  ]
282
305
  if end < total:
283
- more = _call("get_result", pid=pid, analysis=analysis, tasks=tasks, offset=end)
306
+ more = _call(
307
+ "get_result", pid=pid, analysis=analysis, tasks=tasks, offset=end, **focus_args
308
+ )
284
309
  lines.append(f"More rows: {more}")
285
310
  return "\n".join(lines)
286
311
 
@@ -1,6 +1,6 @@
1
1
  import json
2
2
  from enum import IntEnum
3
- from typing import Literal
3
+ from typing import Any, Literal
4
4
  from pathlib import Path
5
5
  from datetime import date
6
6
  from datetime import datetime as datetime_aliased
@@ -35,6 +35,14 @@ class StreamingOptions(BaseModel):
35
35
  "Use 'segment' for segment-level results, 'utterance' for utterance-level results. "
36
36
  "Use 'all' for both segment and utterance results.",
37
37
  )
38
+ focus: list[str] | None = Field(
39
+ default=None,
40
+ description="Behavioral only. Labels to focus on, e.g. ['angry', 'low_confidence']. "
41
+ "Adds a 'focus' result when a label is likely but not the predicted one.",
42
+ )
43
+ sensitivity: Literal["low", "default", "high"] = Field(
44
+ default="default", description="Focus sensitivity: 'high' flags more, 'low' flags fewer."
45
+ )
38
46
 
39
47
  def to_pb_config(self) -> pb.AudioConfig:
40
48
  """Convert the level to a protobuf Level enum."""
@@ -48,6 +56,9 @@ class StreamingOptions(BaseModel):
48
56
  config = pb.AudioConfig(sample_rate_hertz=self.sample_rate, encoding=encoding)
49
57
  if level is not None:
50
58
  config.level = level
59
+ if self.focus is not None:
60
+ config.focus.labels.extend(self.focus)
61
+ config.focus.sensitivity = self.sensitivity
51
62
  return config
52
63
 
53
64
 
@@ -239,14 +250,14 @@ class ResultItem(_SerializableModel):
239
250
  )
240
251
  task: str | None = Field(
241
252
  None,
242
- description="The task. Behavioral: emotion, strength, positivity, speaking_rate, hesitation, engagement, intensity. Speaker: gender, age. Other: diarization, asr, language, features. Deepfakes API: deepfake, visual_deepfake, generator. "
253
+ description="The task. Behavioral: emotion, strength, positivity, speaking_rate, hesitation, engagement, intensity. Speaking style: whispering, shouting, breathiness, monotony, fluency. Speaker: gender, age. Signal quality: signal_quality.snr, signal_quality.c50, signal_quality.sdr, signal_quality.overall. Other: diarization, asr, language, features, focus. Deepfakes API: deepfake, visual_deepfake, generator. "
243
254
  "Consider visiting the guides in behavioralsignals.readme.io for the latest examples.",
244
255
  examples=["emotion"],
245
256
  )
246
257
  prediction: list[ModelPredictions] | None = None
247
258
  finalLabel: str | None = Field(
248
259
  None,
249
- description="The label the API picks for this task. For behavioral tasks it is the label with the highest posterior.",
260
+ description="The label the API picks for this task. For behavioral tasks it is the label with the highest posterior. For focus it is suspected_<label>.",
250
261
  examples=["happy"],
251
262
  )
252
263
  level: str | None = Field(
@@ -308,3 +319,18 @@ class StreamingResultResponse(_SerializableModel):
308
319
  results: list[ResultItem] | None = Field(
309
320
  None, alias="result", description="List of result items"
310
321
  )
322
+
323
+ @field_validator("results", mode="before")
324
+ @classmethod
325
+ def _drop_empty_strings(cls, results: Any) -> Any:
326
+ # The gRPC message has every unset string as "" (e.g. the label and posterior of a score);
327
+ # drop them, so streaming results look like batch ones
328
+ return _without_empty_strings(results)
329
+
330
+
331
+ def _without_empty_strings(value: Any) -> Any:
332
+ if isinstance(value, dict):
333
+ return {key: _without_empty_strings(item) for key, item in value.items() if item != ""}
334
+ if isinstance(value, list):
335
+ return [_without_empty_strings(item) for item in value]
336
+ return value
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: behavioralsignals
3
- Version: 0.7.2
3
+ Version: 1.0.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
@@ -370,8 +370,8 @@ process = client.behavioral.upload_audio(
370
370
 
371
371
  ### Behavioral outputs
372
372
 
373
- The Behavioral API returns **24 signals** across 8 dimensions: 18 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
374
- All eight dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 4 = **5,184 possible profiles** per utterance.
373
+ The Behavioral API returns **28 signals** across 10 dimensions: 22 behavioral signals and 6 speaker signals. Each label is its own signal with its own probability.
374
+ All ten dimensions are scored together on every utterance longer than 1 second, so one utterance can be *sad + weak + negative + slow + hesitating + withdrawn*, with a voice estimated as female and aged 31 - 45. That gives 4 × 3 × 3 × 3 × 2 × 3 × 2 × 2 × 2 × 4 = **20,736 possible profiles** per utterance.
375
375
 
376
376
  | Task | What it measures | Labels | # |
377
377
  |---|---|---|---|
@@ -381,12 +381,16 @@ All eight dimensions are scored together on every utterance longer than 1 second
381
381
  | `speaking_rate` | How fast the speaker talks, compared to speakers in general, not to their own pace | `fast`, `slow`, `normal` | 3 |
382
382
  | `hesitation` | Signs of hesitation | `yes`, `no` | 2 |
383
383
  | `engagement` | Involved or detached tone | `engaged`, `withdrawn`, `neutral` | 3 |
384
+ | `whispering` | Whispered speech | `whispering`, `non-whispering` | 2 |
385
+ | `shouting` | Shouted speech | `shouting`, `non-shouting` | 2 |
384
386
  | `gender` | Sex of the speaker, estimated from the voice | `female`, `male` | 2 |
385
387
  | `age` | Age range of the speaker, estimated from the voice | `18 - 22`, `23 - 30`, `31 - 45`, `46 - 65` | 4 |
386
- | **Total** | | | **24** |
388
+ | **Total** | | | **28** |
387
389
 
388
- Plus `intensity`: how intense the emotion is, as one score between 0 and 1. It is not a score for any one emotion, even when `emotion` is `angry`. It has no labels and is not counted in the 24.
389
- In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all 24 signals and `intensity`, however short it is.
390
+ Plus four scores between 0 and 1, which have no labels and are not counted in the 28:
391
+ `intensity`, how intense the emotion is (not a score for any one emotion, even when `emotion` is `angry`), `breathiness`, how breathy the voice is, `monotony`, how monotone the delivery is (1 = monotone), and `fluency`, how fluent the speech sounds to a listener.
392
+ The quality of the recording comes as four more scores, named `signal_quality.<output>`: `signal_quality.snr` (background noise), `signal_quality.c50` (reverberation), `signal_quality.sdr` (clipping) and `signal_quality.overall`, from 0 to 1 where 1 is clean. `overall` is mostly the worst of the three.
393
+ In batch results, utterances of 1 second or less return only `diarization`, `asr` and `language`. When streaming, every segment gets all the signals and scores, however short it is.
390
394
  In batch results, `gender` and `age` are given per speaker: every utterance of a speaker longer than 1 second gets the same values, averaged over the file. When streaming, `gender` and `age` are estimated on each segment.
391
395
  The other tasks have open-ended values, not fixed labels: `diarization` (a speaker ID such as `SPEAKER_00`), `asr` (the transcript) and `language`. With `embeddings=True`, `features` holds the behavioral embedding.
392
396
  All results of one utterance share its `id`, `startTime` and `endTime`. To split results by speaker, use the `diarization` label of each utterance. Speaker IDs are generic: the API does not say who is the agent and who is the customer.
@@ -397,6 +401,13 @@ All results of one utterance share its `id`, `startTime` and `endTime`. To split
397
401
  When you need a score instead of a label, use the probabilities in `prediction`. They are strings, so convert them with `float()`.
398
402
  For each task in the table they add up to 1, so each label's probability is a score from 0 to 1 that you can track over time, average over a call, or compare against your own threshold.
399
403
  For example, the `angry` probability of `emotion` is a score for anger. `intensity` is not: it does not say which emotion is intense.
404
+ Scores have no `finalLabel`: their `prediction` holds a single `score`.
405
+
406
+ ```python
407
+ for item in result.results:
408
+ if item.task == "signal_quality.overall":
409
+ print(item.st, "signal quality:", float(item.prediction[0].score))
410
+ ```
400
411
 
401
412
  `positivity` is valence and `strength` is arousal, the two dimensions often used in emotion research. The API gives them as probabilities from 0 to 1. To put them on the usual scale from -1 to 1, subtract the probabilities of the two opposite labels:
402
413
 
@@ -529,6 +540,25 @@ for result in client.deepfakes.stream_audio(
529
540
 
530
541
  See the [streaming examples](examples/streaming/) and [streaming documentation](https://behavioralsignals.readme.io/docs/streaming-using-python-sdk) for more.
531
542
 
543
+ ## Focus
544
+
545
+ Focus flags behaviors that are likely but not the predicted label, for example anger in an utterance labeled neutral. It is available in the Behavioral API, for batch and streaming.
546
+
547
+ Labels: `angry`, `happy`, `negative`, `positive`, `slow`, `fast`, `high_stress`, `low_confidence`, `negative_tone`. Sensitivity: `low`, `default` or `high` (flags more).
548
+
549
+ ```python
550
+ # Batch
551
+ process = client.behavioral.upload_audio(file_path="audio.wav")
552
+ result = client.behavioral.wait_for_result(pid=process.pid, focus=["angry", "low_confidence"], sensitivity="high")
553
+
554
+ # Streaming
555
+ options = StreamingOptions(sample_rate=sample_rate, encoding="LINEAR_PCM", focus=["angry", "low_confidence"])
556
+ ```
557
+
558
+ Each flag is a result with `task="focus"` and `finalLabel="suspected_<label>"`, with the same time span as the utterance or segment it belongs to.
559
+
560
+ A stream's focus results are saved with its results: `get_result` returns them, and replaces them if you pass `focus`.
561
+
532
562
  ## Available Methods
533
563
 
534
564
  `client.behavioral` and `client.deepfakes` expose the same methods for audio. Video methods are available only on `client.deepfakes`.
@@ -537,8 +567,8 @@ See the [streaming examples](examples/streaming/) and [streaming documentation](
537
567
  |---|---|
538
568
  | `upload_audio(file_path, ...)` | Uploads an audio file and returns the process, including its `pid` |
539
569
  | `upload_s3_presigned_url(url, ...)` | Submits audio using an S3 presigned URL |
540
- | `wait_for_result(pid, timeout=None)` | Waits for a process to finish and returns its results |
541
- | `get_result(pid)` | Returns the results of a finished process |
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` |
542
572
  | `get_process(pid)` | Returns a process and its current status |
543
573
  | `list_processes(...)` | Lists audio processes |
544
574
  | `stream_audio(audio_stream, options)` | Streams audio and yields results as they arrive |
@@ -676,7 +706,7 @@ The server exposes four tools:
676
706
  |---|---|
677
707
  | `analyze_behavior` | Uploads an audio file or S3 presigned URL for behavioral analysis and returns the results |
678
708
  | `detect_deepfake` | Uploads an audio or video file, or an S3 presigned URL, for deepfake detection (video is experimental) and returns the results |
679
- | `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 |
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` |
680
710
  | `list_processes` | Lists processes, newest first, including the failure reason when available |
681
711
 
682
712
  Notes:
@@ -22,6 +22,7 @@ src/behavioralsignals/generated/api_pb2.py
22
22
  src/behavioralsignals/generated/api_pb2.pyi
23
23
  src/behavioralsignals/generated/api_pb2_grpc.py
24
24
  tests/test_client.py
25
+ tests/test_examples.py
25
26
  tests/test_mcp_server.py
26
27
  tests/test_models.py
27
28
  tests/test_package.py
@@ -293,6 +293,30 @@ def test_get_result_parses_the_response(monkeypatch, api, path):
293
293
  ]
294
294
 
295
295
 
296
+ def test_get_result_sends_focus_only_when_asked(monkeypatch):
297
+ calls = fake_requests(monkeypatch, FakeResponse(body={"pid": 7}))
298
+ behavioral = Client(cid="1", api_key="k").behavioral
299
+ behavioral.get_result(pid=7)
300
+ behavioral.get_result(pid=7, focus=["angry", "low_confidence"], sensitivity="high")
301
+ assert [call.params for call in calls[-2:]] == [
302
+ None,
303
+ {"focus": "angry,low_confidence", "sensitivity": "high"},
304
+ ]
305
+
306
+
307
+ def test_wait_for_result_sends_focus(monkeypatch):
308
+ calls = fake_requests(monkeypatch, FakeResponse(body={"pid": 7, "status": 2}))
309
+ behavioral = Client(cid="1", api_key="k").behavioral
310
+ behavioral.wait_for_result(pid=7, focus=["angry"], sensitivity="high")
311
+ assert calls[-1].params == {"focus": "angry", "sensitivity": "high"}
312
+
313
+
314
+ def test_get_result_sends_an_empty_focus_list_for_the_api_to_reject(monkeypatch):
315
+ calls = fake_requests(monkeypatch, FakeResponse(body={"pid": 7}))
316
+ Client(cid="1", api_key="k").behavioral.get_result(pid=7, focus=[])
317
+ assert calls[-1].params == {"focus": "", "sensitivity": "default"}
318
+
319
+
296
320
  def test_get_video_result_parses_both_result_lists(monkeypatch):
297
321
  body = {
298
322
  "pid": 7,
@@ -0,0 +1,112 @@
1
+ """Runs the example scripts and the README snippets against a fake API.
2
+
3
+ `batch_upload_dataset.py` and `streaming_from_mic.py` are not run: they need a download, a
4
+ microphone and extra packages. CI checks them, and the others, with mypy.
5
+ """
6
+
7
+ import re
8
+ import sys
9
+ import wave
10
+ import runpy
11
+ from types import SimpleNamespace
12
+ from pathlib import Path
13
+
14
+ import pytest
15
+ from test_client import FakeResponse, fake_requests
16
+ from test_streaming import fake_channel
17
+
18
+ from behavioralsignals.models import ProcessStatus
19
+ from behavioralsignals.generated import api_pb2 as pb
20
+
21
+
22
+ ROOT = Path(__file__).parent.parent
23
+ RESULTS = [
24
+ {
25
+ "task": "emotion",
26
+ "startTime": "0.5",
27
+ "endTime": "3.0",
28
+ "finalLabel": "sad",
29
+ "prediction": [{"label": "sad", "posterior": "0.9"}],
30
+ },
31
+ {
32
+ "task": "positivity",
33
+ "startTime": "0.5",
34
+ "endTime": "3.0",
35
+ "finalLabel": "negative",
36
+ "prediction": [
37
+ {"label": "negative", "posterior": "0.7"},
38
+ {"label": "positive", "posterior": "0.1"},
39
+ ],
40
+ },
41
+ {
42
+ "task": "strength",
43
+ "startTime": "0.5",
44
+ "endTime": "3.0",
45
+ "finalLabel": "weak",
46
+ "prediction": [
47
+ {"label": "weak", "posterior": "0.7"},
48
+ {"label": "strong", "posterior": "0.1"},
49
+ ],
50
+ },
51
+ ]
52
+ # The fake API gives this one answer to every request: it fits auth, process and result responses.
53
+ API_RESPONSE = {
54
+ "pid": 1,
55
+ "status": ProcessStatus.COMPLETED,
56
+ "results": RESULTS,
57
+ "audio_results": RESULTS,
58
+ "video_results": RESULTS,
59
+ }
60
+ STREAM_RESPONSE = pb.StreamResult(
61
+ pid=1,
62
+ result=[pb.InferenceResult(task="emotion", final_label="sad", start_time="0", end_time="1")],
63
+ )
64
+
65
+
66
+ def write_silent_wav(path):
67
+ with wave.open(str(path), "wb") as audio:
68
+ audio.setnchannels(1)
69
+ audio.setsampwidth(2)
70
+ audio.setframerate(8000)
71
+ audio.writeframes(b"\0\0" * 8000)
72
+
73
+
74
+ @pytest.fixture
75
+ def fake_api(monkeypatch, tmp_path):
76
+ """Fakes HTTP, gRPC and credentials, inside a folder with audio.wav and video.mp4."""
77
+ monkeypatch.setenv("BEHAVIORALSIGNALS_CID", "1")
78
+ monkeypatch.setenv("BEHAVIORALSIGNALS_API_KEY", "fake")
79
+ # The examples need python-dotenv, which the SDK does not depend on.
80
+ monkeypatch.setitem(sys.modules, "dotenv", SimpleNamespace(load_dotenv=lambda: None))
81
+ fake_requests(monkeypatch, FakeResponse(body=API_RESPONSE))
82
+ fake_channel(monkeypatch, [STREAM_RESPONSE])
83
+ monkeypatch.chdir(tmp_path)
84
+ write_silent_wav(tmp_path / "audio.wav")
85
+ (tmp_path / "video.mp4").write_bytes(b"fake video")
86
+
87
+
88
+ @pytest.mark.parametrize(
89
+ ("script", "args"),
90
+ [
91
+ ("batch/batch_api_polling.py", ["--file_path", "audio.wav", "--api", "behavioral"]),
92
+ ("batch/batch_api_polling.py", ["--file_path", "audio.wav", "--api", "deepfakes"]),
93
+ ("batch/video_deepfake_polling.py", ["--file_path", "video.mp4"]),
94
+ ("streaming/streaming_api_file.py", ["--file_path", "audio.wav", "--api", "behavioral"]),
95
+ ("streaming/streaming_api_file.py", ["--file_path", "audio.wav", "--api", "deepfakes"]),
96
+ ],
97
+ )
98
+ @pytest.mark.usefixtures("fake_api")
99
+ def test_example_runs_and_saves_the_results(monkeypatch, script, args):
100
+ monkeypatch.setattr(sys, "argv", [script, *args, "--output", "out.json"])
101
+ runpy.run_path(str(ROOT / "examples" / script), run_name="__main__")
102
+ assert "sad" in Path("out.json").read_text()
103
+
104
+
105
+ @pytest.mark.usefixtures("fake_api")
106
+ def test_readme_python_snippets_run_in_order():
107
+ # Later snippets use names from earlier ones, as a reader would, so they share a namespace.
108
+ snippets = re.findall(r"(?ms)^```python\n(.*?)^```", (ROOT / "README.md").read_text())
109
+ assert snippets
110
+ namespace = {}
111
+ for snippet in snippets:
112
+ exec(snippet, namespace)
@@ -177,6 +177,41 @@ async def test_tasks_filter_keeps_those_tasks_and_the_more_hint_repeats_it(api):
177
177
  assert none == "pid 7 completed. No result rows. Tasks: asr, emotion"
178
178
 
179
179
 
180
+ async def test_focus_is_sent_shown_and_kept_in_the_hints(api):
181
+ flag = item("focus", "suspected_angry")
182
+ flag.prediction = [ModelPredictions(label="angry", posterior="0.6124")]
183
+ api.responses["wait_for_result"] = ResultResponse(
184
+ pid=7, results=[item("emotion", "neutral"), flag]
185
+ )
186
+ _, text = await call(
187
+ "get_result", pid=7, analysis="behavioral", focus=["angry"], sensitivity="high", limit=1
188
+ )
189
+ _, all_rows = await call("get_result", pid=7, analysis="behavioral", focus=["angry"])
190
+ api.responses["wait_for_result"] = TimeoutError("still running")
191
+ _, waiting = await call(
192
+ "get_result", pid=7, analysis="behavioral", focus=["angry"], wait_seconds=0
193
+ )
194
+ assert api.calls[0] == (
195
+ "wait_for_result",
196
+ {"pid": 7, "timeout": 45.0, "focus": ["angry"], "sensitivity": "high"},
197
+ )
198
+ assert text.endswith(
199
+ 'More rows: get_result(pid=7, analysis="behavioral", offset=1, focus=["angry"], '
200
+ 'sensitivity="high")'
201
+ )
202
+ assert all_rows.splitlines()[-1] == "0.5\t1.5\tfocus\tsuspected_angry\tangry=0.61"
203
+ assert waiting == (
204
+ 'pid 7 is still processing. Call get_result(pid=7, analysis="behavioral", '
205
+ 'focus=["angry"], sensitivity="default") to wait again.'
206
+ )
207
+
208
+
209
+ async def test_focus_on_a_deepfake_result_is_an_error(api):
210
+ is_error, text = await call("get_result", pid=7, analysis="deepfake_audio", focus=["angry"])
211
+ assert is_error and "only available for behavioral results" in text
212
+ assert api.calls == []
213
+
214
+
180
215
  async def test_still_processing_returns_the_pid_to_check_later(api):
181
216
  api.responses["wait_for_video_result"] = TimeoutError("still running")
182
217
  is_error, text = await call("get_result", pid=9, analysis="deepfake_video", wait_seconds=0)
@@ -355,3 +390,19 @@ async def test_list_processes_uses_the_video_list_for_video(api):
355
390
  _, text = await call("list_processes", analysis="deepfake_video")
356
391
  assert api.built == ["Deepfakes"] and api.calls[0][0] == "list_video_processes"
357
392
  assert text == "No processes found."
393
+
394
+
395
+ async def test_a_group_name_selects_all_its_tasks(api):
396
+ api.responses["wait_for_result"] = ResultResponse(
397
+ pid=7,
398
+ results=[
399
+ item("emotion", "sad", "0.706"),
400
+ item("signal_quality.snr", score="0.9594"),
401
+ item("signal_quality.overall", score="0.5125"),
402
+ ],
403
+ )
404
+ _, text = await call("get_result", pid=7, analysis="behavioral", tasks=["signal_quality"])
405
+ assert [line.split("\t")[2] for line in text.splitlines()[2:]] == [
406
+ "signal_quality.snr",
407
+ "signal_quality.overall",
408
+ ]
@@ -86,6 +86,20 @@ def test_streaming_level_all_asks_for_both_levels(monkeypatch):
86
86
  assert not channel.sent[0].config.HasField("level")
87
87
 
88
88
 
89
+ def test_streaming_sends_focus_only_when_asked():
90
+ assert not StreamingOptions(encoding="LINEAR_PCM").to_pb_config().HasField("focus")
91
+ config = StreamingOptions(
92
+ encoding="LINEAR_PCM", focus=["angry", "low_confidence"], sensitivity="high"
93
+ ).to_pb_config()
94
+ assert list(config.focus.labels) == ["angry", "low_confidence"]
95
+ assert config.focus.sensitivity == "high"
96
+
97
+
98
+ def test_streaming_sends_an_empty_focus_list_for_the_api_to_reject():
99
+ config = StreamingOptions(encoding="LINEAR_PCM", focus=[]).to_pb_config()
100
+ assert config.HasField("focus") and list(config.focus.labels) == []
101
+
102
+
89
103
  @pytest.mark.parametrize("cls", [Behavioral, Deepfakes])
90
104
  def test_stream_audio_parses_the_responses(monkeypatch, cls):
91
105
  response = pb.StreamResult(
@@ -109,3 +123,29 @@ def test_stream_audio_parses_the_responses(monkeypatch, cls):
109
123
  item = results[0].results[0]
110
124
  assert (item.st, item.et, item.task, item.finalLabel) == (0.487, 3.001, "emotion", "sad")
111
125
  assert [(p.label, p.posterior) for p in item.prediction] == [("sad", "0.9")]
126
+
127
+
128
+ def test_stream_audio_drops_the_empty_fields_of_a_score(monkeypatch):
129
+ response = pb.StreamResult(
130
+ pid=7,
131
+ result=[
132
+ pb.InferenceResult(
133
+ id="2",
134
+ start_time="0.00",
135
+ end_time="2.00",
136
+ task="intensity",
137
+ level=pb.Level.Value("segment"),
138
+ prediction=[pb.Prediction(score="0.3231", posterior="")],
139
+ )
140
+ ],
141
+ )
142
+ fake_channel(monkeypatch, [response])
143
+ item = stream_audio(Behavioral)[0].results[0]
144
+ assert item.model_dump(exclude={"st", "et"}) == {
145
+ "id": "2",
146
+ "startTime": "0.00",
147
+ "endTime": "2.00",
148
+ "task": "intensity",
149
+ "prediction": [{"score": "0.3231"}],
150
+ "level": "segment",
151
+ }
@@ -46,7 +46,7 @@ def make_client(cls, statuses, video=False):
46
46
  if video:
47
47
  client.get_video_process, client.get_video_result = get_process, lambda pid: result
48
48
  else:
49
- client.get_process, client.get_result = get_process, lambda pid: result
49
+ client.get_process, client.get_result = get_process, lambda pid, *focus: result
50
50
  return client, calls, result
51
51
 
52
52
 
@@ -1,50 +0,0 @@
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\"\xf4\x01\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\x42\x08\n\x06_levelB\t\n\x07_logitsB\x14\n\x12_feature_embedding\"|\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\"}\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=916
35
- _globals['_AUDIOENCODING']._serialized_end=947
36
- _globals['_LEVEL']._serialized_start=949
37
- _globals['_LEVEL']._serialized_end=984
38
- _globals['_AUDIOCONFIG']._serialized_start=38
39
- _globals['_AUDIOCONFIG']._serialized_end=282
40
- _globals['_AUDIOSTREAM']._serialized_start=284
41
- _globals['_AUDIOSTREAM']._serialized_end=408
42
- _globals['_PREDICTION']._serialized_start=410
43
- _globals['_PREDICTION']._serialized_end=535
44
- _globals['_INFERENCERESULT']._serialized_start=538
45
- _globals['_INFERENCERESULT']._serialized_end=795
46
- _globals['_STREAMRESULT']._serialized_start=797
47
- _globals['_STREAMRESULT']._serialized_end=914
48
- _globals['_BEHAVIORALSTREAMINGAPI']._serialized_start=987
49
- _globals['_BEHAVIORALSTREAMINGAPI']._serialized_end=1209
50
- # @@protoc_insertion_point(module_scope)