bithuman-cli 2.3.0__py3-none-macosx_11_0_arm64.whl

bithuman_cli/__init__.py

@@ -0,0 +1,22 @@
+"""bithuman-cli — the bitHuman command-line tool.
+
+Internal package. Users interact via the `bithuman` console script
+installed by this wheel:
+
+    bithuman run model.imx        # live avatar
+    bithuman render -a in.wav -o out.mp4
+    bithuman doctor
+
+Programmatic invocation is also supported:
+
+    python -m bithuman_cli  # equivalent to running `bithuman`
+
+For embedding the bitHuman runtime in a Python application, use the
+bitHuman SDK directly (this wheel depends on it):
+
+    from bithuman import AsyncBithuman
+"""
+from __future__ import annotations
+
+# Keep aligned with cpp/bindings/python-cli/pyproject.toml.
+__version__ = "2.3.0"

bithuman_cli/__main__.py

@@ -0,0 +1,12 @@
+"""bithuman-cli module entry: `python -m bithuman_cli <command>`.
+
+Equivalent to running the `bithuman` console script installed by this
+wheel — both call `bithuman_cli._entry:main`, which locates the
+bundled Rust binary at `bithuman_cli/_bin/bithuman` and `execvpe`s
+into it.
+"""
+import sys
+
+from ._entry import main
+
+sys.exit(main())

bithuman_cli/_avatar_bridge.py

