continuum-task-server-sdk 0.0.9__py3-none-any.whl

continuum_task_server/__init__.py

@@ -0,0 +1,36 @@
+"""Continuum Task Server SDK for Python."""
+
+from __future__ import annotations
+
+from .client import ContinuumClient
+from .exceptions import (
+    BadRequestError,
+    ConflictError,
+    ContinuumError,
+    ForbiddenError,
+    NotFoundError,
+    ServerError,
+    UnauthorizedError,
+)
+from .models import Content, QueueItem, TaskItem, TaskItemVersion, TaskStatus, TaskType
+from .server import TaskServer
+
+__all__ = [
+    "BadRequestError",
+    "ConflictError",
+    "Content",
+    "ContinuumClient",
+    "ContinuumError",
+    "ForbiddenError",
+    "NotFoundError",
+    "QueueItem",
+    "ServerError",
+    "TaskItem",
+    "TaskItemVersion",
+    "TaskServer",
+    "TaskStatus",
+    "TaskType",
+    "UnauthorizedError",
+]
+
+__version__ = "0.1.0"

continuum_task_server/_http.py

@@ -0,0 +1,142 @@
+"""Internal HTTP wrapper. Handles Api-Key auth, JSON (de)serialization, and error mapping."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+
+from .exceptions import ContinuumError, error_for_status
+
+logger = logging.getLogger("continuum_task_server")
+
+
+def _normalize_base_url(url: str) -> str:
+    return url[:-1] if url.endswith("/") else url
+
+
+class HttpClient:
+    """Thin httpx wrapper. Not part of the public API."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        connect_timeout: float = 10.0,
+        request_timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url must not be empty")
+        if not api_key:
+            raise ValueError("api_key must not be empty")
+        self.base_url = _normalize_base_url(base_url)
+        self.api_key = api_key
+        timeout = httpx.Timeout(request_timeout, connect=connect_timeout)
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={"Api-Key": api_key},
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> HttpClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _raise_for_status(self, response: httpx.Response) -> None:
+        if response.status_code >= 400:
+            body = response.text
+            logger.error(
+                "HTTP %s on %s %s: %s",
+                response.status_code,
+                response.request.method,
+                response.request.url,
+                body,
+            )
+            raise error_for_status(response.status_code, body)
+
+    def get_json(self, path: str) -> Any:
+        try:
+            response = self._client.get(path, headers={"Content-Type": "application/json"})
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def get_bytes(self, path: str) -> tuple[bytes, str] | None:
+        """Returns (data, content_type) tuple, or None on 204."""
+        try:
+            response = self._client.get(path)
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        if response.status_code == 204:
+            return None
+        self._raise_for_status(response)
+        mime = response.headers.get("Content-Type", "application/octet-stream")
+        return response.content, mime
+
+    def post_json(self, path: str, body: Any) -> Any:
+        payload = json.dumps(body, default=_json_default) if body is not None else "{}"
+        try:
+            response = self._client.post(
+                path,
+                content=payload,
+                headers={"Content-Type": "application/json"},
+            )
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+    def post_optional(self, path: str, body: Any) -> Any | None:
+        """POST that may return 204 No Content (e.g. claim)."""
+        return self.post_json(path, body)
+
+    def patch_json(self, path: str, body: Any) -> Any:
+        payload = json.dumps(body, default=_json_default) if body is not None else "{}"
+        try:
+            response = self._client.request(
+                "PATCH",
+                path,
+                content=payload,
+                headers={"Content-Type": "application/json"},
+            )
+        except httpx.HTTPError as e:
+            raise ContinuumError(f"Request failed: {e}") from e
+        self._raise_for_status(response)
+        if response.status_code == 204 or not response.content:
+            return None
+        return response.json()
+
+
+def _json_default(obj: Any) -> Any:
+    """Fallback JSON encoder for UUIDs, datetimes, enums."""
+    import datetime as _dt
+    import enum as _enum
+    import uuid as _uuid
+
+    if isinstance(obj, _uuid.UUID):
+        return str(obj)
+    if isinstance(obj, _dt.datetime):
+        return obj.isoformat()
+    if isinstance(obj, _enum.Enum):
+        return obj.value
+    raise TypeError(f"Object of type {type(obj).__name__} is not JSON serializable")
+
+
+def drop_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Strip None values from a dict (mirrors @JsonInclude.NON_NULL)."""
+    return {k: v for k, v in d.items() if v is not None}

continuum_task_server/client.py

@@ -0,0 +1,349 @@
+"""ContinuumClient - pythonic mirror of the Java SDK."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+from urllib.parse import quote
+from uuid import UUID
+
+import httpx
+
+from ._http import HttpClient, drop_none
+from .models import Content, QueueItem, TaskItem, TaskItemVersion, TaskStatus, TaskType
+
+
+def _encode_input(data: Any) -> str | None:
+    """Accept dict/list/str/None and return a JSON string (or None)."""
+    if data is None:
+        return None
+    if isinstance(data, str):
+        return data
+    return json.dumps(data)
+
+
+class TaskTypesApi:
+    _PATH = "/api/management/task-types"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> list[TaskType]:
+        data = self._http.get_json(self._PATH) or []
+        return [TaskType.model_validate(item) for item in data]
+
+    def get_by_id(self, task_type_id: UUID | str) -> TaskType:
+        return TaskType.model_validate(self._http.get_json(f"{self._PATH}/{task_type_id}"))
+
+    def get_by_name(self, name: str) -> TaskType:
+        return TaskType.model_validate(
+            self._http.get_json(f"{self._PATH}/by-name?name={quote(name)}")
+        )
+
+    def save(
+        self,
+        *,
+        id: UUID | str | None = None,
+        name: str | None = None,
+        description: str | None = None,
+        active_flag: bool | None = None,
+        organization_id: UUID | str | None = None,
+        is_core: bool | None = None,
+        max_duration_sec: int | None = None,
+        heartbeat_timeout_sec: int | None = None,
+    ) -> TaskType:
+        """Create (no id) or update (with id) a task type."""
+        body = drop_none(
+            {
+                "id": str(id) if id else None,
+                "name": name,
+                "description": description,
+                "activeFlag": active_flag,
+                "organizationId": str(organization_id) if organization_id else None,
+                "isCore": is_core,
+                "maxDurationSec": max_duration_sec,
+                "heartbeatTimeoutSec": heartbeat_timeout_sec,
+            }
+        )
+        return TaskType.model_validate(self._http.post_json(self._PATH, body))
+
+    def create(
+        self,
+        name: str,
+        *,
+        organization_id: UUID | str | None = None,
+        is_core: bool = False,
+        **kwargs: Any,
+    ) -> TaskType:
+        return self.save(
+            name=name,
+            organization_id=organization_id,
+            is_core=is_core,
+            **kwargs,
+        )
+
+
+class TaskItemVersionsApi:
+    _PATH = "/api/management/task-items"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, task_item_id: UUID | str) -> list[TaskItemVersion]:
+        data = self._http.get_json(f"{self._PATH}/{task_item_id}/versions") or []
+        return [TaskItemVersion.model_validate(item) for item in data]
+
+    def get_by_id(self, version_id: UUID | str) -> TaskItemVersion:
+        return TaskItemVersion.model_validate(
+            self._http.get_json(f"{self._PATH}/versions/{version_id}")
+        )
+
+    def create(
+        self,
+        task_item_id: UUID | str,
+        *,
+        main_path: str,
+        item_definition: str | dict | list | None = None,
+        content: bytes | None = None,
+        mime_type: str | None = None,
+    ) -> TaskItemVersion:
+        body: dict[str, Any] = {"mainPath": main_path}
+        if item_definition is not None:
+            body["itemDefinition"] = (
+                item_definition if isinstance(item_definition, str) else json.dumps(item_definition)
+            )
+        if content is not None:
+            body["contentBytes"] = base64.b64encode(content).decode("ascii")
+            if mime_type:
+                body["mimeType"] = mime_type
+        elif mime_type:
+            body["mimeType"] = mime_type
+
+        return TaskItemVersion.model_validate(
+            self._http.post_json(f"{self._PATH}/{task_item_id}/versions", body)
+        )
+
+    def update(
+        self,
+        task_item_id: UUID | str,
+        version_id: UUID | str,
+        *,
+        main_path: str | None = None,
+        item_definition: str | dict | list | None = None,
+        active_flag: bool | None = None,
+    ) -> TaskItemVersion:
+        body = drop_none(
+            {
+                "mainPath": main_path,
+                "itemDefinition": (
+                    item_definition
+                    if item_definition is None or isinstance(item_definition, str)
+                    else json.dumps(item_definition)
+                ),
+                "activeFlag": active_flag,
+            }
+        )
+        return TaskItemVersion.model_validate(
+            self._http.patch_json(f"{self._PATH}/{task_item_id}/versions/{version_id}", body)
+        )
+
+    def deactivate(self, task_item_id: UUID | str, version_id: UUID | str) -> TaskItemVersion:
+        return self.update(task_item_id, version_id, active_flag=False)
+
+
+class TaskItemsApi:
+    _PATH = "/api/management/task-items"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+        self.versions = TaskItemVersionsApi(http)
+
+    def list(self) -> list[TaskItem]:
+        data = self._http.get_json(self._PATH) or []
+        return [TaskItem.model_validate(item) for item in data]
+
+    def get_by_id(self, task_item_id: UUID | str) -> TaskItem:
+        return TaskItem.model_validate(self._http.get_json(f"{self._PATH}/{task_item_id}"))
+
+    def get_by_name(self, name: str) -> TaskItem:
+        return TaskItem.model_validate(
+            self._http.get_json(f"{self._PATH}/by-name?name={quote(name)}")
+        )
+
+    def create(
+        self,
+        name: str,
+        *,
+        organization_id: UUID | str | None = None,
+        task_type_id: UUID | str | None = None,
+        is_core: bool = False,
+    ) -> TaskItem:
+        body = drop_none(
+            {
+                "name": name,
+                "isCore": is_core,
+                "organizationId": str(organization_id) if organization_id else None,
+                "taskTypeId": str(task_type_id) if task_type_id else None,
+            }
+        )
+        return TaskItem.model_validate(self._http.post_json(self._PATH, body))
+
+    def update(
+        self,
+        task_item_id: UUID | str,
+        *,
+        name: str | None = None,
+        active_flag: bool | None = None,
+        task_type_id: UUID | str | None = None,
+    ) -> TaskItem:
+        body = drop_none(
+            {
+                "name": name,
+                "activeFlag": active_flag,
+                "taskTypeId": str(task_type_id) if task_type_id else None,
+            }
+        )
+        return TaskItem.model_validate(self._http.post_json(f"{self._PATH}/{task_item_id}", body))
+
+    def publish_version(self, task_item_id: UUID | str, version_id: UUID | str) -> TaskItem:
+        return TaskItem.model_validate(
+            self._http.post_json(
+                f"{self._PATH}/{task_item_id}/publish",
+                {"versionId": str(version_id)},
+            )
+        )
+
+
+class QueueApi:
+    _MGMT = "/api/management/queue-items"
+    _QUEUE = "/api/queue"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def add(
+        self,
+        *,
+        task_name: str | None = None,
+        task_item_name: str | None = None,
+        input_data: Any = None,
+        priority: int | None = None,
+        parent_id: UUID | str | None = None,
+    ) -> QueueItem:
+        """Add a queue item. At least one of task_name or task_item_name is required."""
+        if task_name is None and task_item_name is None:
+            raise ValueError("at least one of task_name or task_item_name is required")
+        body = drop_none(
+            {
+                "parent_id": str(parent_id) if parent_id else None,
+                "taskName": task_name,
+                "taskItemName": task_item_name,
+                "priority": priority,
+                "inputData": _encode_input(input_data),
+            }
+        )
+        return QueueItem.model_validate(self._http.post_json(self._MGMT, body))
+
+    def get_by_id(self, queue_item_id: UUID | str) -> QueueItem:
+        return QueueItem.model_validate(self._http.get_json(f"{self._MGMT}/{queue_item_id}"))
+
+    def get_content(self, queue_item_id: UUID | str) -> Content | None:
+        result = self._http.get_bytes(f"{self._QUEUE}/queue-items/{queue_item_id}/content")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+    def claim(self, task_name: str) -> QueueItem | None:
+        """Claim one OPEN queue item for the given task name. Returns None if none available."""
+        result = self._http.post_optional(f"{self._QUEUE}/claim", {"taskName": task_name})
+        if result is None:
+            return None
+        return QueueItem.model_validate(result)
+
+    def heartbeat(self, queue_item_id: UUID | str) -> QueueItem:
+        return QueueItem.model_validate(
+            self._http.post_json(f"{self._QUEUE}/queue-items/{queue_item_id}/heartbeat", {})
+        )
+
+    def update_status(
+        self,
+        queue_item_id: UUID | str,
+        status: TaskStatus,
+        *,
+        output_data: Any = None,
+    ) -> QueueItem:
+        # Server expects `status` on this endpoint (not `taskStatus` on queue item JSON).
+        body: dict[str, Any] = {"status": status.value}
+        encoded = _encode_input(output_data)
+        if encoded is not None:
+            body["outputData"] = encoded
+        return QueueItem.model_validate(
+            self._http.post_json(f"{self._QUEUE}/queue-items/{queue_item_id}/status", body)
+        )
+
+
+class ContentStoreApi:
+    _PATH = "/api/management/content-store"
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get_by_id(self, content_id: UUID | str) -> Content | None:
+        result = self._http.get_bytes(f"{self._PATH}/{content_id}")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+    def get_by_url(self, content_url: str) -> Content | None:
+        result = self._http.get_bytes(f"{self._PATH}?url={quote(content_url, safe='')}")
+        if result is None:
+            return None
+        data, mime = result
+        return Content(data=data, mime_type=mime)
+
+
+class ContinuumClient:
+    """Client for the Continuum Task Server.
+
+    Example:
+        >>> client = ContinuumClient(base_url="http://localhost:8080", api_key="...")
+        >>> task_types = client.task_types.list()
+        >>> item = client.queue.claim("echo")
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        connect_timeout: float = 10.0,
+        request_timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._http = HttpClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
+            transport=transport,
+        )
+        self.task_types = TaskTypesApi(self._http)
+        self.task_items = TaskItemsApi(self._http)
+        self.queue = QueueApi(self._http)
+        self.content_store = ContentStoreApi(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> ContinuumClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

continuum_task_server/exceptions.py

@@ -0,0 +1,69 @@
+"""Exception types raised by the Continuum SDK."""
+
+from __future__ import annotations
+
+
+class ContinuumError(Exception):
+    """Base exception for all Continuum SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.status_code is not None:
+            return f"[{self.status_code}] {base}"
+        return base
+
+
+class BadRequestError(ContinuumError):
+    """HTTP 400."""
+
+
+class UnauthorizedError(ContinuumError):
+    """HTTP 401 - check API key type (Organization vs Worker)."""
+
+
+class ForbiddenError(ContinuumError):
+    """HTTP 403."""
+
+
+class NotFoundError(ContinuumError):
+    """HTTP 404."""
+
+
+class ConflictError(ContinuumError):
+    """HTTP 409."""
+
+
+class ServerError(ContinuumError):
+    """HTTP 5xx."""
+
+
+_STATUS_TO_EXC: dict[int, type[ContinuumError]] = {
+    400: BadRequestError,
+    401: UnauthorizedError,
+    403: ForbiddenError,
+    404: NotFoundError,
+    409: ConflictError,
+}
+
+
+def error_for_status(status_code: int, body: str) -> ContinuumError:
+    """Build the appropriate exception for a non-2xx HTTP response."""
+    exc_cls = _STATUS_TO_EXC.get(status_code)
+    if exc_cls is None:
+        if 500 <= status_code < 600:
+            exc_cls = ServerError
+        else:
+            exc_cls = ContinuumError
+    message = body if body else f"Request failed with status {status_code}"
+    return exc_cls(message, status_code=status_code, body=body)

