Make every example a uv workspace member

.github/pin_example_to_ref.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Pin an example's in-repo dependencies to a git ref, in place.
+
+An example resolves its livekit-* dependencies through the workspace root's
+``[tool.uv.sources]``, which only applies inside this repo. A deploy build
+context is the example directory alone, so appending a git source for every
+in-repo dependency is what builds the image against this checkout's code
+instead of the latest release on PyPI.
+
+    python .github/pin_example_to_ref.py examples/hotel_receptionist --ref main
+
+Needs Python 3.11+ for tomllib.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+import tomllib
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+REPO = "https://github.com/livekit/agents.git"
+
+# The distribution name at the start of a requirement, e.g. "livekit-agents[mcp]>=1.6".
+# Extras stay on the dependency itself; a source is keyed by name alone.
+REQUIREMENT = re.compile(r"^(?P<name>[A-Za-z0-9._-]+)")
+
+
+def monorepo_path(name: str) -> str | None:
+    """Path of ``name`` within this repo, or None if it lives elsewhere.
+
+    Only packages that actually exist in the checkout are pinned. The directory
+    basename is the distribution name for every package here (livekit-agents at
+    the root, everything else under livekit-plugins/). Anything not found
+    (livekit rtc, livekit-blingfire, livekit-local-inference, …) keeps its PyPI
+    specifier.
+    """
+    for rel in (name, f"livekit-plugins/{name}"):
+        if (REPO_ROOT / rel).is_dir():
+            return rel
+    return None
+
+
+def git_sources(dependencies: list[str], ref: str) -> str:
+    lines = [
+        "",
+        "# Written by .github/pin_example_to_ref.py for a deploy: the build context is",
+        "# this directory alone, so the in-repo dependencies come from the git ref being",
+        f"# deployed ({ref}) rather than from PyPI.",
+        "[tool.uv.sources]",
+    ]
+    for dep in dependencies:
+        match = REQUIREMENT.match(dep)
+        if match is None:
+            continue
+        path = monorepo_path(match["name"])
+        if path is None:
+            continue
+        lines.append(
+            f'{match["name"]} = {{ git = "{REPO}", rev = "{ref}", subdirectory = "{path}" }}'
+        )
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("example", type=Path, help="path to the example directory")
+    parser.add_argument(
+        "--ref",
+        required=True,
+        help="git ref in-repo dependencies are pinned to (branch, tag or sha)",
+    )
+    args = parser.parse_args()
+
+    pyproject = args.example / "pyproject.toml"
+    contents = pyproject.read_text()
+    parsed = tomllib.loads(contents)
+    if "sources" in parsed.get("tool", {}).get("uv", {}):
+        parser.error(f"{pyproject} already declares [tool.uv.sources]")
+
+    sources = git_sources(parsed["project"]["dependencies"], args.ref)
+    pyproject.write_text(contents + sources)
+    print(f"--- {pyproject} pinned to {args.ref} ---")
+    print(sources, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/deploy-examples.yml

@@ -30,7 +30,7 @@ jobs:
           # Fetch Git-LFS assets (e.g. examples/drive-thru/bg_noise.mp3) so the
           # real binaries — not pointer files — get uploaded as the build context
           # and copied into the image via `COPY . .`. This checkout authenticates
-          # with GITHUB_TOKEN, so its LFS fetch is allowed (unlike pip's anonymous
+          # with GITHUB_TOKEN, so its LFS fetch is allowed (unlike uv's anonymous
           # git clone). Without this the agent crashes at runtime decoding a
           # 131-byte pointer as audio.
           lfs: true
@@ -73,62 +73,17 @@ jobs:
           print(f"wrote examples/{slug}/livekit.toml")
           PY
 
-      - name: Pin livekit-* requirements to the deployed ref
-        working-directory: examples/${{ matrix.example }}
+      - name: Pin in-repo dependencies to the deployed ref
         env:
           # Build the agent against the code at the ref we're deploying,
           # not the latest release on PyPI. Without this, a branch deploy
           # would silently run against the published livekit-agents instead
           # of the branch's own SDK changes. Mirror the checkout ref above,
-          # using ref_name so it's a plain branch/tag pip can resolve.
+          # using ref_name so it's a plain branch/tag git can resolve.
           DEPLOY_REF: ${{ inputs.ref || github.ref_name }}
         run: |
-          python3 <<'PY'
-          import os, re
-          from pathlib import Path
-
-          REF = os.environ["DEPLOY_REF"]
-          REPO = "git+https://github.com/livekit/agents.git"
-          REPO_ROOT = Path(os.environ["GITHUB_WORKSPACE"])
-
-          # The package name (and optional [extras]) at the start of a
-          # requirement, e.g. "livekit-agents[evals]>=1.5.7".
-          REQUIREMENT = re.compile(r"^(?P<name>[A-Za-z0-9._-]+)(?P<extras>\[.*\])?")
-
-          def monorepo_path(name):
-              """Path of `name` within this repo, or None if it lives elsewhere.
-
-              We only pin packages that actually exist in the checkout. The
-              directory basename is the distribution name for every package
-              here (livekit-agents at the root, everything else under
-              livekit-plugins/). Anything not found (livekit rtc,
-              livekit-blingfire, livekit-local-inference, …) keeps its
-              PyPI pin.
-              """
-              for rel in (name, f"livekit-plugins/{name}"):
-                  if (REPO_ROOT / rel).is_dir():
-                      return rel
-              return None
-
-          def pin_to_ref(line):
-              """Repoint an in-repo requirement at the deployed git ref.
-
-              External requirements, comments and blanks pass through
-              untouched (the regex doesn't match a leading '#' or '').
-              """
-              match = REQUIREMENT.match(line.strip())
-              path = monorepo_path(match["name"]) if match else None
-              if path is None:
-                  return line
-              return f"{match['name']}{match['extras'] or ''} @ {REPO}@{REF}#subdirectory={path}"
-
-          requirements = Path("requirements.txt")
-          pinned = [pin_to_ref(line) for line in requirements.read_text().splitlines()]
-          requirements.write_text("\n".join(pinned) + "\n")
-
-          print(f"--- requirements.txt pinned to {REF} ---")
-          print(requirements.read_text())
-          PY
+          python3 .github/pin_example_to_ref.py \
+            "examples/${{ matrix.example }}" --ref "$DEPLOY_REF"
 
       - name: Build secrets file
         working-directory: examples/${{ matrix.example }}

examples/README.md

@@ -96,6 +96,20 @@ uv run examples/voice_agents/basic_agent.py console
 
 Your agent is now running in the console.
 
+### Taking an example with you
+
+Each example directory stands on its own: copy it anywhere, and
+
+```bash
+uv sync
+uv run agent.py console
+```
+
+installs from PyPI without the rest of the repo. `lk agent deploy .` works the
+same way, off the `Dockerfile` in the directory. Inside this repo the same
+directories are uv workspace members, so they run against your local SDK
+changes instead.
+
 For frontend support, use the [Agents playground](https://agents-playground.livekit.io) or the [starter apps](https://docs.livekit.io/agents/start/frontend/#starter-apps).
 
 ## 📖 Additional Resources

examples/avatar/Dockerfile

@@ -7,7 +7,8 @@ ARG PYTHON_VERSION=3.13
 FROM python:${PYTHON_VERSION}-slim AS base
 
 ENV PYTHONUNBUFFERED=1
-ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.6 /uv /usr/local/bin/uv
 
 ARG UID=10001
 RUN adduser \
@@ -26,16 +27,21 @@ RUN apt-get update && apt-get install -y \
     python3-dev \
   && rm -rf /var/lib/apt/lists/*
 
-# Enable git-lfs so pip's git installs smudge LFS-tracked binaries
+# Enable git-lfs so git dependencies smudge LFS-tracked binaries
 # (e.g. silero's bundled VAD onnx) instead of leaving pointer files.
 # --system so the unprivileged appuser below inherits the filters.
 RUN git lfs install --system
 
 WORKDIR /app
 USER appuser
 
-COPY requirements.txt ./
-RUN pip install --user --no-cache-dir -r requirements.txt
+# The example directory is the whole build context, so pyproject.toml has to
+# resolve on its own here — no workspace, no lockfile. A deploy from this repo
+# repoints the livekit-* dependencies at the ref being deployed first:
+#   python scripts/pin_example_to_ref.py examples/<name> --ref <git-ref>
+COPY pyproject.toml ./
+RUN uv sync --no-cache
+ENV PATH="/app/.venv/bin:${PATH}"
 
 # Pre-download model weights plugins ship (silero VAD, turn-detector, …)
 # so the container is ready to take traffic without a cold-download stall.

examples/avatar/README.md

@@ -13,7 +13,7 @@ Try it in the [LiveKit Playground](https://agents.livekit.io/?example=avatar).
 > authenticates with your LiveKit credentials and the gateway creates the
 > provider session with LiveKit's wholesale key. Requires the
 > `avatar_lemonslice` feature flag on your project. Run with
-> `python inference_agent.py dev` and set `LIVEKIT_URL`, `LIVEKIT_API_KEY`,
+> `uv run inference_agent.py dev` and set `LIVEKIT_URL`, `LIVEKIT_API_KEY`,
 > `LIVEKIT_API_SECRET`, and `LEMONSLICE_IMAGE_URL`.
 
 ## What's in here
@@ -43,8 +43,8 @@ You'll need:
 Then:
 
 ```bash
-pip install -r requirements.txt
-python agent.py dev
+uv sync --all-extras --dev   # from the repository root
+uv run agent.py dev
 ```
 
 Connect from any LiveKit client. The agent reads the starting persona

examples/avatar/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "livekit-example-avatar"
+version = "0"
+requires-python = ">=3.10"
+dependencies = [
+    "livekit-agents>=1.6",
+    "livekit-plugins-lemonslice>=1.5.7",
+    "livekit-plugins-silero>=1.5.7",
+    "livekit-plugins-turn-detector>=1.5.7",
+    "python-dotenv>=1.0.0",
+    "aiohttp>=3.9.0",
+    "numpy>=1.26.0",
+    # python:3.13-slim ships no system tzdata; without this, zoneinfo.ZoneInfo
+    # raises ZoneInfoNotFoundError at runtime.
+    "tzdata>=2024.1",
+]
+
+[tool.uv]
+# an example is a script collection, not an installable distribution
+package = false
+# No [tool.uv.sources] here: the workspace root repoints the livekit-* deps at
+# the in-repo copies for members, and staying free of workspace-only references
+# is what lets a copy of this directory resolve on its own, outside the repo.

examples/drive-thru/Dockerfile

@@ -7,7 +7,8 @@ ARG PYTHON_VERSION=3.13
 FROM python:${PYTHON_VERSION}-slim AS base
 
 ENV PYTHONUNBUFFERED=1
-ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.6 /uv /usr/local/bin/uv
 
 ARG UID=10001
 RUN adduser \
@@ -26,16 +27,21 @@ RUN apt-get update && apt-get install -y \
     python3-dev \
   && rm -rf /var/lib/apt/lists/*
 
-# Enable git-lfs so pip's git installs smudge LFS-tracked binaries
+# Enable git-lfs so git dependencies smudge LFS-tracked binaries
 # (e.g. silero's bundled VAD onnx) instead of leaving pointer files.
 # --system so the unprivileged appuser below inherits the filters.
 RUN git lfs install --system
 
 WORKDIR /app
 USER appuser
 
-COPY requirements.txt ./
-RUN pip install --user --no-cache-dir -r requirements.txt
+# The example directory is the whole build context, so pyproject.toml has to
+# resolve on its own here — no workspace, no lockfile. A deploy from this repo
+# repoints the livekit-* dependencies at the ref being deployed first:
+#   python scripts/pin_example_to_ref.py examples/<name> --ref <git-ref>
+COPY pyproject.toml ./
+RUN uv sync --no-cache
+ENV PATH="/app/.venv/bin:${PATH}"
 
 # Pre-download model weights plugins ship (silero VAD, turn-detector, …)
 # so the container is ready to take traffic without a cold-download stall.

examples/drive-thru/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "livekit-example-drive-thru"
+version = "0"
+requires-python = ">=3.10"
+dependencies = [
+    "livekit-agents>=1.6",
+    "livekit-plugins-silero>=1.5.7",
+    "livekit-plugins-turn-detector>=1.5.7",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[tool.uv]
+# an example is a script collection, not an installable distribution
+package = false
+# No [tool.uv.sources] here: the workspace root repoints the livekit-* deps at
+# the in-repo copies for members, and staying free of workspace-only references
+# is what lets a copy of this directory resolve on its own, outside the repo.

examples/frontdesk/Dockerfile

@@ -7,7 +7,8 @@ ARG PYTHON_VERSION=3.13
 FROM python:${PYTHON_VERSION}-slim AS base
 
 ENV PYTHONUNBUFFERED=1
-ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+
+COPY --from=ghcr.io/astral-sh/uv:0.11.6 /uv /usr/local/bin/uv
 
 ARG UID=10001
 RUN adduser \
@@ -26,16 +27,21 @@ RUN apt-get update && apt-get install -y \
     python3-dev \
   && rm -rf /var/lib/apt/lists/*
 
-# Enable git-lfs so pip's git installs smudge LFS-tracked binaries
+# Enable git-lfs so git dependencies smudge LFS-tracked binaries
 # (e.g. silero's bundled VAD onnx) instead of leaving pointer files.
 # --system so the unprivileged appuser below inherits the filters.
 RUN git lfs install --system
 
 WORKDIR /app
 USER appuser
 
-COPY requirements.txt ./
-RUN pip install --user --no-cache-dir -r requirements.txt
+# The example directory is the whole build context, so pyproject.toml has to
+# resolve on its own here — no workspace, no lockfile. A deploy from this repo
+# repoints the livekit-* dependencies at the ref being deployed first:
+#   python scripts/pin_example_to_ref.py examples/<name> --ref <git-ref>
+COPY pyproject.toml ./
+RUN uv sync --no-cache
+ENV PATH="/app/.venv/bin:${PATH}"
 
 # Pre-download model weights plugins ship (silero VAD, turn-detector, …)
 # so the container is ready to take traffic without a cold-download stall.

examples/frontdesk/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "livekit-example-frontdesk"
+version = "0"
+requires-python = ">=3.10"
+dependencies = [
+    "livekit-agents>=1.6",
+    "livekit-plugins-silero>=1.5.7",
+    "livekit-plugins-turn-detector>=1.5.7",
+    "python-dotenv>=1.0.0",
+    "aiohttp>=3.9.0",
+    # python:3.13-slim ships no system tzdata; without this, zoneinfo.ZoneInfo
+    # raises ZoneInfoNotFoundError at runtime.
+    "tzdata>=2024.1",
+]
+
+[tool.uv]
+# an example is a script collection, not an installable distribution
+package = false
+# No [tool.uv.sources] here: the workspace root repoints the livekit-* deps at
+# the in-repo copies for members, and staying free of workspace-only references
+# is what lets a copy of this directory resolve on its own, outside the repo.