diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..9b25f8b --- /dev/null +++ b/.dockerignore @@ -0,0 +1,19 @@ +*.egg-info +__pycache__ +.pytest_cache +.ruff_cache +.env +.env.* +.DS_Store +.idea +.venv +.vscode +*.pyc +*.pyo +*.pyd +.git +.gitignore +README.md +LICENSE +.github +tests/ \ No newline at end of file diff --git a/.github/workflows/template-check.yml b/.github/workflows/template-check.yml new file mode 100644 index 0000000..23157c7 --- /dev/null +++ b/.github/workflows/template-check.yml @@ -0,0 +1,31 @@ +# As this is a starter template project, we don't want to check in the uv.lock and livekit.toml files in its template form +# However, once you have cloned this repo for your own use, LiveKit recommends you check them in and delete this github workflow entirely + +name: Template Check + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +jobs: + check-template-files: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Check template files not tracked in git + run: | + if git ls-files | grep -q "^uv\.lock$"; then + echo "Error: uv.lock should not be checked into git" + echo "Disable this test and commit the file once you have cloned this repo for your own use" + exit 1 + fi + if git ls-files | grep -q "^livekit\.toml$"; then + echo "Error: livekit.toml should not be checked into git" + echo "Disable this test and commit the file once you have cloned this repo for your own use" + exit 1 + fi + echo "✓ uv.lock and livekit.toml are correctly not tracked in git" \ No newline at end of file diff --git a/.gitignore b/.gitignore index d9442dc..28ac1d0 100644 --- a/.gitignore +++ b/.gitignore @@ -4,7 +4,6 @@ __pycache__ .idea KMS -uv.lock .venv .vscode *.egg-info diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..da69aab --- /dev/null +++ b/Dockerfile @@ -0,0 +1,73 @@ +# This sample Dockerfile creates a production-ready container for a LiveKit voice AI agent +# syntax=docker/dockerfile:1 + +# Use the official UV Python base image with Python 3.11 on Debian Bookworm +# UV is a fast Python package manager that provides better performance than pip +# We use the slim variant to keep the image size smaller while still having essential tools +FROM ghcr.io/astral-sh/uv:python3.11-bookworm-slim + +# Keeps Python from buffering stdout and stderr to avoid situations where +# the application crashes without emitting any logs due to buffering. +ENV PYTHONUNBUFFERED=1 + +# Create a non-privileged user that the app will run under. +# See https://docs.docker.com/develop/develop-images/dockerfile_best-practices/#user +ARG UID=10001 +RUN adduser \ + --disabled-password \ + --gecos "" \ + --home "/home/appuser" \ + --shell "/sbin/nologin" \ + --uid "${UID}" \ + appuser + +# Install build dependencies required for Python packages with native extensions +# gcc: C compiler needed for building Python packages with C extensions +# python3-dev: Python development headers needed for compilation +# We clean up the apt cache after installation to keep the image size down +RUN apt-get update && \ + apt-get install -y \ + gcc \ + python3-dev \ + && rm -rf /var/lib/apt/lists/* + +# Set the working directory to the user's home directory +# This is where our application code will live +WORKDIR /home/appuser + +# Copy all application files into the container +# This includes source code, configuration files, and dependency specifications +# (Excludes files specified in .dockerignore) +COPY . . + +# Change ownership of all app files to the non-privileged user +# This ensures the application can read/write files as needed +RUN chown -R appuser:appuser /home/appuser + +# Switch to the non-privileged user for all subsequent operations +# This improves security by not running as root +USER appuser + +# Create a cache directory for the user +# This is used by UV and Python for caching packages and bytecode +RUN mkdir -p /home/appuser/.cache + +# Install Python dependencies using UV's lock file +# --locked ensures we use exact versions from uv.lock for reproducible builds +# This creates a virtual environment and installs all dependencies +# Ensure your uv.lock file is checked in for consistency across environments +RUN uv sync --locked + +# Pre-download any ML models or files the agent needs +# This ensures the container is ready to run immediately without downloading +# dependencies at runtime, which improves startup time and reliability +RUN uv run src/agent.py download-files + +# Expose the healthcheck port +# This allows Docker and orchestration systems to check if the container is healthy +EXPOSE 8081 + +# Run the application using UV +# UV will activate the virtual environment and run the agent +# The "start" command tells the worker to connect to LiveKit and begin waiting for jobs +CMD ["uv", "run", "src/agent.py", "start"] diff --git a/README.md b/README.md index 3c912ca..e4862a1 100644 --- a/README.md +++ b/README.md @@ -68,22 +68,44 @@ In production, use the `start` command: uv run python src/agent.py start ``` -## Web and mobile frontends +## Frontend & Telephony -To use a prebuilt frontend or build your own, see the [agents frontend guide](https://docs.livekit.io/agents/start/frontend/). +Get started quickly with our pre-built frontend starter apps, or add telephony support: -## Telephony +| Platform | Link | Description | +|----------|----------|-------------| +| **Web** | [`livekit-examples/agent-starter-react`](https://github.com/livekit-examples/agent-starter-react) | Web voice AI assistant with React & Next.js | +| **iOS/macOS** | [`livekit-examples/agent-starter-swift`](https://github.com/livekit-examples/agent-starter-swift) | Native iOS, macOS, and visionOS voice AI assistant | +| **Flutter** | [`livekit-examples/agent-starter-flutter`](https://github.com/livekit-examples/agent-starter-flutter) | Cross-platform voice AI assistant app | +| **React Native** | [`livekit-examples/voice-assistant-react-native`](https://github.com/livekit-examples/voice-assistant-react-native) | Native mobile app with React Native & Expo | +| **Android** | [`livekit-examples/agent-starter-android`](https://github.com/livekit-examples/agent-starter-android) | Native Android app with Kotlin & Jetpack Compose | +| **Web Embed** | [`livekit-examples/agent-starter-embed`](https://github.com/livekit-examples/agent-starter-embed) | Voice AI widget for any website | +| **Telephony** | [📚 Documentation](https://docs.livekit.io/agents/start/telephony/) | Add inbound or outbound calling to your agent | -To add a phone number, see the [agents telephony guide](https://docs.livekit.io/agents/start/telephony/). +For advanced customization, see the [complete frontend guide](https://docs.livekit.io/agents/start/frontend/). ## Tests and evals This project includes a complete suite of evals, based on the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/build/testing/). To run them, use `pytest`. ```console -uv run pytest evals +uv run pytest ``` +## Using this template repo for your own project + +Once you've started your own project based on this repo, you should: + +1. **Check in your `uv.lock`**: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to `livekit.toml`, if you run your agents in LiveKit Cloud) + +2. **Remove the git tracking test**: Delete the "Check files not tracked in git" step from `.github/workflows/tests.yml` since you'll now want this file to be tracked. These are just there for development purposes in the template repo itself. + +3. **Add your own repository secrets**: You must [add secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) for `OPENAI_API_KEY` or your other LLM provider so that the tests can run in CI. + +## Deploying to production + +This project is production-ready and includes a working `Dockerfile`. To deploy it to LiveKit Cloud or another environment, see the [deploying to production](https://docs.livekit.io/agents/ops/deployment/) guide. + ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. \ No newline at end of file diff --git a/evals/test_agent.py b/tests/test_agent.py similarity index 100% rename from evals/test_agent.py rename to tests/test_agent.py