alpha-avatar-core 0.6.4__py3-none-any.whl

alpha_avatar_core-0.6.4.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: alpha-avatar-core
+Version: 0.6.4
+Summary: Core runtime schemas and transport primitives for AlphaAvatar.
+Project-URL: Source, https://github.com/AlphaAvatar/AlphaAvatar
+License-Expression: Apache-2.0
+Keywords: AI,audio,multimodal,omni,realtime,rtc,runtime,video
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: <3.12,>=3.11
+Provides-Extra: livekit
+Requires-Dist: livekit-api<2,>=1.0.4; extra == 'livekit'
+Requires-Dist: livekit-protocol~=1.0; extra == 'livekit'
+Requires-Dist: livekit<2,>=1.0.12; extra == 'livekit'
+Description-Content-Type: text/markdown
+
+# AlphaAvatar Core
+
+## 🧩 Introduction
+
+`avatar-core` provides the transport-agnostic runtime primitives shared across AlphaAvatar.
+
+It defines how multimodal observations are represented, enriched with annotations, published through typed perception streams, aligned on a shared timeline, and selected as consumer-specific windows. The package intentionally remains independent from LiveKit Agents, model providers, and plugin implementations so that RTC adapters, Persona, Memory, Vision, and future multimodal components can evolve without coupling the core runtime to a specific backend.
+
+## 📦 Package Structure
+
+```text
+avatar-core/
+├── README.md
+├── alphaavatar/
+│   └── core/
+│       ├── __init__.py
+│       ├── env/                         # Environment observation envelopes and annotations.
+│       │   ├── __init__.py
+│       │   ├── annotation.py           # Structured metadata attached to an observation.
+│       │   └── observation.py          # Runtime observation envelope for video, audio, screen, and events.
+│       ├── media/                       # Backend-independent multimodal payload representations.
+│       │   ├── __init__.py
+│       │   ├── formats.py              # Payload formats and views such as raw, annotated, and derived.
+│       │   ├── payload.py              # Thread-safe multi-representation MediaPayload container.
+│       │   └── video.py                # Generic video frame buffers and video payload helpers.
+│       ├── perception/                  # Full-duplex perception transport, alignment, and windowing.
+│       │   ├── __init__.py
+│       │   ├── runtime.py              # PerceptionRuntime entry point and typed stream orchestration.
+│       │   ├── stream.py               # Multi-consumer streams with independent cursors and backpressure.
+│       │   ├── timeline.py             # Observation–annotation alignment and renderer coordination.
+│       │   └── window.py               # Ordered multimodal windows for Memory, Persona, Vision, and routers.
+│       └── version.py                  # Package version metadata.
+└── pyproject.toml
+```
+
+## 🔄 Workflow
+
+External RTC or device adapters first normalize incoming media into AlphaAvatar-owned payloads. `EnvObservation` wraps each payload with identity, source, timestamp, and metadata before publishing it to `PerceptionRuntime`. Persona and other perception modules can attach annotations and produce annotated payload views without overwriting the raw representation. Consumer-specific windows then provide ordered observations to modules such as ENV Memory, Sampled Frame Vision, routers, and future audio or event processors.

