listenflow 0.17.6__py3-none-any.whl

listenflow/__init__.py

@@ -0,0 +1,101 @@
+"""listenflow core library: PCM stream input, transcript events output."""
+
+from __future__ import annotations
+
+import importlib
+
+__path__ = __import__("pkgutil").extend_path(__path__, __name__)
+
+from listenflow._version import __version__
+from listenflow.engine import (
+    ClosedUtterance,
+    DiarizationMode,
+    EngineCapabilities,
+    EngineInputFormat,
+    EngineTransport,
+    FinalizationMode,
+    FinalObservation,
+    OfflineModelDirectorySource,
+    PartialMode,
+    ProvisionalObservation,
+    TimestampDetail,
+    UtteranceBoundarySettings,
+    UtteranceBoundarySession,
+    UtteranceDecodePipeline,
+    has_voice,
+)
+from listenflow.base import STTEngineBase
+from listenflow.events import Final, Partial, TranscriptEvent, UtteranceEnd, UtteranceStart
+from listenflow.health import BiasApplicationSnapshot, EngineState, HealthSnapshot
+from listenflow.sync import iterate_async, iterate_sync, run_sync
+from listenflow.errors import (
+    ConfigurationError,
+    EngineClosedError,
+    EngineStateError,
+    EnvironmentUnavailableError,
+    InferenceError,
+    ModuleNotInstalledError,
+    STTError,
+)
+
+__all__ = [
+    "BiasApplicationSnapshot",
+    "ClosedUtterance",
+    "ConfigurationError",
+    "DiarizationMode",
+    "EngineCapabilities",
+    "EngineClosedError",
+    "EngineInputFormat",
+    "EngineState",
+    "EngineStateError",
+    "EngineTransport",
+    "EnvironmentUnavailableError",
+    "Final",
+    "FinalObservation",
+    "FinalizationMode",
+    "HealthSnapshot",
+    "InferenceError",
+    "ModuleNotInstalledError",
+    "OfflineModelDirectorySource",
+    "Partial",
+    "PartialMode",
+    "ProvisionalObservation",
+    "STTEngineBase",
+    "STTError",
+    "TimestampDetail",
+    "TranscriptEvent",
+    "UtteranceEnd",
+    "UtteranceStart",
+    "UtteranceBoundarySettings",
+    "UtteranceBoundarySession",
+    "UtteranceDecodePipeline",
+    "__version__",
+    "has_voice",
+    "iterate_async",
+    "iterate_sync",
+    "run_sync",
+]
+
+# Add engine modules here when they are published on PyPI.
+_MODULE_DISTRIBUTIONS: dict[str, str] = {}
+
+
+def __getattr__(name: str) -> object:
+    try:
+        distribution = _MODULE_DISTRIBUTIONS[name]
+    except KeyError:
+        raise AttributeError(name) from None
+
+    module_name = f"{__name__}.{name}"
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        if exc.name != module_name:
+            raise
+        raise ModuleNotInstalledError(
+            f"why={module_name} is unavailable because {distribution} is not installed; "
+            f"what={distribution} provides {module_name}; "
+            f"how=pip install {distribution}"
+        ) from exc
+    globals()[name] = module
+    return module

listenflow/_async.py

