Scenario yaml source-of-truth + on_simulation_end verdict override

.github/next-release/changeset-soniox-target-segments.md

@@ -0,0 +1,12 @@
+---
+"livekit-agents": patch
+"livekit-plugins-soniox": patch
+---
+
+Surface per-run language segments end-to-end in the Soniox STT plugin, fixing two symmetric symptoms of the same underlying bug where `_TokenAccumulator._lang_segments` was computed but discarded in `send_endpoint_transcript` (and in the interim path). Both fixes live in the same block.
+
+- Add `target_languages` and `target_texts` to `stt.SpeechData`, mirroring the existing `source_languages` / `source_texts` source-side fields.
+- In translation mode, the Soniox plugin now populates `target_*` on `FINAL_TRANSCRIPT` and `INTERIM_TRANSCRIPT` / `PREFLIGHT_TRANSCRIPT` events, exposing per-run target-language breakdowns for code-switched two-way translation (e.g. `target_languages=["en", "es"]` / `target_texts=["Hello, how are you?", " Estoy bien, gracias."]` for the translation of `"Hello, ¿cómo estás? I'm doing fine, gracias."`).
+- In non-translation mode, the plugin now populates `source_languages` / `source_texts` from the same accumulator (previously these were left `None`, making code-switched dictation look monolingual to consumers). For a Japanese-then-English utterance, consumers now see `source_languages=["ja", "en"]` instead of `None`.
+
+`SpeechData.text` and `SpeechData.language` are unchanged for back-compat (still the full concatenation and the first translated/detected language, respectively). Fixes #5685.

.github/workflows/deploy-examples.yml

@@ -1,16 +1,14 @@
 name: Deploy Examples
 
 on:
+  # Manual runs deploy from the branch picked in the Actions "Use workflow
+  # from" selector — no input needed.
   workflow_dispatch:
-    inputs:
-      ref:
-        description: "Branch or ref to deploy from (default: main)"
-        type: string
-        required: false
-        default: "main"
+  # Called by publish.yml after a release to deploy the published commit.
   workflow_call:
     inputs:
       ref:
+        description: "Commit/branch/tag to deploy. Defaults to the triggering ref."
         type: string
         required: false
 
@@ -24,11 +22,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        example: [healthcare, survey, frontdesk, drive-thru]
+        example: [healthcare, survey, frontdesk, drive-thru, inference, avatar]
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
-          ref: ${{ inputs.ref || 'main' }}
+          ref: ${{ inputs.ref || github.ref }}
+          # 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
+          # git clone). Without this the agent crashes at runtime decoding a
+          # 131-byte pointer as audio.
+          lfs: true
 
       - name: Install LiveKit CLI
         run: |
@@ -47,16 +52,101 @@ jobs:
             --api-secret "$LIVEKIT_API_SECRET" \
             --default
 
+      - name: Regenerate livekit.toml from playground.yaml
+        run: |
+          python3 -m pip install --quiet pyyaml
+          python3 <<'PY'
+          import yaml
+          from pathlib import Path
+          data = yaml.safe_load(Path("examples/playground.yaml").read_text())
+          subdomain = data["project"]["subdomain"]
+          slug = "${{ matrix.example }}"
+          entry = data["examples"][slug]
+          toml = (
+              "[project]\n"
+              f'  subdomain = "{subdomain}"\n'
+              "\n"
+              "[agent]\n"
+              f'  id = "{entry["agent_id"]}"\n'
+          )
+          Path(f"examples/{slug}/livekit.toml").write_text(toml)
+          print(f"wrote examples/{slug}/livekit.toml")
+          PY
+
+      - name: Pin livekit-* requirements to the deployed ref
+        working-directory: examples/${{ matrix.example }}
+        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.
+          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/ — including the irregular ones like
+              livekit-blingfire). Anything not found (livekit rtc,
+              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
+
       - name: Build secrets file
         working-directory: examples/${{ matrix.example }}
         env:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          LEMONSLICE_API_KEY: ${{ secrets.LEMONSLICE_API_KEY }}
         run: |
           : > .env.deploy
+          # Register the agent under a deterministic name so the playground
+          # can dispatch to it explicitly. Matches the slug in playground.yaml.
+          echo "LIVEKIT_AGENT_NAME=${{ matrix.example }}" >> .env.deploy
           case "${{ matrix.example }}" in
             healthcare)
               keys="OPENAI_API_KEY"
               ;;
+            avatar)
+              keys="LEMONSLICE_API_KEY"
+              ;;
             *)
               keys=""
               ;;

.github/workflows/publish.yml

