huri-cli 0.1.0__py3-none-any.whl

huri_cli/__init__.py

@@ -0,0 +1 @@
+"""Reference command-line client for HuRI, built on the client SDK."""

huri_cli/__main__.py

@@ -0,0 +1,3 @@
+from huri_cli.main import main
+
+main()

huri_cli/audio.py

@@ -0,0 +1,160 @@
+import asyncio
+import logging
+import os
+import wave
+from datetime import datetime
+from typing import Any, Callable, List, Optional
+
+import numpy as np
+from huri_events.audio import Audio
+from scipy.signal import resample
+
+logger = logging.getLogger("huri_cli.audio")
+
+
+def _open_output(sample_rate: int) -> Any:
+    import sounddevice as sd
+
+    stream = sd.OutputStream(samplerate=sample_rate, channels=1, dtype="int16")
+    stream.start()
+    return stream
+
+
+class AudioPlayer:
+    """Plays `huri.audio.out` on the default output device, optionally saving
+    each utterance as a WAV file.
+
+    The SDK hands chunks over in order, one at a time; the blocking device
+    write runs in a worker thread so the event loop keeps receiving meanwhile.
+    The device is opened on the first chunk, at the TTS sample rate when the
+    device supports it, else at `sample_rate` with resampling.
+    """
+
+    def __init__(
+        self,
+        save_audio_dir: str = "",
+        sample_rate: int = 48000,
+        incoming_sample_rate: int = 16000,
+        open_output: Callable[[int], Any] = _open_output,
+    ):
+        self.sample_rate = sample_rate
+        self.incoming_sample_rate = incoming_sample_rate
+        self._open_output = open_output
+        self.stream: Any = None
+        self._stream_sr: Optional[int] = None
+        self._resample_fallback = False
+
+        self.save_audio_dir = save_audio_dir
+        self._audio_buf: List[np.ndarray] = []
+        self._audio_sr: Optional[int] = None
+        self._audio_idx = 0
+        if save_audio_dir:
+            os.makedirs(save_audio_dir, exist_ok=True)
+
+    def _resample(self, audio: np.ndarray) -> np.ndarray:
+        """Resample float32 audio to the output device's rate."""
+        return np.asarray(
+            resample(
+                audio,
+                int(len(audio) * self.sample_rate / self.incoming_sample_rate),
+            ),
+            dtype=np.float32,
+        )
+
+    def _ensure_stream_for(self, sample_rate: int) -> None:
+        """Run the output device at the TTS rate when it can."""
+        if sample_rate == self._stream_sr:
+            return
+        if self._resample_fallback:
+            if self.stream is None:
+                self.stream = self._open_output(self.sample_rate)
+                self._stream_sr = self.sample_rate
+            return
+        try:
+            stream = self._open_output(sample_rate)
+        except Exception as e:  # noqa: BLE001 - device capability probe
+            logger.warning(
+                "output device will not run at %sHz (%s); resampling to %sHz "
+                "instead (expect chunk clicks)",
+                sample_rate,
+                e,
+                self.sample_rate,
+            )
+            self._resample_fallback = True
+            self._ensure_stream_for(sample_rate)
+            return
+        self.close()
+        self.stream = stream
+        self._stream_sr = sample_rate
+        logger.info("audio output opened at %sHz", sample_rate)
+
+    def close(self) -> None:
+        if self.stream is not None:
+            try:
+                self.stream.stop()
+                self.stream.close()
+            except Exception:  # noqa: BLE001
+                pass
+            self.stream = None
+
+    def _collect_audio(self, samples: np.ndarray, sample_rate: int, end: bool) -> None:
+        if samples.size:
+            self._audio_buf.append(samples)
+            self._audio_sr = sample_rate
+        if end:
+            self._flush_audio()
+
+    def _flush_audio(self) -> None:
+        if not self._audio_buf or self._audio_sr is None:
+            self._audio_buf = []
+            return
+        audio = np.concatenate(self._audio_buf)
+        stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+        path = os.path.join(
+            self.save_audio_dir, f"utt-{self._audio_idx:03d}-{stamp}.wav"
+        )
+        self._write_wav(path, audio, self._audio_sr)
+        logger.info(
+            "saved audio: %s (%d samples, ~%.2fs @ %dHz)",
+            path,
+            audio.size,
+            audio.size / self._audio_sr,
+            self._audio_sr,
+        )
+        self._audio_idx += 1
+        self._audio_buf = []
+
+    @staticmethod
+    def _write_wav(path: str, audio: np.ndarray, sample_rate: int) -> None:
+        # float32 [-1, 1] -> 16-bit PCM, clipped to avoid wraparound on overshoot.
+        pcm = np.clip(audio, -1.0, 1.0)
+        pcm = (pcm * 32767.0).astype("<i2")
+        with wave.open(path, "wb") as wav:
+            wav.setnchannels(1)
+            wav.setsampwidth(2)
+            wav.setframerate(sample_rate)
+            wav.writeframes(pcm.tobytes())
+
+    async def __call__(self, data: Audio) -> None:
+        logger.debug(
+            "audio: pts=%.3fs samples=%d @ %dHz end=%s",
+            data.pts,
+            data.data.size,
+            data.sample_rate,
+            bool(data.end),
+        )
+        samples = np.asarray(data.data, dtype=np.float32)
+        if samples.size:
+            self.incoming_sample_rate = data.sample_rate
+            try:
+                self._ensure_stream_for(data.sample_rate)
+                if self._stream_sr != data.sample_rate:
+                    samples = self._resample(samples)
+                pcm = (np.clip(samples, -1.0, 1.0) * 32767.0).astype(np.int16)
+                await asyncio.to_thread(self.stream.write, pcm.reshape(-1, 1))
+            except Exception as e:  # noqa: BLE001 - never kill the session on audio
+                logger.error("audio playback failed: %s: %s", type(e).__name__, e)
+
+        if self.save_audio_dir:
+            # The incoming chunk, not the resampled one: saved at its own rate.
+            self._collect_audio(data.data, data.sample_rate, bool(data.end))