alpha_avatar_core-0.6.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+alphaavatar/core/__init__.py,sha256=RgNvd3aQnnX-fj5o7PpCR-rSvGFonqD6s6VN0cn031o,583
+alphaavatar/core/version.py,sha256=E0TQJAIHA9qIzlJCRktdYBfRGAwiCdzN3hoMMmQHYb0,604
+alphaavatar/core/env/__init__.py,sha256=uUj0yTnqWvdZ4nY_0XyAo2UoKUj3CFwdtJBBtfDqvyk,719
+alphaavatar/core/env/annotation.py,sha256=ClRAr6FW3Y_EgRj30_mMYwLJivTqxIen7q-EjbQWOO0,1931
+alphaavatar/core/env/observation.py,sha256=ucIv1L4bYqLt8n4_PZUVTwwiC-ZosbrSOfnLuwz0rk0,5737
+alphaavatar/core/media/__init__.py,sha256=ALPmE_gDulwSfFZxRURfPfzKvw04phimP9bT5izVzfQ,922
+alphaavatar/core/media/formats.py,sha256=M2uc536ome5v8b28Q7GZUJ8WROUvd_KSktENW_j9EhM,1640
+alphaavatar/core/media/payload.py,sha256=YJ4odXWfhfAf9TQY6YKy5Hhu9X6rIUpVCO1ITuQEnNI,3927
+alphaavatar/core/media/video.py,sha256=HkdOyPrexmlJVd6KdPHw3BrviPm9bepUGl8nFElebc8,3989
+alphaavatar/core/perception/__init__.py,sha256=dzgnBuTL7MKplD8c0Q-zCporXYSfgp1JoS18PAuwBSU,1066
+alphaavatar/core/perception/runtime.py,sha256=PR_IGuidxxZnxLPTvVmz2JXXPPmHV4VhYfYtbuEXIyo,4423
+alphaavatar/core/perception/stream.py,sha256=XlQSHBTqBshXFy5O7F6tMotFJ-KB3gHeHlKWSQEFETk,3670
+alphaavatar/core/perception/timeline.py,sha256=aRnop-f-5LbaOpWC4Kck6oXUdsJPmlCymqB5pP_Aask,5462
+alphaavatar/core/perception/window.py,sha256=AGzsl_NfN2x_xpc98QOn4MvtgEe13qrozpoAzuCM_vI,3490
+alpha_avatar_core-0.6.4.dist-info/METADATA,sha256=YK5rEACRedpn3jEJUyJb5oawDlrzdvy8JsKZiyOdn-0,3894
+alpha_avatar_core-0.6.4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+alpha_avatar_core-0.6.4.dist-info/RECORD,,

alpha_avatar_core-0.6.4.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

alphaavatar/core/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

alphaavatar/core/env/__init__.py

@@ -0,0 +1,20 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .annotation import EnvAnnotation
+from .observation import EnvObservation
+
+__all__ = [
+    "EnvAnnotation",
+    "EnvObservation",
+]

alphaavatar/core/env/annotation.py

@@ -0,0 +1,62 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class EnvAnnotation:
+    """
+    Lightweight environment annotation attached to an observation or frame.
+
+    Examples:
+    - face boxes from persona.face_stream
+    - object boxes from interaction_router
+    - gaze/focus regions from avatar vision
+    - OCR/screen regions
+    - speaker/voice alignment metadata
+
+    This object must stay LiveKit-independent.
+    """
+
+    source: str
+    annotation_type: str
+    data: dict[str, Any]
+
+    # Usually one of these two is enough.
+    frame_id: str | None = None
+    observation_id: str | None = None
+
+    timestamp: str | None = None
+    annotation_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    @property
+    def target_key(self) -> str | None:
+        if self.observation_id:
+            return f"observation:{self.observation_id}"
+        if self.frame_id:
+            return f"frame:{self.frame_id}"
+        return None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "annotation_id": self.annotation_id,
+            "source": self.source,
+            "type": self.annotation_type,
+            "timestamp": self.timestamp,
+            "frame_id": self.frame_id,
+            "observation_id": self.observation_id,
+            "data": self.data,
+        }

alphaavatar/core/env/observation.py

