@readymadeit/mcp 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: text-to-speech
+# Service Name: Text To Speech
+# Runtime: hkp-python
+# Modes: synthesize (Kokoro-82M via kokoro-onnx)
+# Key Config: model (kokoro-v1.0|kokoro-v1.0-int8), voice (e.g. af_heart),
+#             speed (0.5-2.0), lang (e.g. en-us), modelDir (model file cache)
+# IO: in=String/TextData (the text) or JSON ({text} | {prompt})
+#     -> out=FloatRingBuffer (24 kHz mono float32)
+# Arrays: n/a
+# Binary: emits FloatRingBuffer; non-text inputs yield an error JSON
+# MixedData: not supported
+#
+# The ML dependencies are an optional extra:  uv sync --extra tts
+# Model files (~310 MB onnx + ~27 MB voices) are downloaded lazily on first
+# use from the kokoro-onnx GitHub release; progress is reported through
+# notify() so the UI can show downloading/loading/generating states.
+#
+# The `{text}` input shape is deliberate: the text-generation service's
+# output pipes straight in, completing the local voice loop
+# audio-input -> speech-to-text -> text-generation -> text-to-speech.
+
+import time
+import urllib.request
+from array import array
+from pathlib import Path
+from typing import Any
+
+from ..data import FloatRingBuffer, TextData
+from ..types import JsonRecord, NotifyCallback, ServiceConfiguration, ServiceRegistryEntry
+
+TEXT_TO_SPEECH_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="text-to-speech",
+    service_name="Text To Speech",
+)
+
+# Kokoro synthesizes at this rate; the browser Audio Output service plays
+# FloatRingBuffer data at its configured sampleRate (default 24000).
+OUTPUT_SAMPLE_RATE = 24000
+
+_RELEASE_BASE = (
+    "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
+)
+_MODELS = {
+    "kokoro-v1.0": "kokoro-v1.0.onnx",
+    "kokoro-v1.0-int8": "kokoro-v1.0.int8.onnx",
+}
+_VOICES_FILE = "voices-v1.0.bin"
+
+DEFAULT_MODEL = "kokoro-v1.0"
+DEFAULT_VOICE = "af_heart"
+DEFAULT_SPEED = 1.0
+DEFAULT_LANG = "en-us"
+DEFAULT_MODEL_DIR = Path.home() / ".cache" / "hkp-python" / "kokoro"
+
+INSTALL_HINT = "kokoro-onnx is not installed — run in hkp-python: uv sync --extra tts"
+
+
+def _download(url: str, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    partial = destination.with_suffix(destination.suffix + ".part")
+    urllib.request.urlretrieve(url, partial)
+    partial.replace(destination)
+
+
+def _to_float32_bytes(samples: Any) -> bytes:
+    """kokoro-onnx returns a numpy float32 array; fall back to array('f') for
+    any float-sequence a stubbed backend may produce."""
+    if hasattr(samples, "astype"):
+        return samples.astype("float32").tobytes()
+    return array("f", samples).tobytes()
+
+
+class TextToSpeechService:
+    service_id = TEXT_TO_SPEECH_DESCRIPTOR.service_id
+    service_name = TEXT_TO_SPEECH_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 = DEFAULT_MODEL
+        self._voice = DEFAULT_VOICE
+        self._speed = DEFAULT_SPEED
+        self._lang = DEFAULT_LANG
+        self._model_dir = str(DEFAULT_MODEL_DIR)
+        self._engine: Any = None
+        self._loaded_key: tuple[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("voice"), str) and config["voice"]:
+            self._voice = config["voice"]
+        speed = config.get("speed")
+        if isinstance(speed, (int, float)) and not isinstance(speed, bool) and 0.5 <= speed <= 2.0:
+            self._speed = float(speed)
+        if isinstance(config.get("lang"), str) and config["lang"]:
+            self._lang = config["lang"]
+        if isinstance(config.get("modelDir"), str) and config["modelDir"]:
+            self._model_dir = config["modelDir"]
+
+        # Drop the cached engine if its parameters changed; it reloads lazily.
+        if self._loaded_key is not None and self._loaded_key != self._engine_key():
+            self._engine = None
+            self._loaded_key = None
+        return self.get_state()
+
+    def get_state(self) -> JsonRecord:
+        return {
+            "model": self._model_name,
+            "voice": self._voice,
+            "speed": self._speed,
+            "lang": self._lang,
+            "modelDir": self._model_dir,
+            "sampleRate": OUTPUT_SAMPLE_RATE,
+            "status": self._status,
+            "availableModels": list(_MODELS),
+        }
+
+    def process(self, input: Any, notify: NotifyCallback) -> Any:
+        if input is None:
+            return None
+
+        text = self._to_text(input)
+        if text is None:
+            return self._error(
+                notify,
+                "text-to-speech expects String input or JSON with 'text' or 'prompt'",
+            )
+
+        try:
+            engine = self._ensure_engine(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}")
+
+        voices = list(engine.get_voices())
+        if voices and self._voice not in voices:
+            return self._error(
+                notify,
+                f"unknown voice '{self._voice}' — available: {', '.join(voices[:12])}"
+                + (", ..." if len(voices) > 12 else ""),
+            )
+
+        self._set_status(notify, "generating")
+        started = time.monotonic()
+        try:
+            samples, sample_rate = engine.create(
+                text, voice=self._voice, speed=self._speed, lang=self._lang
+            )
+        except Exception as exc:
+            return self._error(notify, f"synthesis failed: {exc}")
+
+        payload = _to_float32_bytes(samples)
+        sample_count = len(payload) // 4
+
+        self._set_status(notify, "idle")
+        notify(
+            {
+                "voice": self._voice,
+                "sampleRate": sample_rate,
+                "samples": sample_count,
+                "audioMs": int(sample_count / sample_rate * 1000) if sample_rate else 0,
+                "generationMs": int((time.monotonic() - started) * 1000),
+            }
+        )
+        return FloatRingBuffer(samples=payload)
+
+    def set_host(self, host: Any) -> None:
+        pass
+
+    def destroy(self) -> None:
+        self._engine = None
+        self._loaded_key = None
+
+    # ── Internals ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _to_text(input: Any) -> str | None:
+        text: str | None = None
+        if isinstance(input, str):
+            text = input
+        elif isinstance(input, TextData):
+            text = input.text
+        elif isinstance(input, dict):
+            for key in ("text", "prompt"):
+                if isinstance(input.get(key), str) and input[key]:
+                    text = input[key]
+                    break
+        if text is None or not text.strip():
+            return None
+        return text.strip()
+
+    def _engine_key(self) -> tuple[str, str]:
+        return (self._model_name, self._model_dir)
+
+    def _ensure_engine(self, notify: NotifyCallback) -> Any:
+        if self._engine is not None:
+            return self._engine
+
+        from kokoro_onnx import Kokoro
+
+        model_dir = Path(self._model_dir).expanduser()
+        model_path = model_dir / _MODELS[self._model_name]
+        voices_path = model_dir / _VOICES_FILE
+        for path in (model_path, voices_path):
+            if not path.is_file():
+                # Stable status values (idle|downloading|loading|generating|error)
+                # so facade status-indicators can color-map them.
+                self._set_status(notify, "downloading", detail=f"downloading {path.name}")
+                _download(f"{_RELEASE_BASE}/{path.name}", path)
+
+        self._set_status(notify, "loading", detail=f"loading model '{self._model_name}'")
+        self._engine = Kokoro(str(model_path), str(voices_path))
+        self._loaded_key = self._engine_key()
+        return self._engine
+
+    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/timer.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: hookup.to/service/timer
+# Service Name: Timer
+# Runtime: hkp-python
+# Modes: periodic | oneShot
+# Key Config: service-specific timer fields (period, units, triggers)
+# IO: in=any -> out=tick payload or delayed payload
+# Arrays: treated as generic input
+# Binary: pass-through when payload-based
+# MixedData: not native in runtime
+
+import asyncio
+from typing import Any
+
+from ..types import (
+    JsonRecord,
+    NotifyCallback,
+    RuntimeHost,
+    ServiceConfiguration,
+    ServiceRegistryEntry,
+)
+
+TIMER_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="timer",
+    service_name="Timer",
+)
+
+#: The id this service used to answer to, from before it matched hkp-node and
+#: hkp-rt. Kept as a creation-time alias so boards saved against it still load;
+#: it is not advertised in the registry.
+TIMER_LEGACY_SERVICE_ID = "hookup.to/service/timer"
+
+_UNIT_MS: dict[str, float] = {
+    "ms": 1,
+    "s":  1_000,
+    "m":  60_000,
+    "h":  3_600_000,
+    "d":  86_400_000,
+}
+
+
+def _duration_ms(value: float, unit: str) -> float:
+    return value * _UNIT_MS.get(unit, 1_000)
+
+
+class TimerService:
+    service_id = TIMER_DESCRIPTOR.service_id
+    service_name = TIMER_DESCRIPTOR.service_name
+    version: str | None = None
+    capabilities: list[str] | None = None
+
+    def __init__(
+        self,
+        config: ServiceConfiguration,
+        min_interval_ms: float = 0,
+    ) -> None:
+        # Lower bound on the periodic interval. On a shared host a very short
+        # period is a way for one tenant to spend everyone's CPU, so the server
+        # supplies a floor and ticks are clamped to it.
+        self._min_interval_ms = min_interval_ms
+
+        self.uuid = config.uuid
+        self._periodic = False
+        self._periodic_value = 1
+        self._periodic_unit = "s"
+        self._one_shot_delay = 0
+        self._one_shot_delay_unit = "ms"
+        self._running = False
+        self._counter = 0
+        self._condition_until_trigger_count: int | None = None
+        self._task: asyncio.Task | None = None
+        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 {
+            "periodic": self._periodic,
+            "periodicValue": self._periodic_value,
+            "periodicUnit": self._periodic_unit,
+            "oneShotDelay": self._one_shot_delay,
+            "oneShotDelayUnit": self._one_shot_delay_unit,
+            "running": self._running,
+            "counter": self._counter,
+        }
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        periodic_value = config.get("periodicValue")
+        periodic_unit = config.get("periodicUnit")
+        periodic = config.get("periodic")
+        one_shot_delay = config.get("oneShotDelay")
+        one_shot_delay_unit = config.get("oneShotDelayUnit")
+        immediate = config.get("immediate")
+        counter = config.get("counter")
+        until = config.get("until")
+        running = config.get("running")
+        stop = config.get("stop")
+        start = config.get("start")
+        restart = config.get("restart")
+
+        do_stop: bool = bool(stop or restart or (self._running and running is not None and not running))
+        do_start: bool = bool(start or restart)
+
+        def silent_restart() -> None:
+            nonlocal do_start
+            self._cancel_task()
+            do_start = True
+
+        if periodic_value is not None:
+            self._periodic_value = periodic_value
+            self._notify({"periodicValue": periodic_value})
+            if not do_start and running:
+                do_start = True
+            elif self._running:
+                silent_restart()
+
+        if periodic_unit is not None:
+            self._periodic_unit = periodic_unit
+            self._notify({"periodicUnit": periodic_unit})
+            if not do_start and running:
+                do_start = True
+            elif self._running:
+                silent_restart()
+
+        if periodic is not None:
+            self._periodic = periodic
+            self._notify({"periodic": periodic})
+            if not do_start and running:
+                do_start = True
+
+        if one_shot_delay is not None:
+            self._one_shot_delay = one_shot_delay
+            self._notify({"oneShotDelay": one_shot_delay, "periodic": False})
+
+        if counter is not None:
+            self._counter = counter
+
+        if until is not None and isinstance(until, dict):
+            trigger_count = until.get("triggerCount")
+            if trigger_count is not None:
+                self._condition_until_trigger_count = int(trigger_count)
+
+        if one_shot_delay_unit is not None:
+            self._one_shot_delay_unit = one_shot_delay_unit
+            self._notify({"oneShotDelayUnit": one_shot_delay_unit})
+
+        if do_stop:
+            self._clear_timer()
+
+        if do_start:
+            self._schedule(immediate=bool(immediate))
+
+        self._running = self._task is not None and not self._task.done()
+        self._notify({"running": self._running})
+        return self.get_state()
+
+    def process(self, input: Any, _notify: NotifyCallback) -> Any:
+        # Periodic timers drive themselves — passthrough.
+        # One-shot: schedule a delayed fire and return input immediately.
+        if not self._periodic:
+            delay_s = _duration_ms(self._one_shot_delay, self._one_shot_delay_unit) / 1000
+            # The call passes through now; the later tick is a timer emission,
+            # not a delayed answer carrying the person who started it.
+            self._run_soon(self._tick_with_input(input, delay_s))
+        return input
+
+    def destroy(self) -> None:
+        self._clear_timer()
+
+    # ── Private ──────────────────────────────────────────────────────────────
+
+    def _schedule(self, immediate: bool = False) -> None:
+        if self._periodic:
+            self._cancel_task()
+            interval_s = (
+                max(
+                    _duration_ms(self._periodic_value, self._periodic_unit),
+                    self._min_interval_ms,
+                )
+                / 1000
+            )
+            first_delay_s = 0.001 if immediate else interval_s
+            self._run_soon(self._periodic_loop(first_delay_s, interval_s))
+        else:
+            if self._task:
+                self._cancel_task()
+            delay_s = 0.001 if immediate else _duration_ms(self._one_shot_delay, self._one_shot_delay_unit) / 1000
+            self._run_soon(self._oneshot_fire(delay_s))
+
+    def _run_soon(self, coro: Any) -> None:
+        try:
+            loop = asyncio.get_running_loop()
+            self._task = loop.create_task(coro)
+        except RuntimeError:
+            pass  # no event loop (e.g. in tests without asyncio)
+
+    async def _periodic_loop(self, first_delay_s: float, interval_s: float) -> None:
+        await asyncio.sleep(first_delay_s)
+        while True:
+            self._tick()
+            if self._task is None or self._task.cancelled():
+                break
+            await asyncio.sleep(interval_s)
+
+    async def _oneshot_fire(self, delay_s: float) -> None:
+        await asyncio.sleep(delay_s)
+        self._tick()
+        self._task = None
+        self._running = False
+        self._notify({"running": False})
+
+    async def _tick_with_input(self, input: Any, delay_s: float) -> None:
+        await asyncio.sleep(delay_s)
+        trigger_count = self._counter + 1
+        self._counter = trigger_count
+        self._notify({"counter": trigger_count})
+        if self._host:
+            merged = {**(input if isinstance(input, dict) else {}), "triggerCount": trigger_count}
+            result = self._host.process_from(
+                self.uuid,
+                merged,
+                # No-op: the runtime already fans these out to its notification
+                # targets. Re-notifying through the host would deliver each twice.
+                lambda _n: None,
+            )
+            self._host.emit_result(result)
+
+    def _tick(self) -> None:
+        if (
+            self._condition_until_trigger_count is not None
+            and self._counter >= self._condition_until_trigger_count
+        ):
+            self._clear_timer()
+            return
+        trigger_count = self._counter + 1
+        self._counter = trigger_count
+        self._notify({"counter": trigger_count})
+        if self._host:
+            result = self._host.process_from(
+                self.uuid,
+                {"triggerCount": trigger_count},
+                # No-op: the runtime already fans these out to its notification
+                # targets. Re-notifying through the host would deliver each twice.
+                lambda _n: None,
+            )
+            self._host.emit_result(result)
+
+    def _clear_timer(self) -> None:
+        self._cancel_task()
+        self._counter = 0
+        self._running = False
+        self._notify({"running": False, "count": self._counter})
+
+    def _cancel_task(self) -> None:
+        if self._task and not self._task.done():
+            self._task.cancel()
+        self._task = None
+
+    def _notify(self, payload: Any, instance_id: str | None = None) -> None:
+        if self._host:
+            self._host.notify(payload, instance_id or self.uuid)