Metadata-Version: 2.4
Name: openhands-automation
Version: 1.0.0a2
Summary: OpenHands automation service
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: alembic>=1.14
Requires-Dist: asyncpg>=0.30
Requires-Dist: boto3>=1.35
Requires-Dist: cachetools>=7.0.5
Requires-Dist: cloud-sql-python-connector[asyncpg]>=1.16
Requires-Dist: croniter>=2
Requires-Dist: fastapi>=0.115
Requires-Dist: google-cloud-storage>=2.18
Requires-Dist: httpx>=0.27
Requires-Dist: jmespath>=1.0
Requires-Dist: openhands-sdk==1.22.0
Requires-Dist: openhands-workspace==1.22.0
Requires-Dist: pg8000>=1.31
Requires-Dist: pydantic-settings>=2
Requires-Dist: pydantic>=2
Requires-Dist: python-json-logger>=3
Requires-Dist: sqlalchemy[asyncio]>=2
Requires-Dist: tenacity>=9.1.4
Requires-Dist: uvicorn[standard]>=0.30
Description-Content-Type: text/markdown

# OpenHands Automation Service

> ⚠️ **Beta**: This project is currently in beta. APIs and features may change without notice.

Scheduled and event-driven automation execution for OpenHands Cloud. This service allows users to create automations that run on a schedule (cron) or in response to events (webhooks).

## Features

- **Scheduled Automations**: Run OpenHands conversations on a cron schedule
- **Event-Driven**: Trigger automations via webhooks (e.g., GitHub events)
- **API Key Management**: Per-user API keys for secure automation access
- **Run History**: Track automation runs with status and results

## Development

### Prerequisites

- Python 3.12+
- [uv](https://github.com/astral-sh/uv) for dependency management
- PostgreSQL (or use testcontainers for testing)

### Setup

```bash
# Install dependencies
uv sync --group dev

# Run the service locally (requires PostgreSQL)
uv run uvicorn openhands.automation.app:app --host 0.0.0.0 --port 8000 --reload
```

### Testing

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=openhands/automation --cov-report=term-missing
```

### Code Quality

```bash
# Run pre-commit hooks
uv run pre-commit run --all-files

# Format code
uv run ruff format

# Lint code
uv run ruff check --fix

# Type check
uv run pyright
```

### Database Migrations

```bash
# Create a new migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head
```

## Docker

```bash
# Build the image
docker build -t automation -f containers/Dockerfile .

# Run the container
docker run -p 8000:8000 automation
```

## Project Structure

```
openhands/
└── automation/      # Main application package (openhands.automation namespace)
    ├── app.py           # FastAPI application entry point
    ├── router.py        # API routes for CRUD operations
    ├── scheduler.py     # Background scheduler for cron jobs
    ├── dispatcher.py    # Dispatches pending runs to OpenHands
    ├── models.py        # SQLAlchemy models
    ├── schemas.py       # Pydantic schemas for API
    └── utils/           # Utility functions
migrations/          # Alembic database migrations
tests/               # Unit tests
containers/          # Docker configuration
```

## Deployment

This service is deployed via the [deploy repository](https://github.com/All-Hands-AI/deploy). Docker images are automatically built and pushed to `ghcr.io/openhands/automation` on every push to main and on tags.
