Metadata-Version: 2.5
Name: ko-tasks-sdk
Version: 1.0.0
Summary: Python SDK for Komus Tasks — define, test, and deploy task workflows
Project-URL: Documentation, https://github.com/Komus-ai/ko-tasks-platform#readme
Project-URL: Repository, https://github.com/Komus-ai/ko-tasks-platform
Project-URL: Issues, https://github.com/Komus-ai/ko-tasks-platform/issues
Project-URL: Changelog, https://github.com/Komus-ai/ko-tasks-platform/blob/main/CHANGELOG.md
Author-email: "Komus.ai" <codir@komus.ai>
License: MIT
Keywords: async,automation,framework,sdk,task,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiofiles>=24.1.0
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: ko-observability<0.3,>=0.2.0
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-sdk>=1.27.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.0.0
Requires-Dist: structlog>=24.4.0
Provides-Extra: agent
Requires-Dist: websockets>=12; extra == 'agent'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Komus Tasks SDK (Python)

Python SDK for building, testing, and deploying tasks with the Komus Tasks.

## Installation

First public PyPI release: **1.0.0** (`ko-tasks` CLI and bundled agent skills).

```bash
pip install ko-tasks-sdk
```

## Quick Start

### 1. Create a new task

```bash
ko-tasks init my-task --runtime python
cd my-task
```

### 2. Edit `task.py`

```python
async def run(context):
    context.report_progress(0.0, "Starting...")

    inputs = context.get_inputs()
    # ... your logic ...

    context.report_progress(1.0, "Done")
    return [{"kind": "text", "text": "Result"}]
```

### 3. Run locally

```bash
ko-tasks run
```

### 4. Deploy

```bash
ko-tasks deploy --server https://tasks.example.com --admin-key YOUR_ADMIN_KEY
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `ko-tasks init <name>` | Scaffold a new task project |
| `ko-tasks run` | Start a local dev server |
| `ko-tasks package --task-dir . -o task.zip` | Package task for deployment |
| `ko-tasks deploy -s URL --admin-key KEY` | Deploy to remote server |
| `ko-tasks status <thread_id> -s URL --api-key KEY` | Check thread status |
| `ko-tasks list -s URL --admin-key KEY` | List deployed tasks |

## TaskContext API

The `context` object passed to your task function provides:

### Inputs & Outputs
- `context.get_inputs()` — Returns list of input artifacts
- Return a list of output artifacts from your function

### Progress Reporting
- `context.report_progress(fraction, message)` — Report progress (0.0 to 1.0)

### Cooperative Control
- `context.check_pause()` — Blocks if task is paused, raises if cancelled
- `context.is_paused()` — Returns True if pause requested
- `context.is_cancelled()` — Returns True if cancellation requested

### Artifacts
- `context.store_artifact(data, filename, media_type)` — Store output artifact
- `context.get_artifact(artifact_id)` — Retrieve an artifact

### Configuration
- `context.get_config(key)` — Get a configuration/credential value

## Task Definition (task.yaml)

```yaml
name: my-task
version: 1.0.0
description: "What the task does"
entry_point: task:run
runtime: python                   # python | node

input_schemas:
  - ref: input_data
    kind: text
    required: true
    description: "Input description"

output_schemas:
  - kind: file
    media_type: application/pdf
    description: "Output description"

requirements:
  - name: API_KEY
    required: true
    description: "External API key"
```

## Development

```bash
# Clone the monorepo
git clone https://github.com/Komus-ai/ko-tasks-platform.git
cd ko-tasks-platform

# Install in development mode
uv sync

# Run SDK tests
uv run --package ko-tasks-sdk pytest packages/sdk-python/tests/ -v
```

## License

MIT