huri_cli/main.py

@@ -0,0 +1,159 @@
+"""huri-cli: talk to a HuRI server from a terminal.
+
+    huri-cli --config config/client_full.yaml [--log-level DEBUG] [--log-file cli.log]
+
+The client config's `send:` and `subscribe:` pick among the topics below; its
+`cli:` section holds the device settings:
+
+    cli:  # every key is optional; these are the defaults
+      audio_in:  {sample_rate: 16000, frame_duration: 0.030}
+      audio_out: {sample_rate: 48000, incoming_sample_rate: 16000, save_audio_dir: ""}
+      motion:    {save_motion_dir: ""}
+"""
+
+import argparse
+import asyncio
+import logging
+from typing import Any, Awaitable, Callable, Dict, List, Mapping, Optional, Tuple, Type
+
+from huri_core.core.client import (
+    HuRIClient,
+    HuRISessionError,
+    load_raw_client_config,
+)
+from huri_core.core.dataclasses.config import ClientConfig
+from huri_core.core.events import EventData
+from huri_events.audio import Audio
+from huri_events.motion import Motion
+from huri_events.question import RAGQuestion
+from huri_events.text import Token
+
+from .audio import AudioPlayer
+from .senders import send_microphone, send_prompt
+from .viewer import MotionViewer
+
+logger = logging.getLogger("huri_cli")
+
+
+async def print_question(data: RAGQuestion) -> None:
+    print(
+        "<<", data.transcript.text, f"(emotion: {data.emotion})" if data.emotion else ""
+    )
+
+
+async def print_token(data: Token) -> None:
+    """The RAG's streamed reply, token by token; newline at end of utterance."""
+    if data.end:
+        print()
+    else:
+        print(data.text, end="", flush=True)
+
+
+Receiver = Callable[[Any], Awaitable[None]]
+
+# topic -> (event class, factory building the handler from the `cli:` settings)
+RECEIVERS: Dict[str, Tuple[Type[EventData], Callable[[Mapping], Receiver]]] = {
+    "huri.audio.out": (Audio, lambda cli: AudioPlayer(**cli.get("audio_out", {}))),
+    "huri.motion": (Motion, lambda cli: MotionViewer(**cli.get("motion", {}))),
+    "huri.question": (RAGQuestion, lambda cli: print_question),
+    "huri.token": (Token, lambda cli: print_token),
+}
+
+# topic -> coroutine sending it until it returns or is cancelled
+SENDERS: Dict[str, Callable[[HuRIClient, str, Mapping], Awaitable[None]]] = {
+    "huri.audio.in": lambda client, topic, cli: send_microphone(
+        client, topic, **cli.get("audio_in", {})
+    ),
+    "huri.question": lambda client, topic, cli: send_prompt(client, topic),
+}
+
+
+def build_client(config: ClientConfig, cli: Mapping) -> HuRIClient:
+    unsupported = [t for t in config.send if t not in SENDERS]
+    unsupported += [t for t in config.subscribe if t not in RECEIVERS]
+    if unsupported:
+        raise ValueError(
+            f"huri-cli cannot handle topic(s) {unsupported}. It sends "
+            f"{sorted(SENDERS)} and receives {sorted(RECEIVERS)}"
+        )
+    client = HuRIClient.from_config(config)
+    for topic in config.subscribe:
+        event_cls, make = RECEIVERS[topic]
+        client.on(topic, event_cls, make(cli))
+    return client
+
+
+async def run(config: ClientConfig, cli: Optional[Mapping] = None) -> int:
+    cli = cli or {}
+    client = build_client(config, cli)
+    try:
+        await client.connect()
+    except HuRISessionError as e:
+        logger.error("HuRI rejected this client config: %s", e.error)
+        if e.server_modules:
+            logger.error("  server registered : %s", ", ".join(e.server_modules))
+            logger.error("  this config wants : %s", ", ".join(config.modules))
+        return 1
+    except OSError as e:
+        logger.error(
+            "cannot reach HuRI at %s: %s. Is the server deployed? (with "
+            "huri-modules' installer: .huri-local/status.sh; replica logs in "
+            "/tmp/ray/session_latest/logs/serve/)",
+            config.huri_url,
+            e,
+        )
+        return 1
+    logger.info("session started, user_id=%s", client.user_id)
+    try:
+        loops: List[asyncio.Future] = [
+            asyncio.ensure_future(SENDERS[topic](client, topic, cli))
+            for topic in config.send
+        ]
+        closed = asyncio.ensure_future(client.wait_closed())
+        # The session ends when a sender returns (`\exit` at the prompt) or
+        # the server closes the connection.
+        done, pending = await asyncio.wait(
+            loops + [closed], return_when=asyncio.FIRST_COMPLETED
+        )
+        for task in pending:
+            task.cancel()
+        for task in done:
+            if task is not closed and task.exception() is not None:
+                logger.error("sender failed: %r", task.exception())
+                return 1
+        if closed in done:
+            logger.info("the server closed the session")
+        return 0
+    finally:
+        await client.close()
+
+
+def setup_logging(level: str, log_file: Optional[str]) -> None:
+    handlers: List[logging.Handler] = [logging.StreamHandler()]
+    if log_file:
+        handlers.append(logging.FileHandler(log_file))
+    logging.basicConfig(
+        level=level.upper(),
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s",
+        datefmt="%H:%M:%S",
+        handlers=handlers,
+    )
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="huri-cli", description=__doc__.split("\n\n")[0]
+    )
+    parser.add_argument("--config", required=True, help="client config file (YAML)")
+    parser.add_argument("--log-level", default="INFO", help="DEBUG, INFO, WARNING...")
+    parser.add_argument("--log-file", help="also write the logs to this file")
+    args = parser.parse_args(argv)
+
+    setup_logging(args.log_level, args.log_file)
+    raw = load_raw_client_config(args.config)
+    config = ClientConfig.from_dict(raw)
+    try:
+        code = asyncio.run(run(config, dict(raw.get("cli") or {})))
+    except KeyboardInterrupt:
+        code = 0
+    raise SystemExit(code)