@@ -0,0 +1,205 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from alphaavatar.core.media import MediaPayload
+
+from .annotation import EnvAnnotation
+
+
+@dataclass(slots=True)
+class EnvObservation:
+    """
+    Runtime environment observation envelope.
+
+    payload:
+        AlphaAvatar-owned MediaPayload.
+
+        It must not directly contain:
+        - LiveKit rtc.VideoFrame
+        - provider-specific content blocks
+        - LangChain message objects
+
+    path:
+        Optional persisted evidence path.
+    """
+
+    kind: str
+    timestamp: str
+    source_id: str
+
+    observation_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+
+    path: str | None = None
+    mime_type: str | None = None
+
+    payload: MediaPayload | None = field(
+        default=None,
+        repr=False,
+        compare=False,
+    )
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+    annotations: list[EnvAnnotation] = field(default_factory=list)
+
+    @property
+    def frame_id(self) -> str | None:
+        metadata_frame_id = self.metadata.get("frame_id")
+        if metadata_frame_id:
+            return str(metadata_frame_id)
+
+        payload_frame_id = getattr(self.payload, "frame_id", None)
+        if payload_frame_id:
+            return str(payload_frame_id)
+
+        return None
+
+    @property
+    def has_payload(self) -> bool:
+        return self.payload is not None and self.payload.has_any
+
+    @property
+    def has_persisted_evidence(self) -> bool:
+        return bool(self.path)
+
+    def add_annotation(self, annotation: EnvAnnotation) -> bool:
+        """
+        Add annotation once.
+
+        Returns True when added and False when it already existed.
+        """
+
+        for current in self.annotations:
+            if current.annotation_id == annotation.annotation_id:
+                return False
+
+        self.annotations.append(annotation)
+        return True
+
+    def clear_payload(self) -> None:
+        if self.payload is not None:
+            self.payload.clear()
+
+        self.payload = None
+
+    def to_evidence_dict(self) -> dict[str, Any]:
+        if self.path:
+            data: dict[str, Any] = {
+                "observation_id": self.observation_id,
+                "kind": self.kind,
+                "timestamp": self.timestamp,
+                "source_id": self.source_id,
+                "mime_type": self.mime_type,
+                "metadata": self.metadata,
+                "annotations": [annotation.to_dict() for annotation in self.annotations],
+                "path": self.path,
+            }
+
+            return data
+        else:
+            return {}
+
+    @classmethod
+    def video_frame(
+        cls,
+        *,
+        timestamp: str,
+        source_id: str,
+        payload: MediaPayload,
+        path: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        annotations: list[EnvAnnotation] | None = None,
+    ) -> EnvObservation:
+        return cls(
+            kind="video_frame",
+            timestamp=timestamp,
+            source_id=source_id,
+            path=path,
+            mime_type="image/jpeg",
+            payload=payload,
+            metadata=metadata or {},
+            annotations=annotations or [],
+        )
+
+    @classmethod
+    def screen_frame(
+        cls,
+        *,
+        timestamp: str,
+        source_id: str,
+        payload: MediaPayload,
+        path: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        annotations: list[EnvAnnotation] | None = None,
+    ) -> EnvObservation:
+        return cls(
+            kind="screen_frame",
+            timestamp=timestamp,
+            source_id=source_id,
+            path=path,
+            mime_type="image/jpeg",
+            payload=payload,
+            metadata=metadata or {},
+            annotations=annotations or [],
+        )
+
+    @classmethod
+    def video_clip(
+        cls,
+        *,
+        timestamp: str,
+        source_id: str,
+        payload: MediaPayload | None = None,
+        path: str | None = None,
+        mime_type: str = "video/mp4",
+        metadata: dict[str, Any] | None = None,
+        annotations: list[EnvAnnotation] | None = None,
+    ) -> EnvObservation:
+        return cls(
+            kind="video_clip",
+            timestamp=timestamp,
+            source_id=source_id,
+            path=path,
+            mime_type=mime_type,
+            payload=payload,
+            metadata=metadata or {},
+            annotations=annotations or [],
+        )
+
+    @classmethod
+    def audio_segment(
+        cls,
+        *,
+        timestamp: str,
+        source_id: str,
+        payload: MediaPayload | None = None,
+        path: str | None = None,
+        mime_type: str = "audio/wav",
+        metadata: dict[str, Any] | None = None,
+        annotations: list[EnvAnnotation] | None = None,
+    ) -> EnvObservation:
+        return cls(
+            kind="audio_segment",
+            timestamp=timestamp,
+            source_id=source_id,
+            path=path,
+            mime_type=mime_type,
+            payload=payload,
+            metadata=metadata or {},
+            annotations=annotations or [],
+        )

alphaavatar/core/media/__init__.py

@@ -0,0 +1,26 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from .formats import PayloadFormat, PayloadView
+from .payload import MediaPayload, PayloadFormatUnavailable
+from .video import PixelFormat, VideoFrame, VideoFramePayload
+
+__all__ = [
+    "MediaPayload",
+    "PayloadFormat",
+    "PayloadFormatUnavailable",
+    "PayloadView",
+    "PixelFormat",
+    "VideoFrame",
+    "VideoFramePayload",
+]

alphaavatar/core/media/formats.py

