huri-module-stt 0.1.0__tar.gz

huri_module_stt-0.1.0/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: huri-module-stt
+Version: 0.1.0
+Summary: HuRI module: Speech to text (faster-whisper) as a Ray Serve deployment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core[server]<0.5,>=0.4
+Requires-Dist: huri-events<0.2,>=0.1
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: faster-whisper<1.3,>=1.2.1
+
+# huri-module-stt
+
+Speech to text (faster-whisper) as a Ray Serve deployment.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `stt` | `huri.voice` → `huri.transcript` | Transcribes speech with faster-whisper (CPU or GPU) |
+
+```sh
+pip install -e packages/huri-module-stt     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=stt ...   # enable it on the server
+```
+
+Hardware-specific pins: `requirements-amd.txt`, `requirements-nvidia.txt` (install them before the package).
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-stt @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-stt"
+```

huri_module_stt-0.1.0/README.md

@@ -0,0 +1,29 @@
+# huri-module-stt
+
+Speech to text (faster-whisper) as a Ray Serve deployment.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `stt` | `huri.voice` → `huri.transcript` | Transcribes speech with faster-whisper (CPU or GPU) |
+
+```sh
+pip install -e packages/huri-module-stt     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=stt ...   # enable it on the server
+```
+
+Hardware-specific pins: `requirements-amd.txt`, `requirements-nvidia.txt` (install them before the package).
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-stt @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-stt"
+```

