@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-python/src/hkp/services/speech_to_text.py

@@ -0,0 +1,186 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: speech-to-text
+# Service Name: Speech To Text
+# Runtime: hkp-python
+# Modes: transcribe (faster-whisper backend)
+# Key Config: model (tiny|base|small|medium|large-v3|distil-large-v3),
+#             language ("auto" or ISO code), computeType (int8|int8_float16|float16|float32),
+#             device (auto|cpu|cuda), sampleRate (rate of incoming samples, default 16000)
+# IO: in=FloatRingBuffer (mono float32 at the configured sampleRate) -> out=JSON
+#     { text, language, languageProbability, durationMs, segments: [{start, end, text}] }
+# Arrays: n/a
+# Binary: consumes FloatRingBuffer; other inputs yield an error JSON
+# MixedData: not supported
+#
+# The ML dependencies are an optional extra:  uv sync --extra asr
+# The model is loaded lazily on first use (first call downloads it from
+# Hugging Face); progress is reported through notify() so the UI can show
+# loading/transcribing states.
+
+from typing import Any
+
+from ..data import FloatRingBuffer
+from ..types import JsonRecord, NotifyCallback, ServiceConfiguration, ServiceRegistryEntry
+
+SPEECH_TO_TEXT_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="speech-to-text",
+    service_name="Speech To Text",
+)
+
+# Whisper-family models require this rate; input at any other configured
+# sampleRate is resampled to it before transcription.
+WHISPER_SAMPLE_RATE = 16000
+
+_MODELS = ["tiny", "base", "small", "medium", "large-v3", "distil-large-v3"]
+_COMPUTE_TYPES = ["int8", "int8_float16", "float16", "float32"]
+_DEVICES = ["auto", "cpu", "cuda"]
+
+INSTALL_HINT = "faster-whisper is not installed — run in hkp-python: uv sync --extra asr"
+
+
+def _resample_linear(audio: Any, from_rate: int, to_rate: int) -> Any:
+    import numpy as np
+
+    if from_rate == to_rate or len(audio) == 0:
+        return audio
+    out_length = int(len(audio) * to_rate / from_rate)
+    positions = np.arange(out_length) * (from_rate / to_rate)
+    return np.interp(positions, np.arange(len(audio)), audio).astype(np.float32)
+
+
+class SpeechToTextService:
+    service_id = SPEECH_TO_TEXT_DESCRIPTOR.service_id
+    service_name = SPEECH_TO_TEXT_DESCRIPTOR.service_name
+    version: str | None = None
+    capabilities: list[str] | None = None
+
+    def __init__(self, config: ServiceConfiguration, _create_service: Any = None) -> None:
+        self.uuid = config.uuid
+        self._model_name = "small"
+        self._language = "auto"
+        self._compute_type = "int8"
+        self._device = "auto"
+        self._sample_rate = WHISPER_SAMPLE_RATE
+        self._model: Any = None
+        self._loaded_key: tuple[str, str, str] | None = None
+        self._status = "idle"
+
+        if config.state:
+            self.configure(config.state)
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        if config.get("model") in _MODELS:
+            self._model_name = config["model"]
+        if isinstance(config.get("language"), str) and config["language"]:
+            self._language = config["language"]
+        if config.get("computeType") in _COMPUTE_TYPES:
+            self._compute_type = config["computeType"]
+        if config.get("device") in _DEVICES:
+            self._device = config["device"]
+        sample_rate = config.get("sampleRate")
+        if isinstance(sample_rate, (int, float)) and sample_rate > 0:
+            self._sample_rate = int(sample_rate)
+
+        # Drop the cached model if its parameters changed; it reloads lazily.
+        if self._loaded_key is not None and self._loaded_key != self._model_key():
+            self._model = None
+            self._loaded_key = None
+        return self.get_state()
+
+    def get_state(self) -> JsonRecord:
+        return {
+            "model": self._model_name,
+            "language": self._language,
+            "computeType": self._compute_type,
+            "device": self._device,
+            "sampleRate": self._sample_rate,
+            "status": self._status,
+            "availableModels": _MODELS,
+        }
+
+    def process(self, input: Any, notify: NotifyCallback) -> Any:
+        if input is None:
+            return None
+        if not isinstance(input, FloatRingBuffer):
+            return self._error(
+                notify,
+                "speech-to-text expects FloatRingBuffer input (mono float32 at the configured sampleRate)",
+            )
+
+        try:
+            model = self._ensure_model(notify)
+        except ImportError:
+            return self._error(notify, INSTALL_HINT)
+        except Exception as exc:
+            return self._error(notify, f"failed to load model '{self._model_name}': {exc}")
+
+        import numpy as np
+
+        audio = np.frombuffer(input.samples, dtype=np.float32)
+        duration_ms = int(len(audio) / self._sample_rate * 1000)
+        if self._sample_rate != WHISPER_SAMPLE_RATE:
+            audio = _resample_linear(audio, self._sample_rate, WHISPER_SAMPLE_RATE)
+
+        self._set_status(notify, "transcribing")
+        try:
+            language = None if self._language == "auto" else self._language
+            segments_iter, info = model.transcribe(audio, language=language)
+            segments = [
+                {"start": round(s.start, 3), "end": round(s.end, 3), "text": s.text.strip()}
+                for s in segments_iter
+            ]
+        except Exception as exc:
+            return self._error(notify, f"transcription failed: {exc}")
+
+        self._set_status(notify, "idle")
+        result = {
+            "text": " ".join(s["text"] for s in segments).strip(),
+            "language": getattr(info, "language", self._language),
+            "languageProbability": round(getattr(info, "language_probability", 0.0), 3),
+            "durationMs": duration_ms,
+            "segments": segments,
+        }
+        notify(result)
+        return result
+
+    def set_host(self, host: Any) -> None:
+        pass
+
+    def destroy(self) -> None:
+        self._model = None
+        self._loaded_key = None
+
+    # ── Internals ──────────────────────────────────────────────────────────────
+
+    def _model_key(self) -> tuple[str, str, str]:
+        return (self._model_name, self._device, self._compute_type)
+
+    def _ensure_model(self, notify: NotifyCallback) -> Any:
+        if self._model is not None:
+            return self._model
+
+        from faster_whisper import WhisperModel
+
+        # Stable status values (idle|loading|transcribing|error) so facade
+        # status-indicators can color-map them; the model name goes in detail.
+        self._set_status(notify, "loading", detail=f"loading model '{self._model_name}'")
+        self._model = WhisperModel(
+            self._model_name, device=self._device, compute_type=self._compute_type
+        )
+        self._loaded_key = self._model_key()
+        return self._model
+
+    def _set_status(self, notify: NotifyCallback, status: str, detail: str | None = None) -> None:
+        self._status = status
+        payload: JsonRecord = {"status": status}
+        if detail is not None:
+            payload["detail"] = detail
+        notify(payload)
+
+    def _error(self, notify: NotifyCallback, message: str) -> JsonRecord:
+        self._set_status(notify, "error")
+        result = {"error": message}
+        notify(result)
+        return result

