pipecat-spatialreal 0.1.0__tar.gz

pipecat_spatialreal-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,102 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    # A run takes about two minutes; a hung one is cut off here instead of at GitHub's six hours.
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        # 3.11 is the floor (pipecat-ai >= 1.0 requires it); 3.12 is what the codegen workflow runs.
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # tests/probe_check.mjs runs the probe page's analysis under Node, so the test that calls it
+      # needs one; the runner image's own Node is not something to count on.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+
+      # The example extra brings FastAPI and the Pipecat runner, which the token-route tests of
+      # examples/bot.py import: without it they are skipped.
+      - name: Install (dev and example extras)
+        run: uv sync --extra dev --extra example
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest
+
+      - name: Build
+        run: uv build
+
+  # The test job resolves the newest versions on every run. This one resolves the lowest that
+  # pyproject.toml declares for every direct dependency, so that the floors users can install
+  # (pipecat-ai, spatialreal and protobuf above all) stay tested once newer releases come out.
+  floors:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      # For every uv command of the job: `uv run` locks and syncs again before it runs, and with
+      # the default resolution it would bring the newest versions back.
+      UV_RESOLUTION: lowest-direct
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+
+      - name: Install the lowest declared versions (dev and example extras)
+        run: uv sync --resolution lowest-direct --extra dev --extra example
+
+      # The resolver moves past a floor that cannot be installed (one that conflicts with another
+      # requirement, say) without a word. Fail instead, so that such a floor is raised on purpose.
+      - name: Check that every runtime floor is what got installed
+        run: |
+          uv run python - <<'EOF'
+          import importlib.metadata
+          import tomllib
+
+          from packaging.requirements import Requirement
+          from packaging.version import Version
+
+          with open("pyproject.toml", "rb") as file:
+              dependencies = tomllib.load(file)["project"]["dependencies"]
+          wrong = []
+          for line in dependencies:
+              requirement = Requirement(line)
+              floors = [spec.version for spec in requirement.specifier if spec.operator == ">="]
+              installed = importlib.metadata.version(requirement.name)
+              print(f"{requirement.name}: declared {requirement.specifier}, installed {installed}")
+              if floors and Version(installed) != Version(floors[0]):
+                  wrong.append(requirement.name)
+          if wrong:
+              raise SystemExit(f"Not installed at the declared floor: {', '.join(wrong)}")
+          EOF
+
+      - name: Test
+        run: uv run pytest

pipecat_spatialreal-0.1.0/.github/workflows/compat.yml

