Merge pull request #2355 from pipecat-ai/mb/update-readme-for-uv

Update the README with uv-centric steps

README.md

@@ -69,80 +69,80 @@ You can connect to Pipecat from any platform using our official SDKs:
 
 ## ⚡ Getting started
 
-You can get started with Pipecat running on your local machine, then move your agent processes to the cloud when you’re ready.
+You can get started with Pipecat running on your local machine, then move your agent processes to the cloud when you're ready.
 
-```shell
+1. Install uv
-# Install the module
-pip install pipecat-ai
 
-# Set up your environment
+   ```bash
-cp dot-env.template .env
+   curl -LsSf https://astral.sh/uv/install.sh | sh
-```
+   ```
 
-To keep things lightweight, only the core framework is included by default. If you need support for third-party AI services, you can add the necessary dependencies with:
+   > **Need help?** Refer to the [uv install documentation](https://docs.astral.sh/uv/getting-started/installation/).
 
-```shell
+2. Install the module
-pip install "pipecat-ai[option,...]"
+
-```
+   ```bash
+   # For new projects
+   uv init my-pipecat-app
+   cd my-pipecat-app
+   uv add pipecat-ai
+
+   # Or for existing projects
+   uv add pipecat-ai
+   ```
+
+3. Set up your environment
+
+   ```bash
+   cp env.example .env
+   ```
+
+4. To keep things lightweight, only the core framework is included by default. If you need support for third-party AI services, you can add the necessary dependencies with:
+
+   ```bash
+   uv add "pipecat-ai[option,...]"
+   ```
+
+> **Using pip?** You can still use `pip install pipecat-ai` and `pip install "pipecat-ai[option,...]"` to get set up.
 
 ## 🧪 Code examples
 
 - [Foundational](https://github.com/pipecat-ai/pipecat/tree/main/examples/foundational) — small snippets that build on each other, introducing one or two concepts at a time
 - [Example apps](https://github.com/pipecat-ai/pipecat-examples) — complete applications that you can use as starting points for development
 
-## 🛠️ Hacking on the framework itself
+## 🛠️ Contributing to the framework
 
-1. Set up a virtual environment before following these instructions. From the root of the repo:
+1. Clone the repository and navigate to it:
 
-   ```shell
+   ```bash
-   python3 -m venv venv
+   git clone https://github.com/pipecat-ai/pipecat.git
-   source venv/bin/activate
+   cd pipecat
    ```
 
-2. Install the development dependencies:
+2. Install development and testing dependencies:
 
-   ```shell
+   ```bash
-   pip install -r dev-requirements.txt
+   uv sync --group dev --all-extras --no-extra krisp
    ```
 
-3. Install the git pre-commit hooks (these help ensure your code follows project rules):
+3. Install the git pre-commit hooks:
 
-   ```shell
+   ```bash
-   pre-commit install
+   uv run pre-commit install
-   ```
-
-4. Install the `pipecat-ai` package locally in editable mode:
-
-   ```shell
-   pip install -e .
-   ```
-
-   > The `-e` or `--editable` option allows you to modify the code without reinstalling.
-
-5. Include optional dependencies as needed. For example:
-
-   ```shell
-   pip install -e ".[daily,deepgram,cartesia,openai,silero]"
-   ```
-
-6. (Optional) If you want to use this package from another directory:
-
-   ```shell
-   pip install "path_to_this_repo[option,...]"
    ```
 
 ### Running tests
 
-Install the test dependencies:
+To run all tests, from the root directory:
 
-```shell
+```bash
-pip install -r test-requirements.txt
+uv run pytest
 ```
 
-From the root directory, run:
+Run a specific test suite:
 
-```shell
+```bash
-pytest
+uv run pytest tests/test_name.py
 ```
 
 ### Setting up your editor

env.example

@@ -122,7 +122,6 @@ SONIOX_API_KEY=
 # Speechmatics
 SPEECHMATICS_API_KEY=...
 
-
 # SambaNova
 SAMBANOVA_API_KEY=...
 

examples/foundational/README.md

@@ -2,70 +2,71 @@
 
 This directory contains examples showing how to build voice and multimodal agents with Pipecat. Each example demonstrates specific features, progressing from basic to advanced concepts.
 
-## Learning Paths
+## Setup
 
-Depending on what you're trying to build, these learning paths will guide you through relevant examples:
+1. Make sure you have uv installed:
-
-- **New to Pipecat**: Start with examples [01](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/01-say-one-thing.py), [02](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/02-llm-say-one-thing.py), [07](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/07-interruptible.py)
-- **Building conversational bots**: [07](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/07-interruptible.py), [10](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/10-wake-phrase.py), [38](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/38-smart-turn-fal.py)
-- **Common add-on capabilities**: [17](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/17-detect-user-idle.py), [24](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/24-stt-mute-filter.py), [28](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/28-transcription-processor.py), [34](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/34-audio-recording.py)
-- **Adding visual capabilities**: [03](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/03-still-frame.py), [12](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/12a-describe-video-gemini-flash.py), [26](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/26c-gemini-multimodal-live-video.py)
-- **Advanced agent capabilities**: [14](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/14-function-calling.py), [20](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/20a-persistent-context-openai.py), [37](https://github.com/pipecat-ai/pipecat/blob/main/examples/foundational/37-mem0.py)
-
-## Quick Start
-
-1. Set up a virtual environment:
 
    ```bash
-   python -m venv venv
+   curl -LsSf https://astral.sh/uv/install.sh | sh
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
    ```
 
-2. Install dependencies:
+   > **Need help?** Refer to the [uv install documentation](https://docs.astral.sh/uv/getting-started/installation/).
+
+2. Create a venv and install example dependencies:
 
    ```bash
-   pip install -r requirements.txt
+   uv sync --all-extras --no-extra krisp
    ```
 
-3. Create a `.env` file with your API keys.
+3. Create a `.env` file with your API keys:
-
-4. Run any example:
 
    ```bash
-   python 01-say-one-thing.py
+   cp env.example .env
+   # Edit .env with your API keys
    ```
 
-5. Open the web interface at http://localhost:7860 and click "Connect"
+4. Navigate to the examples directory:
+
+   ```bash
+   cd examples/foundational
+   ```
+
+5. Run any example:
+
+   ```bash
+   uv run python 01-say-one-thing.py
+   ```
+
+6. Open the web interface at http://localhost:7860/client/ and click "Connect"
 
 ## Running examples with other transports
 
-It is possible to run most of the examples with other transports such as Twilio or Daily.
+Most examples support running with other transports, like Twilio or Daily.
 
 ### Daily
 
 You need to create a Daily account at https://dashboard.daily.co/u/signup. Once signed up, you can create your own room from the dashboard and set the environment variables `DAILY_SAMPLE_ROOM_URL` and `DAILY_API_KEY`. Alternatively, you can let the example create a room for you (still needs `DAILY_API_KEY` environment variable). Then, start any example with `-t daily`:
 
 ```bash
-python 07-interruptible.py -t daily
+uv run 07-interruptible.py -t daily
 ```
 
 ### Twilio
 
-It is also possible to run the example through a Twilio phone number. You will
+It is also possible to run the example through a Twilio phone number. You will need to setup a few things:
-need to setup a few things:
 
 1. Install and run [ngrok](https://ngrok.com/download).
 
-  ```bash
+```bash
-  ngrok http 7860
+ngrok http 7860
-  ```
+```
 
 2. Configure your Twilio phone number. One way is to setup a TwiML app and set the request URL to the ngrok URL from step (1). Then, set your phone number to use the new TwiML app.
 
 Then, run the example with:
 
 ```bash
-python 07-interruptible.py -t twilio -x NGROK_HOST_NAME (no protocol)
+uv run 07-interruptible.py -t twilio -x NGROK_HOST_NAME
 ```
 
 ## Examples by Feature
@@ -133,21 +134,18 @@ python 07-interruptible.py -t twilio -x NGROK_HOST_NAME (no protocol)
 
 - **[16-gpu-container-local-bot.py](./16-gpu-container-local-bot.py)**: GPU-accelerated local bot (Performance measurement)
 
-### Utilities
-
 ## Advanced Usage
 
 ### Customizing Network Settings
 
 ```bash
-python <example-name> --host 0.0.0.0 --port 8080
+uv run python <example-name> --host 0.0.0.0 --port 8080
 ```
 
 ### Troubleshooting
 
 - **No audio/video**: Check browser permissions for microphone and camera
 - **Connection errors**: Verify API keys in `.env` file
-- **Missing dependencies**: Run `pip install -r requirements.txt`
 - **Port conflicts**: Use `--port` to change the port
 
-For more examples, visit our [GitHub repository](https://github.com/pipecat-ai/pipecat/tree/main/examples).
+For more examples, visit our the [`pipecat-examples repository](https://github.com/pipecat-ai/pipecat-examples).

examples/foundational/requirements.txt

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