diff --git a/README.md b/README.md index 6eca5af47..cf1263817 100644 --- a/README.md +++ b/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 -# Install the module -pip install pipecat-ai +1. Install uv -# Set up your environment -cp dot-env.template .env -``` + ```bash + 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 -pip install "pipecat-ai[option,...]" -``` +2. Install the module + + ```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 - python3 -m venv venv - source venv/bin/activate + ```bash + git clone https://github.com/pipecat-ai/pipecat.git + cd pipecat ``` -2. Install the development dependencies: +2. Install development and testing dependencies: - ```shell - pip install -r dev-requirements.txt + ```bash + 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 - 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,...]" + ```bash + uv run pre-commit install ``` ### Running tests -Install the test dependencies: +To run all tests, from the root directory: -```shell -pip install -r test-requirements.txt +```bash +uv run pytest ``` -From the root directory, run: +Run a specific test suite: -```shell -pytest +```bash +uv run pytest tests/test_name.py ``` ### Setting up your editor diff --git a/dot-env.template b/env.example similarity index 99% rename from dot-env.template rename to env.example index 696c2ca0a..0aed0eb83 100644 --- a/dot-env.template +++ b/env.example @@ -122,7 +122,6 @@ SONIOX_API_KEY= # Speechmatics SPEECHMATICS_API_KEY=... - # SambaNova SAMBANOVA_API_KEY=... diff --git a/examples/foundational/README.md b/examples/foundational/README.md index 16e3ce42f..91631017b 100644 --- a/examples/foundational/README.md +++ b/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: - -- **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: +1. Make sure you have uv installed: ```bash - python -m venv venv - source venv/bin/activate # On Windows: venv\Scripts\activate + curl -LsSf https://astral.sh/uv/install.sh | sh ``` -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. - -4. Run any example: +3. Create a `.env` file with your API keys: ```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 -need to setup a few things: +It is also possible to run the example through a Twilio phone number. You will need to setup a few things: 1. Install and run [ngrok](https://ngrok.com/download). - ```bash - ngrok http 7860 - ``` +```bash +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 --host 0.0.0.0 --port 8080 +uv run python --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). diff --git a/examples/foundational/requirements.txt b/examples/foundational/requirements.txt deleted file mode 100644 index 2f0c97b37..000000000 --- a/examples/foundational/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -pipecat-ai[webrtc,websocket,daily,deepgram,cartesia,silero,runner]>=0.0.77 \ No newline at end of file