@@ -0,0 +1,130 @@
+name: Pipecat compatibility
+
+# Once a week, runs the tests against the newest pipecat-ai that pyproject.toml allows, to learn
+# early when a Pipecat release breaks this package.
+#
+# When the tests fail, the job fails and the run is the report: nothing is changed. When they pass
+# on a release newer than the one the README says the package was tested with ("Tested with Pipecat
+# vX.Y.Z"), a second job opens a pull request that moves that line.
+#
+# The two jobs are kept apart because the first runs freshly resolved third-party code (the newest
+# Pipecat and whatever it pulls in). It holds a read-only token and nothing else; its checkout does
+# not keep even that. The second holds the write token and runs no dependency code: it checks out
+# the repository without keeping the token, edits one line of the README itself, and the pull
+# request can carry README.md and nothing else.
+#
+# The pull request is opened with the workflow's own token, so GitHub starts no other workflow on
+# it. The repository setting "Allow GitHub Actions to create and approve pull requests" must be on.
+#
+# workflow_dispatch only finds workflows that are on the default branch.
+
+on:
+  schedule:
+    - cron: "23 6 * * 1" # Mondays, 06:23 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    # A run takes a few minutes; a hung one is cut off here instead of at GitHub's six hours.
+    timeout-minutes: 15
+    # The job's token, which setup-uv also receives by default (its github-token input), can only
+    # read.
+    permissions:
+      contents: read
+    outputs:
+      installed: ${{ steps.version.outputs.installed }}
+      bump: ${{ steps.version.outputs.bump }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+
+      # tests/probe_check.mjs runs the probe page's analysis under Node.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+
+      # Libraries resolve fresh here (uv.lock is not committed), and --upgrade-package makes the
+      # newest pipecat-ai win even when a lock file has been restored from somewhere. Resolving
+      # again, rather than upgrading the installed package alone, keeps the dependencies of the
+      # extras in step with the new release.
+      - name: Install the newest Pipecat that pyproject.toml allows
+        run: uv sync --extra dev --extra example --upgrade-package pipecat-ai
+
+      # The suite includes tests/test_rtvi_smoke.py, which sends the avatar messages through RTVI
+      # and Pipecat's eval transport.
+      - name: Test
+        run: uv run pytest -q
+
+      - name: Compare with the README
+        id: version
+        run: |
+          installed="$(uv run python -c 'import importlib.metadata as m; print(m.version("pipecat-ai"))')"
+          stated="$(grep -oE 'Tested with Pipecat v[0-9]+(\.[0-9]+)*' README.md | head -n 1 | sed 's/^.* v//')"
+          if [ -z "$stated" ]; then
+            echo "README.md has no 'Tested with Pipecat vX.Y.Z' line" >&2
+            exit 1
+          fi
+          echo "The README says v${stated}; the tests passed on v${installed}."
+          newest="$(printf '%s\n%s\n' "$stated" "$installed" | sort -V | tail -n 1)"
+          {
+            echo "installed=${installed}"
+            if [ "$installed" != "$stated" ] && [ "$newest" = "$installed" ]; then
+              echo "bump=true"
+            else
+              echo "bump=false"
+            fi
+          } >> "$GITHUB_OUTPUT"
+
+  pr:
+    needs: check
+    if: needs.check.outputs.bump == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      # The version comes from the job that ran third-party code, so it is checked before it is
+      # used anywhere, and it goes through env, not into the script text.
+      - name: Move the README to the tested version
+        env:
+          INSTALLED: ${{ needs.check.outputs.installed }}
+        run: |
+          if ! [[ "$INSTALLED" =~ ^[0-9]+(\.[0-9]+)*$ ]]; then
+            echo "Not a release version: '${INSTALLED}'" >&2
+            exit 1
+          fi
+          sed -E "s/Tested with Pipecat v[0-9]+(\.[0-9]+)*/Tested with Pipecat v${INSTALLED}/" README.md > README.md.new
+          mv README.md.new README.md
+          git diff --stat
+
+      - name: Open a pull request
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ github.token }}
+          # Only the README goes into the pull request, whatever else is in the working tree.
+          add-paths: README.md
+          branch: compat/pipecat-${{ needs.check.outputs.installed }}
+          delete-branch: true
+          commit-message: "docs: tested with Pipecat v${{ needs.check.outputs.installed }}"
+          title: "docs: tested with Pipecat v${{ needs.check.outputs.installed }}"
+          body: |
+            The weekly compatibility check ran the tests against pipecat-ai
+            ${{ needs.check.outputs.installed }} and they passed, so the README now says the
+            package was tested with it.
+
+            Nothing else changed. The check does not raise the `pipecat-ai` floor in
+            `pyproject.toml`.

pipecat_spatialreal-0.1.0/.github/workflows/protobuf-codegen.yml