package/bundle/hkp-python/src/hkp/services/spread.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: spread
+# Service Name: Spread
+# Runtime: hkp-python
+# Modes: none
+# Key Config: itemsFrom, bypass
+# IO: in=a list, or a single item -> out=one {item, group, index, total} per item, each sent on by itself
+# Arrays: the point of the service
+# Binary: an item may be bytes; it travels untouched under `item`
+# MixedData: not native in runtime
+
+"""One value in, as many out as it has items.
+
+A value leaving a runtime travels as one message, however many items it holds.
+Spread sends each item down the rest of the board on its own — the services
+after it, and the runtimes after this one — so each crosses as a message of its
+own, and a Gather on the far side puts them back together.
+
+It is not an Iterator: it holds no pipeline, and nothing comes back. It returns
+None and continues the run itself, once per item — the pull pattern — so every
+item goes on in the run that reached it.
+
+**Each item goes on wrapped**, as ``{item, group, index, total}``. **A single
+item is a list of one.** Items go on one at a time, in order.
+
+Matches ``spread`` in hkp-node and ``hookup.to/service/spread`` in the browser.
+"""
+
+import uuid as _uuid_mod
+from typing import Any
+
+from ..types import (
+    JsonRecord,
+    NotifyCallback,
+    RuntimeHost,
+    ServiceConfiguration,
+    ServiceRegistryEntry,
+)
+from .iterator import value_at
+
+SPREAD_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="spread",
+    service_name="Spread",
+    version="v1",
+    capabilities=[],
+)
+
+
+class SpreadService:
+    service_id = SPREAD_DESCRIPTOR.service_id
+    service_name = SPREAD_DESCRIPTOR.service_name
+    version = SPREAD_DESCRIPTOR.version
+    capabilities = SPREAD_DESCRIPTOR.capabilities
+
+    def __init__(self, config: ServiceConfiguration, _create_service: Any = None) -> None:
+        self.uuid = config.uuid
+        self._bypass = False
+        self._items_from = ""
+        self._last_total = 0
+        self._host: RuntimeHost | None = None
+
+        if config.state:
+            self.configure(config.state)
+
+    def set_host(self, host: RuntimeHost) -> None:
+        self._host = host
+
+    def get_state(self) -> JsonRecord:
+        return {
+            "bypass": self._bypass,
+            "itemsFrom": self._items_from,
+            "lastTotal": self._last_total,
+        }
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        if isinstance(config.get("bypass"), bool):
+            self._bypass = config["bypass"]
+        if isinstance(config.get("itemsFrom"), str):
+            self._items_from = config["itemsFrom"]
+        return self.get_state()
+
+    def process(self, input: Any, notify: NotifyCallback) -> Any:
+        if self._bypass or not self._host:
+            return input
+        host = self._host
+        run = host.current_context()
+
+        items = self._items(input)
+        if items:
+            group = str(_uuid_mod.uuid4())
+            total = len(items)
+            for index, item in enumerate(items):
+                output = host.process_from(
+                    self.uuid,
+                    {"item": item, "group": group, "index": index, "total": total},
+                    lambda _n: None,
+                    run,
+                )
+                # An item the rest of the pipeline stopped goes no further; the
+                # others still do.
+                if output is not None:
+                    host.emit_result(output)
+            self._last_total = total
+            notify({"lastTotal": total}, None)
+        # Every item has gone on already; there is nothing left to pass.
+        return None
+
+    def _items(self, input: Any) -> list[Any]:
+        source = value_at(input, self._items_from) if self._items_from else input
+        if source is None:
+            return []
+        return source if isinstance(source, list) else [source]

