Metadata-Version: 2.4
Name: playpi
Version: 1.0.3
Summary: Automate AI chat workflows through browser automation
Project-URL: Documentation, https://github.com/twardoch/playpi#readme
Project-URL: Issues, https://github.com/twardoch/playpi/issues
Project-URL: Source, https://github.com/twardoch/playpi
Author-email: Adam Twardoch <adam+github@twardoch.com>
License: MIT
License-File: LICENSE
Keywords: ai,automation,browser,chat,gemini,playwright
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: fire>=0.5.0
Requires-Dist: html2text>=2020.1.16
Requires-Dist: loguru>=0.7.0
Requires-Dist: platformdirs>=3.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Provides-Extra: dev
Requires-Dist: absolufy-imports>=0.3.1; extra == 'dev'
Requires-Dist: isort>=6.0.1; extra == 'dev'
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pre-commit>=4.1.0; extra == 'dev'
Requires-Dist: pyupgrade>=3.19.1; extra == 'dev'
Requires-Dist: ruff>=0.9.7; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=3.0.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=2.0.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'docs'
Requires-Dist: sphinx>=7.2.6; extra == 'docs'
Provides-Extra: test
Requires-Dist: coverage[toml]>=7.6.12; extra == 'test'
Requires-Dist: pytest-asyncio>=0.25.3; extra == 'test'
Requires-Dist: pytest-benchmark[histogram]>=5.1.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-playwright>=0.4.0; extra == 'test'
Requires-Dist: pytest-xdist>=3.6.1; extra == 'test'
Requires-Dist: pytest>=8.3.4; extra == 'test'
Description-Content-Type: text/markdown

# PlayPi

Automate AI chat workflows through browser automation.

PlayPi provides simple, high-level functions for automating browser-based AI chat workflows, starting with Google Gemini Deep Research.

## Installation

```bash
pip install playpi
```

Or for development:

```bash
git clone https://github.com/twardoch/playpi
cd playpi
uv sync
```

## Quick Start

### Google Deep Research

```python
import asyncio
from playpi import google_deep_research

async def main():
    # Perform deep research on a topic
    result = await google_deep_research(
        "Analyze the impact of quantum computing on cryptography",
        headless=True,  # Run browser in background
        timeout=600,    # 10 minute timeout
        verbose=True    # Enable detailed logging
    )

    print(result)  # Markdown-formatted research results

asyncio.run(main())
```

### Command Line Interface

```bash
# Perform research and save to file
playpi google "What are the latest developments in renewable energy?" --output research.md

# Interactive mode (visible browser)
playpi google "Climate change mitigation strategies" --headless=false --verbose

# Test browser session
playpi test
```

## Prerequisites

### Authentication

Before using Google Deep Research, you need to:

1. **Install Playwright browsers**: `playwright install chromium`
2. **Login to Google**: Open https://gemini.google.com in your browser and sign in
3. **Browser profiles**: PlayPi reuses browser sessions, so you only need to login once

### System Requirements

- Python 3.12+
- Chromium browser (installed automatically)
- 2GB+ RAM for browser automation
- Internet connection

## Features

- ✅ **Google Gemini Deep Research** - Automated research with source compilation
- ✅ **Session Management** - Persistent authentication across multiple queries
- ✅ **Cross-Platform** - Works on Windows, macOS, and Linux
- ✅ **Concurrent Processing** - Run up to 3 research tasks simultaneously
- ✅ **Rich Output** - Clean Markdown formatting with links and structure
- ✅ **Error Handling** - Graceful handling of timeouts and UI changes

## API Reference

### `google_deep_research(prompt, **options)`

Perform Google Gemini Deep Research on a given prompt.

**Parameters:**
- `prompt` (str): Research query or question
- `headless` (bool): Run browser in headless mode (default: True)
- `timeout` (int): Maximum wait time in seconds (default: 600)
- `verbose` (bool): Enable detailed logging (default: False)
- `profile` (str): Browser profile name (reserved for future use)

**Returns:**
- `str`: Research results formatted as Markdown

**Raises:**
- `AuthenticationError`: Not logged in to Google/Gemini
- `PlayPiTimeoutError`: Research exceeded timeout limit
- `ProviderError`: UI elements not found or changed

## Development

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/playpi --cov-report=html

# Run specific test categories
uv run pytest tests/test_session.py -v
```

### Code Quality

```bash
# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking
uv run mypy src/playpi
```

## License

MIT License. See [LICENSE](LICENSE) for details.