huri_module_stt-0.1.0/huri_module_stt.egg-info/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: huri-module-stt
+Version: 0.1.0
+Summary: HuRI module: Speech to text (faster-whisper) as a Ray Serve deployment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core[server]<0.5,>=0.4
+Requires-Dist: huri-events<0.2,>=0.1
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: faster-whisper<1.3,>=1.2.1
+
+# huri-module-stt
+
+Speech to text (faster-whisper) as a Ray Serve deployment.
+
+| Module | Topics | What it does |
+|---|---|---|
+| `stt` | `huri.voice` → `huri.transcript` | Transcribes speech with faster-whisper (CPU or GPU) |
+
+```sh
+pip install -e packages/huri-module-stt     # from a huri-modules checkout, next to huri-core and huri-events
+HURI_MODULES=stt ...   # enable it on the server
+```
+
+Hardware-specific pins: `requirements-amd.txt`, `requirements-nvidia.txt` (install them before the package).
+
+A distribution of
+[huri-modules](https://github.com/Lucy-Robotics/huri-modules), versioned in its
+`pyproject.toml` (see RELEASING.md there). It depends on `huri-core` and
+`huri-events`, which are not on PyPI: without a checkout, install them from git
+in the same pip command, so pip never looks them up on an index:
+
+```sh
+ref=0.1.0   # a huri-modules release tag
+core=0.4.0  # HURI_CORE_REF in that release's versions.env
+pip install \
+  "huri-core[server] @ git+https://github.com/Lucy-Robotics/huri-core.git@$core" \
+  "huri-events @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-events" \
+  "huri-module-stt @ git+https://github.com/Lucy-Robotics/huri-modules.git@$ref#subdirectory=packages/huri-module-stt"
+```

huri_module_stt-0.1.0/huri_module_stt.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+huri_module_stt.egg-info/PKG-INFO
+huri_module_stt.egg-info/SOURCES.txt
+huri_module_stt.egg-info/dependency_links.txt
+huri_module_stt.egg-info/entry_points.txt
+huri_module_stt.egg-info/requires.txt
+huri_module_stt.egg-info/top_level.txt
+huri_stt/__init__.py
+huri_stt/huri_module.toml
+huri_stt/module.py
+tests/test_stt.py

huri_module_stt-0.1.0/huri_module_stt.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

huri_module_stt-0.1.0/huri_module_stt.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[huri.modules]
+stt = huri_stt.module:STT

huri_module_stt-0.1.0/huri_module_stt.egg-info/requires.txt

@@ -0,0 +1,4 @@
+huri-core[server]<0.5,>=0.4
+huri-events<0.2,>=0.1
+numpy<2,>=1.26
+faster-whisper<1.3,>=1.2.1

huri_module_stt-0.1.0/huri_module_stt.egg-info/top_level.txt

@@ -0,0 +1 @@
+huri_stt

huri_module_stt-0.1.0/huri_stt/huri_module.toml

@@ -0,0 +1,7 @@
+name = "stt"
+summary = "Transcribes speech with faster-whisper (CPU or GPU)"
+input = { topic = "huri.voice", event = "huri_events.speech:Voice" }
+output = { topic = "huri.transcript", event = "huri_events.speech:Transcript" }
+events = ["huri-events>=0.1,<0.2"]
+requires = { gpu = false, actuation = false }
+huri_core = ">=0.4,<0.5"

huri_module_stt-0.1.0/huri_stt/module.py

@@ -0,0 +1,209 @@
+import asyncio
+import os
+from concurrent.futures import ThreadPoolExecutor
+from typing import AsyncGenerator, List
+
+import numpy as np
+from huri_events.speech import Transcript, Voice
+from ray import serve
+from ray.serve import handle
+
+from huri_core.core.module import ModuleWithHandle
+
+_MODEL_PATH = os.environ.get("HURI_STT_MODEL_PATH", "base")
+_NUM_WORKERS = int(os.environ.get("HURI_STT_NUM_WORKERS", "2"))
+# Set by the generated Serve config (scripts/install_local.sh) from the install
+# plan's STT decision, already translated into faster-whisper's vocabulary:
+# "cpu" | "cuda" | "auto" for the device, "int8"/"float16"/"auto" for the type.
+# Defaulting to "auto" here keeps the hand-written configs in config/ working.
+_DEVICE = os.environ.get("HURI_STT_DEVICE", "auto")
+_COMPUTE_TYPE = os.environ.get("HURI_STT_COMPUTE_TYPE", "auto")
+
+
+@serve.deployment(name="STTHandle", max_ongoing_requests=8)
+class STTHandle:
+    """faster-whisper model wrapper.
+
+    Holds the WhisperModel and runs transcription on its own Ray Serve actor,
+    off the HuRI master actor — model load and GPU inference no longer block the
+    websocket ingress / per-session router. Pinned to a GPU worker via
+    ray_actor_options in the Serve config (see deploy values.yaml).
+
+    Stateless across calls: the per-session sliding-window buffering lives in the
+    STT module, so this deployment is shared across all sessions.
+
+    :model: path to (or size name of) the faster-whisper model. Defaults to the
+        HURI_STT_MODEL_PATH env var, falling back to "base".
+    :device: "cpu", "cuda", or "auto".
+    :compute_type: e.g. "int8", "float16", or "auto".
+    """
+
+    def __init__(
+        self,
+        model: str = _MODEL_PATH,
+        device: str = _DEVICE,
+        compute_type: str = _COMPUTE_TYPE,
+        num_workers: int = _NUM_WORKERS,
+    ):
+        from faster_whisper import WhisperModel
+
+        # num_workers lets CTranslate2 service several transcriptions at once on
+        # this single replica — each "worker" is an independent inference slot
+        # over the shared (read-only) weights. Combined with the thread pool
+        # below, N sessions are transcribed concurrently while staying fully
+        # independent: no per-call client state is ever held here (the sliding
+        # window lives in the per-session STT module).
+        self.model_faster = WhisperModel(
+            model,
+            device=device,
+            compute_type=compute_type,
+            num_workers=num_workers,
+        )
+        # Run the *blocking* faster-whisper call off the actor's asyncio loop.
+        # transcribe() used to be an async method that called the synchronous
+        # model inline, blocking the replica's event loop for the whole inference
+        # — serialising every session on the replica and stalling Serve health
+        # checks. Offloading to a thread pool (sized to num_workers) keeps the
+        # loop free to accept other sessions' requests while inference runs.
+        self._executor = ThreadPoolExecutor(
+            max_workers=num_workers, thread_name_prefix="stt-transcribe"
+        )
+
+    async def transcribe(self, audio: np.ndarray, language: str = "en") -> str:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            self._executor, self._transcribe_sync, audio, language
+        )
+
+    def _transcribe_sync(self, audio: np.ndarray, language: str) -> str:
+        segments, _ = self.model_faster.transcribe(
+            audio,
+            language=language,
+            beam_size=1,  # faster for realtime
+        )
+        return " ".join([seg.text for seg in segments]).strip()
+
+
+class STT(ModuleWithHandle):
+    """STT Module
+
+    Transcribe voice using Faster_Whisper.
+
+    Holds the per-session sliding-window buffer and delegates the actual
+    transcription to a handle-backed STTHandle, so the Whisper model runs
+    off the HuRI master node.
+
+    input: huri.voice,
+    output: huri.transcript
+
+    :language: language spoken in the audio. It should be a language code such
+        as "en" or "fr".
+    :sample_rate: size of received voice audio. Usually 8000, 16000 or 48000.
+    :block_duration: size of received voice audio (in s).
+    :transcribe_window: duration of audio per transcription (in s).
+    :transcribe_step: overlap between consecutive transcription windows (in s).
+    """
+
+    _handle_cls = STTHandle
+    input_type = "huri.voice"
+    output_type = "huri.transcript"
+    input_event = Voice
+    output_event = Transcript
+
+    def __init__(
+        self,
+        _handle: handle.DeploymentHandle,
+        language: str = "en",
+        sample_rate: int = 16000,
+        block_duration: float = 0.020,  # s
+        transcribe_window: float = 2.0,  # s
+        transcribe_step: float = 1.0,  # s
+        **kwargs,
+    ):
+        super().__init__(_handle=_handle, **kwargs)
+
+        self.language = language
+
+        self.sample_rate = sample_rate
+        self.window_size: int = int(transcribe_window / block_duration)
+        self.step_size: int = int(transcribe_step / block_duration)
+
+        self.buffer: List[np.ndarray] = []
+        # Number of leading frames in `buffer` already covered by a previous
+        # transcription (the overlap kept when the window slides). Frames past
+        # it are audio Whisper has not heard yet.
+        self._covered: int = 0
+
+        self.running = False
+        self.lock: asyncio.Lock = asyncio.Lock()
+
+        # Set when the end of the voice is received. Remembered if a
+        # transcription is in flight, so that call handles it once it finishes.
+        self._end_requested: bool = False
+
+    async def process(self, voice: Voice) -> AsyncGenerator[Transcript, None]:
+        async with self.lock:
+            if voice.data is None:
+                self._end_requested = True
+            else:
+                self.buffer.append(voice.data)
+            if self.running:
+                return
+            self.running = True
+
+        try:
+            async for transcript in self._transcribe_pending():
+                yield transcript
+        finally:
+            self.running = False
+
+    async def _transcribe_pending(self) -> AsyncGenerator[Transcript, None]:
+        """Run transcriptions until there is nothing left to do.
+
+        Loops so that an end-of-turn that arrives while a window is being
+        transcribed is handled right after it, in this same call. Each pass is
+        yielded as its own Transcript.
+        """
+
+        while True:
+            async with self.lock:
+                end = self._end_requested
+                if end:
+                    self._end_requested = False
+                    chunks = list(self.buffer)
+                    if len(chunks) <= self._covered:
+                        # Nothing new since the last window (only the already
+                        # transcribed overlap is left): re-running Whisper on it
+                        # would only repeat itself or invite hallucinations.
+                        self.buffer = []
+                        self._covered = 0
+                        chunks = []
+                else:
+                    if len(self.buffer) < self.window_size:
+                        return
+                    chunks = self.buffer[: self.window_size]
+
+            if end and not chunks:
+                yield Transcript("", True)
+                return
+
+            audio = np.concatenate(chunks, axis=0)
+            text = await self._handle.transcribe.remote(audio, self.language)
+
+            async with self.lock:
+                if end:
+                    # Whole remaining buffer was transcribed: reset per-turn
+                    # state so the NEXT utterance is independent. Frames that
+                    # arrived during the await belong to the next turn.
+                    self.buffer = self.buffer[len(chunks) :]
+                    self._covered = 0
+                else:
+                    # Mid-utterance: slide the window forward, keeping the
+                    # overlap.
+                    processed = self.window_size - self.step_size
+                    self.buffer = self.buffer[processed:]
+                    self._covered = max(0, len(chunks) - processed)
+
+            yield Transcript(text, end)
+            if not self._end_requested:
+                return

