Metadata-Version: 2.4
Name: pipecat-replicate
Version: 0.1.0
Summary: Replicate image generation integration for Pipecat
Project-URL: Repository, https://github.com/bnovik0v/pipecat-replicate
Project-URL: Issues, https://github.com/bnovik0v/pipecat-replicate/issues
Author-email: Borislav Novikov <borislav@polaro.com>
License-Expression: BSD-2-Clause
License-File: LICENSE
Requires-Python: <3.14,>=3.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: loguru>=0.7
Requires-Dist: pillow>=10.0
Requires-Dist: pipecat-ai>=0.0.108
Description-Content-Type: text/markdown

# pipecat-replicate

[Replicate](https://replicate.com/) image generation integration for [Pipecat](https://github.com/pipecat-ai/pipecat) — a framework for building voice and multimodal conversational AI applications.

## Pipecat Compatibility

**Tested with Pipecat v0.0.108**

## Features

- Text-to-image generation using any Replicate-hosted model
- Official models (`owner/name`) and versioned community models (`owner/name:version`)
- Sync prediction requests with automatic polling fallback
- Returns `URLImageRawFrame` for direct use in Pipecat pipelines
- Configurable via the standard Pipecat `Settings` dataclass pattern

## Installation

### Using pip

```bash
pip install pipecat-replicate
```

### Using uv

```bash
uv add pipecat-replicate
```

### From source

```bash
git clone https://github.com/bnovik0v/pipecat-replicate.git
cd pipecat-replicate
pip install -e .
```

## Quick Start

1. Get your Replicate API token at https://replicate.com/account/api-tokens

2. Set the environment variable:

```bash
export REPLICATE_API_TOKEN=r8_...
```

3. Use in a Pipecat pipeline:

```python
import aiohttp
from pipecat.frames.frames import TextFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineTask
from pipecat_replicate import ReplicateImageGenService

async with aiohttp.ClientSession() as session:
    imagegen = ReplicateImageGenService(
        aiohttp_session=session,
        settings=ReplicateImageGenService.Settings(
            model="black-forest-labs/flux-schnell",
            aspect_ratio="1:1",
        ),
    )

    pipeline = Pipeline([imagegen, ...])
    task = PipelineTask(pipeline)
    await task.queue_frames([TextFrame("a cat in the style of a screenprint poster")])

    runner = PipelineRunner()
    await runner.run(task)
```

## Configuration

### Settings

| Field                    | Type   | Default                            | Description                               |
| ------------------------ | ------ | ---------------------------------- | ----------------------------------------- |
| `model`                  | `str`  | `"black-forest-labs/flux-schnell"` | Replicate model identifier                |
| `aspect_ratio`           | `str`  | `"1:1"`                            | Aspect ratio for generated images         |
| `num_outputs`            | `int`  | `1`                                | Number of images to generate (1–4)        |
| `num_inference_steps`    | `int`  | `4`                                | Number of denoising steps                 |
| `seed`                   | `int`  | `None`                             | Random seed for reproducible generation   |
| `output_format`          | `str`  | `"webp"`                           | Output image format                       |
| `output_quality`         | `int`  | `80`                               | Output quality (0–100)                    |
| `disable_safety_checker` | `bool` | `False`                            | Whether to disable the model safety check |
| `go_fast`                | `bool` | `True`                             | Use the model's fast generation mode      |
| `megapixels`             | `str`  | `"1"`                              | Approximate megapixel count               |

### Constructor Parameters

| Parameter            | Type                   | Default                                | Description                          |
| -------------------- | ---------------------- | -------------------------------------- | ------------------------------------ |
| `aiohttp_session`    | `aiohttp.ClientSession`| *(required)*                           | HTTP session for API requests        |
| `api_token`          | `str`                  | `$REPLICATE_API_TOKEN`                 | Replicate API token                  |
| `settings`           | `Settings`             | *(see defaults above)*                 | Generation settings                  |
| `base_url`           | `str`                  | `"https://api.replicate.com/v1"`       | API base URL                         |
| `wait_timeout_secs`  | `int`                  | `60`                                   | Sync wait timeout (Prefer header)    |
| `poll_interval_secs` | `float`                | `0.5`                                  | Poll interval for async predictions  |
| `max_poll_attempts`  | `int`                  | `120`                                  | Maximum number of polling attempts   |

## Examples

See [`examples/basic_image_gen.py`](examples/basic_image_gen.py) for a complete example that generates an image and displays it in a Tk window.

```bash
REPLICATE_API_TOKEN=r8_... python examples/basic_image_gen.py
```

## Running Tests

```bash
uv sync --group dev
uv run pytest
```

## License

BSD 2-Clause — see [LICENSE](LICENSE).
