huri-events 0.1.0__tar.gz

huri_events-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: huri-events
+Version: 0.1.0
+Summary: The curated HuRI event vocabulary: the huri.* topics and their wire formats
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core<0.5,>=0.4
+Requires-Dist: numpy<2,>=1.26
+
+# huri-events
+
+The curated HuRI event vocabulary: one event class per `huri.*` topic, with its
+wire format, registered through the `huri.events` entry point group. The
+`huri.` namespace is reserved for this package; third-party events use their
+own (`acme.*`), see [Modules as plugins](../../README.md#modules-as-plugins).
+
+It is deliberately light (huri-core and numpy): a client installs it next to
+`huri-core[client]` to decode every curated topic.
+
+```sh
+# from a huri-modules checkout:
+pip install "huri-core[client] @ git+https://github.com/Lucy-Robotics/huri-core.git@$(. ./versions.env && echo "$HURI_CORE_REF")" \
+  ./packages/huri-events
+```
+
+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`, which is
+not on PyPI: without a checkout, install it from git in the same pip command,
+so pip never looks it 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 @ 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_events-0.1.0/README.md

@@ -0,0 +1,29 @@
+# huri-events
+
+The curated HuRI event vocabulary: one event class per `huri.*` topic, with its
+wire format, registered through the `huri.events` entry point group. The
+`huri.` namespace is reserved for this package; third-party events use their
+own (`acme.*`), see [Modules as plugins](../../README.md#modules-as-plugins).
+
+It is deliberately light (huri-core and numpy): a client installs it next to
+`huri-core[client]` to decode every curated topic.
+
+```sh
+# from a huri-modules checkout:
+pip install "huri-core[client] @ git+https://github.com/Lucy-Robotics/huri-core.git@$(. ./versions.env && echo "$HURI_CORE_REF")" \
+  ./packages/huri-events
+```
+
+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`, which is
+not on PyPI: without a checkout, install it from git in the same pip command,
+so pip never looks it 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 @ 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_events-0.1.0/huri_events/__init__.py

@@ -0,0 +1,34 @@
+"""The curated HuRI events, one class per `huri.*` topic.
+
+| topic                   | class             | wire   |
+|-------------------------|-------------------|--------|
+| huri.audio.in           | BytesEvent (core) | binary |
+| huri.voice              | Voice             | json   |
+| huri.transcript         | Transcript        | json   |
+| huri.emotion            | Emotion           | -      |
+| huri.partial_question   | PartialQuestion   | json   |
+| huri.question           | RAGQuestion       | json   |
+| huri.token              | Token             | json   |
+| huri.audio.out          | Audio             | binary |
+| huri.motion             | Motion            | binary |
+
+`Emotion` and `Voice` only travel between modules inside the server.
+"""
+
+from huri_events.audio import Audio
+from huri_events.emotion import Emotion
+from huri_events.motion import Motion
+from huri_events.question import PartialQuestion, RAGQuestion
+from huri_events.speech import Transcript, Voice
+from huri_events.text import Token
+
+__all__ = [
+    "Audio",
+    "Emotion",
+    "Motion",
+    "PartialQuestion",
+    "RAGQuestion",
+    "Token",
+    "Transcript",
+    "Voice",
+]

huri_events-0.1.0/huri_events/audio.py

@@ -0,0 +1,47 @@
+import logging
+import struct
+from dataclasses import dataclass
+
+import numpy as np
+
+from huri_core.core.events import EventData
+
+logger = logging.getLogger("ray.serve")
+
+
+@dataclass
+class Audio(EventData[bytes]):
+    """Synthesized speech: float32 mono samples.
+
+    Wire (binary): ``>IBd`` header — sample_rate (u32), end (u8), pts (f64,
+    seconds from utterance start) — then the float32 samples.
+    """
+
+    data: np.ndarray
+    sample_rate: int
+    end: bool = False
+    pts: float = 0.0  # presentation timestamp in seconds from utterance start
+
+    def to_wire(self) -> bytes:
+        logger.info(
+            "Audio samples=%d sr=%d end=%s pts=%.3fs",
+            self.data.shape[0],
+            self.sample_rate,
+            self.end,
+            self.pts,
+        )
+        header = struct.pack(">IBd", self.sample_rate, int(self.end), self.pts)
+        return header + bytes(self.data.tobytes())
+
+    @classmethod
+    def from_wire(cls, data: bytes) -> "Audio":
+        sample_rate, end, pts = struct.unpack(">IBd", data[:13])
+        samples = np.frombuffer(data[13:], dtype=np.float32)
+
+        return cls(sample_rate=sample_rate, end=end, pts=pts, data=samples)
+
+    def summarize(self) -> str:
+        """Short repr that avoids dumping full numpy arrays into the log."""
+
+        cls = type(self).__name__
+        return f"{cls}(shape={self.data.shape}, dtype={self.data.dtype})"

huri_events-0.1.0/huri_events/emotion.py

@@ -0,0 +1,16 @@
+from dataclasses import dataclass
+from typing import Dict
+
+from huri_core.core.events import EventData
+
+
+@dataclass
+class Emotion(EventData):
+    """Speech emotion: best `label`, its `confidence`, all `scores`; `end`
+    marks the utterance's final estimate. Travels between modules only
+    (EMO -> EAG), it has no wire format."""
+
+    label: str
+    confidence: float
+    scores: Dict[str, float]
+    end: bool

huri_events-0.1.0/huri_events/motion.py

@@ -0,0 +1,81 @@
+import logging
+import struct
+from dataclasses import dataclass
+
+import numpy as np
+
+from huri_core.core.events import EventData
+
+_EMAGE_FPS = 30
+
+# Layout of the per-frame vectors, shared by to_wire/from_wire.
+_POSE_DIM = 165  # 55 SMPL-X joints x 3 axis-angle
+_EXPR_DIM = 100  # facial expression coefficients
+_TRANS_DIM = 3  # global root translation
+
+logger = logging.getLogger("ray.serve")
+
+
+@dataclass
+class Motion(EventData[bytes]):
+    """SMPL-X gesture frames paired with the speech (`pts` matches Audio.pts).
+
+    Wire (binary): ``>dII`` header — pts (f64), fps (u32), frame count (u32) —
+    then float32 poses (t x 165), expressions (t x 100) and trans (t x 3).
+    """
+
+    poses: np.ndarray  # (t, 165)  SMPL-X axis-angle, 55 joints × 3
+    expressions: np.ndarray  # (t, 100)  facial expression coefficients
+    trans: np.ndarray  # (t, 3)    global root translation
+    fps: int = _EMAGE_FPS
+    pts: float = 0.0  # presentation timestamp in seconds, paired with Audio.pts
+
+    def to_wire(self) -> bytes:
+        n_frames = self.poses.shape[0]
+        logger.info(
+            "Motion frames=%d fps=%d pts=%.3fs",
+            n_frames,
+            self.fps,
+            self.pts,
+        )
+        header = struct.pack(">dII", self.pts, self.fps, n_frames)
+        body: bytes = (
+            self.poses.astype(np.float32).tobytes()
+            + self.expressions.astype(np.float32).tobytes()
+            + self.trans.astype(np.float32).tobytes()
+        )
+        return header + body
+
+    def summarize(self) -> str:
+        cls = type(self).__name__
+        return (
+            f"{cls}(frames={self.poses.shape[0]}, "
+            f"fps={self.fps}, pts={self.pts:.3f}s)"
+        )
+
+    @classmethod
+    def from_wire(cls, data: bytes) -> "Motion":
+        pts, fps, n_frames = struct.unpack(">dII", data[:16])
+
+        body = np.frombuffer(data[16:], dtype=np.float32)
+        expected = n_frames * (_POSE_DIM + _EXPR_DIM + _TRANS_DIM)
+        if body.size < expected:
+            raise ValueError(
+                f"truncated motion frame: {body.size} floats, expected {expected} "
+                f"for {n_frames} frames"
+            )
+
+        offset = 0
+        out = []
+        for dim in (_POSE_DIM, _EXPR_DIM, _TRANS_DIM):
+            out.append(body[offset : offset + n_frames * dim].reshape(n_frames, dim))
+            offset += n_frames * dim
+        poses, expressions, trans = out
+
+        return cls(
+            poses=poses,
+            expressions=expressions,
+            trans=trans,
+            fps=fps,
+            pts=pts,
+        )

huri_events-0.1.0/huri_events/question.py

@@ -0,0 +1,58 @@
+from dataclasses import dataclass
+from typing import Any, Mapping, Optional
+
+from huri_events.emotion import Emotion
+from huri_events.speech import Transcript
+
+from huri_core.core.events import JsonEvent
+
+
+@dataclass
+class PartialQuestion(JsonEvent):
+    """Partial question used to aggregate a sentence to an emotion: either
+    part may be missing (TAG sends the transcript, EAG the emotion)."""
+
+    transcript: Optional[Transcript]
+    emotion: Optional[Emotion]
+
+
+@dataclass
+class RAGQuestion(JsonEvent):
+    """Fully aggregated question to send to the RAG.
+
+    Wire: JSON ``{"transcript": {"text", "end"}, "emotion": {...} | null}``,
+    or the shorthand ``{"text": str}`` a client sends for a typed question.
+    """
+
+    transcript: Transcript
+    emotion: Optional[Emotion] = None
+
+    @classmethod
+    def from_wire(cls, data: Mapping[str, Any]) -> "RAGQuestion":
+        """Accept a typed question straight off the wire.
+
+        In-pipeline, QAG builds this from a Transcript + Emotion. External clients
+        (the website backend, the CLI text sender) inject a typed question as a
+        bare ``{"text": ...}`` — no live emotion — which we wrap into a final
+        Transcript. The nested branch also hydrates the dataclasses (JSON gives
+        plain dicts) so a fully-shaped payload round-trips too.
+        """
+        if "text" in data:
+            return cls(Transcript(text=data["text"], end=True), None)
+
+        # Thomas: it's nasty, but ragquestion is a subclass and doesn't work well with
+        # ray for my end, i get RAGQuestion.__init__() got an unexpected keyword
+        # argument 'text' if there is a agnostic way, we can fix this, but until now
+        # it's like this
+
+        transcript = data.get("transcript")
+        if isinstance(transcript, Mapping):
+            transcript = Transcript(**transcript)
+        if not isinstance(transcript, Transcript):
+            raise ValueError(
+                "RAGQuestion.from_wire needs a 'text' or 'transcript' field"
+            )
+        emotion = data.get("emotion")
+        if isinstance(emotion, Mapping):
+            emotion = Emotion(**emotion)
+        return cls(transcript, emotion)

huri_events-0.1.0/huri_events/speech.py

@@ -0,0 +1,34 @@
+from dataclasses import dataclass
+from typing import Optional
+
+import numpy as np
+
+from huri_core.core.events import JsonEvent
+
+
+@dataclass
+class Transcript(JsonEvent):
+    """Text recognized from speech; `end` closes the utterance.
+
+    Wire: JSON ``{"text": str, "end": bool}``.
+    """
+
+    text: str
+    end: bool
+
+
+@dataclass
+class Voice(JsonEvent):
+    """A frame of detected speech (float32 samples), or `data=None` to mark the
+    end of the utterance. Travels between modules only (VAD -> STT, EMO)."""
+
+    data: Optional[np.ndarray]
+
+    def summarize(self) -> str:
+        """Short repr that avoids dumping full numpy arrays into the log."""
+
+        if self.data is not None:
+            cls = type(self).__name__
+            return f"{cls}(shape={self.data.shape}, dtype={self.data.dtype})"
+        else:
+            return super().summarize()

huri_events-0.1.0/huri_events/text.py

@@ -0,0 +1,15 @@
+from dataclasses import dataclass
+
+from huri_core.core.events import JsonEvent
+
+
+@dataclass
+class Token(JsonEvent):
+    """A delta of the assistant's streamed reply; `end` marks the end of the
+    utterance (with empty text).
+
+    Wire: JSON ``{"text": str, "end": bool}``.
+    """
+
+    text: str
+    end: bool

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

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: huri-events
+Version: 0.1.0
+Summary: The curated HuRI event vocabulary: the huri.* topics and their wire formats
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: huri-core<0.5,>=0.4
+Requires-Dist: numpy<2,>=1.26
+
+# huri-events
+
+The curated HuRI event vocabulary: one event class per `huri.*` topic, with its
+wire format, registered through the `huri.events` entry point group. The
+`huri.` namespace is reserved for this package; third-party events use their
+own (`acme.*`), see [Modules as plugins](../../README.md#modules-as-plugins).
+
+It is deliberately light (huri-core and numpy): a client installs it next to
+`huri-core[client]` to decode every curated topic.
+
+```sh
+# from a huri-modules checkout:
+pip install "huri-core[client] @ git+https://github.com/Lucy-Robotics/huri-core.git@$(. ./versions.env && echo "$HURI_CORE_REF")" \
+  ./packages/huri-events
+```
+
+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`, which is
+not on PyPI: without a checkout, install it from git in the same pip command,
+so pip never looks it 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 @ 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_events-0.1.0/huri_events.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+huri_events/__init__.py
+huri_events/audio.py
+huri_events/emotion.py
+huri_events/motion.py
+huri_events/question.py
+huri_events/speech.py
+huri_events/text.py
+huri_events.egg-info/PKG-INFO
+huri_events.egg-info/SOURCES.txt
+huri_events.egg-info/dependency_links.txt
+huri_events.egg-info/entry_points.txt
+huri_events.egg-info/requires.txt
+huri_events.egg-info/top_level.txt
+tests/test_wire.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,10 @@
+[huri.events]
+huri.audio.in = huri_core.core.events:BytesEvent
+huri.audio.out = huri_events.audio:Audio
+huri.emotion = huri_events.emotion:Emotion
+huri.motion = huri_events.motion:Motion
+huri.partial_question = huri_events.question:PartialQuestion
+huri.question = huri_events.question:RAGQuestion
+huri.token = huri_events.text:Token
+huri.transcript = huri_events.speech:Transcript
+huri.voice = huri_events.speech:Voice

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

@@ -0,0 +1,2 @@
+huri-core<0.5,>=0.4
+numpy<2,>=1.26

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

@@ -0,0 +1 @@
+huri_events

huri_events-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=64,<82"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "huri-events"
+version = "0.1.0"
+description = "The curated HuRI event vocabulary: the huri.* topics and their wire formats"
+readme = "README.md"
+requires-python = ">=3.10"
+# Light on purpose: a client decodes every curated topic with this and
+# huri-core[client], no torch, no ray.
+dependencies = [
+  "huri-core>=0.4,<0.5",
+  "numpy>=1.26,<2",
+]
+
+# Topic -> event class. The huri.* namespace is reserved for this package.
+[project.entry-points."huri.events"]
+"huri.audio.in" = "huri_core.core.events:BytesEvent"  # inbound mic frames (raw int16 PCM)
+"huri.audio.out" = "huri_events.audio:Audio"
+"huri.voice" = "huri_events.speech:Voice"
+"huri.transcript" = "huri_events.speech:Transcript"
+"huri.emotion" = "huri_events.emotion:Emotion"
+"huri.partial_question" = "huri_events.question:PartialQuestion"
+"huri.question" = "huri_events.question:RAGQuestion"
+"huri.token" = "huri_events.text:Token"
+"huri.motion" = "huri_events.motion:Motion"
+
+[tool.setuptools.packages.find]
+include = ["huri_events*"]

huri_events-0.1.0/setup.cfg

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

huri_events-0.1.0/tests/test_wire.py

@@ -0,0 +1,112 @@
+"""Every curated event survives its wire format, and huri-events owns huri.*."""
+
+from importlib.metadata import entry_points
+
+import numpy as np
+import pytest
+from huri_events import (
+    Audio,
+    Emotion,
+    Motion,
+    PartialQuestion,
+    RAGQuestion,
+    Token,
+    Transcript,
+    Voice,
+)
+
+from huri_core.core.events import BytesEvent
+
+
+def roundtrip(event):
+    return type(event).from_wire(event.to_wire())
+
+
+@pytest.mark.parametrize(
+    "event",
+    [
+        Transcript("hello robot", True),
+        Token("Hel", False),
+        Token("", True),
+        BytesEvent(b"\x00\x01\x02\x03"),
+    ],
+    ids=lambda e: type(e).__name__,
+)
+def test_simple_events_roundtrip(event):
+    assert roundtrip(event) == event
+
+
+def test_question_roundtrips_with_and_without_emotion():
+    emotion = Emotion("neu", 0.9, {"neu": 0.9, "ang": 0.1}, True)
+    for question in (
+        RAGQuestion(Transcript("hi", True), None),
+        RAGQuestion(Transcript("hi", True), emotion),
+    ):
+        assert roundtrip(question) == question
+
+
+def test_typed_question_shorthand():
+    assert RAGQuestion.from_wire({"text": "hi"}) == RAGQuestion(Transcript("hi", True))
+
+
+def test_audio_roundtrip_keeps_samples_and_timing():
+    audio = Audio(np.linspace(-1, 1, 480, dtype=np.float32), 24000, True, 1.25)
+    back = roundtrip(audio)
+    assert (back.sample_rate, bool(back.end), back.pts) == (24000, True, 1.25)
+    np.testing.assert_array_equal(back.data, audio.data)
+
+
+def test_motion_roundtrip_and_truncation():
+    frames = 3
+    motion = Motion(
+        poses=np.arange(frames * 165, dtype=np.float32).reshape(frames, 165),
+        expressions=np.ones((frames, 100), dtype=np.float32),
+        trans=np.zeros((frames, 3), dtype=np.float32),
+        pts=0.5,
+    )
+    back = roundtrip(motion)
+    np.testing.assert_array_equal(back.poses, motion.poses)
+    assert (back.fps, back.pts) == (motion.fps, 0.5)
+    with pytest.raises(ValueError, match="truncated"):
+        Motion.from_wire(motion.to_wire()[:-4])
+
+
+def test_internal_events_are_constructible():
+    assert Voice(None).data is None
+    assert PartialQuestion(Transcript("a", True), None).emotion is None
+
+
+def test_huri_events_registers_every_curated_topic():
+    eps = {ep.name: ep for ep in entry_points(group="huri.events")}
+    curated = {name for name in eps if name.startswith("huri.")}
+    assert curated == {
+        "huri.audio.in",
+        "huri.audio.out",
+        "huri.voice",
+        "huri.transcript",
+        "huri.emotion",
+        "huri.partial_question",
+        "huri.question",
+        "huri.token",
+        "huri.motion",
+    }
+    dists = {getattr(eps[name].dist, "name", None) for name in curated}
+    assert dists == {"huri-events"}
+
+
+def test_motion_survives_the_wire():
+    """from_wire used to drop the body, yielding a zero-frame Motion."""
+    frames = 4
+    original = Motion(
+        poses=np.arange(frames * 165, dtype=np.float32).reshape(frames, 165),
+        expressions=np.arange(frames * 100, dtype=np.float32).reshape(frames, 100),
+        trans=np.arange(frames * 3, dtype=np.float32).reshape(frames, 3),
+        pts=1.5,
+    )
+    decoded = roundtrip(original)
+
+    assert decoded.pts == pytest.approx(original.pts)
+    assert decoded.fps == original.fps
+    np.testing.assert_array_equal(decoded.poses, original.poses)
+    np.testing.assert_array_equal(decoded.expressions, original.expressions)
+    np.testing.assert_array_equal(decoded.trans, original.trans)