ko-tasks-sdk 1.0.0__tar.gz

ko_tasks_sdk-1.0.0/.gitignore

@@ -0,0 +1,82 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Node
+node_modules/
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# uv
+uv.lock
+
+# Generated scaffold E2E tasks (examples/test_scaffold_combinations_e2e.py)
+examples/_scaffold_e2e/
+
+# Data directories (local dev)
+data/
+test-data/
+*.db
+*.sqlite3
+
+# Test fixture runtime artefacts (written by test runs)
+packages/server/tests/fixtures/*/environments/
+packages/server/tests/fixtures/*/task_registry.json
+packages/server/tests/fixtures/*/*-data/
+packages/server/tests/fixtures/*/node-test-data/
+
+# Package builds
+packages/sdk-python/dist/
+packages/server/dist/
+
+# Worktrees
+.worktrees/
+
+# Secrets
+.env
+.env.local
+.env.production
+.env.otel
+.env.otel-platform
+.env.prod-e2e
+.gitnexus
+uv.lock
+packages/ui-react/.next
+packages/ui-react/out
+.claude/skills
+.claude/skills/gitnexus
+.claude/skills/gitnexus/gitnexus-cli/SKILL.md
+.claude/skills/gitnexus/gitnexus-debugging/SKILL.md
+.claude/skills/gitnexus/gitnexus-exploring/SKILL.md
+.claude/skills/gitnexus/gitnexus-guide/SKILL.md
+.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md
+.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md
+.claude/

ko_tasks_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+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

ko_tasks_sdk-1.0.0/README.md

@@ -0,0 +1,123 @@
+# 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

ko_tasks_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ko-tasks-sdk"
+version = "1.0.0"
+description = "Python SDK for Komus Tasks — define, test, and deploy task workflows"
+readme = "README.md"
+requires-python = ">=3.13"
+license = {text = "MIT"}
+authors = [
+    {name = "Komus.ai", email = "codir@komus.ai"}
+]
+keywords = [
+    "task",
+    "workflow",
+    "sdk",
+    "automation",
+    "async",
+    "framework",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Distributed Computing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "aiofiles>=24.1.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.3",
+    "httpx>=0.27.0",
+    "click>=8.1.0",
+    "structlog>=24.4.0",
+    "rich>=14.0.0",
+    "InquirerPy>=0.3.4",
+    "ko-observability>=0.2.0,<0.3",
+    "opentelemetry-api>=1.27.0",
+    "opentelemetry-sdk>=1.27.0",
+]
+
+[project.urls]
+Documentation = "https://github.com/Komus-ai/ko-tasks-platform#readme"
+Repository = "https://github.com/Komus-ai/ko-tasks-platform"
+Issues = "https://github.com/Komus-ai/ko-tasks-platform/issues"
+Changelog = "https://github.com/Komus-ai/ko-tasks-platform/blob/main/CHANGELOG.md"
+
+[project.scripts]
+ko-tasks = "komus_tasks.cli:main"
+ko-tasks-agent = "komus_tasks.agent.__main__:main"
+
+[project.optional-dependencies]
+agent = ["websockets>=12"]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-asyncio>=0.24.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.8.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/komus_tasks"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/komus_tasks"]

ko_tasks_sdk-1.0.0/src/komus_tasks/__init__.py

@@ -0,0 +1,16 @@
+"""Komus Tasks Python SDK — Build and run tasks with ease."""
+
+from komus_tasks.context import TaskContext
+from komus_tasks.decorators import task, get_task_registry, discover_tasks_in_module
+from komus_tasks.thread_state import ThreadState
+from komus_tasks.version import __version__, get_sdk_version
+
+__all__ = [
+    "TaskContext",
+    "ThreadState",
+    "task",
+    "get_task_registry",
+    "discover_tasks_in_module",
+    "__version__",
+    "get_sdk_version",
+]

ko_tasks_sdk-1.0.0/src/komus_tasks/agent/__init__.py

