livekit-plugins-atmee 0.1.0__py3-none-any.whl

livekit/plugins/atmee/__init__.py

@@ -0,0 +1,63 @@
+# Copyright 2026 Atmanity
+#
+# 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.
+
+"""Atmee avatar plugin for LiveKit Agents.
+
+Bring your own LiveKit voice agent; Atmee renders a talking-head avatar from a
+single portrait into your room and bills per minute::
+
+    from livekit.plugins import atmee
+
+    avatar_id = await atmee.AtmeeAPI().create_avatar(name="Val", image="portrait.jpg")
+
+    avatar = atmee.AvatarSession(avatar_id=avatar_id)   # ATMEE_API_KEY in the environment
+    await avatar.start(session, room=ctx.room)
+    await session.start(agent=..., room=ctx.room)       # the agent's TTS drives the avatar's video
+
+See https://github.com/Atmanity/atmee_livekit_plugin for the architecture notes.
+"""
+
+from .api import (
+    AtmeeAPI,
+    AtmeeAvatarNotReadyError,
+    AtmeeException,
+    AtmeeNoCapacityError,
+    AvatarInfo,
+    AvatarSessionInfo,
+)
+from .avatar import AvatarSession
+from .version import __version__
+
+__all__ = [
+    "AtmeeAPI",
+    "AtmeeAvatarNotReadyError",
+    "AtmeeException",
+    "AtmeeNoCapacityError",
+    "AvatarInfo",
+    "AvatarSession",
+    "AvatarSessionInfo",
+    "__version__",
+]
+
+from livekit.agents import Plugin
+
+from .log import logger
+
+
+class AtmeePlugin(Plugin):
+    def __init__(self) -> None:
+        super().__init__(__name__, __version__, __package__, logger)
+
+
+Plugin.register_plugin(AtmeePlugin())

livekit/plugins/atmee/api.py

