grctl-sdk-python 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

grctl/client/__init__.py

@@ -0,0 +1,16 @@
+"""Ground Control Python SDK client package."""
+
+from grctl.client.client import Client
+from grctl.logging_config import get_logger, setup_logging
+from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
+from grctl.nats.connection import Connection
+
+__all__ = [
+    "Client",
+    "Connection",
+    "WorkflowAlreadyRunningError",
+    "WorkflowError",
+    "WorkflowNotFoundError",
+    "get_logger",
+    "setup_logging",
+]

grctl/client/client.py

@@ -0,0 +1,175 @@
+"""Workflow Engine Client.
+
+Provides a simple interface for interacting with workflows.
+"""
+
+import logging
+import secrets
+import socket
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar, overload
+
+import msgspec
+from ulid import ULID
+
+from grctl.models import DescribeCmd, GrctlAPIResponse, HistoryEvent, RunInfo
+from grctl.models.command import CmdKind, Command
+from grctl.models.errors import (
+    WorkflowAlreadyRunningError,
+    WorkflowError,
+    WorkflowNotFoundError,
+    WorkflowTypeNotRegisteredError,
+)
+from grctl.nats.connection import Connection
+from grctl.nats.history_fetch import fetch_run_history
+from grctl.worker.codec import CodecRegistry
+from grctl.workflow.handle import WorkflowHandle
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T")
+
+ErrWorkflowAlreadyRunningCode = 4001
+ErrWorkflowRunNotFoundCode = 4002
+ErrWorkflowTypeNotRegisteredCode = 4004
+
+
+class Client:
+    """Client for interacting with the Workflow Engine."""
+
+    def __init__(self, connection: Connection, codec: CodecRegistry | None = None) -> None:
+        self._connection = connection
+        self._codec = codec or CodecRegistry()
+        self.id = f"c_{secrets.token_hex(4)}@{socket.gethostname()}"
+
+    async def describe(self, wf_id: str) -> RunInfo:
+        """Describe the latest run for a workflow ID."""
+        cmd = Command(
+            id=str(ULID()),
+            kind=CmdKind.run_describe,
+            timestamp=datetime.now(UTC),
+            msg=DescribeCmd(wf_id=wf_id),
+            sender_id=self.id,
+        )
+        # Use a routing-only RunInfo — publish_cmd only needs wf_id for subject routing.
+        routing_info = RunInfo(id="", wf_type="", wf_id=wf_id)
+        response_bytes = await self._connection.publisher.publish_cmd(routing_info, cmd)
+
+        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
+        if not response.success:
+            error_msg = response.error.message if response.error else "unknown error"
+            error_code = response.error.code if response.error else 0
+            if error_code == ErrWorkflowRunNotFoundCode:
+                raise WorkflowNotFoundError(f"workflow '{wf_id}' not found: {error_msg}")
+            raise WorkflowError(f"describe failed (code={error_code}): {error_msg}")
+
+        return msgspec.msgpack.decode(response.payload, type=RunInfo)
+
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: type[_T] = ...,
+    ) -> _T: ...
+
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: None = ...,
+    ) -> Any: ...
+
+    async def run_workflow(
+        self,
+        type: str,  # noqa: A002
+        id: str,  # noqa: A002
+        input: Any | None = None,  # noqa: A002
+        timeout: timedelta | None = None,  # noqa: ASYNC109
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
+        """Run a workflow and wait for its result."""
+        wf_handle = await self.start_workflow(
+            type=type,
+            id=id,
+            input=input,
+            timeout=timeout,
+            return_type=return_type,
+        )
+        wait_timeout = timeout.total_seconds() if timeout else None
+        return await wf_handle.result(timeout=wait_timeout)
+
+    async def get_workflow_handle(self, wfid: str) -> WorkflowHandle:
+        """Get a handle for an already-running workflow."""
+        run_info = await self.describe(wfid)
+
+        handle = WorkflowHandle(
+            run_info=run_info,
+            payload=None,
+            connection=self._connection,
+            codec=self._codec,
+            sender_id=self.id,
+        )
+        await handle.attach()
+        return handle
+
+    async def get_history(self, wf_id: str, run_id: str | None = None) -> list[HistoryEvent]:
+        """Return the ordered history events for a workflow run."""
+        resolved_run_id = run_id
+        if resolved_run_id is None:
+            resolved_run_id = (await self.describe(wf_id)).id
+
+        return await fetch_run_history(
+            js=self._connection.js,
+            manifest=self._connection.manifest,
+            wf_id=wf_id,
+            run_id=resolved_run_id,
+        )
+
+    async def start_workflow(
+        self,
+        type: str,  # noqa: A002
+        id: str,  # noqa: A002
+        input: Any | None = None,  # noqa: A002
+        timeout: timedelta | None = None,  # noqa: ASYNC109
+        return_type: type | None = None,
+    ) -> WorkflowHandle:
+        """Start a workflow and return a handle to track and interact with it."""
+        workflow_run_id = str(ULID())
+
+        run_info = RunInfo(
+            id=workflow_run_id,
+            wf_type=type,
+            wf_id=id,
+            timeout=int(timeout.total_seconds()) if timeout else None,
+            created_at=datetime.now(UTC),
+        )
+
+        handle = WorkflowHandle(
+            run_info=run_info,
+            payload=input,
+            connection=self._connection,
+            codec=self._codec,
+            return_type=return_type,
+            sender_id=self.id,
+        )
+
+        # Start the workflow future (subscribe to events and publish run command)
+        response_bytes = await handle.start()
+        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
+        if not response.success:
+            await handle.future.stop()
+            error_msg = response.error.message if response.error else "unknown error"
+            error_code = response.error.code if response.error else 0
+            if error_code == ErrWorkflowAlreadyRunningCode:
+                raise WorkflowAlreadyRunningError(f"workflow '{id}' already has an active run: {error_msg}")
+            if error_code == ErrWorkflowTypeNotRegisteredCode:
+                raise WorkflowTypeNotRegisteredError(f"no worker registered for workflow type '{type}': {error_msg}")
+            raise WorkflowError(f"start_workflow failed (code={error_code}): {error_msg}")
+
+        return handle

grctl/models/__init__.py

@@ -0,0 +1,153 @@
+"""Messaging infrastructure for workflow run operations.
+
+This module provides NATS-based messaging for workflow lifecycle events,
+enabling clients to start workflows and track execution through observable events.
+"""
+
+from grctl.models.api import GrctlAPIError, GrctlAPIResponse
+from grctl.models.command import (
+    CancelCmd,
+    CmdKind,
+    Command,
+    DescribeCmd,
+    EventCmd,
+    EventDef,
+    RegisterCmd,
+    StartCmd,
+    TerminateCmd,
+    WorkflowTypeDef,
+    command_decoder,
+    command_encoder,
+)
+from grctl.models.directive import (
+    Cancel,
+    Complete,
+    Directive,
+    DirectiveKind,
+    DirectiveMessage,
+    Event,
+    Fail,
+    FailStep,
+    Start,
+    Step,
+    StepPickedUp,
+    StepResult,
+    Wait,
+    directive_decoder,
+    directive_encoder,
+)
+from grctl.models.history import (
+    ChildWorkflowStarted,
+    DeterministicEvents,
+    ErrorDetails,
+    HistoryEvent,
+    HistoryKind,
+    ParentEventSent,
+    RandomRecorded,
+    RunCancelled,
+    RunCancelReceived,
+    RunCompleted,
+    RunEvents,
+    RunFailed,
+    RunScheduled,
+    RunStarted,
+    RunTerminated,
+    RunTimeout,
+    SleepRecorded,
+    StepCancelled,
+    StepCompleted,
+    StepEvents,
+    StepFailed,
+    StepStarted,
+    StepTimeout,
+    TaskAttemptFailed,
+    TaskCancelled,
+    TaskCompleted,
+    TaskEvents,
+    TaskFailed,
+    TaskStarted,
+    TimestampRecorded,
+    UuidRecorded,
+    WaitStarted,
+    WaitTimedOut,
+    history_decoder,
+    history_encoder,
+)
+from grctl.models.run_info import RunInfo, RunStateKind, RunStatus
+from grctl.models.run_info_helper import RunInfoManager
+
+__all__ = [  # noqa: RUF022
+    # API response types
+    "GrctlAPIError",
+    "GrctlAPIResponse",
+    # Command types
+    "Command",
+    "StartCmd",
+    "CancelCmd",
+    "DescribeCmd",
+    "EventCmd",
+    "RegisterCmd",
+    "TerminateCmd",
+    "WorkflowTypeDef",
+    "EventDef",
+    "CmdKind",
+    "command_decoder",
+    "command_encoder",
+    # Directive types
+    "Directive",
+    "DirectiveMessage",
+    "DirectiveKind",
+    "Start",
+    "Cancel",
+    "Event",
+    "Complete",
+    "Fail",
+    "FailStep",
+    "Step",
+    "StepPickedUp",
+    "StepResult",
+    "Wait",
+    "directive_decoder",
+    "directive_encoder",
+    # History event types
+    "HistoryEvent",
+    "HistoryKind",
+    "RunScheduled",
+    "RunStarted",
+    "RunCompleted",
+    "RunEvents",
+    "RunFailed",
+    "RunCancelReceived",
+    "RunCancelled",
+    "RunTerminated",
+    "RunTimeout",
+    "StepEvents",
+    "StepStarted",
+    "StepCompleted",
+    "StepFailed",
+    "StepCancelled",
+    "StepTimeout",
+    "TaskEvents",
+    "TaskStarted",
+    "TaskCompleted",
+    "TaskFailed",
+    "TaskAttemptFailed",
+    "TaskCancelled",
+    "DeterministicEvents",
+    "TimestampRecorded",
+    "RandomRecorded",
+    "UuidRecorded",
+    "SleepRecorded",
+    "WaitStarted",
+    "WaitTimedOut",
+    "ChildWorkflowStarted",
+    "ParentEventSent",
+    "history_decoder",
+    "history_encoder",
+    # Common types
+    "RunInfo",
+    "RunStateKind",
+    "RunStatus",
+    "ErrorDetails",
+    "RunInfoManager",
+]

grctl/models/api.py

@@ -0,0 +1,13 @@
+import msgspec
+
+
+class GrctlAPIError(msgspec.Struct):
+    code: int
+    message: str
+    detail: str = ""
+
+
+class GrctlAPIResponse(msgspec.Struct):
+    success: bool
+    payload: msgspec.Raw = msgspec.field(default_factory=lambda: msgspec.Raw(b""))
+    error: GrctlAPIError | None = None

grctl/models/command.py

@@ -0,0 +1,161 @@
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+import msgspec
+
+from grctl.models.run_info import RunInfo
+
+
+class CmdKind(StrEnum):
+    run_start = "run.start"
+    run_cancel = "run.cancel"
+    run_describe = "run.describe"
+    run_terminate = "run.terminate"
+    run_event = "run.event"
+    worker_register = "worker.register"
+    worker_terminate_run = "worker.terminate_run"
+
+
+class StartCmd(msgspec.Struct):
+    """Request to start workflow execution."""
+
+    run_info: RunInfo
+    input: Any | None
+
+
+class CancelCmd(msgspec.Struct):
+    """Request to cancel a running workflow."""
+
+    wf_id: str
+    reason: str | None
+
+
+class DescribeCmd(msgspec.Struct):
+    """Request to describe a workflow run."""
+
+    wf_id: str
+
+
+class EventCmd(msgspec.Struct):
+    """Request to emit an event to a running workflow."""
+
+    wf_id: str
+    event_name: str
+    payload: Any | None
+
+
+class TerminateCmd(msgspec.Struct):
+    """Request to terminate a running workflow."""
+
+    wf_id: str
+    reason: str | None
+
+
+class WorkerTerminateRunCmd(msgspec.Struct):
+    """Server→worker signal to cancel a specific in-flight run."""
+
+    run_id: str
+
+
+class EventDef(msgspec.Struct, kw_only=True):
+    """Per-event timeout config carried through registration."""
+
+    name: str
+    timeout_ms: int = 0
+
+
+class WorkflowTypeDef(msgspec.Struct):
+    """Structural definition of one workflow type reported at registration.
+
+    Field names and order mirror the Go WorkflowTypeDef msgpack tags.
+    """
+
+    type: str
+    start_step: str
+    steps: list[str]
+    events: list[EventDef]
+    queries: list[str]
+    start_step_timeout_ms: int = 0
+
+
+class RegisterCmd(msgspec.Struct):
+    """Worker startup sync of its workflow type catalog to the server."""
+
+    worker_id: str
+    types: list[WorkflowTypeDef]
+
+
+type CommandMessage = StartCmd | EventCmd | CancelCmd | DescribeCmd | TerminateCmd | RegisterCmd | WorkerTerminateRunCmd
+
+
+class Command(msgspec.Struct):
+    id: str
+    kind: CmdKind
+    timestamp: datetime
+    msg: CommandMessage
+    sender_id: str = ""
+
+
+# Factory map for kind-based deserialization
+command_factories: dict[str, type] = {
+    "run.start": StartCmd,
+    "run.cancel": CancelCmd,
+    "run.describe": DescribeCmd,
+    "run.terminate": TerminateCmd,
+    "run.event": EventCmd,
+    "worker.register": RegisterCmd,
+    "worker.terminate_run": WorkerTerminateRunCmd,
+}
+
+
+class CommandWire(msgspec.Struct):
+    """Wire format for Command with compact field names matching Go server.
+
+    Encoded as a dict/map (not array) to match Go's msgpack tag expectations.
+    """
+
+    id: str
+    k: CmdKind
+    m: bytes
+    t: datetime
+    s: str = ""
+
+
+def command_encoder(cmd: Command) -> bytes:
+    """Encode command to msgpack with compact wire format."""
+    if cmd.msg is None:
+        raise ValueError("Command message cannot be None")
+    if cmd.sender_id == "":
+        raise ValueError("Command sender ID cannot be empty")
+
+    msg_bytes = msgspec.msgpack.encode(cmd.msg)
+
+    wire = CommandWire(
+        id=cmd.id,
+        k=cmd.kind,
+        m=msg_bytes,
+        t=cmd.timestamp,
+        s=cmd.sender_id,
+    )
+
+    return msgspec.msgpack.encode(wire)
+
+
+def command_decoder(data: bytes) -> Command:
+    """Decode msgpack to command."""
+    wire = msgspec.msgpack.decode(data, type=CommandWire)
+
+    factory = command_factories.get(wire.k)
+    if factory is None:
+        raise ValueError(f"Unknown command kind: {wire.k}")
+
+    msg = msgspec.msgpack.decode(wire.m, type=factory)
+
+    return Command(
+        id=wire.id,
+        kind=wire.k,
+        msg=msg,  # ty:ignore[invalid-argument-type]
+        timestamp=wire.t,
+        sender_id=wire.s,
+    )

grctl/models/common.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from msgspec import Struct
+
+
+class ErrorDetails(Struct):
+    type: str
+    message: str
+    stack_trace: str
+    qualified_type: str = ""