@@ -0,0 +1,20 @@
+"""Remote worker agent (client side).
+
+The agent dials *into* the Komus Tasks server over a WebSocket (outbound-only —
+the VM running the agent needs no inbound ports / public IP), registers its
+runtimes and slot capacity, and on demand provisions task bundles and spawns the
+**existing local worker runner** (``python -m komus_tasks.worker`` /
+``node node-runner.js``). The worker's NDJSON protocol frames are tunnelled over
+the connection; the server's ``NetworkTransport`` is the other end of that pipe.
+
+Ships inside ``ko-tasks-sdk`` so ``pip install ko-tasks-sdk[agent]``
+provides the ``ko-tasks-agent`` console script.
+
+This package is importable **without** the optional ``websockets`` dependency:
+the import is performed lazily inside :class:`~komus_tasks.agent.client.AgentClient`
+so the SDK keeps importing cleanly when the ``agent`` extra is not installed.
+"""
+
+from komus_tasks.agent.client import AgentClient, AgentConfig
+
+__all__ = ["AgentClient", "AgentConfig"]

ko_tasks_sdk-1.0.0/src/komus_tasks/agent/__main__.py

@@ -0,0 +1,114 @@
+"""``ko-tasks-agent`` CLI — run a remote worker agent.
+
+Dials into a Komus Tasks server over WebSocket, registers this host's runtimes
+and slot capacity, then provisions task bundles and runs local workers on demand,
+tunnelling their protocol frames back to the server.
+
+Usage:
+    python -m komus_tasks.agent \\
+        --server-url wss://tasks.example.com/agent/connect \\
+        --token "$KO_TASKS_AGENT_TOKEN" \\
+        --labels python,node \\
+        --max-slots 8 \\
+        --work-dir /var/lib/ko-tasks-agent
+
+Environment fallbacks:
+    KO_TASKS_AGENT_SERVER_URL  →  --server-url
+    KO_TASKS_AGENT_TOKEN       →  --token
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from komus_tasks.agent.client import AgentClient, AgentConfig, HelloRejected
+from komus_tasks.logging import configure_logging, logger
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ko-tasks-agent",
+        description=(
+            "Run a Komus Tasks remote worker agent. The agent dials into the "
+            "server (outbound-only), registers its runtimes/slots, and runs "
+            "task workers on this host on demand."
+        ),
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument(
+        "--server-url",
+        default=os.environ.get("KO_TASKS_AGENT_SERVER_URL"),
+        help="WebSocket URL of the server agent gateway "
+        "(e.g. wss://host/agent/connect). Env: KO_TASKS_AGENT_SERVER_URL.",
+    )
+    parser.add_argument(
+        "--token",
+        default=os.environ.get("KO_TASKS_AGENT_TOKEN"),
+        help="Shared agent auth token presented in `hello`. Env: KO_TASKS_AGENT_TOKEN.",
+    )
+    parser.add_argument(
+        "--labels",
+        default="python",
+        help="Comma-separated runtimes this agent can run (e.g. python,node).",
+    )
+    parser.add_argument(
+        "--max-slots",
+        type=int,
+        default=4,
+        help="Maximum concurrent worker leases this agent will accept.",
+    )
+    parser.add_argument(
+        "--work-dir",
+        type=Path,
+        default=Path.home() / ".ko-tasks-agent" / "work",
+        help="Directory for unpacked task bundles and per-lease venvs.",
+    )
+    parser.add_argument(
+        "--agent-id",
+        default=None,
+        help="Stable agent identifier (defaults to host-pid).",
+    )
+    return parser
+
+
+def main() -> None:
+    configure_logging()
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    if not args.server_url:
+        parser.error("--server-url is required (or set KO_TASKS_AGENT_SERVER_URL)")
+    if not args.token:
+        parser.error("--token is required (or set KO_TASKS_AGENT_TOKEN)")
+
+    runtimes = [r.strip() for r in args.labels.split(",") if r.strip()]
+    if not runtimes:
+        runtimes = ["python"]
+
+    config_kwargs: dict = {
+        "server_url": args.server_url,
+        "token": args.token,
+        "runtimes": runtimes,
+        "max_slots": args.max_slots,
+        "work_dir": args.work_dir,
+    }
+    if args.agent_id:
+        config_kwargs["agent_id"] = args.agent_id
+
+    config = AgentConfig(**config_kwargs)
+    client = AgentClient(config)
+
+    try:
+        asyncio.run(client.run_forever())
+    except HelloRejected as exc:
+        logger.error("agent.rejected", reason=str(exc))
+        sys.exit(2)
+    except KeyboardInterrupt:
+        logger.info("agent.shutdown")
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()