grctl-sdk-python 0.2.0__py3-none-any.whl → 0.2.1__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,161 @@
+"""Workflow Engine Client.
+
+Provides a simple interface for interacting with workflows.
+"""
+
+import logging
+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
+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
+
+
+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()
+
+    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),
+        )
+        # 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,
+        )
+        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,
+        )
+
+        # 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}")
+            raise WorkflowError(f"start_workflow failed (code={error_code}): {error_msg}")
+
+        return handle

grctl/models/__init__.py

@@ -0,0 +1,139 @@
+"""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,
+    StartCmd,
+    command_decoder,
+    command_encoder,
+)
+from grctl.models.directive import (
+    Cancel,
+    Complete,
+    Directive,
+    DirectiveKind,
+    DirectiveMessage,
+    Event,
+    Fail,
+    FailStep,
+    Start,
+    Step,
+    StepResult,
+    Wait,
+    directive_decoder,
+    directive_encoder,
+)
+from grctl.models.history import (
+    ChildWorkflowStarted,
+    DeterministicEvents,
+    ErrorDetails,
+    HistoryEvent,
+    HistoryKind,
+    ParentEventSent,
+    RandomRecorded,
+    RunCancelled,
+    RunCompleted,
+    RunEvents,
+    RunFailed,
+    RunScheduled,
+    RunStarted,
+    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",
+    "CmdKind",
+    "command_decoder",
+    "command_encoder",
+    # Directive types
+    "Directive",
+    "DirectiveMessage",
+    "DirectiveKind",
+    "Start",
+    "Cancel",
+    "Event",
+    "Complete",
+    "Fail",
+    "FailStep",
+    "Step",
+    "StepResult",
+    "Wait",
+    "directive_decoder",
+    "directive_encoder",
+    # History event types
+    "HistoryEvent",
+    "HistoryKind",
+    "RunScheduled",
+    "RunStarted",
+    "RunCompleted",
+    "RunEvents",
+    "RunFailed",
+    "RunCancelled",
+    "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,117 @@
+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"
+
+
+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
+
+
+type CommandMessage = StartCmd | EventCmd | CancelCmd | DescribeCmd | TerminateCmd
+
+
+class Command(msgspec.Struct):
+    id: str
+    kind: CmdKind
+    timestamp: datetime
+    msg: CommandMessage
+
+
+# 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,
+}
+
+
+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
+
+
+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")
+
+    msg_bytes = msgspec.msgpack.encode(cmd.msg)
+
+    wire = CommandWire(
+        id=cmd.id,
+        k=cmd.kind,
+        m=msg_bytes,
+        t=cmd.timestamp,
+    )
+
+    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,
+    )

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 = ""

grctl/models/directive.py

@@ -0,0 +1,191 @@
+"""Custom msgpack encoding/decoding for Directive types.
+
+This module provides msgpack serialization for Directive messages with a compact wire format
+that matches the Go server implementation.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Any
+
+import msgspec
+
+from grctl.logging_config import get_logger
+from grctl.models.common import ErrorDetails
+from grctl.models.run_info import RunInfo
+
+logger = get_logger(__name__)
+
+
+class RetryPolicy(msgspec.Struct, omit_defaults=True):
+    max_attempts: int | None = None
+    initial_delay_ms: int | None = None
+    backoff_multiplier: float | None = None
+    max_delay_ms: int | None = None
+    jitter: float | None = None
+    retryable_errors: list[str] | None = None
+    non_retryable_errors: list[str] | None = None
+
+
+class Start(msgspec.Struct):
+    """Request to start workflow execution."""
+
+    input: Any | None = None
+    timeout_ms: int | None = 3_000  # 3 seconds in nanoseconds (Go time.Duration)
+
+
+class Cancel(msgspec.Struct):
+    """Request to cancel a running workflow."""
+
+    reason: str | None = None
+
+
+class Event(msgspec.Struct):
+    """Request to emit an event to a running workflow."""
+
+    event_name: str
+    payload: Any | None = None
+
+
+class Step(msgspec.Struct):
+    """Request to execute a specific step in a workflow."""
+
+    step_name: str
+    timeout_ms: int | None = 3_000  # 3 seconds in nanoseconds (Go time.Duration)
+
+
+class Wait(msgspec.Struct):
+    """Worker directive to park the run; optionally times out to a named step."""
+
+    timeout_ms: int = 0
+    timeout_step_name: str = ""
+
+
+class Complete(msgspec.Struct):
+    """Worker directive to mark workflow complete."""
+
+    result: Any
+
+
+class Fail(msgspec.Struct):
+    """Worker directive to mark workflow failed."""
+
+    error: ErrorDetails
+
+
+class FailStep(msgspec.Struct):
+    """Worker directive to mark a step as failed and fail the run."""
+
+    step_name: str
+    error: ErrorDetails
+
+
+class DirectiveKind(StrEnum):
+    start = "start"
+    cancel = "cancel"
+    terminate = "terminate"
+    complete = "complete"
+    fail = "fail"
+    step = "step"
+    event = "event"
+    wait = "wait"
+    wait_timeout = "wait_timeout"
+    step_result = "step_result"
+    fail_step = "fail_step"
+
+
+class StepResult(msgspec.Struct):
+    """Worker directive to mark step complete."""
+
+    processed_msg_kind: DirectiveKind
+    # Any because processed_msg and next_msg are type-erased at wire level;
+    # the _kind fields carry the type info needed for deserialization.
+    processed_msg: Any
+    worker_id: str
+    kv_updates: dict[str, Any]
+    next_msg_kind: DirectiveKind
+    next_msg: Any
+    duration_ms: int = 0
+
+
+DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | Wait | StepResult
+
+
+# Factory map for kind-based deserialization
+directive_factories: dict[str, type[DirectiveMessage]] = {
+    "start": Start,
+    "cancel": Cancel,
+    "event": Event,
+    "complete": Complete,
+    "fail": Fail,
+    "step": Step,
+    "wait": Wait,
+    "step_result": StepResult,
+}
+
+
+class Directive(msgspec.Struct):
+    id: str
+    timestamp: datetime
+    kind: DirectiveKind
+    run_info: RunInfo
+    msg: DirectiveMessage
+    attempt: int = 0
+    kv_revs: dict[str, Any] | None = None
+
+
+class DirectiveWire(msgspec.Struct, omit_defaults=True):
+    """Wire format for Directive with compact field names matching Go server.
+
+    Encoded as a dict/map (not array) to match Go's msgpack tag expectations.
+    """
+
+    id: str
+    k: str  # kind
+    m: bytes  # message
+    r: RunInfo  # run_info
+    t: datetime  # timestamp
+    a: int = 0  # attempt
+    kv: dict[str, Any] | None = None  # kv_revs
+
+
+def directive_encoder(directive: Directive, enc_hook: Any = None) -> bytes:
+    if directive.msg is None:
+        raise ValueError("Directive message cannot be None")
+
+    msg_bytes = msgspec.msgpack.encode(directive.msg, enc_hook=enc_hook)
+
+    wire = DirectiveWire(
+        id=directive.id,
+        k=directive.kind,
+        m=msg_bytes,
+        r=directive.run_info,
+        t=directive.timestamp,
+        a=directive.attempt,
+        kv=directive.kv_revs,
+    )
+
+    return msgspec.msgpack.encode(wire)
+
+
+def directive_decoder(data: bytes) -> Directive:
+    wire = msgspec.msgpack.decode(data, type=DirectiveWire)
+
+    factory = directive_factories.get(wire.k)
+    if factory is None:
+        raise ValueError(f"Unknown directive kind: {wire.k}")
+
+    msg = msgspec.msgpack.decode(wire.m, type=factory)
+
+    # Convert kind string to DirectiveKind enum
+    kind_enum = DirectiveKind(wire.k)
+
+    return Directive(
+        id=wire.id,
+        kind=kind_enum,
+        attempt=wire.a,
+        kv_revs=wire.kv or {},
+        msg=msg,
+        run_info=wire.r,
+        timestamp=wire.t,
+    )

grctl/models/errors.py

@@ -0,0 +1,10 @@
+class WorkflowError(Exception):
+    """Workflow error."""
+
+
+class WorkflowNotFoundError(WorkflowError):
+    """Raised when a workflow ID does not correspond to any active run."""
+
+
+class WorkflowAlreadyRunningError(WorkflowError):
+    """Raised when a workflow ID already has an active run."""