Merge pull request #2491 from pipecat-ai/mb/update-quickstart

.github/workflows/sync-quickstart.yaml

@@ -23,17 +23,12 @@ jobs:
           token: ${{ secrets.QUICKSTART_SYNC_TOKEN }}
           path: quickstart-repo
 
-      - name: Sync files (excluding READMEs)
+      - name: Sync files (excluding uv.lock and README.md)
         run: |
-          # Copy code files only, skip READMEs
-          cp examples/quickstart/bot.py quickstart-repo/
-          cp examples/quickstart/requirements.txt quickstart-repo/
-          cp examples/quickstart/env.example quickstart-repo/
-
-          # Copy any other files that aren't README.md
+          # Copy all files except uv.lock and README.md
           find examples/quickstart -type f \
             -not -name "README.md" \
-            -not -name "*.md" \
+            -not -name "uv.lock" \
             -exec cp {} quickstart-repo/ \;
 
       - name: Commit and push changes

examples/quickstart/Dockerfile

@@ -0,0 +1,16 @@
+FROM dailyco/pipecat-base:latest
+
+# Enable bytecode compilation
+ENV UV_COMPILE_BYTECODE=1
+
+# Copy from the cache instead of linking since it's a mounted volume
+ENV UV_LINK_MODE=copy
+
+# Install the project's dependencies using the lockfile and settings
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-install-project --no-dev
+
+# Copy the application code
+COPY ./bot.py bot.py

examples/quickstart/README.md

@@ -1,87 +1,159 @@
 # Pipecat Quickstart
 
-Run your first Pipecat bot in under 5 minutes. This example creates a voice AI bot that you can talk to in your browser.
+Build and deploy your first voice AI bot in under 10 minutes. Develop locally, then scale to production on Pipecat Cloud.
 