@@ -0,0 +1,202 @@
+name: Protobuf Codegen
+
+# Regenerates src/pipecat_spatialreal/proto/generated/ and commits it once the gates pass.
+#
+# Trigger: shared-proto's tag CI dispatches this workflow; it can also be run by hand here.
+# Pushes and PRs do not trigger it: the contract is released only when shared-proto is tagged.
+# workflow_dispatch only finds workflows that are on the default branch.
+#
+# Auth: the org GitHub App `spatialreal-codegen` (secrets CODEGEN_APP_ID /
+# CODEGEN_APP_PRIVATE_KEY), not a personal token. The App installation must include this repo and
+# shared-proto.
+#
+# The App can reach every repository of its installation, so neither its key nor a token of its own
+# is ever in a job that runs third-party code. A job is the unit that matters: GitHub gives a job
+# every secret it names when the job starts. Three jobs, in order:
+#
+#   contract  reads the contract from shared-proto with a token that can only read that repository,
+#             and hands pipecat/v1/avatar.proto on. It runs GitHub's own actions and git, nothing
+#             else.
+#   generate  installs the dev extra (freshly resolved third-party packages), generates the code and
+#             runs the gates. It names no secret, holds a read-only token and keeps none of it in
+#             the checkout, and hands the two generated files on.
+#   publish   takes exactly those two files, and only then mints a token that can only write this
+#             repository, used by the push alone. It runs no dependency code.
+
+on:
+  workflow_dispatch:
+    inputs:
+      shared_proto_ref:
+        description: shared-proto ref (tag / branch / sha)
+        type: string
+        required: false
+        default: main
+
+permissions:
+  contents: read
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      short_sha: ${{ steps.ref.outputs.short_sha }}
+    steps:
+      - name: Mint a token that can only read shared-proto
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.CODEGEN_APP_ID }}
+          private-key: ${{ secrets.CODEGEN_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: shared-proto
+          permission-contents: read
+
+      - name: Checkout shared-proto
+        uses: actions/checkout@v5
+        with:
+          repository: SpatialReal-ai/shared-proto
+          ref: ${{ inputs.shared_proto_ref || 'main' }}
+          token: ${{ steps.app-token.outputs.token }}
+          persist-credentials: false
+          path: proto-src
+
+      - name: Record the commit
+        id: ref
+        run: echo "short_sha=$(git -C proto-src rev-parse --short HEAD)" >> "$GITHUB_OUTPUT"
+
+      # Only the file this package is generated from: the rest of shared-proto stays out of the job
+      # that runs third-party code. Should avatar.proto ever import another file, protoc names it
+      # and it is added here.
+      - uses: actions/upload-artifact@v7
+        with:
+          name: contract
+          path: proto-src/pipecat/v1/avatar.proto
+          if-no-files-found: error
+          retention-days: 1
+
+  generate:
+    needs: contract
+    runs-on: ubuntu-latest
+    # A run takes a few minutes; a hung one is cut off here instead of at GitHub's six hours.
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: contract
+          path: proto-src/pipecat/v1
+
+      # No pip cache: what a third-party package left in it would come back in later runs.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # tests/probe_check.mjs runs the probe page's analysis under Node.
+      - uses: actions/setup-node@v7
+        with:
+          node-version: lts/*
+
+      # grpcio-tools is pinned in the dev extra: it decides the gencode protobuf version, which
+      # must stay <= the `protobuf>=` floor in pyproject.toml, or an older runtime refuses to
+      # import the generated code. Bump the pin together with that floor.
+      - name: Install (dev extra)
+        run: python -m pip install -e ".[dev]"
+
+      - name: Generate
+        run: |
+          out="$(mktemp -d)"
+          gen=src/pipecat_spatialreal/proto/generated
+          python -m grpc_tools.protoc -I proto-src \
+            --python_out="$out" --pyi_out="$out" pipecat/v1/avatar.proto
+          rm -f "$gen/avatar_pb2.py" "$gen/avatar_pb2.pyi"
+          mv "$out/pipecat/v1/avatar_pb2.py" "$out/pipecat/v1/avatar_pb2.pyi" "$gen/"
+          rm -rf proto-src "$out"
+          git status --short "$gen"
+
+      # Gate: the package still imports (the generated module loads against the installed protobuf
+      # runtime) and the tests pass. A failure usually means plugin code relies on something the
+      # generated code no longer has — fix that first, then re-run.
+      - name: Gate — import smoke test
+        run: python -c "import pipecat_spatialreal"
+
+      - name: Gate — unit tests
+        run: python -m pytest tests -q
+
+      # The contract lives in shared-proto; this repo holds generated code only.
+      - name: Gate — generated code only
+        run: |
+          if git ls-files --others --cached --exclude-standard '*.proto' | grep .; then
+            echo "Only generated code is committed here." >&2
+            exit 1
+          fi
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: generated
+          path: |
+            src/pipecat_spatialreal/proto/generated/avatar_pb2.py
+            src/pipecat_spatialreal/proto/generated/avatar_pb2.pyi
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    needs: [contract, generate]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: generated
+          path: ${{ runner.temp }}/generated
+
+      # The two generated files by name, whatever else the artifact might hold.
+      - name: Take the generated code
+        id: take
+        run: |
+          gen=src/pipecat_spatialreal/proto/generated
+          cp "$RUNNER_TEMP/generated/avatar_pb2.py" "$RUNNER_TEMP/generated/avatar_pb2.pyi" "$gen/"
+          git status --short
+          if git diff --quiet; then
+            echo "No changes."
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Minted last, and with no owner given, for this repository alone.
+      - name: Mint a token that can only write this repository
+        if: steps.take.outputs.changed == 'true'
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.CODEGEN_APP_ID }}
+          private-key: ${{ secrets.CODEGEN_APP_PRIVATE_KEY }}
+          permission-contents: write
+
+      # The ref goes through env, not into the script text: a tag name is not trusted input. The
+      # token reaches git through a credential helper for this one push: it is never written to the
+      # git config and never appears on a command line.
+      - name: Commit and push
+        if: steps.take.outputs.changed == 'true'
+        env:
+          SHARED_PROTO_REF: ${{ inputs.shared_proto_ref || 'main' }}
+          SHORT_SHA: ${{ needs.contract.outputs.short_sha }}
+          PUSH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add src/pipecat_spatialreal/proto/generated/avatar_pb2.py \
+            src/pipecat_spatialreal/proto/generated/avatar_pb2.pyi
+          git commit -m "chore(proto): regenerate from shared-proto@${SHARED_PROTO_REF} (${SHORT_SHA})"
+          # shellcheck disable=SC2016 # the helper's shell expands $1 and $PUSH_TOKEN, not this one
+          git -c credential.helper= \
+            -c 'credential.helper=!f() { test "$1" = get && printf "username=x-access-token\npassword=%s\n" "$PUSH_TOKEN"; }; f' \
+            push

pipecat_spatialreal-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,75 @@
+name: Release
+
+# Publishing a GitHub Release triggers this; pushing the tag alone does not. `published` is the
+# type that fires for a release made in the GitHub UI (`created` is skipped for a draft that is
+# published later). Publishing uses PyPI trusted publishing (OIDC), so there is no API token:
+# PyPI holds a publisher for SpatialReal-ai/pipecat-spatialreal, workflow `release.yml`,
+# environment `pypi`. Those three must stay as they are, or the upload is refused.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.11"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      # The release tag names the version PyPI will show forever; refuse a tag that does not
+      # match the version the package was built with (src/pipecat_spatialreal/version.py).
+      - name: Check the release tag against the built version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          for whl in dist/*.whl; do
+            built=$(basename "$whl" | sed -E 's/^pipecat_spatialreal-([^-]+)-.*/\1/')
+          done
+          echo "tag=$TAG built=$built"
+          test "$TAG" = "v$built" || { echo "release tag $TAG does not match the built version $built"; exit 1; }
+
+      # The generated protobuf module is what a broken build drops silently, and the package
+      # imports it at load time. Install the built wheel, not the source tree, into a fresh
+      # environment and import it from outside the checkout.
+      - name: Smoke-test the built wheel in a fresh environment
+        run: |
+          uv venv "$RUNNER_TEMP/wheel-venv"
+          uv pip install --python "$RUNNER_TEMP/wheel-venv/bin/python" dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/wheel-venv/bin/python" -c "import pipecat_spatialreal, pipecat_spatialreal.proto.generated.avatar_pb2; print(pipecat_spatialreal.__file__)"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      # id-token for PyPI trusted publishing; contents because naming any permission drops the
+      # defaults for the rest.
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pipecat_spatialreal-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+.venv/
+__pycache__/
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+.env
+
+# Libraries resolve fresh in CI (see ci.yml) instead of pinning through a lock file.
+uv.lock
+
+# The contract lives in shared-proto; this repo holds generated code only. The codegen
+# workflow refuses any committed .proto, this keeps one from being added by accident.
+*.proto
+
+# hack/sync-sim/thrsearch_stall.py's data cache, if one is pointed into the repo.
+hack/sync-sim/*.pkl

pipecat_spatialreal-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

pipecat_spatialreal-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-11-09
+
+First release. Tested with Pipecat v1.15.0, the SpatialReal Python SDK 0.3.0 and the SpatialReal
+web SDK 1.0.0-beta.6, on Daily and LiveKit.
+
+### Added
+
+- `SpatialRealAvatarProcessor`: place it right after the TTS service. It streams the bot's speech
+  to SpatialReal for facial animation, sends the animation to the browser as RTVI server messages,
+  and releases the audio in step with it. The SpatialReal web SDK (1.0.0-beta.6 or newer) renders
+  the avatar in the browser, so the pipeline carries no video.
+- Audio and animation stay in sync: the web SDK lines the animation up with the audio the browser
+  actually receives.
+- Interruptions stop the avatar together with the voice. If SpatialReal cannot be reached, the bot
+  keeps talking without animation and the processor reconnects.
+- Works with Pipecat's Daily and LiveKit transports.
+- An example bot (`examples/bot.py`) and web page (`examples/client`). The bot gives the browser a
+  short-lived session token, so the API key stays on the server.