huri_cli/senders.py

@@ -0,0 +1,61 @@
+import asyncio
+import logging
+
+import numpy as np
+from huri_core.core.client import HuRIClient
+from huri_core.core.events import BytesEvent
+from huri_events.question import RAGQuestion
+from huri_events.speech import Transcript
+
+logger = logging.getLogger("huri_cli")
+
+
+async def send_microphone(
+    client: HuRIClient,
+    topic: str,
+    sample_rate: int = 16000,
+    frame_duration: float = 0.030,
+) -> None:
+    """Streams 16-bit mono microphone frames until cancelled."""
+
+    import sounddevice as sd
+
+    loop = asyncio.get_running_loop()
+    queue: asyncio.Queue[np.ndarray] = asyncio.Queue()
+
+    def callback(indata: np.ndarray, frames, time, status):
+        if status:
+            logger.warning("microphone: %s", status)
+        loop.call_soon_threadsafe(queue.put_nowait, indata.copy())
+
+    logger.info("microphone: %s", sd.query_devices(kind="input")["name"])
+    with sd.InputStream(
+        samplerate=sample_rate,
+        channels=1,
+        dtype="int16",
+        callback=callback,
+        blocksize=int(sample_rate * frame_duration),
+    ):
+        while True:
+            chunk = await queue.get()
+            await client.send(topic, BytesEvent(data=chunk.tobytes()))
+
+
+async def send_prompt(client: HuRIClient, topic: str) -> None:
+    """Sends each typed line as a question; returns on `\\exit` or EOF."""
+
+    from prompt_toolkit import PromptSession
+    from prompt_toolkit.patch_stdout import patch_stdout
+
+    print("'\\exit' or CTRL+D/C to exit.")
+    session: PromptSession = PromptSession()
+    try:
+        while True:
+            with patch_stdout():
+                text = await session.prompt_async(">> ")
+            if text == "\\exit":
+                return
+            if text.strip():
+                await client.send(topic, RAGQuestion(Transcript(text, True), None))
+    except (EOFError, KeyboardInterrupt):
+        pass