-## Prerequisites
+**Two steps**: [🏠 Local Development](#run-your-bot-locally) → [☁️ Production Deployment](#deploy-to-production)
 
-### Python 3.10+
+> 🎯 Quick start: Local bot in 5 minutes, production deployment in 5 more
 
-Pipecat requires Python 3.10 or newer. Check your version:
+## Step 1: Local Development (5 min)
 
-```bash
-python --version
-```
+### Prerequisites
 
-If you need to upgrade Python, we recommend using a version manager like `uv` or `pyenv`.
+#### Environment
 
-### AI Service API keys
+- Python 3.10 or later
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager installed
 
-Pipecat orchestrates different AI services in a pipeline, ensuring low latency communication. In this quickstart example, we'll use:
+#### AI Service API keys
 
-- [Deepgram](https://console.deepgram.com/signup) for Speech-to-Text transcriptions
+You'll need API keys from three services:
+
+- [Deepgram](https://console.deepgram.com/signup) for Speech-to-Text
 - [OpenAI](https://auth.openai.com/create-account) for LLM inference
-- [Cartesia](https://play.cartesia.ai/sign-up) for Text-to-Speech audio generation
+- [Cartesia](https://play.cartesia.ai/sign-up) for Text-to-Speech
 
-Have your API keys ready. We'll add them to your `.env` shortly.
+> 💡 **Tip**: Sign up for all three now. You'll need them for both local and cloud deployment.
 
-## Setup
+### Setup
 
-1. Set up a virtual environment
+Navigate to the quickstart directory and set up your environment.
 
-From the `examples/quickstart` directory, run:
+1. Install dependencies:
+
+   ```bash
+   uv sync
+   ```
+
+2. Configure your API keys:
+
+   Create a `.env` file:
+
+   ```bash
+   cp env.example .env
+   ```
+
+   Then, add your API keys:
+
+   ```ini
+   DEEPGRAM_API_KEY=your_deepgram_api_key
+   OPENAI_API_KEY=your_openai_api_key
+   CARTESIA_API_KEY=your_cartesia_api_key
+   ```
+
+### Run your bot locally
 
 ```bash
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uv run bot.py
 ```
 
-> Using `uv`? Create your venv using: `uv venv && source .venv/bin/activate`.
-
-2. Install dependencies
-
-```bash
-pip install -r requirements.txt
-```
-
-> Using `uv`? Install requirements using: `uv pip install -r requirements.txt`.
-
-3. Configure environment variables
-
-Create a `.env` file:
-
-```bash
-cp env.example .env
-```
-
-Then, add your API keys:
-
-```
-DEEPGRAM_API_KEY=your_deepgram_api_key
-OPENAI_API_KEY=your_openai_api_key
-CARTESIA_API_KEY=your_cartesia_api_key
-```
-
-4. Run the example
-
-Run your bot using:
-
-```bash
-python bot.py
-```
-
-> Using `uv`? Run your bot using: `uv run bot.py`.
-
 **Open http://localhost:7860 in your browser** and click `Connect` to start talking to your bot.
 
-> 💡 First run note: The initial startup may take ~10 seconds as Pipecat downloads required models, like the Silero VAD model.
+> 💡 First run note: The initial startup may take ~20 seconds as Pipecat downloads required models and imports.
 
-## Troubleshooting
+🎉 **Success!** Your bot is running locally. Now let's deploy it to production so others can use it.
 
-- **Browser permissions**: Make sure to allow microphone access when prompted by your browser.
-- **Connection issues**: If the WebRTC connection fails, first try a different browser. If that fails, make sure you don't have a VPN or firewall rules blocking traffic. WebRTC uses UDP to communicate.
-- **Audio issues**: Check that your microphone and speakers are working and not muted.
+---
 
-## Next Steps
+## Step 2: Deploy to Production (5 min)
 
-- **Read the docs**: Check out [Pipecat's docs](https://docs.pipecat.ai/) for guides and reference information.
-- **Join Discord**: Join [Pipecat's Discord server](https://discord.gg/pipecat) to get help and learn about what others are building.
+Transform your local bot into a production-ready service. Pipecat Cloud handles scaling, monitoring, and global deployment.
+
+### Prerequisites
+
+1. [Sign up for Pipecat Cloud](https://pipecat.daily.co/sign-up).
+
+2. Install the Pipecat Cloud CLI:
+
+   ```bash
+   uv add pipecatcloud
+   ```
+
+> 💡 Tip: You can run the `pipecatcloud` CLI using the `pcc` alias.
+
+3. Set up Docker for building your bot image:
+
+   - **Install [Docker](https://www.docker.com/)** on your system
+   - **Create a [Docker Hub](https://hub.docker.com/) account**
+   - **Login to Docker Hub:**
+
+     ```bash
+     docker login
+     ```
+
+### Configure your deployment
+
+The `pcc-deploy.toml` file tells Pipecat Cloud how to run your bot. **Update the image field** with your Docker Hub username by editing `pcc-deploy.toml`.
+
+```ini
+agent_name = "quickstart"
+image = "YOUR_DOCKERHUB_USERNAME/quickstart:0.1"  # 👈 Update this line
+secret_set = "quickstart-secrets"
+
+[scaling]
+	min_agents = 1
+```
+
+**Understanding the TOML file settings:**
+
+- `agent_name`: Your bot's name in Pipecat Cloud
+- `image`: The Docker image to deploy (format: `username/image:version`)
+- `secret_set`: Where your API keys are stored securely
+- `min_agents`: Number of bot instances to keep ready (1 = instant start)
+
+> 💡 Tip: [Set up `image_credentials`](https://docs.pipecat.ai/deployment/pipecat-cloud/fundamentals/secrets#image-pull-secrets) in your TOML file for authenticated image pulls
+
+### Configure secrets
+
+Upload your API keys to Pipecat Cloud's secure storage:
+
+```bash
+uv run pcc secrets set quickstart-secrets --file .env
+```
+
+This creates a secret set called `quickstart-secrets` (matching your TOML file) and uploads all your API keys from `.env`.
+
+### Build and deploy
+
+Build your Docker image and push to Docker Hub:
+
+```bash
+# Update build.sh with your Docker Hub username, then:
+./build.sh
+```
+
+Deploy to Pipecat Cloud:
+
+```bash
+uv run pcc deploy
+```
+
+### Connect to your agent
+
+1. Open your [Pipecat Cloud dashboard](https://pipecat.daily.co/)
+2. Select your `quickstart` agent → **Sandbox**
+3. Allow microphone access and click **Connect**
+
+---
+
+## What's Next?
+
+**🔧 Customize your bot**: Modify `bot.py` to change personality, add functions, or integrate with your data  
+**📚 Learn more**: Check out [Pipecat's docs](https://docs.pipecat.ai/) for advanced features  
+**💬 Get help**: Join [Pipecat's Discord](https://discord.gg/pipecat) to connect with the community
+
+### Troubleshooting
+
+- **Browser permissions**: Allow microphone access when prompted
+- **Connection issues**: Try a different browser or check VPN/firewall settings
+- **Audio issues**: Verify microphone and speakers are working and not muted

examples/quickstart/bot.py

@@ -7,18 +7,16 @@
 """Pipecat Quickstart Example.
 
 The example runs a simple voice AI bot that you can connect to using your
-browser and speak with it.
+browser and speak with it. You can also deploy this bot to Pipecat Cloud.
 
 Required AI services:
 - Deepgram (Speech-to-Text)
 - OpenAI (LLM)
 - Cartesia (Text-to-Speech)
 
-The example connects between client and server using a P2P WebRTC connection.
-
 Run the bot using::
 
-    python bot.py
+    uv run bot.py
 """
 
 import os
@@ -27,7 +25,7 @@ from dotenv import load_dotenv
 from loguru import logger
 
 print("🚀 Starting Pipecat bot...")
-print("⏳ Loading AI models (30-40 seconds first run, <2 seconds after)\n")
+print("⏳ Loading models and imports (20 seconds first run only)\n")
 
 logger.info("Loading Silero VAD model...")
 from pipecat.audio.vad.silero import SileroVADAnalyzer
@@ -40,15 +38,12 @@ from pipecat.pipeline.task import PipelineParams, PipelineTask
 from pipecat.processors.aggregators.openai_llm_context import OpenAILLMContext
 from pipecat.processors.frameworks.rtvi import RTVIConfig, RTVIObserver, RTVIProcessor
 from pipecat.runner.types import RunnerArguments
+from pipecat.runner.utils import create_transport
 from pipecat.services.cartesia.tts import CartesiaTTSService
 from pipecat.services.deepgram.stt import DeepgramSTTService
 from pipecat.services.openai.llm import OpenAILLMService
 from pipecat.transports.base_transport import BaseTransport, TransportParams
-
-logger.info("✅ Pipeline components loaded")
-
-logger.info("Loading WebRTC transport...")
-from pipecat.transports.network.small_webrtc import SmallWebRTCTransport
+from pipecat.transports.services.daily import DailyParams
 
 logger.info("✅ All components loaded successfully!")
 
@@ -121,14 +116,20 @@ async def run_bot(transport: BaseTransport, runner_args: RunnerArguments):
 async def bot(runner_args: RunnerArguments):
     """Main bot entry point for the bot starter."""
 
-    transport = SmallWebRTCTransport(
-        params=TransportParams(
+    transport_params = {
+        "daily": lambda: DailyParams(
             audio_in_enabled=True,
             audio_out_enabled=True,
             vad_analyzer=SileroVADAnalyzer(),
         ),
-        webrtc_connection=runner_args.webrtc_connection,
-    )
+        "webrtc": lambda: TransportParams(
+            audio_in_enabled=True,
+            audio_out_enabled=True,
+            vad_analyzer=SileroVADAnalyzer(),
+        ),
+    }
+
+    transport = await create_transport(runner_args, transport_params)
 
     await run_bot(transport, runner_args)
 

examples/quickstart/build.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+set -e
+
+VERSION="0.1"
+DOCKER_USERNAME="your_username"
+AGENT_NAME="quickstart"
+
+# Build the Docker image with the correct context
+echo "Building Docker image..."
+docker build --platform=linux/arm64 -t "$DOCKER_USERNAME/$AGENT_NAME:$VERSION" -t "$DOCKER_USERNAME/$AGENT_NAME:latest" .
+
+# Push the Docker images
+echo "Pushing Docker image $DOCKER_USERNAME/$AGENT_NAME:$VERSION..."
+docker push "$DOCKER_USERNAME/$AGENT_NAME:$VERSION"
+
+echo "Pushing Docker image $DOCKER_USERNAME/$AGENT_NAME:latest..."
+docker push "$DOCKER_USERNAME/$AGENT_NAME:latest"
+
+echo "Successfully built and pushed $DOCKER_USERNAME/$AGENT_NAME:$VERSION and $DOCKER_USERNAME/$AGENT_NAME:latest"

examples/quickstart/env.example

@@ -1,3 +1,6 @@
 DEEPGRAM_API_KEY=your_deepgram_api_key
 OPENAI_API_KEY=your_openai_api_key
-CARTESIA_API_KEY=your_cartesia_api_key
+CARTESIA_API_KEY=your_cartesia_api_key
+
+# Optional: Connect via Daily WebRTC locally
+DAILY_API_KEY=your_daily_api_key

examples/quickstart/pcc-deploy.toml

@@ -0,0 +1,6 @@
+agent_name = "quickstart"
+image = "your_username/quickstart:0.1"
+secret_set = "quickstart-secrets"
+
+[scaling]
+	min_agents = 1

examples/quickstart/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "pipecat-quickstart"
+version = "0.1.0"
+description = "Quickstart example for building voice AI bots with Pipecat"
+requires-python = ">=3.10"
+dependencies = [
+    "pipecat-ai[webrtc,daily,silero,deepgram,openai,cartesia,runner]>=0.0.79",
+    "pipecatcloud>=0.2.3"
+]
+
+[dependency-groups]
+dev = [
+    "ruff~=0.12.1",
+]
+
+[tool.ruff]
+line-length = 100
+[tool.ruff.lint]
+select = ["I"]

examples/quickstart/requirements.txt

@@ -1 +0,0 @@
-pipecat-ai[webrtc,silero,deepgram,openai,cartesia,runner]>=0.0.77