178 lines
4.8 KiB
Markdown
178 lines
4.8 KiB
Markdown
# Claude Code Setup for Pipecat
|
|
|
|
This directory contains configuration and custom skills for working with the Pipecat project using Claude Code.
|
|
|
|
## Project Overview
|
|
|
|
Pipecat is an open-source Python framework for building real-time voice and multimodal conversational agents. It provides a composable, frame-based architecture for orchestrating audio, video, AI services, and conversation pipelines.
|
|
|
|
## Architecture
|
|
|
|
### Core Concepts
|
|
|
|
1. **Frames** - The fundamental data units in Pipecat (audio, text, images, system messages, etc.)
|
|
- Located in: `src/pipecat/frames/frames.py`
|
|
- Different frame types for different data: `AudioRawFrame`, `TextFrame`, `ImageRawFrame`, etc.
|
|
|
|
2. **Processors** - Processing units that receive, transform, and emit frames
|
|
- Base class: `src/pipecat/processors/frame_processor.py`
|
|
- Can be chained to form pipelines
|
|
- Examples: STT services, LLMs, TTS services, aggregators, etc.
|
|
|
|
3. **Pipelines** - Chains of processors that define data flow
|
|
- Created using the `Pipeline` class
|
|
- Processors linked using `link()` method or `|` operator
|
|
|
|
4. **Transports** - Handle input/output for audio/video streams
|
|
- WebRTC (Daily), WebSocket, Local audio, etc.
|
|
- Located in: `src/pipecat/transports/`
|
|
|
|
### Key Directories
|
|
|
|
- `src/pipecat/` - Main source code
|
|
- `frames/` - Frame definitions and utilities
|
|
- `processors/` - Base processors and common processors
|
|
- `services/` - AI service integrations (STT, TTS, LLM, etc.)
|
|
- `transports/` - Transport implementations
|
|
- `audio/` - Audio processing utilities
|
|
- `examples/` - Example applications and foundational examples
|
|
- `tests/` - Test suite
|
|
- `docs/` - Documentation source
|
|
|
|
## Development Workflow
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Install dependencies
|
|
uv sync --group dev --all-extras --no-extra gstreamer --no-extra krisp --no-extra local
|
|
|
|
# Install pre-commit hooks
|
|
uv run pre-commit install
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
uv run pytest
|
|
|
|
# Specific test file
|
|
uv run pytest tests/test_name.py
|
|
|
|
# With coverage
|
|
uv run coverage run --module pytest
|
|
uv run coverage report
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# Format code
|
|
uv run ruff format .
|
|
|
|
# Lint code
|
|
uv run ruff check .
|
|
|
|
# Fix linting issues
|
|
uv run ruff check --fix .
|
|
|
|
# Type checking
|
|
uv run pyright
|
|
|
|
# Run all pre-commit hooks
|
|
uv run pre-commit run --all-files
|
|
```
|
|
|
|
### Building
|
|
|
|
```bash
|
|
# Build package
|
|
uv build
|
|
```
|
|
|
|
## Custom Skills
|
|
|
|
This project includes custom Claude Code skills:
|
|
|
|
### `/docstring`
|
|
Document Python modules and classes using Google-style docstrings.
|
|
|
|
Usage: `/docstring ClassName`
|
|
|
|
### `/changelog`
|
|
Generate changelog entries using towncrier.
|
|
|
|
### `/pr-description`
|
|
Generate comprehensive PR descriptions based on changes.
|
|
|
|
## Coding Standards
|
|
|
|
1. **Docstrings** - Use Google-style docstrings for all public APIs
|
|
- Module docstrings required
|
|
- Class docstrings with purpose and event handlers
|
|
- Method docstrings with Args/Returns/Raises
|
|
- Constructor (`__init__`) must document all parameters
|
|
|
|
2. **Type Hints** - Required for all function signatures
|
|
- Use `from typing import ...` for complex types
|
|
- Dataclasses should have field type annotations
|
|
|
|
3. **Async/Await** - Consistent use of async patterns
|
|
- Most processors use async methods
|
|
- Tests use pytest-asyncio
|
|
|
|
4. **Code Style**
|
|
- Line length: 100 characters max
|
|
- Ruff for linting and formatting
|
|
- Follow existing patterns in the codebase
|
|
|
|
5. **Testing**
|
|
- Write tests for new features
|
|
- Use pytest fixtures for common setups
|
|
- Mock external services when appropriate
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Make changes following coding standards
|
|
4. Add tests for new functionality
|
|
5. Run pre-commit hooks: `uv run pre-commit run --all-files`
|
|
6. Submit a pull request
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a New Service Integration
|
|
|
|
1. Create service file in `src/pipecat/services/<category>/`
|
|
2. Inherit from appropriate base class (e.g., `TTSService`, `LLMService`)
|
|
3. Implement required abstract methods
|
|
4. Add service to `pyproject.toml` optional dependencies
|
|
5. Add documentation
|
|
6. Add tests in `tests/`
|
|
|
|
### Adding a New Processor
|
|
|
|
1. Create processor in `src/pipecat/processors/`
|
|
2. Inherit from `FrameProcessor` or appropriate subclass
|
|
3. Override `process_frame()` method
|
|
4. Handle relevant frame types
|
|
5. Emit frames using `await self.push_frame()`
|
|
6. Add tests
|
|
|
|
### Adding a New Frame Type
|
|
|
|
1. Add frame definition to `src/pipecat/frames/frames.py`
|
|
2. Inherit from appropriate base frame class
|
|
3. Use `@dataclass` decorator for data frames
|
|
4. Document the frame type and its fields
|
|
5. Update processors that should handle this frame type
|
|
|
|
## Resources
|
|
|
|
- [Documentation](https://docs.pipecat.ai)
|
|
- [GitHub Repository](https://github.com/pipecat-ai/pipecat)
|
|
- [Examples](https://github.com/pipecat-ai/pipecat-examples)
|
|
- [Discord Community](https://discord.gg/pipecat)
|