@@ -0,0 +1,250 @@
+"""Inline LiveKit avatar bridge — replaces `livekit-plugins-bithuman`.
+
+WHY THIS EXISTS
+---------------
+Upstream `livekit-plugins-bithuman` pins `bithuman<1.12`, which blocks
+installs of our 2.x SDK wheel. Until the upstream pin relaxes (or our
+PR lands on PyPI), `pip install bithuman-cli` would fail to resolve.
+
+Rather than wait, we re-implement the small slice of `AvatarSession`
+that the CLI actually uses — the *cloud* / remote-serve path — directly
+on top of livekit-agents primitives. This drops a transitive dependency
+chain (`bithuman-cli → livekit-plugins-bithuman → bithuman<1.12`) and
+makes `pip install bithuman-cli` resolve cleanly on its own.
+
+SCOPE — only what `bithuman_cli.agent` calls:
+    avatar = AvatarSession(
+        api_url=f"{serve_url}/launch",
+        api_secret=...,
+        avatar_id=...,
+        model="essence",
+    )
+    await avatar.start(session, room=ctx.room)
+
+We do NOT reimplement:
+  * Local in-process runtime (`model_path`/`runtime` kwargs) — `agent.py`
+    has its own `BITHUMAN_LOCAL_AVATAR` branch.
+  * Custom avatar images (`avatar_image=`) — CLI never sets these.
+  * The multipart/form-data path for `auth.api.bithuman.ai` / expression
+    workers — CLI only talks to `bithuman serve`'s `/launch` JSON endpoint.
+  * `BithumanGenerator` / `VideoGenerator` — used only by the local path.
+
+SUNSET PATH
+-----------
+When upstream relaxes its `bithuman<1.12` pin (tracked in pyproject.toml),
+delete this file and switch `agent.py` back to:
+
+    from livekit.plugins import bithuman as lk_bh
+    avatar = lk_bh.AvatarSession(...)
+
+The protocol is identical (this file is a literal extract), so the swap
+is mechanical and behaviour-preserving.
+
+Apache-2.0; (c) bitHuman.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Optional
+
+import aiohttp
+from livekit import api, rtc
+from livekit.agents import (
+    DEFAULT_API_CONNECT_OPTIONS,
+    APIConnectionError,
+    APIConnectOptions,
+    APIStatusError,
+    get_job_context,
+    utils,
+)
+from livekit.agents.types import ATTRIBUTE_PUBLISH_ON_BEHALF
+from livekit.agents.voice import AgentSession
+from livekit.agents.voice.avatar import (
+    AvatarSession as BaseAvatarSession,
+    DataStreamAudioOutput,
+)
+
+logger = logging.getLogger("bithuman_cli.avatar")
+
+
+_AVATAR_AGENT_IDENTITY = "bithuman-avatar-agent"
+_AVATAR_AGENT_NAME = "bithuman-avatar-agent"
+
+
+class BitHumanException(Exception):
+    """Raised by the inline avatar bridge for misconfiguration or launch errors."""
+
+
+class AvatarSession(BaseAvatarSession):
+    """Drop-in replacement for `livekit.plugins.bithuman.AvatarSession`,
+    cloud-mode only.
+
+    POSTs an avatar-launch request to ``api_url`` (i.e.
+    ``<bithuman-serve>/launch``), then routes the agent's TTS audio to the
+    spawned avatar participant via livekit-agents' ``DataStreamAudioOutput``.
+    The serve process publishes the rendered video track into the room
+    on the avatar participant's behalf.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_url: str,
+        api_secret: str,
+        avatar_id: str,
+        model: str = "essence",
+        conn_options: APIConnectOptions = DEFAULT_API_CONNECT_OPTIONS,
+        avatar_participant_identity: Optional[str] = None,
+        avatar_participant_name: Optional[str] = None,
+    ) -> None:
+        super().__init__()
+        if not api_url:
+            raise BitHumanException("api_url is required")
+        if not api_secret:
+            raise BitHumanException("api_secret is required")
+        if not avatar_id:
+            raise BitHumanException("avatar_id is required")
+
+        self._api_url = api_url
+        self._api_secret = api_secret
+        self._avatar_id = avatar_id
+        self._model = model
+        self._conn_options = conn_options
+        self._avatar_participant_identity = (
+            avatar_participant_identity or _AVATAR_AGENT_IDENTITY
+        )
+        self._avatar_participant_name = (
+            avatar_participant_name or _AVATAR_AGENT_NAME
+        )
+        self._http_session: Optional[aiohttp.ClientSession] = None
+
+    @property
+    def avatar_identity(self) -> str:
+        return self._avatar_participant_identity
+
+    @property
+    def provider(self) -> str:
+        return "bithuman"
+
+    async def start(
+        self,
+        agent_session: AgentSession,
+        room: rtc.Room,
+        *,
+        livekit_url: Optional[str] = None,
+        livekit_api_key: Optional[str] = None,
+        livekit_api_secret: Optional[str] = None,
+    ) -> None:
+        # Base class: registers shutdown callback, starts the
+        # wait-for-avatar-join task, wires conversation_item_added.
+        await super().start(agent_session, room)
+
+        livekit_url = livekit_url or os.getenv("LIVEKIT_URL")
+        livekit_api_key = livekit_api_key or os.getenv("LIVEKIT_API_KEY")
+        livekit_api_secret = livekit_api_secret or os.getenv("LIVEKIT_API_SECRET")
+        if not livekit_url or not livekit_api_key or not livekit_api_secret:
+            raise BitHumanException(
+                "livekit_url, livekit_api_key, and livekit_api_secret must be "
+                "set by arguments or environment variables"
+            )
+
+        # Mint a JWT for the avatar participant. The
+        # ATTRIBUTE_PUBLISH_ON_BEHALF attribute lets serve publish video
+        # tracks attributed to our local agent participant.
+        job_ctx = get_job_context()
+        local_participant_identity = job_ctx.local_participant_identity
+
+        attributes: dict[str, str] = {
+            ATTRIBUTE_PUBLISH_ON_BEHALF: local_participant_identity,
+            "api_secret": self._api_secret,
+            "agent_id": self._avatar_id,
+        }
+
+        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))
+            .with_attributes(attributes)
+            .to_jwt()
+        )
+
+        logger.debug("starting avatar session")
+        await self._launch(livekit_url, livekit_token, room.name)
+
+        # Route agent TTS into the avatar over the LiveKit data stream.
+        # The avatar reads this audio and renders matching lipsync video.
+        agent_session.output.audio = DataStreamAudioOutput(
+            room=room,
+            destination_identity=self._avatar_participant_identity,
+            wait_playback_start=False,
+        )
+
+    async def _launch(
+        self, livekit_url: str, livekit_token: str, room_name: str
+    ) -> None:
+        """POST the avatar-launch request to ``api_url`` (bithuman-serve's
+        ``/launch``) using the JSON format expected by serve.
+
+        The CLI always talks to a custom self-hosted serve endpoint —
+        never the default ``auth.api.bithuman.ai`` BitHuman cloud — but
+        serve consumes the same JSON shape as the upstream plugin's
+        default-API path (``mode: cpu`` + ``agent_id`` + ``api-secret``
+        header). No multipart/form-data path needed.
+        """
+        json_data = {
+            "livekit_url": livekit_url,
+            "livekit_token": livekit_token,
+            "room_name": room_name,
+            "mode": "cpu" if self._model == "essence" else "gpu",
+            "agent_id": self._avatar_id,
+        }
+        headers = {
+            "Content-Type": "application/json",
+            "api-secret": self._api_secret,
+        }
+
+        last_err: Optional[Exception] = None
+        for i in range(self._conn_options.max_retry):
+            try:
+                async with self._ensure_http_session().post(
+                    self._api_url,
+                    headers=headers,
+                    json=json_data,
+                    timeout=aiohttp.ClientTimeout(
+                        sock_connect=self._conn_options.timeout
+                    ),
+                ) as response:
+                    if not response.ok:
+                        text = await response.text()
+                        raise APIStatusError(
+                            "Server returned an error",
+                            status_code=response.status,
+                            body=text,
+                        )
+                    return
+            except Exception as e:
+                last_err = e
+                if isinstance(e, APIConnectionError):
+                    logger.warning(
+                        "failed to call bithuman avatar api",
+                        extra={"error": str(e)},
+                    )
+                else:
+                    logger.exception("failed to call bithuman avatar api")
+                if i < self._conn_options.max_retry - 1:
+                    await asyncio.sleep(self._conn_options.retry_interval)
+
+        raise APIConnectionError(
+            f"Failed to start Bithuman Avatar Session after "
+            f"{self._conn_options.max_retry} retries: {last_err}"
+        )
+
+    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

