Make every example a uv workspace member

.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 scripts/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.

examples/healthcare/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/healthcare/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "livekit-example-healthcare"
+version = "0"
+requires-python = ">=3.10"
+dependencies = [
+    "livekit-agents>=1.6",
+    "livekit-plugins-openai>=1.5.7",
+    "livekit-plugins-silero>=1.5.7",
+    "openai>=1.0.0",
+    "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.