package/bundle/hkp-python/src/hkp/services/stopper.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: stopper
+# Service Name: Stopper
+# Runtime: hkp-python
+# Modes: none
+# Key Config: bypass
+# IO: in=anything -> out=None (nothing is forwarded)
+#
+# Returns None on every call, which the runtime reads as "nothing to pass on":
+# the services after it are not called, and the runtime emits no result, so the
+# next runtime in the chain is not driven either.
+#
+# That last part is the reason to reach for it on a board with several runtimes.
+# Runtimes are chained — the result of one becomes the input of the next — so a
+# runtime whose work is a side effect rather than a value should end here,
+# instead of feeding whatever it happened to produce into the next runtime.
+# Mirrors hkp-node's and hkp-rt's `stopper`, and the browser runtime's
+# `hookup.to/service/stopper`.
+
+from typing import Any
+
+from ..types import JsonRecord, NotifyCallback, ServiceConfiguration, ServiceRegistryEntry
+
+STOPPER_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="stopper",
+    service_name="Stopper",
+    version="v1",
+    capabilities=[],
+)
+
+
+class StopperService:
+    service_id = STOPPER_DESCRIPTOR.service_id
+    service_name = STOPPER_DESCRIPTOR.service_name
+    version = STOPPER_DESCRIPTOR.version
+    capabilities = STOPPER_DESCRIPTOR.capabilities
+
+    def __init__(self, config: ServiceConfiguration, _create_service: Any = None) -> None:
+        self.uuid = config.uuid
+        self._bypass = False
+
+        if config.state:
+            self.configure(config.state)
+
+    def get_state(self) -> JsonRecord:
+        return {"bypass": self._bypass}
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        # Bypass is the only setting worth having: it turns the dead end back
+        # into a passthrough, so a chain can be opened up without moving
+        # services around.
+        if isinstance(config.get("bypass"), bool):
+            self._bypass = config["bypass"]
+        return self.get_state()
+
+    def process(self, input: Any, _notify: NotifyCallback) -> Any:
+        return input if self._bypass else None