bithuman_cli/_entry.py

@@ -0,0 +1,112 @@
+"""Python entry shim for the bundled `bithuman` Rust CLI.
+
+The wheel ships the Rust binary at `bithuman_cli/_bin/bithuman`
+(per-platform; vendored dylibs sit beside it). This shim is the
+`bithuman` console-script entry point — it locates the binary, sets
+up the env so the embedded conversation agent finds the wheel's Python
+interpreter + bundled `agent.py`, and `execvpe`s into the binary so signal
+handling + tty interaction behave exactly as if the user had invoked
+the Rust binary directly.
+
+Why a shim at all (vs. exposing the binary directly under
+`venv/bin/bithuman`):
+    - The Rust binary discovers Python via `BITHUMAN_AGENT_PYTHON` env
+      (`BITHUMAN_BRAIN_PYTHON` is honored as a deprecated alias for one
+      release). A shim is the cleanest place to point that at
+      `sys.executable` (the venv's own python) without depending on PATH
+      ordering.
+    - It also lets the wheel attach a clear error when the binary
+      slot is empty (e.g. a sdist install or an unsupported platform).
+
+Phase B split (2026-05-28): this file used to live at `bithuman/_cli.py`
+inside the unified `bithuman` wheel. The CLI was extracted into its
+own `bithuman-cli` PyPI wheel; the file is now `bithuman_cli/_entry.py`.
+The `BITHUMAN_WHEEL_VERSION` env that the Rust binary surfaces in
+`bithuman --version` / `bithuman doctor` now reports the `bithuman-cli`
+wheel version (was `bithuman` pre-split).
+
+Apache-2.0; (c) bitHuman.
+"""
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from pathlib import Path
+
+
+_PKG_DIR = Path(__file__).resolve().parent
+_BIN_DIR = _PKG_DIR / "_bin"
+
+
+def _binary_name() -> str:
+    return "bithuman.exe" if platform.system() == "Windows" else "bithuman"
+
+
+def _binary_path() -> Path:
+    return _BIN_DIR / _binary_name()
+
+
+def _missing_binary_message() -> str:
+    triple = f"{platform.system()}-{platform.machine()}".lower()
+    return (
+        f"bithuman: the bundled CLI binary is missing for this platform "
+        f"({triple}).\n"
+        f"  Expected at: {_binary_path()}\n"
+        "\n"
+        "  This usually means you installed an sdist or a wheel built\n"
+        "  for a different OS/arch. Reinstall with:\n"
+        "      pip install --upgrade --force-reinstall bithuman-cli\n"
+        "\n"
+        "  If your platform isn't covered by an upstream wheel yet, see:\n"
+        "      https://github.com/bithuman-product/bithuman-sdk/issues\n"
+    )
+
+
+def main() -> int:
+    binary = _binary_path()
+    if not binary.is_file():
+        sys.stderr.write(_missing_binary_message())
+        return 64  # EX_USAGE
+
+    # Point the Rust binary's agent discovery at this wheel's Python
+    # (the venv that pip-installed us) so the embedded `agent.py`
+    # picks up all the dependencies (livekit-agents[openai],
+    # livekit-plugins-bithuman, aiohttp) declared as required wheel deps.
+    # Set BOTH the new (`BITHUMAN_AGENT_*`) and the deprecated
+    # (`BITHUMAN_BRAIN_*`) names so an old Rust binary in a mixed install
+    # still picks them up; the Rust side prefers the new names.
+    env = os.environ.copy()
+    env.setdefault("BITHUMAN_AGENT_PYTHON", sys.executable)
+    env.setdefault("BITHUMAN_BRAIN_PYTHON", sys.executable)
+    agent_script = _PKG_DIR / "agent.py"
+    if agent_script.is_file():
+        env.setdefault("BITHUMAN_AGENT_SCRIPT", str(agent_script))
+        env.setdefault("BITHUMAN_BRAIN_SCRIPT", str(agent_script))
+
+    # Expose the pip wheel version to the Rust binary so `bithuman doctor`
+    # and `bithuman --version` can show the PyPI package version
+    # alongside the libessence engine. Use importlib.metadata as the
+    # source of truth (always matches the actual installed wheel).
+    # Phase B split: this is the `bithuman-cli` wheel; the user-visible
+    # version shown by `bithuman --version` is the CLI wheel's version
+    # (was `bithuman` pre-split — same value when they release in
+    # lockstep, but conceptually it's the CLI version now).
+    try:
+        from importlib.metadata import version as _pkg_version
+        env.setdefault("BITHUMAN_WHEEL_VERSION", _pkg_version("bithuman-cli"))
+    except Exception:
+        pass
+
+    argv = [str(binary), *sys.argv[1:]]
+    # execvpe replaces the current process — the Rust binary inherits
+    # the tty + signal handlers cleanly. On Windows there's no execve
+    # equivalent; we'd subprocess.run() + sys.exit() instead, but Phase
+    # 4 ships macOS arm64 + Linux first, so we punt on that branch.
+    os.execvpe(str(binary), argv, env)
+    # Unreachable; execvpe never returns on success.
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())