a11-kit 0.2.2__tar.gz → 0.2.3__tar.gz

{a11_kit-0.2.2 → a11_kit-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: a11-kit
-Version: 0.2.2
+Version: 0.2.3
 Summary: Concurrent action and streaming runtime with a native C++ backend
 Requires-Python: >=3.11
 Requires-Dist: absl-py>=2.5.0

a11_kit-0.2.3/VERSION

@@ -0,0 +1 @@
+0.2.3

{a11_kit-0.2.2 → a11_kit-0.2.3}/a11/__init__.py

@@ -118,6 +118,12 @@ from .timing import (
 
 
 def get_deadline(action: Action) -> Time:
+    """Read the ``x-a11-deadline`` header as an absolute :class:`Time`.
+
+    The value is a base-10 count of **milliseconds** since the Unix epoch, or a
+    base-10 count of **nanoseconds** when suffixed with ``ns``. An absent header
+    means no deadline (:func:`infinite_future`).
+    """
     deadline_str = action.get_header("x-a11-deadline", decode=True)
     if deadline_str is None:
         return infinite_future()
@@ -130,29 +136,31 @@ def get_deadline(action: Action) -> Time:
     try:
         deadline = int(deadline_str)
     except ValueError:
-        raise Status(
-            code=StatusCode.INVALID_ARGUMENT,
-            message=(
-                "Deadline header must be an integer optionally followed by 'ns'"
-            ),
-        ).to_exception()
-
+        deadline = -1
     if deadline < 0:
         raise Status(
             code=StatusCode.INVALID_ARGUMENT,
             message=(
-                "Deadline header must be a non-negative integer optionally"
-                " followed by 'ns'"
+                "The x-a11-deadline header must be a non-negative base-10"
+                " integer of milliseconds since the epoch, or nanoseconds with"
+                " an 'ns' suffix."
             ),
         ).to_exception()
 
-    if nanos:
+    # Bare values are milliseconds; only the 'ns' form is already nanoseconds.
+    if not nanos:
         deadline *= 1000000
 
     return Time.from_nanoseconds_since_epoch(deadline)
 
 
 def set_deadline_header(action: Action, deadline: Time = infinite_future()):
+    """Write ``deadline`` to the ``x-a11-deadline`` header as milliseconds.
+
+    An infinite deadline clears the header. The value is emitted as a bare
+    base-10 millisecond count, the representation :func:`get_deadline` reads by
+    default.
+    """
     if deadline == infinite_future():
         try:
             action.remove_header("x-a11-deadline")

{a11_kit-0.2.2 → a11_kit-0.2.3}/a11/_native.pyi

@@ -40,6 +40,8 @@ __all__: list[str] = [
     "ActionSettings",
     "AsyncNode",
     "AudioBuffer",
+    "AudioCaptureEvent",
+    "AudioControlEvent",
     "AudioDeviceInfo",
     "AudioInput",
     "AudioInputOptions",
@@ -121,6 +123,7 @@ __all__: list[str] = [
     "TCP",
     "TLS",
     "Time",
+    "TranscriptionEvent",
     "TurnRelayType",
     "TurnServer",
     "UDP",
@@ -143,6 +146,8 @@ __all__: list[str] = [
     "WireStream",
     "WireStreamOptions",
     "WireStreamWithRecv",
+    "audio_buffer_from_msgpack",
+    "audio_buffer_to_msgpack",
     "audio_device_info",
     "create_in_process_wire_stream_pair",
     "default_audio_input_device",
@@ -159,6 +164,7 @@ __all__: list[str] = [
     "obs_recorded_spans",
     "obs_shutdown",
     "obs_start_span",
+    "register_audio_actions",
     "reset_default_redis_client",
     "set_default_redis_client",
     "status_code_from_http",
@@ -1586,6 +1592,16 @@ class AudioBuffer:
         Return a buffer object that exposes the underlying memory of the object.
         """
 
+    def __init__(
+        self,
+        data: collections.abc.Buffer,
+        sample_rate: typing.SupportsFloat,
+        num_channels: typing.SupportsInt = 1,
+    ) -> None:
+        """
+        Build an AudioBuffer from a buffer-protocol object (bytes, a NumPy array, a CPU PyTorch tensor, ...). Samples are read as channel-major float32 (raw bytes are reinterpreted as float32); a 2-D buffer's first dimension is the channel count.
+        """
+
     def __release_buffer__(self, buffer):
         """
         Release the buffer object that exposes the underlying memory of the object.
@@ -1626,6 +1642,72 @@ class AudioBuffer:
         A zero-copy read-only ``(channels, frames)`` float view.
         """
 
+class AudioCaptureEvent:
+    """
+    A capture lifecycle or dropped-buffer notification from capture_audio.
+    """
+
+    __hash__: None = None  # pyright: ignore[reportIncompatibleMethodOverride]
+    @staticmethod
+    def buffers_dropped(count: typing.SupportsInt) -> AudioCaptureEvent: ...
+    @staticmethod
+    def started() -> AudioCaptureEvent: ...
+    @staticmethod
+    def stopped() -> AudioCaptureEvent: ...
+    def __eq__(self, arg0: object) -> bool: ...
+    def __init__(
+        self, kind: str = "started", dropped: typing.SupportsInt = 0
+    ) -> None:
+        """
+        Construct a capture event.
+        """
+
+    def __repr__(self) -> str: ...
+
+    @property
+    def dropped(self) -> int:
+        """
+        Buffers dropped since the previous event.
+        """
+    @dropped.setter
+    def dropped(self, arg0: typing.SupportsInt) -> None: ...
+
+    @property
+    def kind(self) -> str:
+        """
+        The event kind: 'started', 'buffers_dropped' or 'stopped'.
+        """
+    @kind.setter
+    def kind(self, arg1: str) -> None: ...
+
+class AudioControlEvent:
+    """
+    A command on an Action's control_events input; 'stop' finishes capture gracefully.
+    """
+
+    __hash__: None = None  # pyright: ignore[reportIncompatibleMethodOverride]
+    @staticmethod
+    def stop() -> AudioControlEvent:
+        """
+        A stop command that finishes capture gracefully.
+        """
+
+    def __eq__(self, arg0: object) -> bool: ...
+    def __init__(self, command: str = "stop") -> None:
+        """
+        Construct a control event.
+        """
+
+    def __repr__(self) -> str: ...
+
+    @property
+    def command(self) -> str:
+        """
+        The command name, e.g. 'stop'.
+        """
+    @command.setter
+    def command(self, arg1: str) -> None: ...
+
 class AudioDeviceInfo:
     """
     Static metadata describing one host audio device.
@@ -1787,10 +1869,12 @@ class AudioInputOptions:
     def __init__(
         self,
         device_index: typing.SupportsInt = -1,
+        device_name: str = "",
         sample_rate: typing.SupportsFloat = 0.0,
         channels: typing.SupportsInt = 0,
         block_frames: typing.SupportsInt = 256,
         ring_blocks: typing.SupportsInt = 32,
+        buffer_frames: typing.SupportsInt = 0,
     ) -> None:
         """
         Construct validated audio input options.
@@ -1813,6 +1897,14 @@ class AudioInputOptions:
     @block_frames.setter
     def block_frames(self, arg0: typing.SupportsInt) -> None: ...
 
+    @property
+    def buffer_frames(self) -> int:
+        """
+        Frames per delivered subscription buffer, or 0 for the block size.
+        """
+    @buffer_frames.setter
+    def buffer_frames(self, arg0: typing.SupportsInt) -> None: ...
+
     @property
     def channels(self) -> int:
         """
@@ -1829,6 +1921,14 @@ class AudioInputOptions:
     @device_index.setter
     def device_index(self, arg0: typing.SupportsInt) -> None: ...
 
+    @property
+    def device_name(self) -> str:
+        """
+        Input device name to capture from; empty selects by index or the default input.
+        """
+    @device_name.setter
+    def device_name(self, arg0: str) -> None: ...
+
     @property
     def ring_blocks(self) -> int:
         """
@@ -5153,7 +5253,7 @@ class SignallingTransport:
 
 class SpeechRecognizer:
     """
-    Restartable local automatic speech recognizer backed by whisper.cpp. It invokes inference only for speech endpointed by its adaptive VAD.
+    Restartable local automatic speech recognizer backed by whisper.cpp. A cheap energy gate endpoints utterances so silence never reaches the decoder; a Silero VAD model, when configured, then filters each utterance to genuine speech before inference.
     """
 
     @staticmethod
@@ -5231,7 +5331,7 @@ class SpeechRecognizer:
 
 class SpeechRecognizerOptions:
     """
-    Configuration for whisper.cpp transcription and adaptive VAD.
+    Configuration for whisper.cpp transcription, a cheap energy VAD gate, and optional whisper.cpp Silero neural VAD.
     """
 
     _a11_options_installed: typing.ClassVar[bool] = True
@@ -5250,6 +5350,7 @@ class SpeechRecognizerOptions:
     def __eq__(self, other: object) -> bool: ...
     def __init__(
         self,
+        model_path: str = "",
         language: str = "auto",
         translate: bool = False,
         inference_threads: typing.SupportsInt = 0,
@@ -5337,6 +5438,14 @@ class SpeechRecognizerOptions:
     @min_speech_millis.setter
     def min_speech_millis(self, arg0: typing.SupportsInt) -> None: ...
 
+    @property
+    def model_path(self) -> str:
+        """
+        Path to the whisper.cpp model; used by the transcription action (empty is rejected there).
+        """
+    @model_path.setter
+    def model_path(self, arg0: str) -> None: ...
+
     @property
     def silero_threshold(self) -> float:
         """
@@ -5669,6 +5778,36 @@ class Time:
         The time as nanoseconds since the Unix epoch.
         """
 
+class TranscriptionEvent:
+    """
+    A capture/inference lifecycle notification from capture_transcription.
+    """
+
+    __hash__: None = None  # pyright: ignore[reportIncompatibleMethodOverride]
+    @staticmethod
+    def capture_started() -> TranscriptionEvent: ...
+    @staticmethod
+    def capture_stopped() -> TranscriptionEvent: ...
+    @staticmethod
+    def inference_started() -> TranscriptionEvent: ...
+    @staticmethod
+    def inference_stopped() -> TranscriptionEvent: ...
+    def __eq__(self, arg0: object) -> bool: ...
+    def __init__(self, kind: str = "capture_started") -> None:
+        """
+        Construct a transcription event.
+        """
+
+    def __repr__(self) -> str: ...
+
+    @property
+    def kind(self) -> str:
+        """
+        The event kind, e.g. 'inference_started'.
+        """
+    @kind.setter
+    def kind(self, arg1: str) -> None: ...
+
 class TurnRelayType:
     """
     Members:
@@ -7308,6 +7447,16 @@ class _StringSchemaMapView:
         Return a view of the map's values.
         """
 
+def audio_buffer_from_msgpack(data: bytes) -> AudioBuffer:
+    """
+    Decode an AudioBuffer from A11's MessagePack representation.
+    """
+
+def audio_buffer_to_msgpack(buffer: AudioBuffer) -> bytes:
+    """
+    Encode an AudioBuffer to A11's MessagePack representation.
+    """
+
 def audio_device_info(index: typing.SupportsInt) -> AudioDeviceInfo:
     """
     Return metadata for the audio device at `index`.
@@ -7403,6 +7552,11 @@ def obs_start_span(
     Starts a new span with the given name and kind, optionally parented by a W3C traceparent.
     """
 
+def register_audio_actions(registry: ActionRegistry | None) -> None:
+    """
+    Register the list_audio_inputs, capture_audio and capture_transcription Actions on `registry`, wiring each port's typeinfo to the matching audio type and ensuring their serializers are installed.
+    """
+
 def reset_default_redis_client() -> None:
     """
     Clear the global Redis client so its environment is reread.

a11_kit-0.2.3/a11/sdk/audio/actions.py

@@ -0,0 +1,84 @@
+"""Action-based interface to the audio SDK.
+
+Three native (C++) Actions wrap the capture and recognition primitives and can
+be registered on any :class:`a11.ActionRegistry`:
+
+* ``list_audio_inputs`` streams one :class:`~a11.sdk.audio.AudioDeviceInfo` per
+  available input device;
+* ``capture_audio`` streams :class:`~a11.sdk.audio.AudioBuffer` blocks with a
+  control input that accepts a stop command;
+* ``capture_transcription`` streams recognized text pieces, reusing the capture
+  path and driving whisper.cpp recognition;
+* ``transcribe_audio`` streams recognized text pieces from a caller-supplied
+  :class:`~a11.sdk.audio.AudioBuffer` stream instead of a device, stopping on
+  input closure or cancellation.
+
+Call :func:`register` to install all three on a registry; their handlers and
+value-type serialization live in C++, and each port's ``typeinfo`` is wired to
+the matching native audio class so schema-driven tooling sees the right types.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from a11 import _native
+from a11._native_options import install_native_options
+from a11.sdk.audio.client import register_json_codec
+
+from a11._native import AudioCaptureEvent
+from a11._native import AudioControlEvent
+from a11._native import TranscriptionEvent
+
+if TYPE_CHECKING:
+    from a11.actions import ActionRegistry
+
+#: Registered name of the list-inputs Action.
+LIST_AUDIO_INPUTS = "list_audio_inputs"
+#: Registered name of the capture Action.
+CAPTURE_AUDIO = "capture_audio"
+#: Registered name of the transcription Action.
+CAPTURE_TRANSCRIPTION = "capture_transcription"
+#: Registered name of the buffer-stream transcription Action.
+TRANSCRIBE_AUDIO = "transcribe_audio"
+
+install_native_options(AudioControlEvent, {"command": (str, "stop")})
+install_native_options(
+    AudioCaptureEvent, {"kind": (str, "started"), "dropped": (int, 0)}
+)
+install_native_options(TranscriptionEvent, {"kind": (str, "capture_started")})
+
+# JSON codecs so the event types round-trip through the Python serialization
+# registry the AsyncNode uses, matching the native C++ tags.
+register_json_codec(AudioControlEvent, "a11.sdk.audio.AudioControlEvent")
+register_json_codec(AudioCaptureEvent, "a11.sdk.audio.AudioCaptureEvent")
+register_json_codec(TranscriptionEvent, "a11.sdk.audio.TranscriptionEvent")
+
+_native_register_audio_actions = _native.register_audio_actions
+
+
+def register(registry: ActionRegistry) -> None:
+    """Register the three audio Actions on ``registry``.
+
+    Installs ``list_audio_inputs``, ``capture_audio`` and
+    ``capture_transcription`` (schema + native handler) and ensures the audio
+    value-type serializers are available. Raises if a name is already
+    registered.
+    """
+    _native_register_audio_actions(registry)
+
+
+for _class in (AudioControlEvent, AudioCaptureEvent, TranscriptionEvent):
+    _class.__module__ = __name__
+
+
+__all__ = [
+    "CAPTURE_AUDIO",
+    "CAPTURE_TRANSCRIPTION",
+    "LIST_AUDIO_INPUTS",
+    "TRANSCRIBE_AUDIO",
+    "AudioCaptureEvent",
+    "AudioControlEvent",
+    "TranscriptionEvent",
+    "register",
+]

{a11_kit-0.2.2 → a11_kit-0.2.3}/a11/sdk/audio/client.py

@@ -10,6 +10,7 @@ and ``buffer.channel(i)`` is one channel's row.
 
 from __future__ import annotations
 
+import json
 import os
 from collections.abc import Awaitable, Callable, Mapping
 from typing import Any, Self
@@ -17,6 +18,10 @@ from typing import Any, Self
 from a11 import _native
 from a11._native_options import install_native_options
 from a11._native_protocol import attach_protocol
+from a11.data.serialization import (
+    get_global_serialization_registry,
+    set_global_type_tag,
+)
 from a11.status import Status, StatusCode, StatusException
 
 from a11._native import AudioBuffer
@@ -34,16 +39,19 @@ install_native_options(
     AudioInputOptions,
     {
         "device_index": (int, -1),
+        "device_name": (str, ""),
         "sample_rate": (float, 0.0),
         "channels": (int, 0),
         "block_frames": (int, 256),
         "ring_blocks": (int, 32),
+        "buffer_frames": (int, 0),
     },
 )
 
 install_native_options(
     SpeechRecognizerOptions,
     {
+        "model_path": (str, ""),
         "language": (str, "auto"),
         "translate": (bool, False),
         "inference_threads": (int, 0),
@@ -64,6 +72,71 @@ install_native_options(
     },
 )
 
+def register_json_codec(cls: type, tag: str) -> None:
+    """Register a JSON codec for ``cls`` on the global Python registry.
+
+    Mirrors the native C++ codec so an audio value serialized by one language
+    (with the tag ``application/json;type=<tag>``) round-trips through the
+    other. ``cls`` must expose ``model_dump``/``model_validate`` (installed by
+    :func:`install_native_options`). Idempotent across repeated imports.
+    """
+    registry = get_global_serialization_registry()
+    set_global_type_tag(cls, tag)
+
+    def _serialize(obj: Any, _cls: type = cls) -> str:
+        return json.dumps(obj.model_dump())
+
+    def _deserialize(chunk: Any, _cls: type = cls) -> Any:
+        data = chunk.data
+        if isinstance(data, (bytes, bytearray)):
+            data = bytes(data).decode("utf-8")
+        return _cls.model_validate(json.loads(data))
+
+    try:
+        registry.register(
+            cls, "application/json", _serialize, _deserialize,
+            receives_chunk=True,
+        )
+    except StatusException:
+        pass  # already registered in this process
+
+
+register_json_codec(AudioInputOptions, "a11.sdk.audio.AudioInputOptions")
+register_json_codec(
+    SpeechRecognizerOptions, "a11.sdk.audio.SpeechRecognizerOptions"
+)
+
+
+def _register_audio_buffer_codec() -> None:
+    """Register the MessagePack codec for AudioBuffer on the global registry.
+
+    Both directions delegate to the native encoder/decoder so the bytes are
+    byte-for-byte identical to what C++ produces and consumes (samples as a
+    little-endian float32 blob).
+    """
+    registry = get_global_serialization_registry()
+    set_global_type_tag(AudioBuffer, "a11.sdk.audio.AudioBuffer")
+
+    def _serialize(buffer: AudioBuffer) -> bytes:
+        return _native.audio_buffer_to_msgpack(buffer)
+
+    def _deserialize(chunk: Any) -> AudioBuffer:
+        data = chunk.data
+        if isinstance(data, (bytes, bytearray)):
+            data = bytes(data)
+        return _native.audio_buffer_from_msgpack(data)
+
+    try:
+        registry.register(
+            AudioBuffer, "application/x-msgpack", _serialize, _deserialize,
+            receives_chunk=True,
+        )
+    except StatusException:
+        pass  # already registered in this process
+
+
+_register_audio_buffer_codec()
+
 _native_list_devices = _native.list_audio_devices
 _native_default_input_device = _native.default_audio_input_device
 _native_device_info = _native.audio_device_info