Make every example a uv workspace member

[u9g]

Each example declared its dependencies in a requirements.txt that nothing in the root sync path read — [tool.uv.workspace].members covered only livekit-plugins/* and livekit-agents, and pytest ignores examples. So uv sync left example dependencies uninstalled, and an example crashed at import on its first missing one:

File "examples/hotel_receptionist/benchmark.py", line 20, in <module>
  import apsw
ModuleNotFoundError: No module named 'apsw'

apsw>=3.46 had been declared in examples/hotel_receptionist/requirements.txt the whole time. The lk CLI also classified the examples as pip projects from that file, launched a bare interpreter resolved from the enclosing workspace, and has no missing-dependency gate on that path — the uv path fast-fails with run uv sync, the pip path does not.

What changed

Every example that had a requirements.txt (9 of them) now declares its dependencies in a pyproject.toml and joins the workspace. Dependencies land in the root lock, so uv sync --all-extras --dev installs them, and [tool.uv.sources] keeps in-repo dependencies resolving to the local editable packages rather than PyPI.

A deploy build context is the example directory alone, where workspace sources cannot resolve, so requirements.txt is rendered from the declared dependencies at deploy time instead of being checked in. The pinning logic moved out of the deploy-examples.yml heredoc into scripts/render_example_requirements.py first, unchanged, so it can also be run by hand before lk agent deploy:

python scripts/render_example_requirements.py examples/hotel_receptionist --ref main

Verified

• uv sync --all-extras --dev --dry-run now includes apsw, aiocsv and duckduckgo-search.
• uv.lock records each example as source = { virtual = ... } with livekit-agents as editable = "livekit-agents" — local SDK changes are still what the examples run against.
• lk agent dockerfile in an example now reports Detected agent language [python.uv], was python.pip.
• The render script reproduces the previous CI output for all 9 examples.
• uv lock --check, ruff and mypy --strict clean. Ruff still resolves the root config for example files, since the new pyproject.tomls carry no [tool.ruff].
• The deploy preflight still passes: the CLI's static version check prefers pyproject.toml over requirements.txt, and it reads only .dockerignore, never .gitignore, so the rendered file still uploads.

Notes

• No per-example uv.lock. One would pin livekit-agents to a path source, so an isolated Docker build context still could not uv sync --locked — 9 lockfiles to keep in sync for no deploy benefit.
• Dockerfiles keep pip install -r requirements.txt. The upstream python.uv Dockerfile template does COPY pyproject.toml uv.lock + uv sync --locked, which needs a self-contained project; a workspace member is not one. All 8 stay byte-identical, with a comment pointing at the render script.
• livekit-agents[evals] dropped from avatar, frontdesk, homepage and hotel_receptionist. There is no evals extra in livekit-agents — pip silently ignored it, uv rejects it.
• cd examples/foo && uv sync no longer works standalone, and a first sync pulls the whole workspace. examples/README.md already documented root uv sync --all-extras --dev plus uv run; the three example READMEs that still said pip install -r requirements.txt now match.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 2 additional findings in Devin Review.

[devin-ai-integration]

🟡 Example container images may be built with a downloaded Python instead of the one the image is pinned to

The dependency install step for every example image is run without telling the tool which Python to use (uv sync --no-cache at examples/avatar/Dockerfile:43), so it can fetch and use its own newest Python instead of the version the image is pinned to.
Impact: Example deployments can silently run on a different Python than intended, and the image build can fail when a dependency has no prebuilt package for that newer Python.

Why the interpreter is not the image's python3.13

The base image is python:${PYTHON_VERSION}-slim with ARG PYTHON_VERSION=3.13 (examples/avatar/Dockerfile:6-7), but uv's default python-preference is managed with automatic downloads enabled, which is exactly why Astral's own Docker guide sets UV_PYTHON_DOWNLOADS=0 "because we want to use the system interpreter". The example pyproject.toml only declares requires-python = ">=3.10" (examples/avatar/pyproject.toml:4) and there is no .python-version, so uv is free to install a managed interpreter (e.g. 3.14, still allowed by livekit-agents' >=3.10,<3.15) and create /app/.venv from it. Consequences: (1) ARG PYTHON_VERSION no longer controls the runtime interpreter; (2) dependencies are resolved for that interpreter, so packages such as av (a livekit-agents dependency) or apsw may have no wheel and fall back to an sdist build, which for av needs ffmpeg dev libraries not installed in the image. All 8 example Dockerfiles are byte-identical, so this applies to avatar, drive-thru, frontdesk, healthcare, homepage, hotel_receptionist, inference and survey.

The previous pip install --user -r requirements.txt always used the image's interpreter.

Suggested change

	COPY pyproject.toml ./
	RUN uv sync --no-cache
	ENV PATH="/app/.venv/bin:${PATH}"
	COPY pyproject.toml ./
	# Use the interpreter this image is pinned to instead of letting uv download
	# and prefer a managed Python of its own choosing.
	ENV UV_PYTHON_DOWNLOADS=0
	RUN uv sync --no-cache --python "$(command -v python3)"
	ENV PATH="/app/.venv/bin:${PATH}"

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟡 Avatar example image can be broken by a virtual environment left in the copied directory

The avatar example builds its dependencies into a virtual environment inside the image (uv sync at examples/avatar/Dockerfile:43) and then copies the whole directory on top of it, but that directory has no ignore file, so a virtual environment sitting next to the sources overwrites the one built in the image and the agent fails to start.
Impact: Deploying the avatar example from a working copy where someone already installed its dependencies locally produces an image that cannot run.

Missing .dockerignore in examples/avatar

Every other example with a Dockerfile ships a .dockerignore that excludes **/.venv/ (e.g. examples/hotel_receptionist/.dockerignore), so the final COPY . . (examples/avatar/Dockerfile:50) cannot clobber /app/.venv. examples/avatar/ has no .dockerignore at all. With the old pip install --user layout a stray host .venv in the context was inert; now /app/.venv is the interpreter selected by ENV PATH="/app/.venv/bin:${PATH}", so a host .venv (wrong platform, absolute paths baked in) replaces it and CMD ["python", "agent.py", "start"] breaks. examples/README.md:99-111 now explicitly tells users to copy an example directory and run uv sync there before lk agent deploy ., which is exactly how such a .venv appears.

Prompt for agents

examples/avatar/ is the only example with a Dockerfile that has no .dockerignore. The new Dockerfile installs dependencies into /app/.venv and puts it first on PATH, then runs `COPY . .`, so any .venv present in the build context replaces the image's environment and the container's `python` becomes a host-built venv. Add a .dockerignore to examples/avatar mirroring the one used by the other examples (e.g. examples/hotel_receptionist/.dockerignore), which excludes **/.venv/, caches, .env files and tests.

---

Was this helpful? React with 👍 or 👎 to provide feedback.