# presentations-ai

Python client for the [Presentations.AI](https://presentations.ai) REST API. Create, transform, and manage presentations programmatically.

[![PyPI version](https://img.shields.io/pypi/v/presentations-ai)](https://pypi.org/project/presentations-ai/)
[![Python versions](https://img.shields.io/pypi/pyversions/presentations-ai)](https://pypi.org/project/presentations-ai/)
[![License](https://img.shields.io/pypi/l/presentations-ai)](https://github.com/presentations-ai/integrations/blob/main/LICENSE)

## Installation

```bash
pip install presentations-ai
```

For Claude-powered presentation creation:

```bash
pip install presentations-ai[cloudy]
```

## Quick start

```python
from presentations_ai import PresentationsAI

client = PresentationsAI(api_key="pai_...")

result = client.create_from_topic(
    topic="Series B Pitch: AI-Powered Design Platform",
    export_type="pptx",
    slide_count=12,
)

print(result.docurl)  # https://app.presentations.ai/view/...
```

## Async support

```python
from presentations_ai import AsyncPresentationsAI

async with AsyncPresentationsAI(api_key="pai_...") as client:
    result = await client.create_from_topic(
        topic="Q4 Product Roadmap",
        export_type="pptx",
    )
```

## API methods

| Method | Description |
|--------|-------------|
| `create_from_topic()` | Generate a presentation from a topic description |
| `create_from_file()` | Convert a file (PDF, DOCX, PPTX) into a presentation |
| `create_single_slide()` | Generate a single slide |
| `create_from_content()` | Build from structured slide content (title + body per slide) |
| `create_from_raw_content()` | Transform raw text into slides |
| `update_slides()` | Update slides in an existing presentation |
| `check_job_status()` | Check the status of an async job |

## Cloudy runtime (Claude + MCP)

Create presentations with natural language using Claude:

```python
from presentations_ai.cloudy import CloudyRuntime

cloudy = CloudyRuntime(anthropic_api_key="sk-ant-...")

response = cloudy.chat(
    "Create a 12-slide investor pitch deck for an AI-powered design platform",
    presentations_api_key="pai_...",
)

print(response.text)              # Claude's natural language response
print(response.presentation_url)  # https://app.presentations.ai/view/...
```

## Configuration

```python
client = PresentationsAI(
    api_key="pai_...",             # or set PRESENTATIONS_AI_API_KEY env var
    base_url="...",                # default: https://developers.presentations.ai
    timeout_ms=60_000,             # default: 60 seconds
    max_retries=3,                 # default: 3 retries with exponential backoff
)
```

## Error handling

```python
from presentations_ai import PresentationsAI, AuthenticationError, RateLimitError

try:
    result = client.create_from_topic(topic="...", export_type="pptx")
except AuthenticationError as e:
    print(e.code)         # "API_UNAUTHORIZED"
    print(e.remediation)  # "Verify your API key..."
except RateLimitError:
    print("Too many requests, wait and retry")
```

## Polling async jobs

```python
from presentations_ai import PresentationsAI, poll_until_complete

client = PresentationsAI(api_key="pai_...")
job = client.create_from_topic(topic="...", export_type="pptx")

if hasattr(job, "job_id"):
    result = poll_until_complete(client, job.job_id)
    print(result.docurl)
```

## Requirements

- Python >= 3.10
- [Presentations.AI API key](https://developers.presentations.ai)

## License

[MIT](https://github.com/presentations-ai/integrations/blob/main/LICENSE)