continuum_task_server/models.py

@@ -0,0 +1,113 @@
+"""Pydantic models mirroring the Continuum Task Server JSON shapes."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class TaskStatus(str, Enum):
+    """Status of a queue item in the task processing lifecycle."""
+
+    OPEN = "OPEN"
+    CLAIMED = "CLAIMED"
+    STARTED = "STARTED"
+    TIMEDOUT = "TIMEDOUT"
+    CANCELLED = "CANCELLED"
+    KILLED = "KILLED"
+    ENDED = "ENDED"
+
+
+class _Base(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")
+
+
+class TaskType(_Base):
+    id: UUID | None = None
+    name: str | None = None
+    description: str | None = None
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    is_global: bool = Field(default=False, alias="isGlobal")
+    max_duration_sec: int | None = Field(default=None, alias="maxDurationSec")
+    heartbeat_timeout_sec: int | None = Field(default=None, alias="heartbeatTimeoutSec")
+
+
+class TaskItem(_Base):
+    id: UUID | None = None
+    name: str | None = None
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    is_global: bool = Field(default=False, alias="isGlobal")
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    published_version: int | None = Field(default=None, alias="publishedVersion")
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+
+
+class TaskItemVersion(_Base):
+    id: UUID | None = None
+    task_item_id: UUID | None = Field(default=None, alias="taskItemId")
+    version_number: int = Field(default=0, alias="versionNumber")
+    content_url: str | None = Field(default=None, alias="contentUrl")
+    main_path: str | None = Field(default=None, alias="mainPath")
+    item_definition: str | None = Field(default=None, alias="itemDefinition")
+    active_flag: bool = Field(default=False, alias="activeFlag")
+    created_by: UUID | None = Field(default=None, alias="createdBy")
+    created_dtm: datetime | None = Field(default=None, alias="createdDtm")
+
+    @property
+    def item_definition_json(self) -> Any:
+        if not self.item_definition:
+            return None
+        try:
+            return json.loads(self.item_definition)
+        except (ValueError, TypeError):
+            return self.item_definition
+
+
+class QueueItem(_Base):
+    id: UUID
+    depth: int = 0
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+    task_item_version_id: UUID | None = Field(default=None, alias="taskItemVersionId")
+    priority: int = 0
+    task_status: TaskStatus | None = Field(default=None, alias="taskStatus")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    created_dtm: datetime | None = Field(default=None, alias="createdDtm")
+    created_by: UUID | None = Field(default=None, alias="createdBy")
+    input_data: str | None = Field(default=None, alias="inputData")
+    output_data: str | None = Field(default=None, alias="outputData")
+
+    @property
+    def input_data_json(self) -> Any:
+        """Parse `input_data` as JSON. Returns None if input_data is None/empty,
+        or the raw string if it's not valid JSON."""
+        if not self.input_data:
+            return None
+        try:
+            return json.loads(self.input_data)
+        except (ValueError, TypeError):
+            return self.input_data
+
+    @property
+    def output_data_json(self) -> Any:
+        if not self.output_data:
+            return None
+        try:
+            return json.loads(self.output_data)
+        except (ValueError, TypeError):
+            return self.output_data
+
+
+class Content(_Base):
+    """Raw content returned from a content-store or queue-item content endpoint."""
+
+    data: bytes
+    mime_type: str = "application/octet-stream"
+
+    def as_text(self, encoding: str = "utf-8") -> str:
+        return self.data.decode(encoding)

