Metadata-Version: 2.4
Name: nexora-tasks-sdk
Version: 1.0.1
Summary: Python SDK for Nexora Tasks — define, test, and deploy task workflows
Project-URL: Documentation, https://github.com/Tessi-Wekey/tasks-platform#readme
Project-URL: Repository, https://github.com/Tessi-Wekey/tasks-platform
Project-URL: Issues, https://github.com/Tessi-Wekey/tasks-platform/issues
Project-URL: Changelog, https://github.com/Tessi-Wekey/tasks-platform/blob/main/CHANGELOG.md
Author-email: Cinco AI <dev@cinco.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: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: opentelemetry-api>=1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=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: 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

# Nexora Tasks SDK (Python)

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

## Installation

```bash
pip install nexora-tasks-sdk
```

## Quick Start

### 1. Create a new task

```bash
task 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
task run
```

### 4. Deploy

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

## CLI Commands

| Command | Description |
|---------|-------------|
| `task init <name>` | Scaffold a new task project |
| `task run` | Start a local dev server |
| `task package -t . -o task.zip` | Package task for deployment |
| `task deploy -s URL -k KEY` | Deploy to remote server |
| `task status <thread_id> -s URL -k KEY` | Check thread status |
| `task list -s URL -k 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/Tessi-Wekey/tasks-platform.git
cd tasks-platform

# Install in development mode
uv sync

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

## License

MIT