huri_module_stt-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=64,<82"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "huri-module-stt"
+version = "0.1.0"
+description = "HuRI module: Speech to text (faster-whisper) as a Ray Serve deployment"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "huri-core[server]>=0.4,<0.5",
+  "huri-events>=0.1,<0.2",
+  "numpy>=1.26,<2",
+  "faster-whisper>=1.2.1,<1.3",
+]
+
+[project.entry-points."huri.modules"]
+stt = "huri_stt.module:STT"
+
+[tool.setuptools.packages.find]
+include = ["huri_stt*"]
+
+[tool.setuptools.package-data]
+huri_stt = ["huri_module.toml", "manifests/*/huri_module.toml"]

huri_module_stt-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

huri_module_stt-0.1.0/tests/test_stt.py

@@ -0,0 +1,105 @@
+import asyncio
+
+import numpy as np
+from huri_events.speech import Transcript, Voice
+
+from huri_core.testing import LocalHandle, ModuleHarness
+
+
+class FakeWhisper:
+    """Stands in for STTHandle: one scripted text per call; can block the first."""
+
+    def __init__(self, texts, gate=None):
+        self.texts = list(texts)
+        self.gate = gate
+        self.calls = []
+
+    async def transcribe(self, audio, language):
+        self.calls.append(len(audio))
+        if self.gate is not None and len(self.calls) == 1:
+            await self.gate.wait()
+        return self.texts.pop(0)
+
+
+def _stt(whisper):
+    from huri_stt.module import STT
+
+    # 20 ms blocks -> window 10 frames, step 5 frames (fast tests).
+    return ModuleHarness(
+        STT, handle=LocalHandle(whisper), transcribe_window=0.2, transcribe_step=0.1
+    )
+
+
+def _voice():
+    return Voice(np.zeros(4, dtype=np.float32))
+
+
+async def _feed(stt, n):
+    return await stt.feed_all(*[_voice() for _ in range(n)])
+
+
+def test_end_event_during_inflight_transcription_is_not_lost():
+    async def run():
+        gate = asyncio.Event()
+        h = FakeWhisper(["what is the", "the weather"], gate)
+        stt = _stt(h)
+        first = asyncio.create_task(_feed(stt, 10))
+        await asyncio.sleep(0)
+        await asyncio.sleep(0)
+        # In-flight call is blocked: more speech arrives, then the VAD
+        # reports end of turn.
+        for _ in range(12):
+            assert await stt.feed(_voice()) == []
+        assert await stt.feed(Voice(None)) == []
+        gate.set()
+        out = await first
+        # STT does not merge: one Transcript per pass, in order (TAG stitches
+        # them, see huri-module-tag's tests).
+        assert out == [
+            Transcript("what is the", False),
+            Transcript("the weather", True),
+        ]
+
+    asyncio.run(run())
+
+
+def test_tail_beyond_first_window_is_transcribed_at_end():
+    async def run():
+        h = FakeWhisper(["b c d e f"])
+        stt = _stt(h)
+        # Backlog: more frames buffered than one window, then the turn ends.
+        stt.module.buffer = [np.zeros(4, np.float32)] * 14
+        out = await stt.feed(Voice(None))
+        assert out == [Transcript("b c d e f", True)]
+        assert h.calls == [14 * 4]  # whole buffer, not just first window
+        assert stt.module.buffer == [] and stt.module._covered == 0
+
+    asyncio.run(run())
+
+
+def test_end_with_no_new_audio_skips_whisper():
+    async def run():
+        h = FakeWhisper(["hello world", "should not be called"])
+        stt = _stt(h)
+        out = await _feed(stt, 10)
+        assert out == [Transcript("hello world", False)]
+        stt.module.buffer = stt.module.buffer[
+            : stt.module._covered
+        ]  # only overlap left
+        out = await stt.feed(Voice(None))
+        assert out == [Transcript("", True)]
+        assert len(h.calls) == 1
+
+    asyncio.run(run())
+
+
+def test_short_utterance_below_one_window_is_still_transcribed():
+    async def run():
+        h = FakeWhisper(["yes"])
+        stt = _stt(h)
+        out = await _feed(stt, 3)  # far less than one window / overlap
+        assert out == []
+        out = await stt.feed(Voice(None))
+        assert out == [Transcript("yes", True)]
+
+    asyncio.run(run())