continuum_task_server/server.py

@@ -0,0 +1,364 @@
+"""TaskServer - worker-loop abstraction for handling Continuum queue items.
+
+Register handlers per task-type name with ``@server.task("name")`` and call
+``server.run()``. The server polls for OPEN items, claims them, heartbeats while
+the handler runs, then reports ENDED (return value) or KILLED (exception).
+
+Use ``@server.task(..., auto_complete=False)`` when the handler records work
+elsewhere and you will call ``complete_queue_item`` / ``fail_queue_item`` later.
+The SDK does **not** heartbeat after the handler returns; you must call
+``client.queue.heartbeat`` yourself (for example on each pass of your DB poll) so
+the claim stays alive across process restarts.
+"""
+
+from __future__ import annotations
+
+import logging
+import signal
+import threading
+import time
+import traceback
+import uuid
+from collections.abc import Callable
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from .client import ContinuumClient
+from .exceptions import ContinuumError
+from .models import QueueItem, TaskStatus
+
+logger = logging.getLogger("continuum_task_server")
+
+Handler = Callable[[QueueItem], Any]
+
+
+@dataclass
+class _Registration:
+    name: str
+    handler: Handler
+    concurrency: int
+    auto_complete: bool
+    semaphore: threading.Semaphore = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.semaphore = threading.Semaphore(self.concurrency)
+
+
+class TaskServer:
+    """Worker-first task server.
+
+    Example:
+        >>> server = TaskServer(base_url="http://localhost:8080", api_key="...")
+        >>> @server.task("echo")
+        ... def echo(item):
+        ...     return {"echoed": item.input_data_json}
+        >>> server.run()  # blocks until SIGINT/SIGTERM
+
+    With ``auto_complete=True`` (default), handler return values become ``outputData``
+    and the task is marked ENDED. Raising any exception marks the task KILLED.
+
+    With ``auto_complete=False``, the handler returns without ENDED; you are
+    responsible for heartbeats until you call ``complete_queue_item`` or
+    ``fail_queue_item`` (see README). Heartbeats only run while the handler is
+    executing, not after it returns.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        max_workers: int = 4,
+        poll_interval: float = 1.0,
+        max_poll_interval: float = 5.0,
+        heartbeat_interval: float = 15.0,
+        shutdown_timeout: float = 30.0,
+        client: ContinuumClient | None = None,
+        connect_timeout: float = 10.0,
+        request_timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = client or ContinuumClient(
+            base_url=base_url,
+            api_key=api_key,
+            connect_timeout=connect_timeout,
+            request_timeout=request_timeout,
+            transport=transport,
+        )
+        self._owns_client = client is None
+        self._max_workers = max_workers
+        self._poll_interval = poll_interval
+        self._max_poll_interval = max_poll_interval
+        self._heartbeat_interval = heartbeat_interval
+        self._shutdown_timeout = shutdown_timeout
+        self._handlers: dict[str, _Registration] = {}
+        self._stop_event = threading.Event()
+        self._executor: ThreadPoolExecutor | None = None
+        self._inflight: set[Future[Any]] = set()
+        self._inflight_lock = threading.Lock()
+
+    @property
+    def client(self) -> ContinuumClient:
+        """Underlying ContinuumClient. Useful for management operations from handlers."""
+        return self._client
+
+    def task(
+        self,
+        name: str,
+        *,
+        concurrency: int = 1,
+        auto_complete: bool = True,
+    ) -> Callable[[Handler], Handler]:
+        """Decorator registering ``handler`` for queue items of task-type ``name``.
+
+        ``concurrency`` is the max number of in-flight items for this task name.
+
+        If ``auto_complete`` is False, the handler returns without the server sending
+        ENDED; call ``complete_queue_item`` or ``fail_queue_item`` when done. You must
+        heartbeat the queue item yourself until then (see README).
+        """
+        if concurrency < 1:
+            raise ValueError("concurrency must be >= 1")
+
+        def decorator(handler: Handler) -> Handler:
+            if name in self._handlers:
+                raise ValueError(f"a handler for task {name!r} is already registered")
+            self._handlers[name] = _Registration(
+                name=name,
+                handler=handler,
+                concurrency=concurrency,
+                auto_complete=auto_complete,
+            )
+            return handler
+
+        return decorator
+
+    def register(
+        self,
+        name: str,
+        handler: Handler,
+        *,
+        concurrency: int = 1,
+        auto_complete: bool = True,
+    ) -> None:
+        """Imperative alternative to ``@task``."""
+        self.task(name, concurrency=concurrency, auto_complete=auto_complete)(handler)
+
+    def complete_queue_item(
+        self,
+        queue_item_id: uuid.UUID | str,
+        *,
+        output_data: Any = None,
+    ) -> None:
+        """Mark a queue item ENDED.
+
+        Use after ``auto_complete=False`` when work finished successfully. Uses the
+        same ``ContinuumClient`` (and API key) as this ``TaskServer``.
+        """
+        qid = self._normalize_queue_id(queue_item_id)
+        self._safe_update_status_by_id(qid, TaskStatus.ENDED, output=output_data)
+
+    def fail_queue_item(
+        self,
+        queue_item_id: uuid.UUID | str,
+        *,
+        error: BaseException | str | dict[str, Any] | None = None,
+    ) -> None:
+        """Mark a queue item KILLED."""
+        qid = self._normalize_queue_id(queue_item_id)
+        payload: dict[str, Any]
+        if isinstance(error, dict):
+            payload = dict(error)
+        elif isinstance(error, str):
+            payload = {"error": error}
+        elif isinstance(error, BaseException):
+            payload = {
+                "error": str(error),
+                "type": type(error).__name__,
+                "traceback": "".join(
+                    traceback.format_exception(type(error), error, error.__traceback__)
+                ),
+            }
+        else:
+            payload = {"error": "failed"}
+        self._safe_update_status_by_id(qid, TaskStatus.KILLED, output=payload)
+
+    @staticmethod
+    def _normalize_queue_id(queue_item_id: uuid.UUID | str) -> uuid.UUID:
+        if isinstance(queue_item_id, uuid.UUID):
+            return queue_item_id
+        return uuid.UUID(str(queue_item_id))
+
+    def run(self, *, install_signal_handlers: bool = True) -> None:
+        """Block and poll until ``stop()`` is called or a shutdown signal arrives."""
+        if not self._handlers:
+            raise RuntimeError("no task handlers registered; use @server.task(...) first")
+
+        if install_signal_handlers:
+            self._install_signal_handlers()
+
+        self._stop_event.clear()
+        self._executor = ThreadPoolExecutor(max_workers=self._max_workers)
+
+        logger.info(
+            "Continuum task server started: tasks=%s, max_workers=%d",
+            list(self._handlers),
+            self._max_workers,
+        )
+
+        try:
+            self._poll_loop()
+        finally:
+            self._drain()
+
+    def stop(self) -> None:
+        """Signal the server to stop polling and drain in-flight handlers."""
+        if not self._stop_event.is_set():
+            logger.info("Continuum task server shutdown requested")
+        self._stop_event.set()
+
+    def _install_signal_handlers(self) -> None:
+        def _handler(signum: int, _frame: object) -> None:
+            logger.info("Received signal %d, stopping", signum)
+            self.stop()
+
+        try:
+            signal.signal(signal.SIGINT, _handler)
+            signal.signal(signal.SIGTERM, _handler)
+        except ValueError:
+            logger.debug("signal handlers not installed (not on main thread)")
+
+    def _poll_loop(self) -> None:
+        names = list(self._handlers)
+        index = 0
+        backoff = self._poll_interval
+
+        while not self._stop_event.is_set():
+            registration = self._handlers[names[index % len(names)]]
+            index += 1
+
+            if not registration.semaphore.acquire(blocking=False):
+                if index % len(names) == 0:
+                    self._stop_event.wait(timeout=self._poll_interval)
+                continue
+
+            try:
+                item = self._client.queue.claim(registration.name)
+            except ContinuumError as e:
+                registration.semaphore.release()
+                logger.error("claim(%s) failed: %s", registration.name, e)
+                self._stop_event.wait(timeout=min(backoff, self._max_poll_interval))
+                backoff = min(backoff * 2, self._max_poll_interval)
+                continue
+
+            if item is None:
+                registration.semaphore.release()
+                if index % len(names) == 0:
+                    self._stop_event.wait(timeout=backoff)
+                    backoff = min(backoff * 2, self._max_poll_interval)
+                continue
+
+            backoff = self._poll_interval
+            self._dispatch(registration, item)
+
+    def _dispatch(self, registration: _Registration, item: QueueItem) -> None:
+        assert self._executor is not None
+        future = self._executor.submit(self._run_item, registration, item)
+        with self._inflight_lock:
+            self._inflight.add(future)
+        future.add_done_callback(self._on_done)
+
+    def _on_done(self, future: Future[Any]) -> None:
+        with self._inflight_lock:
+            self._inflight.discard(future)
+
+    def _run_item(self, registration: _Registration, item: QueueItem) -> None:
+        try:
+            logger.info("Claimed queue item %s (task=%s)", item.id, registration.name)
+            stop_heartbeat = threading.Event()
+            heartbeat_thread = threading.Thread(
+                target=self._heartbeat_loop,
+                args=(item, stop_heartbeat),
+                name=f"hb-{item.id}",
+                daemon=True,
+            )
+            heartbeat_thread.start()
+
+            try:
+                self._safe_update_status(item, TaskStatus.STARTED)
+                try:
+                    result = registration.handler(item)
+                except Exception as e:
+                    logger.exception("Handler raised for queue item %s", item.id)
+                    error_payload = {
+                        "error": str(e),
+                        "type": type(e).__name__,
+                        "traceback": traceback.format_exc(),
+                    }
+                    self._safe_update_status(item, TaskStatus.KILLED, output=error_payload)
+                    return
+
+                if registration.auto_complete:
+                    self._safe_update_status(item, TaskStatus.ENDED, output=result)
+                    logger.info("Completed queue item %s", item.id)
+                else:
+                    logger.info(
+                        "Handler returned for queue item %s without ENDED "
+                        "(auto_complete=False); caller must heartbeat and complete",
+                        item.id,
+                    )
+            finally:
+                stop_heartbeat.set()
+                heartbeat_thread.join(timeout=5.0)
+        finally:
+            registration.semaphore.release()
+
+    def _heartbeat_loop(self, item: QueueItem, stop_event: threading.Event) -> None:
+        while not stop_event.wait(timeout=self._heartbeat_interval):
+            try:
+                self._client.queue.heartbeat(item.id)
+            except ContinuumError as e:
+                logger.warning("heartbeat for %s failed: %s", item.id, e)
+
+    def _safe_update_status(
+        self,
+        item: QueueItem,
+        status: TaskStatus,
+        *,
+        output: Any = None,
+    ) -> None:
+        self._safe_update_status_by_id(item.id, status, output=output)
+
+    def _safe_update_status_by_id(
+        self,
+        queue_item_id: uuid.UUID,
+        status: TaskStatus,
+        *,
+        output: Any = None,
+    ) -> None:
+        try:
+            self._client.queue.update_status(queue_item_id, status, output_data=output)
+        except ContinuumError as e:
+            logger.error("update_status(%s, %s) failed: %s", queue_item_id, status.value, e)
+
+    def _drain(self) -> None:
+        if self._executor is None:
+            return
+        logger.info("Draining in-flight tasks (timeout=%.1fs)", self._shutdown_timeout)
+        deadline = time.monotonic() + self._shutdown_timeout
+        with self._inflight_lock:
+            futures = list(self._inflight)
+        for future in futures:
+            remaining = max(0.0, deadline - time.monotonic())
+            try:
+                future.result(timeout=remaining)
+            except Exception:
+                logger.debug("drain: handler future raised", exc_info=True)
+        self._executor.shutdown(wait=False, cancel_futures=True)
+        self._executor = None
+        if self._owns_client:
+            self._client.close()
+        logger.info("Continuum task server stopped")

continuum_task_server_sdk-0.0.9.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: continuum-task-server-sdk
+Version: 0.0.9
+Summary: Python SDK for the Continuum Task Server
+Project-URL: Homepage, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python
+Project-URL: Issues, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python/issues
+Author: Continuum
+License: MIT
+Keywords: continuum,queue,sdk,task,worker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Continuum Task Server SDK for Python
+
+Python client for the [Continuum](https://github.com/ContinuumWorkflow) task server. Designed so a 20-line script can stand up a worker that claims queue items, runs your code, and reports results.
+
+- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Long-running claims (`auto_complete=False`) need **your** heartbeat loop (documented below).
+- **`ContinuumClient`** — thin pythonic client over the management + queue REST APIs (task types, task items, versions, queue, content store).
+
+Requires Python 3.10+.
+
+## Installation
+
+Tagged releases (`v*`) are published to [PyPI](https://pypi.org/project/continuum-task-server-sdk/):
+
+```bash
+pip install continuum-task-server-sdk
+```
+
+Dev and PR builds are still attached to private GitHub Releases. Install those with a token:
+
+```bash
+pip install \
+  "https://${GITHUB_TOKEN}@github.com/ContinuumWorkflow/continuum-task-server-sdk-python/releases/download/v0.1.0/continuum_task_server_sdk-0.1.0-py3-none-any.whl"
+```
+
+`GITHUB_TOKEN` must be a PAT with repo read access.
+
+## Quickstart: build a task server in 20 lines
+
+```python
+import os
+from continuum_task_server import TaskServer
+
+server = TaskServer(
+    base_url=os.environ["CONTINUUM_URL"],
+    api_key=os.environ["CONTINUUM_API_KEY"],
+)
+
+@server.task("echo")
+def echo(item):
+    return {"echoed": item.input_data_json}
+
+@server.task("greet")
+def greet(item):
+    name = (item.input_data_json or {}).get("name", "world")
+    return {"message": f"hello, {name}"}
+
+if __name__ == "__main__":
+    server.run()
+```
+
+Run it. The server polls `/api/queue/claim` for `echo` and `greet`, claims items as they become available, runs your handler in a thread, heartbeats while it runs, and:
+
+- **Handler returns** a value → queue item marked `ENDED`, return value JSON-encoded as `outputData` (default `auto_complete=True`).
+- **Handler raises** → queue item marked `KILLED`, error info written to `outputData`.
+
+Press `Ctrl+C` (or send `SIGTERM`) and the server stops polling and waits up to `shutdown_timeout` seconds for in-flight handlers to finish.
+
+### Deferred completion (`auto_complete=False`)
+
+The handler runs under the normal **in-handler** heartbeat (same as any task). When it returns, the server **does not** send `ENDED` and **does not** keep heartbeating: you own the claim until you finish or lose it to timeouts.
+
+Typical pattern: persist `item.id` (and anything else you need), then on each pass of **your** poller (cron, loop, worker restart), call **`server.client.queue.heartbeat(queue_item_id)`** so the Continuum claim stays alive, and when the real-world condition is met call **`server.complete_queue_item(...)`** or **`server.fail_queue_item(...)`**. Use the **same worker API key** as the process that claimed the item (often the same `TaskServer` / `ContinuumClient` config loaded from env).
+
+```python
+@server.task("wait-for-mail", auto_complete=False)
+def wait_for_mail(item):
+    db.insert_outstanding(queue_item_id=str(item.id), payload=item.input_data_json)
+    # Returns without ENDED — no background heartbeat from TaskServer
+
+# Elsewhere: each time you poll your DB for outstanding work (including after restart):
+for row in db.outstanding_rows():
+    server.client.queue.heartbeat(row.queue_item_id)
+    if mail_arrived(row):
+        server.complete_queue_item(row.queue_item_id, output_data={"received": True})
+```
+
+Standalone process (no `TaskServer`): build a `ContinuumClient` with the worker key and call `client.queue.heartbeat` / `client.queue.update_status` the same way.
+
+### TaskServer options
+
+```python
+TaskServer(
+    base_url="http://localhost:8080",
+    api_key="...",
+    max_workers=4,            # thread pool size across all tasks
+    poll_interval=1.0,        # initial poll delay (backs off when idle)
+    max_poll_interval=5.0,    # max idle poll delay
+    heartbeat_interval=15.0,  # how often to call /heartbeat per running task
+    shutdown_timeout=30.0,    # how long to wait for handlers during shutdown
+)
+```
+
+Per-task concurrency limit:
+
+```python
+@server.task("docker-run", concurrency=2)
+def run_docker(item):
+    ...
+```
+
+Handler signature: `def handler(item: QueueItem) -> dict | list | str | None`. Inside, you have:
+
+- `item.input_data` — raw JSON string from the queue item (or `None`).
+- `item.input_data_json` — parsed value (`dict` / `list` / `str` / `None`).
+- `server.client` — full `ContinuumClient` if you need to chain management calls, fetch content, enqueue child tasks, etc.
+
+## Using `ContinuumClient` directly
+
+```python
+from continuum_task_server import ContinuumClient, TaskStatus
+
+with ContinuumClient(base_url="http://localhost:8080", api_key="...") as client:
+    # Task types
+    types = client.task_types.list()
+    echo_type = client.task_types.get_by_name("echo")
+
+    # Task items + versions
+    item = client.task_items.get_by_name("my-task")
+    versions = client.task_items.versions.list(item.id)
+
+    # Enqueue work
+    queued = client.queue.add(task_name="echo", input_data={"hello": "world"})
+
+    # Worker-side primitives (normally handled by TaskServer)
+    claimed = client.queue.claim("echo")
+    if claimed is not None:
+        client.queue.heartbeat(claimed.id)
+        client.queue.update_status(claimed.id, TaskStatus.ENDED, output_data={"ok": True})
+
+    # Content store
+    content = client.content_store.get_by_url("db://...")
+    if content is not None:
+        print(content.as_text())
+```
+
+`input_data` / `output_data` accept `dict` / `list` / `str` / `None`; non-string values are JSON-encoded for you.
+
+### Errors
+
+All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ServerError`. Each carries `status_code` and `body`.
+
+```python
+from continuum_task_server import ContinuumClient, NotFoundError
+
+with ContinuumClient(...) as client:
+    try:
+        client.task_types.get_by_name("does-not-exist")
+    except NotFoundError as e:
+        print(e.status_code, e.body)
+```
+
+## Endpoints covered
+
+| Group | Method | Path |
+| --- | --- | --- |
+| Task Types | `GET`/`POST` | `/api/management/task-types[/{id}\|/by-name]` |
+| Task Items | `GET`/`POST` | `/api/management/task-items[/{id}\|/by-name\|/{id}/publish]` |
+| Task Item Versions | `GET`/`POST`/`PATCH` | `/api/management/task-items/{id}/versions[...]` |
+| Queue (management) | `GET`/`POST` | `/api/management/queue-items[/{id}]` |
+| Queue (worker) | `POST` | `/api/queue/claim`, `/api/queue/queue-items/{id}/heartbeat`, `/api/queue/queue-items/{id}/status` |
+| Queue content | `GET` | `/api/queue/queue-items/{id}/content` |
+| Content store | `GET` | `/api/management/content-store[/{id}\|?url=db://...]` |
+
+All requests send `Api-Key: <your-key>`. `204 No Content` responses are normalized to `None` (e.g. `client.queue.claim()` returns `None` when nothing's available).
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+
+ruff check .
+ruff format --check .
+pytest
+```
+
+Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport — no live server required.
+
+## Versioning
+
+- **Tag `v1.2.3`** → release wheel `1.2.3` attached to a `v1.2.3` GitHub Release.
+- **Push to `main`** → prerelease wheel `0.1.0.dev{run}+{shortsha}` attached to a `dev-{shortsha}` Release.
+- **Pull request** → prerelease wheel `0.1.0b{pr}.{run}` attached to a `pr-{pr}` Release; install command posted as a PR comment.
+
+## License
+
+MIT.

continuum_task_server_sdk-0.0.9.dist-info/RECORD

@@ -0,0 +1,9 @@
+continuum_task_server/__init__.py,sha256=skwstGRatClptyxyDNtwOJbtqEmqs7XJgQ50nrANnwo,740
+continuum_task_server/_http.py,sha256=feeOeqCUAwDASEfH3RS6mtEysHPkmj_6mtNCyGo3J9o,4776
+continuum_task_server/client.py,sha256=AaLlFasKFBlgQn3GDOvnd2SiouxL_lBBMdbzRg1yKVk,11573
+continuum_task_server/exceptions.py,sha256=BFnmKX_qAqFaw-4Fd7qVGFN2bubrFqVeYSYbtCNEuec,1666
+continuum_task_server/models.py,sha256=6JEABBRG_F6vhbEkX02zgI4R7Tt7O0ICZLurnxH-ZXI,4009
+continuum_task_server/server.py,sha256=tfPlVUbsMUX0GpvZbnZN71N1N24buttsGEf2nd1DTBY,13242
+continuum_task_server_sdk-0.0.9.dist-info/METADATA,sha256=1YJ5thdNqJrb1A5-RCObCTFvvDxYM-gm7vkXoqxh2Vs,8762
+continuum_task_server_sdk-0.0.9.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+continuum_task_server_sdk-0.0.9.dist-info/RECORD,,

continuum_task_server_sdk-0.0.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any