@@ -254,3 +254,41 @@ jobs:
     with:
       ref: ${{ inputs.branch || github.event.pull_request.merge_commit_sha }}
     secrets: inherit
+
+  dispatch-downstream-bumps:
+    name: Bump livekit-agents in downstream repos
+    needs: [publish]
+    # Only fire for stable releases merged via a release/vX.Y.Z PR.
+    # RC head refs look like release/v1.5.13rc1 and won't match the regex below.
+    # Republish retries should use internal-actions' workflow_dispatch fallback.
+    if: |
+      always()
+      && needs.publish.result == 'success'
+      && github.event_name == 'pull_request'
+      && github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve stable version from head ref
+        id: version
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          version="${HEAD_REF#release/v}"
+          if ! echo "$version" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+            echo "::notice::Head ref '$HEAD_REF' is not a stable release — skipping downstream bump."
+            exit 0
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch to internal-actions
+        if: steps.version.outputs.version != ''
+        env:
+          GH_TOKEN: ${{ secrets.SYNC_DISPATCH_TOKEN }}
+          TARGET_REPO: ${{ vars.TARGET_REPO }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          gh api -X POST "repos/${TARGET_REPO}/dispatches" \
+            -f event_type="livekit-agents-published" \
+            -f client_payload[version]="$VERSION" \
+            -f client_payload[source_repo]="${{ github.repository }}" \
+            -f client_payload[source_sha]="${{ github.event.pull_request.merge_commit_sha }}"

.github/workflows/test-realtime.yml

@@ -52,4 +52,4 @@ jobs:
           AZURE_OPENAI_API_VERSION: ${{ secrets.AZURE_OPENAI_API_VERSION }}
           # XAI_API_KEY not set — xAI rate-limits GitHub Actions IPs (429 on ws handshake)
         run: |
-          uv run pytest -v tests/test_realtime/ -s --tb=long -p no:xdist
+          uv run pytest --realtime -v -s --tb=long -p no:xdist

.github/workflows/test-stt.yml

@@ -198,7 +198,7 @@ jobs:
           # AWS_REGION: ${{ secrets.AWS_REGION }}
           SARVAM_API_KEY: ${{ secrets.SARVAM_API_KEY }}
         run: |
-          uv run pytest -n 3 -v tests/test_stt.py --tb=long --junitxml=test-results.xml 2>&1 | tee test-output.txt || true
+          uv run pytest -n 3 -v --stt --tb=long --junitxml=test-results.xml 2>&1 | tee test-output.txt || true
 
       - name: Cleanup Google credentials
         if: always()

.github/workflows/tests.yml

@@ -90,7 +90,7 @@ jobs:
           LIVEKIT_API_KEY: ${{ secrets.LIVEKIT_API_KEY }}
           LIVEKIT_API_SECRET: ${{ secrets.LIVEKIT_API_SECRET }}
 
-        run: uv run pytest tests/test_workflows.py tests/test_evals.py
+        run: uv run pytest --evals
 
   tests:
     # don't run tests for PRs on forks

AGENTS.md

@@ -20,12 +20,39 @@ make check            # Run all checks (format-check, lint, type-check)
 
 ### Testing
 ```bash
-uv run pytest                           # Run all tests
+uv run pytest --unit                    # Run all unit tests
 uv run pytest tests/test_tools.py       # Run a single test file
-uv run pytest tests/test_tools.py -k "test_name"  # Run specific test
-cd tests && make unit-tests             # Run unit tests that doesn't require cloud accounts
+make unit-tests                         # Run unit tests that don't require cloud accounts
 ```
 
+#### Test categories
+
+Every test module declares exactly one category via a module-level marker, and
+each category has a matching `--<category>` selection flag. Selection happens
+*before* import, so a category run never imports (or fails on) modules outside
+it.
+
+| Marker | Flag | Meaning |
+|--------|------|---------|
+| `pytest.mark.unit` | `--unit` | fast, hermetic, no external providers/credentials/network |
+| `pytest.mark.plugin("name")` | `--plugin [name]` | provider integration test (needs that provider's deps/keys) |
+| `pytest.mark.stt` | `--stt` | cross-provider speech-to-text suite (`tests/test_stt.py`) |
+| `pytest.mark.tts` | `--tts` | cross-provider text-to-speech suite (`tests/test_tts.py`) |
+| `pytest.mark.realtime("name")` | `--realtime [name]` | realtime-model test |
+| `pytest.mark.evals` | `--evals` | behavioral evals against the LiveKit inference gateway |
+| `pytest.mark.docs` | `--docs` | tests for the docs-build tooling under `.github/` |
+
+```bash
+uv run pytest --unit                    # the CI unit gate (no cloud accounts)
+uv run pytest --plugin openai           # only the openai provider tests
+uv run pytest --list-categories         # list every module grouped by category, then exit
+```
+
+**Adding a test:** give the new module a category marker (`pytestmark =
+pytest.mark.unit`, etc.) — collection fails with a hint if it lacks one. Run
+pytest with the `--allow-uncategorized` option to temporarily disable this rule
+(CI keeps it on by default).
+
 ### Running Agents
 ```bash
 python myagent.py console   # Terminal mode with local audio I/O (no server needed)

README.md

@@ -38,7 +38,7 @@ agents that can see, hear, and understand.
 - **Telephony integration**: Works seamlessly with LiveKit's [telephony stack](https://docs.livekit.io/sip/), allowing your agent to make calls to or receive calls from phones.
 - **Exchange data with clients**: Use [RPCs](https://docs.livekit.io/home/client/data/rpc/) and other [Data APIs](https://docs.livekit.io/home/client/data/) to seamlessly exchange data with clients.
 - **Semantic turn detection**: Uses a transformer model to detect when a user is done with their turn, helps to reduce interruptions.
-- **MCP support**: Native support for MCP. Integrate tools provided by MCP servers with one loc.
+- **MCP support**: Native support for MCP. Integrate tools provided by MCP servers with one line of code.
 - **Builtin test framework**: Write tests and use judges to ensure your agent is performing as expected.
 - **Open-source**: Fully open-source, allowing you to run the entire stack on your own servers, including [LiveKit server](https://github.com/livekit/livekit), one of the most widely used WebRTC media servers.
 
@@ -186,7 +186,7 @@ class StoryAgent(Agent):
     def __init__(self, name: str, location: str) -> None:
         super().__init__(
             instructions=f"You are a storyteller. Use the user's information in order to make the story personalized."
-            f"The user's name is {name}, from {location}"
+            f"The user's name is {name}, from {location}",
             # override the default model, switching to Realtime API from standard LLMs
             llm=openai.realtime.RealtimeModel(voice="echo"),
             chat_ctx=chat_ctx,
@@ -222,7 +222,7 @@ Automated tests are essential for building reliable agents, especially with the
 @pytest.mark.asyncio
 async def test_no_availability() -> None:
     llm = google.LLM()
-    async AgentSession(llm=llm) as sess:
+    async with AgentSession(llm=llm) as sess:
         await sess.start(MyAgent())
         result = await sess.run(
             user_input="Hello, I need to place an order."
@@ -409,7 +409,7 @@ For more information, see the [examples README](examples/README.md).
 Unit tests are in the `tests` directory and can be run with:
 
 ```shell
-uv run pytest tests/test_tools.py
+uv run pytest --unit
 ```
 
 Integration tests for each plugin require various API credentials and run automatically in GitHub CI for PRs submitted by project maintainers. See the [tests workflow](.github/workflows/tests.yml) for details.

examples/Dockerfile-example

@@ -40,10 +40,10 @@ WORKDIR /home/appuser
 COPY requirements.txt .
 RUN python -m pip install --user --no-cache-dir -r requirements.txt
 
-COPY . .
-
 # ensure that any dependent models are downloaded at build-time
-RUN python myagent.py download-files
+RUN python -m livekit.agents download-files
+
+COPY . .
 
 # Run the application.
 ENTRYPOINT ["python", "myagent.py"]

examples/avatar/Dockerfile

@@ -0,0 +1,46 @@
+# syntax=docker/dockerfile:1
+#
+# Shared Dockerfile for every example under examples/. Byte-identical
+# across the tree — each example's entry script is named `agent.py`,
+# so there's no per-example variation left.
+ARG PYTHON_VERSION=3.13
+FROM python:${PYTHON_VERSION}-slim AS base
+
+ENV PYTHONUNBUFFERED=1
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+
+ARG UID=10001
+RUN adduser \
+    --disabled-password \
+    --gecos "" \
+    --home "/app" \
+    --shell "/sbin/nologin" \
+    --uid "${UID}" \
+    appuser
+
+RUN apt-get update && apt-get install -y \
+    git \
+    git-lfs \
+    gcc \
+    g++ \
+    python3-dev \
+  && rm -rf /var/lib/apt/lists/*
+
+# Enable git-lfs so pip's git installs 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
+
+# Pre-download model weights plugins ship (silero VAD, turn-detector, …)
+# so the container is ready to take traffic without a cold-download stall.
+RUN python -m livekit.agents download-files
+
+COPY . .
+
+CMD ["python", "agent.py", "start"]