@@ -0,0 +1,57 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class PayloadView(StrEnum):
+    """
+    Logical representation view.
+
+    RAW:
+        Original input representation produced by an input adapter.
+
+    ANNOTATED:
+        Representation containing perception annotations, such as face boxes.
+
+    DERIVED:
+        Other derived representations, such as thumbnails or provider-ready blocks.
+    """
+
+    RAW = "raw"
+    ANNOTATED = "annotated"
+    DERIVED = "derived"
+
+
+class PayloadFormat(StrEnum):
+    """
+    AlphaAvatar-owned payload formats.
+
+    Do not add provider-specific or RTC-specific classes here.
+    """
+
+    # Generic video frame owned by AlphaAvatar.
+    VIDEO_FRAME = "video.frame"
+
+    # Encoded visual representations.
+    IMAGE_JPEG_BYTES = "image/jpeg.bytes"
+    IMAGE_PNG_BYTES = "image/png.bytes"
+
+    # Reserved for later audio implementation.
+    AUDIO_PCM16_BYTES = "audio/pcm16.bytes"
+    AUDIO_WAV_BYTES = "audio/wav.bytes"
+
+    # Reserved for provider adapters.
+    PROVIDER_CONTENT_BLOCK = "provider.content_block"

alphaavatar/core/media/payload.py

@@ -0,0 +1,142 @@
+# Copyright 2026 AlphaAvatar project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+from threading import RLock
+from typing import Any
+
+from .formats import PayloadFormat, PayloadView
+
+
+class PayloadFormatUnavailable(LookupError):
+    """Requested payload representation is unavailable."""
+
+
+class MediaPayload:
+    """
+    Multi-representation runtime media payload.
+
+    One logical media item can expose several representations:
+
+        RAW + VIDEO_FRAME
+        RAW + IMAGE_JPEG_BYTES
+        ANNOTATED + VIDEO_FRAME
+        ANNOTATED + IMAGE_JPEG_BYTES
+
+    Consumers explicitly request the representation they need.
+    """
+
+    def __init__(
+        self,
+        *,
+        modality: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        self.modality = modality
+        self.metadata = metadata or {}
+
+        self._representations: dict[
+            tuple[PayloadView, PayloadFormat],
+            Any,
+        ] = {}
+
+        self._lock = RLock()
+        self._revision = 0
+
+    @property
+    def revision(self) -> int:
+        with self._lock:
+            return self._revision
+
+    @property
+    def has_any(self) -> bool:
+        with self._lock:
+            return bool(self._representations)
+
+    def put(
+        self,
+        fmt: PayloadFormat,
+        value: Any,
+        *,
+        view: PayloadView = PayloadView.RAW,
+    ) -> None:
+        if value is None:
+            raise ValueError(f"Cannot store None payload representation: view={view}, format={fmt}")
+
+        with self._lock:
+            self._representations[(view, fmt)] = value
+            self._revision += 1
+
+    def has(
+        self,
+        fmt: PayloadFormat,
+        *,
+        view: PayloadView = PayloadView.RAW,
+        fallback_to_raw: bool = True,
+    ) -> bool:
+        with self._lock:
+            if (view, fmt) in self._representations:
+                return True
+
+            if fallback_to_raw and view != PayloadView.RAW:
+                return (PayloadView.RAW, fmt) in self._representations
+
+            return False
+
+    def get(
+        self,
+        fmt: PayloadFormat,
+        *,
+        view: PayloadView = PayloadView.RAW,
+        fallback_to_raw: bool = True,
+    ) -> Any:
+        with self._lock:
+            key = (view, fmt)
+
+            if key in self._representations:
+                return self._representations[key]
+
+            if fallback_to_raw and view != PayloadView.RAW:
+                raw_key = (PayloadView.RAW, fmt)
+                if raw_key in self._representations:
+                    return self._representations[raw_key]
+
+        raise PayloadFormatUnavailable(
+            "Payload representation unavailable: "
+            f"modality={self.modality!r}, "
+            f"view={view.value!r}, "
+            f"format={fmt.value!r}"
+        )
+
+    def remove(
+        self,
+        fmt: PayloadFormat,
+        *,
+        view: PayloadView,
+    ) -> None:
+        with self._lock:
+            removed = self._representations.pop((view, fmt), None)
+            if removed is not None:
+                self._revision += 1
+
+    def clear(self) -> None:
+        with self._lock:
+            self._representations.clear()
+            self._revision += 1
+
+    def available_representations(
+        self,
+    ) -> tuple[tuple[PayloadView, PayloadFormat], ...]:
+        with self._lock:
+            return tuple(self._representations.keys())