huri_cli/viewer.py

@@ -0,0 +1,90 @@
+"""A terminal view of the gesture stream (`huri.motion`).
+
+Each Motion chunk carries SMPL-X poses: 55 joints x 3 axis-angle values per
+frame. The viewer groups the joints by body part and shows how much each part
+moves (mean absolute change of its joint rotations between frames), so one can
+see at a glance whether gestures follow the speech. Optionally every chunk is
+saved as .npz for offline rendering with the EMAGE/SMPL-X tooling.
+"""
+
+import logging
+import os
+from typing import Dict, List, Optional, Sequence
+
+import numpy as np
+from huri_events.motion import Motion
+
+logger = logging.getLogger("huri_cli.motion")
+
+# SMPL-X joint indices (55-joint body + jaw/eyes + hands layout).
+BODY_PARTS: Dict[str, Sequence[int]] = {
+    "head": (12, 15, 22, 23, 24),
+    "torso": (0, 3, 6, 9),
+    "l_arm": (13, 16, 18, 20),
+    "r_arm": (14, 17, 19, 21),
+    "hands": tuple(range(25, 55)),
+    "legs": (1, 2, 4, 5, 7, 8, 10, 11),
+}
+_BAR = " ▁▂▃▄▅▆▇█"
+
+
+def part_activity(
+    poses: np.ndarray, previous: Optional[np.ndarray] = None
+) -> Dict[str, float]:
+    """Mean absolute rotation change per frame (radians) of each body part."""
+
+    frames = poses.reshape(len(poses), 55, 3)
+    if previous is not None:
+        frames = np.concatenate([previous.reshape(1, 55, 3), frames])
+    if len(frames) < 2:
+        return {part: 0.0 for part in BODY_PARTS}
+    delta = np.abs(np.diff(frames, axis=0))  # (t-1, 55, 3)
+    return {
+        part: float(delta[:, list(joints), :].mean())
+        for part, joints in BODY_PARTS.items()
+    }
+
+
+def bar(value: float, full_scale: float = 0.05) -> str:
+    level = min(int(value / full_scale * (len(_BAR) - 1)), len(_BAR) - 1)
+    return _BAR[max(level, 0)]
+
+
+class MotionViewer:
+    """Logs one line per Motion chunk: timing plus a bar per body part."""
+
+    def __init__(self, save_motion_dir: str = "", full_scale: float = 0.05):
+        self.full_scale = full_scale
+        self.save_motion_dir = save_motion_dir
+        self._last_pose: Optional[np.ndarray] = None
+        self._index = 0
+        if save_motion_dir:
+            os.makedirs(save_motion_dir, exist_ok=True)
+
+    def render(self, motion: Motion) -> str:
+        activity = part_activity(motion.poses, self._last_pose)
+        parts: List[str] = [
+            f"{part} {bar(value, self.full_scale)}" for part, value in activity.items()
+        ]
+        n = motion.poses.shape[0]
+        return (
+            f"motion pts={motion.pts:7.3f}s {n:3d}f @{motion.fps}fps "
+            f"({n / max(motion.fps, 1):.2f}s) | " + "  ".join(parts)
+        )
+
+    async def __call__(self, motion: Motion) -> None:
+        if motion.poses.shape[0] == 0:
+            return
+        logger.info(self.render(motion))
+        self._last_pose = motion.poses[-1]
+        if self.save_motion_dir:
+            path = os.path.join(self.save_motion_dir, f"motion-{self._index:04d}.npz")
+            np.savez(
+                path,
+                poses=motion.poses,
+                expressions=motion.expressions,
+                trans=motion.trans,
+                fps=motion.fps,
+                pts=motion.pts,
+            )
+            self._index += 1