huri-events 0.1.0.dev0__py3-none-any.whl

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/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/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/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/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/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/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.dev0.dist-info/METADATA

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: huri-events
+Version: 0.1.0.dev0
+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.0.dev0
+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.dev0.dist-info/RECORD

@@ -0,0 +1,12 @@
+huri_events/__init__.py,sha256=vToUbd1mI8IeBDbu9DzYjPSU8koDLhLVXzsYzBJ6Flk,1164
+huri_events/audio.py,sha256=i-kUIS1TCgZ3dSLSpzJygNb9qke_2GeRDl3Npu8-860,1401
+huri_events/emotion.py,sha256=AP7XutAGA6VxWfzQfLK5EcJZs1bCBs3LH3cR7GAhIqc,413
+huri_events/motion.py,sha256=_8iKWL1GYWPU3CkdclSIBHw7WAzOrsQCmPnFGZBEyWo,2577
+huri_events/question.py,sha256=hP3io6nHF5seqnKK3aEtrH1UVcQV5DWrJokvFjm0YdE,2182
+huri_events/speech.py,sha256=Xn24ZtGw7GErot_bw48yOVas0g5VIciXTVkjzN-bwjY,858
+huri_events/text.py,sha256=gHQe-f7Fa6zNtiAjTQ2ERLX4oqcKLHtLsiBYHW6bqqc,311
+huri_events-0.1.0.dev0.dist-info/METADATA,sha256=y5yKwmscmruCqYtrKGoyVBU70jfOcflG6xjS5ghB64M,1539
+huri_events-0.1.0.dev0.dist-info/WHEEL,sha256=YLJXdYXQ2FQ0Uqn2J-6iEIC-3iOey8lH3xCtvFLkd8Q,91
+huri_events-0.1.0.dev0.dist-info/entry_points.txt,sha256=clc3USkQxq78TyRpwCwQO_gmIBj9Vg2v4luzI3Nwmp0,419
+huri_events-0.1.0.dev0.dist-info/top_level.txt,sha256=EmPGEYiIh5iXk-WuHIpq-njvZVH6vEExz6n_6cXTE3o,12
+huri_events-0.1.0.dev0.dist-info/RECORD,,

huri_events-0.1.0.dev0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (81.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

huri_events-0.1.0.dev0.dist-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.dev0.dist-info/top_level.txt

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