@@ -0,0 +1,23 @@
+"""Wait for owned asynchronous work without interrupting its cleanup twice."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def cancel_once(task: asyncio.Task[object]) -> None:
+    if not task.done() and not task.cancelling():
+        task.cancel()
+
+
+async def finish(task: asyncio.Future[object]) -> None:
+    while not task.done():
+        try:
+            # Wait without adding this frame and its callers to a failed task's traceback.
+            await asyncio.wait((task,))
+        except asyncio.CancelledError:
+            continue
+        except BaseException:
+            break
+    if not task.cancelled():
+        task.exception()

listenflow/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.17.6'
+__version_tuple__ = version_tuple = (0, 17, 6)
+
+__commit_id__ = commit_id = None

listenflow/base.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator, Coroutine, Mapping
+from typing import Self
+
+from listenflow._async import cancel_once as _cancel, finish as _finish
+from listenflow.engine import EngineCapabilities, EngineInputFormat, validate_pcm_chunk
+from listenflow.errors import (
+    ConfigurationError,
+    EngineClosedError,
+    EngineStateError,
+    InferenceError,
+)
+from listenflow.events import TranscriptEvent
+from listenflow.health import EngineState, HealthSnapshot
+
+
+class STTEngineBase(ABC):
+    """Shared preparation, recognition, closure, and health behavior.
+
+    Use one engine instance on one event loop. Modules implement the hooks,
+    map native errors into STTError subclasses, and finish native work before
+    returning from a cancelled hook. Failed loads clean up their own resources.
+    """
+
+    def __init__(self) -> None:
+        self._model_lock = asyncio.Lock()
+        self._operations: set[asyncio.Task[None]] = set()
+        self._stream_started = asyncio.Event()
+        self._loaded = False
+        self._close_task: asyncio.Task[None] | None = None
+        self._last_progress_monotonic_s: float | None = None
+
+    @property
+    @abstractmethod
+    def capabilities(self) -> EngineCapabilities:
+        """Return the module's immutable, static capability declaration."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _load(self) -> None:
+        """Load resources and run a trial inference; clean up a failed load."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def _release(self) -> None:
+        """Return resources created by a successful load."""
+        raise NotImplementedError
+
+    @abstractmethod
+    def _recognize(self, pcm_chunks: AsyncIterator[bytes]) -> AsyncIterator[TranscriptEvent]:
+        """Recognize PCM; cancellation and iterator closure must finish native work."""
+        raise NotImplementedError
+
+    def _health_details(self) -> Mapping[str, object]:
+        """Return recognition fields only, without the three shared health fields."""
+        return {}
+
+    def _mark_progress(self) -> None:
+        """Record a processed PCM chunk or completed utterance decode."""
+        self._last_progress_monotonic_s = time.monotonic()
+
+    @property
+    def _closing(self) -> bool:
+        return self._close_task is not None
+
+    def _check_open(self) -> None:
+        if self._closing:
+            raise EngineClosedError("engine is closed")
+
+    def _start(self, coroutine: Coroutine[object, object, None]) -> asyncio.Task[None]:
+        task = asyncio.create_task(coroutine)
+        self._operations.add(task)
+        task.add_done_callback(self._operations.discard)
+        return task
+
+    async def prepare(self) -> None:
+        """Load and trial the model once; retry after an unsuccessful load."""
+        self._check_open()
+        if self._loaded:
+            return
+        task = self._start(self._prepare())
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            caller = asyncio.current_task()
+            if self._closing and caller is not None and not caller.cancelling():
+                raise EngineClosedError("engine closed while preparing") from None
+            _cancel(task)
+            await _finish(task)
+            raise
+        except Exception as error:
+            if self._closing:
+                raise EngineClosedError("engine closed while preparing") from error
+            raise
+        finally:
+            # A failed task retains this frame through the exception traceback.
+            del task
+
+    async def _prepare(self) -> None:
+        acquired = False
+        try:
+            await self._acquire_model_slot()
+            acquired = True
+            self._check_open()
+            if not self._loaded:
+                await self._load()
+                self._loaded = True
+            self._check_open()
+        except asyncio.CancelledError:
+            if self._closing:
+                raise EngineClosedError("engine closed while preparing") from None
+            raise
+        finally:
+            if acquired:
+                self._model_lock.release()
+
+    def stream(self, pcm_chunks: AsyncIterator[bytes]) -> AsyncIterator[TranscriptEvent]:
+        """Start recognition on the first read and keep its slot through cleanup.
+
+        The returned iterator supports aclose(). Close it explicitly when stopping
+        before the end, or use contextlib.aclosing around the iterator.
+        """
+        return _EngineStream(self, pcm_chunks)
+
+    async def _acquire_model_slot(self, *, recognition: bool = False) -> None:
+        self._check_open()
+        if recognition and self._stream_started.is_set():
+            raise EngineStateError("engine already has an active stream")
+        acquire = asyncio.create_task(self._model_lock.acquire())
+        overlap = asyncio.create_task(self._stream_started.wait()) if recognition else None
+        try:
+            if overlap is not None:
+                await asyncio.wait((acquire, overlap), return_when=asyncio.FIRST_COMPLETED)
+            self._check_open()
+            if overlap is not None and overlap.done():
+                raise EngineStateError("engine already has an active stream")
+            await acquire
+        except BaseException:
+            _cancel(acquire)
+            if overlap is not None:
+                _cancel(overlap)
+                await _finish(overlap)
+            await _finish(acquire)
+            if not acquire.cancelled() and acquire.exception() is None:
+                self._model_lock.release()
+            raise
+        finally:
+            if overlap is not None:
+                _cancel(overlap)
+
+    async def _validated_pcm(self, pcm_chunks: AsyncIterator[bytes]) -> AsyncIterator[bytes]:
+        input_format = self.capabilities.input_format
+        async for chunk in pcm_chunks:
+            if input_format in (EngineInputFormat.PCM_S16LE, EngineInputFormat.PCM_F32):
+                try:
+                    validate_pcm_chunk(chunk, input_format=input_format)
+                except ValueError as error:
+                    raise ConfigurationError(str(error)) from error
+            yield chunk
+
+    async def _run_stream(self, stream: _EngineStream) -> None:
+        iterator: AsyncIterator[TranscriptEvent] | None = None
+        acquired = False
+        recognizing = False
+        try:
+            await self._acquire_model_slot(recognition=True)
+            acquired = True
+            if not self._loaded:
+                raise EngineStateError("prepare the engine before recognition")
+            self._stream_started.set()
+            recognizing = True
+            iterator = aiter(self._recognize(self._validated_pcm(stream._pcm_chunks)))
+            while True:
+                request = await stream._requests.get()
+                try:
+                    event = await anext(iterator)
+                except StopAsyncIteration:
+                    self._check_open()
+                    break
+                self._check_open()
+                if stream._closed:
+                    break
+                if not request.done():
+                    request.set_result(event)
+        except asyncio.CancelledError:
+            if self._closing:
+                raise EngineClosedError("engine closed during recognition") from None
+            raise
+        finally:
+            try:
+                if iterator is not None and hasattr(iterator, "aclose"):
+                    await iterator.aclose()
+            finally:
+                if recognizing:
+                    self._stream_started.clear()
+                if acquired:
+                    self._model_lock.release()
+                # Do not let an exception traceback lead back to its task or Future.
+                request = None
+                del stream
+
+    async def aclose(self) -> None:
+        """Cancel operations, wait for their cleanup, and release resources once."""
+        first = self._close_task is None
+        if first:
+            self._close_task = asyncio.create_task(self._close())
+        task = self._close_task
+        assert task is not None
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            await _finish(task)
+            raise
+        except BaseException:
+            if first:
+                raise
+
+    async def _close(self) -> None:
+        operations = tuple(self._operations)
+        for task in operations:
+            _cancel(task)
+        await asyncio.gather(*operations, return_exceptions=True)
+        if self._loaded:
+            self._loaded = False
+            try:
+                await self._release()
+            except Exception as error:
+                raise InferenceError("engine resource release failed") from error
+
+    async def __aenter__(self) -> Self:
+        await self.prepare()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        await self.aclose()
+
+    def health(self) -> HealthSnapshot:
+        """Return held values immediately, including after closure."""
+        state = (
+            EngineState.CLOSED
+            if self._closing
+            else EngineState.READY
+            if self._loaded
+            else EngineState.UNPREPARED
+        )
+        return HealthSnapshot(
+            state=state,
+            busy=self._model_lock.locked(),
+            last_progress_monotonic_s=self._last_progress_monotonic_s,
+            **self._health_details(),
+        )
+
+
+class _EngineStream(AsyncIterator[TranscriptEvent]):
+    """Keep the model operation alive while the consumer pauses between reads."""
+
+    def __init__(self, engine: STTEngineBase, pcm_chunks: AsyncIterator[bytes]) -> None:
+        self._engine = engine
+        self._pcm_chunks = pcm_chunks
+        self._requests: asyncio.Queue[asyncio.Future[TranscriptEvent]] = asyncio.Queue()
+        self._task: asyncio.Task[None] | None = None
+        self._pending: asyncio.Future[TranscriptEvent] | None = None
+        self._closed = False
+
+    async def __anext__(self) -> TranscriptEvent:
+        future = None
+        try:
+            if self._closed:
+                raise StopAsyncIteration
+            self._engine._check_open()
+            if self._pending is not None:
+                raise EngineStateError("stream already has a pending read")
+            if self._task is not None and self._task.done():
+                self._task.result()
+                self._closed = True
+                raise StopAsyncIteration
+            future = asyncio.get_running_loop().create_future()
+            self._pending = future
+            self._requests.put_nowait(future)
+            if self._task is None:
+                self._task = self._engine._start(self._engine._run_stream(self))
+                self._task.add_done_callback(self._completed)
+            try:
+                return await future
+            except asyncio.CancelledError:
+                await self.aclose()
+                raise
+            finally:
+                self._pending = None
+        finally:
+            # Both the Future and the stream's task may hold the raised exception.
+            del self, future
+
+    def _completed(self, task: asyncio.Task[None]) -> None:
+        error = (
+            EngineClosedError("engine closed during recognition")
+            if task.cancelled() and self._engine._closing
+            else asyncio.CancelledError()
+            if task.cancelled()
+            else task.exception()
+        )
+        if self._engine._closing and not isinstance(error, EngineClosedError):
+            closed = EngineClosedError("engine closed during recognition")
+            closed.__cause__ = error
+            error = closed
+        if self._pending is not None and not self._pending.done():
+            self._pending.set_exception(error or StopAsyncIteration())
+
+    async def aclose(self) -> None:
+        self._closed = True
+        if self._task is not None:
+            _cancel(self._task)
+            await _finish(self._task)