@@ -0,0 +1,447 @@
+# Copyright 2026 Atmanity
+#
+# 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.
+
+"""Thin async client for the Atmee API (session_service) used by the plugin.
+
+Two resources matter here: **avatars** (create one from a portrait, read its
+status) and **avatar sessions** (render an avatar into your LiveKit room for
+your agent, end it). Authentication is your Atmee API key (``sk_atmee_...``)
+in the ``X-Api-Key`` header; the key never reaches a browser.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal
+
+import aiohttp
+
+from livekit.agents import (
+    DEFAULT_API_CONNECT_OPTIONS,
+    NOT_GIVEN,
+    APIConnectOptions,
+    NotGivenOr,
+    utils,
+)
+
+from .log import logger
+
+DEFAULT_API_URL = "https://api.atmanity.us"
+
+WaitFor = Literal["initializing", "avatar_joined"]
+
+# Overall budget of the start call: the worker acknowledges within seconds, but
+# waiting for the avatar to join covers model priming on a cold pod (the
+# server's own join timeout is 90 s) plus the room join.
+_START_TOTAL_TIMEOUT: dict[str, float] = {"initializing": 60.0, "avatar_joined": 180.0}
+_DEFAULT_TOTAL_TIMEOUT = 120.0
+
+
+class AtmeeException(Exception):
+    """An Atmee API call failed.
+
+    ``status_code`` is the HTTP status (0 when the request never got an
+    answer), ``code`` the machine-readable ``error`` field of the response
+    body when the API sent one (``invalid_livekit_token``,
+    ``avatar_not_renderable``, ``insufficient_credits``, ...), and
+    ``message`` its human-readable text.
+    """
+
+    def __init__(self, message: str, *, status_code: int = 0, code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.message = message
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code:
+            parts.append(f"[{self.code}]")
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        return " ".join(parts)
+
+
+class AtmeeNoCapacityError(AtmeeException):
+    """Every rendering worker is busy (HTTP 503 ``no_capacity``).
+
+    Never retried by the client: a render slot frees up on the order of
+    seconds to minutes, not the milliseconds a transport retry covers.
+    ``retry_after`` is the server's hint in seconds, when it sent one.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None) -> None:
+        super().__init__(message, status_code=503, code="no_capacity")
+        self.retry_after = retry_after
+
+
+class AtmeeAvatarNotReadyError(AtmeeException):
+    """The avatar cannot be rendered yet (HTTP 409 ``avatar_not_renderable``):
+    it has no portrait, or its appearance is still being processed."""
+
+
+@dataclass
+class AvatarSessionInfo:
+    """The ``202`` body of ``POST /v1/avatars/{avatarId}/avatar_sessions``."""
+
+    session_id: str
+    status: str
+    avatar_participant_identity: str
+    agent_identity: str
+    room_name: str
+    max_duration_seconds: int
+    billing_mode: str
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+
+@dataclass
+class AvatarInfo:
+    """What ``GET /v1/avatars/{avatarId}`` (and a create) report about an avatar."""
+
+    avatar_id: str
+    status: str
+    kind: str | None = None
+    name: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def ready(self) -> bool:
+        return self.status == "ready"
+
+
+_IMAGE_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+}
+
+
+class AtmeeAPI:
+    """Async client for the Atmee API.
+
+    Args:
+        api_key: your ``sk_atmee_...`` key; defaults to ``ATMEE_API_KEY``.
+        api_url: API base; defaults to ``ATMEE_API_URL`` or ``https://api.atmanity.us``.
+        conn_options: retry/timeout policy for transport failures and 5xx
+            answers (a 503 ``no_capacity`` is never retried).
+        session: an ``aiohttp.ClientSession`` to reuse. Inside a LiveKit job the
+            worker's shared session is used; outside (scripts, tests) a private
+            one is created and closed by :meth:`aclose`.
+    """
+
+    def __init__(
+        self,
+        api_key: NotGivenOr[str] = NOT_GIVEN,
+        api_url: NotGivenOr[str] = NOT_GIVEN,
+        *,
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+        session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        key = api_key or os.getenv("ATMEE_API_KEY")
+        if not key:
+            raise AtmeeException(
+                "ATMEE_API_KEY must be set (or pass api_key=...); create one in the Atmee "
+                "developer settings"
+            )
+        self._api_key = key
+        self._api_url = (api_url or os.getenv("ATMEE_API_URL") or DEFAULT_API_URL).rstrip("/")
+        self._conn_options = conn_options
+        self._session = session
+        self._owns_session = False
+
+    @property
+    def api_url(self) -> str:
+        return self._api_url
+
+    # --- avatar sessions -------------------------------------------------
+
+    async def create_avatar_session(
+        self,
+        avatar_id: str,
+        *,
+        livekit_url: str,
+        livekit_token: str,
+        agent_identity: str | None = None,
+        max_duration_seconds: int | None = None,
+        metadata: dict[str, Any] | None = None,
+        wait_for: WaitFor = "initializing",
+    ) -> AvatarSessionInfo:
+        """Render ``avatar_id`` into the room ``livekit_token`` grants.
+
+        ``livekit_token`` is a LiveKit access token you minted with YOUR
+        project's secret for the avatar participant: ``kind=agent``, a
+        ``roomJoin`` grant for your room, and the ``lk.publish_on_behalf``
+        attribute naming your agent (:class:`AvatarSession` does this for
+        you). Returns as soon as the rendering worker acknowledged the start,
+        or once the avatar joined with ``wait_for="avatar_joined"``.
+        """
+        payload: dict[str, Any] = {"livekitUrl": livekit_url, "livekitToken": livekit_token}
+        if agent_identity:
+            payload["agentIdentity"] = agent_identity
+        if max_duration_seconds is not None:
+            payload["maxDurationSeconds"] = int(max_duration_seconds)
+        if metadata:
+            payload["metadata"] = metadata
+        params: dict[str, str] | None = (
+            {"waitFor": wait_for} if wait_for != "initializing" else None
+        )
+        # Never retried: the POST reserves and bills a session as soon as the
+        # server accepts it, so a retry after a timeout or a 5xx could open a
+        # second render for the same room. The caller decides whether to try
+        # again (the AvatarSession does not).
+        data = await self._request(
+            "POST",
+            f"/v1/avatars/{avatar_id}/avatar_sessions",
+            json=payload,
+            params=params,
+            retry=False,
+            total_timeout=_START_TOTAL_TIMEOUT[wait_for],
+        )
+        return AvatarSessionInfo(
+            session_id=str(data.get("sessionId", "")),
+            status=str(data.get("status", "")),
+            avatar_participant_identity=str(data.get("avatarParticipantIdentity", "")),
+            agent_identity=str(data.get("agentIdentity", "")),
+            room_name=str(data.get("roomName", "")),
+            max_duration_seconds=int(data.get("maxDurationSeconds") or 0),
+            billing_mode=str(data.get("billingMode", "")),
+            raw=data,
+        )
+
+    async def end_avatar_session(self, session_id: str) -> dict[str, Any]:
+        """Stop billing for a session now. Idempotent: ending an ended session
+        answers normally with ``alreadyEnded: true``. Does not remove the avatar
+        from your room — :meth:`AvatarSession.aclose` does that."""
+        return await self._request("POST", f"/v1/avatar_sessions/{session_id}/end")
+
+    async def get_avatar_session(self, session_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/v1/avatar_sessions/{session_id}")
+
+    # --- avatars -----------------------------------------------------------
+
+    async def create_avatar(
+        self,
+        name: str,
+        image: str | Path | bytes,
+        *,
+        description: str | None = None,
+        content_type: str | None = None,
+    ) -> str:
+        """Create a render-only avatar from a single portrait and return its id.
+
+        ``image`` is a local file path, the image bytes, or an ``https://``
+        URL the Atmee service can download. A portrait-only avatar is ready
+        at once; nothing to poll. Add a voice later in the Atmee studio (or
+        ``PUT /v1/avatars/{id}/voice``) to make it conversational as well.
+        """
+        info = await self.create_avatar_info(
+            name, image, description=description, content_type=content_type
+        )
+        return info.avatar_id
+
+    async def create_avatar_info(
+        self,
+        name: str,
+        image: str | Path | bytes,
+        *,
+        description: str | None = None,
+        content_type: str | None = None,
+    ) -> AvatarInfo:
+        """Like :meth:`create_avatar`, returning the whole response."""
+        if isinstance(image, str) and _is_url(image):
+            manifest: dict[str, Any] = {
+                "schemaVersion": 1,
+                "name": name,
+                "assets": {"image": {"url": image}},
+            }
+            if description:
+                manifest["description"] = description
+            data = await self._request("POST", "/v1/avatars", json=manifest, retry=False)
+            return _avatar_info(data)
+
+        if isinstance(image, bytes | bytearray):
+            blob = bytes(image)
+            filename = "portrait" + _extension_for(content_type) if content_type else "portrait.jpg"
+            ctype = content_type or "image/jpeg"
+        else:
+            blob, filename, ctype = await asyncio.to_thread(_load_image_file, image, content_type)
+        form = aiohttp.FormData()
+        form.add_field("name", name)
+        if description:
+            form.add_field("description", description)
+        form.add_field("file", blob, filename=filename, content_type=ctype)
+        data = await self._request("POST", "/v1/avatars", data=form, retry=False)
+        return _avatar_info(data)
+
+    async def get_avatar(self, avatar_id: str) -> AvatarInfo:
+        return _avatar_info(await self._request("GET", f"/v1/avatars/{avatar_id}"))
+
+    async def wait_until_ready(
+        self, avatar_id: str, *, timeout: float = 600.0, poll_interval: float = 5.0
+    ) -> AvatarInfo:
+        """Poll until the avatar reports ``ready`` (a conversational avatar
+        builds asynchronously; a portrait-only one is ready immediately)."""
+        deadline = asyncio.get_running_loop().time() + timeout
+        while True:
+            info = await self.get_avatar(avatar_id)
+            if info.ready:
+                return info
+            if info.status == "failed":
+                raise AtmeeException(f"avatar {avatar_id} failed to build", code="avatar_failed")
+            if asyncio.get_running_loop().time() >= deadline:
+                raise AtmeeException(
+                    f"avatar {avatar_id} not ready after {timeout:.0f}s (status {info.status})",
+                    code="timeout",
+                )
+            await asyncio.sleep(poll_interval)
+
+    # --- plumbing ------------------------------------------------------------
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is not None and not self._session.closed:
+            return self._session
+        try:
+            self._session = utils.http_context.http_session()
+        except RuntimeError:
+            # Outside a LiveKit job (a script creating avatars, tests): own one.
+            self._session = aiohttp.ClientSession()
+            self._owns_session = True
+        return self._session
+
+    async def aclose(self) -> None:
+        """Close the HTTP session if this client created it."""
+        if self._owns_session and self._session is not None and not self._session.closed:
+            await self._session.close()
+        self._session = None
+        self._owns_session = False
+
+    async def __aenter__(self) -> AtmeeAPI:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: aiohttp.FormData | None = None,
+        params: dict[str, str] | None = None,
+        retry: bool = True,
+        total_timeout: float = _DEFAULT_TOTAL_TIMEOUT,
+    ) -> dict[str, Any]:
+        """One API call with the plugin's retry policy: transport errors and
+        5xx answers are retried ``conn_options.max_retry`` times; a 503
+        ``no_capacity`` and every 4xx are final. ``retry=False`` for calls
+        that are not idempotent (creating a session or an avatar)."""
+        attempts = max(1, self._conn_options.max_retry) if retry else 1
+        last_error: Exception | None = None
+        for attempt in range(attempts):
+            try:
+                async with self._ensure_session().request(
+                    method,
+                    f"{self._api_url}{path}",
+                    headers={"X-Api-Key": self._api_key, "Accept": "application/json"},
+                    json=json,
+                    data=data,
+                    params=params,
+                    timeout=aiohttp.ClientTimeout(
+                        sock_connect=self._conn_options.timeout, total=total_timeout
+                    ),
+                ) as response:
+                    if response.ok:
+                        if response.status == 204 or response.content_length == 0:
+                            return {}
+                        payload = await response.json(content_type=None)
+                        return payload if isinstance(payload, dict) else {"data": payload}
+                    raise await _error_from_response(response)
+            except AtmeeException as e:
+                if e.status_code >= 500 and not isinstance(e, AtmeeNoCapacityError):
+                    last_error = e
+                else:
+                    raise
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                last_error = AtmeeException(f"could not reach the Atmee API: {e}")
+            if attempt < attempts - 1:
+                logger.warning(
+                    "atmee api call failed; retrying",
+                    extra={"path": path, "attempt": attempt + 1, "error": str(last_error)},
+                )
+                await asyncio.sleep(self._conn_options.retry_interval)
+        assert last_error is not None
+        raise last_error
+
+
+async def _error_from_response(response: aiohttp.ClientResponse) -> AtmeeException:
+    text = await response.text()
+    code: str | None = None
+    message = text.strip() or response.reason or f"HTTP {response.status}"
+    try:
+        body = await response.json(content_type=None)
+    except Exception:
+        body = None
+    if isinstance(body, dict):
+        code = body.get("error") if isinstance(body.get("error"), str) else None
+        message = str(body.get("message") or body.get("detail") or message)
+    if response.status == 503 and code in (None, "no_capacity"):
+        retry_after: float | None = None
+        header = response.headers.get("Retry-After")
+        if header:
+            try:
+                retry_after = float(header)
+            except ValueError:
+                retry_after = None
+        return AtmeeNoCapacityError(message, retry_after=retry_after)
+    if response.status == 409 and code == "avatar_not_renderable":
+        return AtmeeAvatarNotReadyError(message, status_code=409, code=code)
+    return AtmeeException(message, status_code=response.status, code=code)
+
+
+def _avatar_info(data: dict[str, Any]) -> AvatarInfo:
+    return AvatarInfo(
+        avatar_id=str(data.get("avatarId") or data.get("id") or ""),
+        status=str(data.get("status", "")),
+        kind=data.get("kind"),
+        name=data.get("name"),
+        raw=data,
+    )
+
+
+def _is_url(value: str) -> bool:
+    return value.startswith(("http://", "https://"))
+
+
+def _load_image_file(image: str | Path, content_type: str | None) -> tuple[bytes, str, str]:
+    path = Path(image)
+    ctype = (
+        content_type
+        or _IMAGE_TYPES.get(path.suffix.lower())
+        or mimetypes.guess_type(path.name)[0]
+        or "application/octet-stream"
+    )
+    return path.read_bytes(), path.name, ctype
+
+
+def _extension_for(content_type: str) -> str:
+    for ext, ctype in _IMAGE_TYPES.items():
+        if ctype == content_type and ext != ".jpeg":
+            return ext
+    return mimetypes.guess_extension(content_type) or ""

livekit/plugins/atmee/avatar.py

@@ -0,0 +1,275 @@
+# Copyright 2026 Atmanity
+#
+# 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 asyncio
+import os
+from datetime import timedelta
+from typing import Any, Literal
+
+import aiohttp
+
+from livekit import api, rtc
+from livekit.agents import (
+    DEFAULT_API_CONNECT_OPTIONS,
+    NOT_GIVEN,
+    AgentSession,
+    APIConnectOptions,
+    NotGivenOr,
+    get_job_context,
+    utils,
+)
+from livekit.agents.voice.avatar import AvatarSession as BaseAvatarSession
+from livekit.agents.voice.avatar import DataStreamAudioOutput
+from livekit.agents.voice.room_io import ATTRIBUTE_PUBLISH_ON_BEHALF
+
+from .api import AtmeeAPI, AtmeeException, AvatarSessionInfo, WaitFor
+from .log import logger
+
+# The rendering worker resamples nothing: it consumes 16 kHz mono PCM over the
+# data stream, so the agent's audio tail is asked for exactly that.
+SAMPLE_RATE = 16000
+_AVATAR_AGENT_IDENTITY = "atmee-avatar-agent"
+_AVATAR_AGENT_NAME = "atmee-avatar-agent"
+# Ceiling of a session when none is given (also the most a session can bill
+# if the agent dies without the worker ever reporting; server default).
+DEFAULT_MAX_DURATION_SECONDS = 3600
+# The avatar's token outlives the session ceiling by this much so a slow start
+# never joins with an expired token.
+_TOKEN_TTL_SLACK = timedelta(minutes=10)
+
+
+class AvatarSession(BaseAvatarSession[Literal["avatar_disconnected"]]):
+    """An Atmee avatar session: render an Atmee avatar into your agent's room.
+
+    The avatar joins the room as its own participant (``atmee-avatar-agent``)
+    publishing on behalf of your agent; your agent's audio output is replaced
+    by a data stream to it, and the avatar publishes synced video and audio.
+    Billing runs while the avatar is in the room and stops when your agent
+    leaves, the room closes, or :meth:`aclose` runs (which also removes the
+    avatar participant); a ceiling of ``max_duration_seconds`` bounds it.
+
+    Emits ``avatar_disconnected`` (the ``rtc.RemoteParticipant``) if the
+    avatar participant leaves the room while the session is still running,
+    for example because its rendering worker died.
+    """
+
+    def __init__(
+        self,
+        *,
+        avatar_id: str,
+        api_url: NotGivenOr[str] = NOT_GIVEN,
+        api_key: NotGivenOr[str] = NOT_GIVEN,
+        avatar_participant_identity: NotGivenOr[str] = NOT_GIVEN,
+        avatar_participant_name: NotGivenOr[str] = NOT_GIVEN,
+        max_duration_seconds: int = DEFAULT_MAX_DURATION_SECONDS,
+        metadata: dict[str, Any] | None = None,
+        wait_for: WaitFor = "initializing",
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+        http_session: aiohttp.ClientSession | None = None,
+    ) -> None:
+        """
+        Args:
+            avatar_id: the Atmee avatar to render (``AtmeeAPI.create_avatar``).
+            api_key: your ``sk_atmee_...`` key; defaults to ``ATMEE_API_KEY``.
+            api_url: API base; defaults to ``ATMEE_API_URL`` or the Atmee cloud.
+            avatar_participant_identity: identity the avatar joins with
+                (``atmee-avatar-agent``). Set it when one room hosts several
+                avatars.
+            max_duration_seconds: hard ceiling of the session (default 3600).
+            metadata: free-form JSON attached to the session on the Atmee side.
+            wait_for: ``"initializing"`` (default) returns from :meth:`start`
+                once the worker acknowledged the start; ``"avatar_joined"``
+                blocks until the avatar is in the room.
+            http_session: an aiohttp session to reuse; the job's shared one by
+                default.
+        """
+        super().__init__()
+        if not avatar_id:
+            raise AtmeeException("avatar_id is required")
+        self._avatar_id = avatar_id
+        self._max_duration_seconds = int(max_duration_seconds)
+        self._metadata = metadata
+        self._wait_for: WaitFor = wait_for
+        self._conn_options = conn_options
+        self._http_session = http_session
+        self._api = AtmeeAPI(
+            api_key=api_key,
+            api_url=api_url,
+            conn_options=conn_options,
+            session=self._ensure_http_session(),
+        )
+
+        self._avatar_participant_identity = avatar_participant_identity or _AVATAR_AGENT_IDENTITY
+        self._avatar_participant_name = avatar_participant_name or _AVATAR_AGENT_NAME
+
+        self.session_id: str | None = None
+        """The Atmee avatar session id once :meth:`start` returned."""
+        self.session_info: AvatarSessionInfo | None = None
+        """The full start response once :meth:`start` returned."""
+
+        self._end_task: asyncio.Task[None] | None = None
+        self._ended = False
+        self._room_for_events: rtc.Room | None = None
+
+    @property
+    def avatar_identity(self) -> str:
+        return self._avatar_participant_identity
+
+    @property
+    def provider(self) -> str:
+        return "atmee"
+
+    @property
+    def api(self) -> AtmeeAPI:
+        """The API client this session uses (same key and base URL)."""
+        return self._api
+
+    def _ensure_http_session(self) -> aiohttp.ClientSession:
+        if self._http_session is None:
+            self._http_session = utils.http_context.http_session()
+        return self._http_session
+
+    async def start(
+        self,
+        agent_session: AgentSession[Any],
+        room: rtc.Room,
+        *,
+        livekit_url: NotGivenOr[str] = NOT_GIVEN,
+        livekit_api_key: NotGivenOr[str] = NOT_GIVEN,
+        livekit_api_secret: NotGivenOr[str] = NOT_GIVEN,
+    ) -> None:
+        """Start rendering the avatar into ``room`` for ``agent_session``.
+
+        Mints a LiveKit access token for the avatar participant with YOUR
+        project's credentials (``LIVEKIT_URL`` / ``LIVEKIT_API_KEY`` /
+        ``LIVEKIT_API_SECRET`` or the arguments), asks Atmee to render into
+        the room, and routes the agent's audio to the avatar. Call before
+        ``agent_session.start``.
+        """
+        await super().start(agent_session, room)
+
+        livekit_url = livekit_url or (os.getenv("LIVEKIT_URL") or NOT_GIVEN)
+        livekit_api_key = livekit_api_key or (os.getenv("LIVEKIT_API_KEY") or NOT_GIVEN)
+        livekit_api_secret = livekit_api_secret or (os.getenv("LIVEKIT_API_SECRET") or NOT_GIVEN)
+        if not livekit_url or not livekit_api_key or not livekit_api_secret:
+            raise AtmeeException(
+                "livekit_url, livekit_api_key, and livekit_api_secret must be set "
+                "by arguments or environment variables"
+            )
+
+        job_ctx = get_job_context(required=False)
+        local_participant_identity = (
+            job_ctx.local_participant_identity
+            if job_ctx is not None
+            else room.local_participant.identity
+        )
+        livekit_token = (
+            api.AccessToken(api_key=livekit_api_key, api_secret=livekit_api_secret)
+            .with_kind("agent")
+            .with_identity(self._avatar_participant_identity)
+            .with_name(self._avatar_participant_name)
+            .with_grants(api.VideoGrants(room_join=True, room=room.name))
+            # allow the avatar to publish audio and video on behalf of your local agent
+            .with_attributes({ATTRIBUTE_PUBLISH_ON_BEHALF: local_participant_identity})
+            .with_ttl(timedelta(seconds=self._max_duration_seconds) + _TOKEN_TTL_SLACK)
+            .to_jwt()
+        )
+
+        logger.debug(
+            "starting atmee avatar session",
+            extra={"avatar_id": self._avatar_id, "room": room.name},
+        )
+        info = await self._api.create_avatar_session(
+            self._avatar_id,
+            livekit_url=livekit_url,
+            livekit_token=livekit_token,
+            agent_identity=local_participant_identity,
+            max_duration_seconds=self._max_duration_seconds,
+            metadata=self._metadata,
+            wait_for=self._wait_for,
+        )
+        self.session_info = info
+        self.session_id = info.session_id
+        logger.info(
+            "atmee avatar session started",
+            extra={
+                "session_id": info.session_id,
+                "status": info.status,
+                "billing_mode": info.billing_mode,
+                "max_duration_seconds": info.max_duration_seconds,
+            },
+        )
+
+        self._room_for_events = room
+        room.on("participant_disconnected", self._on_participant_disconnected)
+
+        agent_session.output.replace_audio_tail(
+            DataStreamAudioOutput(
+                room=room,
+                destination_identity=self._avatar_participant_identity,
+                sample_rate=SAMPLE_RATE,
+                wait_remote_track=rtc.TrackKind.KIND_VIDEO,
+            ),
+        )
+
+    def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
+        if participant.identity != self._avatar_participant_identity or self._ended:
+            return
+        # The avatar left while we are still running: its worker died or was
+        # removed. The worker reports its own end to Atmee; ending here too
+        # closes the gap for a worker that could not (idempotent).
+        logger.warning(
+            "atmee avatar participant left the room",
+            extra={"session_id": self.session_id, "identity": participant.identity},
+        )
+        self.emit("avatar_disconnected", participant)
+        self._schedule_end()
+
+    def _schedule_end(self) -> None:
+        if self._end_task is None or self._end_task.done():
+            self._end_task = asyncio.create_task(self._end_session())
+
+    async def _end_session(self) -> None:
+        """Best-effort ``POST /v1/avatar_sessions/{id}/end`` — once."""
+        if self._ended or not self.session_id:
+            return
+        self._ended = True
+        try:
+            await self._api.end_avatar_session(self.session_id)
+            logger.debug("atmee avatar session ended", extra={"session_id": self.session_id})
+        except Exception as e:  # never let a billing hint break teardown
+            logger.warning(
+                "failed to end atmee avatar session; the worker's own report or the "
+                "session ceiling will settle it",
+                extra={"session_id": self.session_id, "error": str(e)},
+            )
+
+    async def aclose(self) -> None:
+        """End the Atmee session and remove the avatar from the room.
+
+        Registered as a job shutdown callback by :meth:`start`; call it
+        yourself when running outside a job.
+        """
+        if self._room_for_events is not None:
+            self._room_for_events.off("participant_disconnected", self._on_participant_disconnected)
+            self._room_for_events = None
+        if self._end_task is not None and not self._end_task.done():
+            try:
+                await self._end_task
+            except Exception:
+                pass
+        await self._end_session()
+        await super().aclose()

livekit/plugins/atmee/log.py

@@ -0,0 +1,3 @@
+import logging
+
+logger = logging.getLogger("livekit.plugins.atmee")

livekit/plugins/atmee/version.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Atmanity
+#
+# 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.
+
+__version__ = "0.1.0"

livekit_plugins_atmee-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.5
+Name: livekit-plugins-atmee
+Version: 0.1.0
+Summary: LiveKit Agents plugin for Atmee avatars: render a talking-head avatar from a single portrait into your agent's room
+Project-URL: Documentation, https://github.com/Atmanity/atmee_livekit_plugin#readme
+Project-URL: Website, https://atmee.ai
+Project-URL: Source, https://github.com/Atmanity/atmee_livekit_plugin
+Author-email: Atmanity <hello@atmee.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: atmee,audio,avatar,livekit,realtime,video,webrtc
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: livekit-agents<2,>=1.6.8
+Requires-Dist: livekit-api>=1.0
+Description-Content-Type: text/markdown
+
+# Atmee avatar plugin for LiveKit Agents
+
+Bring your own LiveKit voice agent; Atmee renders a talking-head avatar from a
+single portrait into your room and bills per minute. Works like the other
+avatar plugins for [LiveKit Agents](https://docs.livekit.io/agents/): the
+avatar joins your room as its own participant, your agent's speech drives its
+video.
+
+```python
+from livekit.plugins import atmee
+
+avatar_id = await atmee.AtmeeAPI().create_avatar(name="Val", image="portrait.jpg")
+
+avatar = atmee.AvatarSession(avatar_id=avatar_id)   # ATMEE_API_KEY in the environment
+await avatar.start(session, room=ctx.room)
+await session.start(agent=..., room=ctx.room)       # the agent's TTS drives the avatar's video
+```
+
+## Installation
+
+```bash
+pip install livekit-plugins-atmee
+```
+
+Python 3.10+, `livekit-agents` 1.6.8 or newer.
+
+## Prerequisites
+
+- An **Atmee API key** (`sk_atmee_...`) from your Atmee developer settings, in
+  `ATMEE_API_KEY`. Keep it on your agent's side; it never goes to a browser.
+- Your **own LiveKit project** (LiveKit Cloud or self-hosted): `LIVEKIT_URL`,
+  `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` — the same variables your agent
+  already uses. Atmee never sees your LiveKit secret: the plugin mints a token
+  for the avatar participant locally and hands only that token to Atmee.
+
+## Usage
+
+### 1. Create an avatar from a portrait
+
+Once, from a script or your backend (see `examples/create_avatar.py`):
+
+```python
+async with atmee.AtmeeAPI() as api:
+    avatar_id = await api.create_avatar(name="Val", image="portrait.jpg")   # path, bytes, or https URL
+```
+
+A portrait-only avatar is ready immediately. You can also create and manage
+avatars in the Atmee studio; any avatar of your account with a portrait works.
+
+### 2. Render it in your agent
+
+```python
+async def entrypoint(ctx: agents.JobContext):
+    await ctx.connect()
+    session = AgentSession(stt=..., llm=..., tts=..., vad=...)
+
+    avatar = atmee.AvatarSession(avatar_id=os.environ["ATMEE_AVATAR_ID"])
+    await avatar.start(session, room=ctx.room)        # before session.start
+
+    await session.start(agent=MyAgent(), room=ctx.room)
+```
+
+`start()` returns as soon as Atmee's rendering worker acknowledged the start
+(about a second); the avatar's video and audio tracks appear in the room a few
+seconds later, published by the participant `atmee-avatar-agent`. Your agent
+publishes no audio of its own — the avatar speaks for it, lips in sync.
+
+Options on `AvatarSession`:
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `avatar_id` | required | The Atmee avatar to render. |
+| `api_key`, `api_url` | `ATMEE_API_KEY`, `ATMEE_API_URL` | Credentials and API base. |
+| `avatar_participant_identity` | `atmee-avatar-agent` | Identity the avatar joins with; set it when one room hosts several avatars. |
+| `max_duration_seconds` | `3600` | Hard ceiling of the session; also the most it can bill if your agent dies without a trace. |
+| `wait_for` | `"initializing"` | `"avatar_joined"` makes `start()` block until the avatar is in the room. |
+| `metadata` | `None` | Free-form JSON stored with the session on the Atmee side. |
+
+`avatar.session_id` and `avatar.session_info` hold the Atmee session after
+`start()`; `avatar.on("avatar_disconnected", ...)` fires if the avatar
+participant leaves while your agent is still running.
+
+### Lifecycle and billing
+
+Billing starts when the avatar sees your agent in the room and runs by the
+minute. It stops when
+
+- your agent leaves the room or the room closes (the rendering worker notices
+  and reports the end itself — a crashed agent stops being billed within
+  seconds),
+- `aclose()` runs — registered automatically as a job shutdown callback; it
+  ends the session and removes the avatar participant from your room,
+- the rendering worker itself dies or loses contact: it proves it is alive
+  once a minute, and a session silent for a few minutes is closed and billed
+  only up to the last proof,
+- or the session reaches `max_duration_seconds`.
+
+### Errors
+
+All API failures raise `atmee.AtmeeException` with `status_code`, `code`
+(the API's error code, e.g. `insufficient_credits`, `avatar_not_renderable`,
+`missing_publish_on_behalf`) and `message`. Two subclasses are worth
+handling: `AtmeeNoCapacityError` (every rendering worker is busy; check
+`retry_after` and try again later) and `AtmeeAvatarNotReadyError` (the avatar
+has no portrait yet).
+
+## Examples
+
+- [`examples/agent.py`](examples/agent.py) — a Deepgram + OpenAI + Silero agent
+  with an Atmee avatar; run with `python examples/agent.py dev` and open the
+  LiveKit Agents Playground.
+- [`examples/create_avatar.py`](examples/create_avatar.py) — create an avatar
+  from a portrait and print its id.
+- [`tests/test_live_agent.py`](tests/test_live_agent.py) — a manual live
+  smoke test: a real GPT voice agent (OpenAI LLM + TTS, silero VAD) with an
+  Atmee avatar in a real LiveKit room, asserting the avatar joins, publishes
+  video, and that its agent-driven audio flows. Skipped unless
+  `RUN_LIVE_ATMEE_AGENT=1` and the credentials are set:
+
+  ```bash
+  RUN_LIVE_ATMEE_AGENT=1 ATMEE_API_KEY=… ATMEE_AVATAR_ID=… \
+  LIVEKIT_URL=… LIVEKIT_API_KEY=… LIVEKIT_API_SECRET=… OPENAI_API_KEY=… \
+  uv run --group dev --with "livekit-agents[openai,silero]" \
+      pytest tests/test_live_agent.py -m live -s
+  ```
+
+## How it works
+
+```
+your agent (livekit-agents) ── plugin ──► Atmee API        (X-Api-Key, https)
+        │                                     │
+        │  audio over lk.audio_stream          ▼
+        └──────────────► your LiveKit room ◄── Atmee rendering worker
+                                              joins as atmee-avatar-agent,
+                                              publishes video + audio
+```
+
+1. `AvatarSession.start()` mints a LiveKit access token for the avatar
+   participant with **your** LiveKit credentials: identity
+   `atmee-avatar-agent`, `kind: agent`, a `roomJoin` grant for your room,
+   and the attribute `lk.publish_on_behalf` set to your agent's identity.
+   Atmee receives only that token, never your secret.
+2. It calls `POST /v1/avatars/{avatarId}/avatar_sessions` with your LiveKit
+   URL and the token. Atmee reserves a session, starts a rendering worker,
+   and answers as soon as the worker acknowledged the start.
+3. The worker joins your room with the token, waits for your agent, receives
+   its audio over the LiveKit data stream (`lk.audio_stream`, 16 kHz PCM, the
+   standard `DataStreamAudioOutput`), and publishes lip-synced video and
+   audio on behalf of your agent.
+4. When your agent leaves or the room closes, the worker notices from inside
+   the room and reports the end to Atmee, which stops billing. `aclose()`
+   removes the avatar participant and ends the session explicitly as well.
+
+## Development
+
+```bash
+uv venv && uv pip install -e . --group dev
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+Releases are published to PyPI from `v*` tags by `.github/workflows/publish.yml`
+(PyPI trusted publishing).
+
+## License
+
+Apache-2.0.

livekit_plugins_atmee-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+livekit/plugins/atmee/__init__.py,sha256=rsTsuct4riIW7H1Ol05W9RtlTFo2ob5nonw6476L4Ng,1846
+livekit/plugins/atmee/api.py,sha256=JFNUvspvrqK59aMCILIj0_NKOg9-5J9xt3h1fV9wBJM,17358
+livekit/plugins/atmee/avatar.py,sha256=Y6WNpvqGKqNzMiP-ef6gOwZUaS807N5p36U9bDFfjJ0,11456
+livekit/plugins/atmee/log.py,sha256=xg7UdKD7FaYxwL6KOsLGHTE8uxutz8k5Atid-zvwa9A,68
+livekit/plugins/atmee/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+livekit/plugins/atmee/version.py,sha256=Oq2wWv9CnzGmaw5MjGmr-PC4s6VqxCLUhE9wn8oCJ2o,595
+livekit_plugins_atmee-0.1.0.dist-info/METADATA,sha256=N-uatr1VcA5uM-WtqDH59d-vFfidkI9Scj1s7taBmGQ,8400
+livekit_plugins_atmee-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+livekit_plugins_atmee-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+livekit_plugins_atmee-0.1.0.dist-info/RECORD,,

livekit_plugins_atmee-0.1.0.dist-info/WHEEL

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

livekit_plugins_atmee-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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.