alpha-avatar-core 0.6.4__tar.gz

alpha_avatar_core-0.6.4/.gitignore

@@ -0,0 +1,182 @@
+**/.vscode
+**/.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+KMS
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.dev
+.env.demo
+.env.personal
+.env.prod
+.venv
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# trunk
+.trunk/
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+auth
+node_modules
+
+credentials.json
+pyrightconfig.json
+
+# Database files
+*.db
+.alphaavatar_workspace
+
+docs/releases/.generated/

alpha_avatar_core-0.6.4/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,38 @@
+# 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/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.

alpha_avatar_core-0.6.4/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",
+]

alpha_avatar_core-0.6.4/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,
+        }

alpha_avatar_core-0.6.4/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 [],
+        )

alpha_avatar_core-0.6.4/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",
+]

alpha_avatar_core-0.6.4/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"