grctl-sdk-python 0.1.4__py3-none-any.whl → 0.2.1__py3-none-any.whl

grctl/client/client.py

@@ -3,7 +3,6 @@
 Provides a simple interface for interacting with workflows.
 """
 
-import asyncio
 import logging
 from datetime import UTC, datetime, timedelta
 from typing import Any, TypeVar, overload
@@ -90,15 +89,10 @@ class Client:
             id=id,
             input=input,
             timeout=timeout,
+            return_type=return_type,
         )
         wait_timeout = timeout.total_seconds() if timeout else None
-        try:
-            result = await asyncio.wait_for(wf_handle.future, timeout=wait_timeout)
-            if return_type is not None:
-                return self._codec.from_primitive(result, return_type)
-            return result
-        finally:
-            await wf_handle.future.stop()
+        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."""
@@ -132,6 +126,7 @@ class Client:
         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())
@@ -149,6 +144,7 @@ class Client:
             payload=input,
             connection=self._connection,
             codec=self._codec,
+            return_type=return_type,
         )
 
         # Start the workflow future (subscribe to events and publish run command)

grctl/models/__init__.py

@@ -23,12 +23,11 @@ from grctl.models.directive import (
     DirectiveMessage,
     Event,
     Fail,
-    Sleep,
-    SleepUntil,
+    FailStep,
     Start,
     Step,
     StepResult,
-    WaitEvent,
+    Wait,
     directive_decoder,
     directive_encoder,
 )
@@ -62,6 +61,8 @@ from grctl.models.history import (
     TaskStarted,
     TimestampRecorded,
     UuidRecorded,
+    WaitStarted,
+    WaitTimedOut,
     history_decoder,
     history_encoder,
 )
@@ -90,11 +91,10 @@ __all__ = [  # noqa: RUF022
     "Event",
     "Complete",
     "Fail",
+    "FailStep",
     "Step",
     "StepResult",
-    "WaitEvent",
-    "Sleep",
-    "SleepUntil",
+    "Wait",
     "directive_decoder",
     "directive_encoder",
     # History event types
@@ -124,6 +124,8 @@ __all__ = [  # noqa: RUF022
     "RandomRecorded",
     "UuidRecorded",
     "SleepRecorded",
+    "WaitStarted",
+    "WaitTimedOut",
     "ChildWorkflowStarted",
     "ParentEventSent",
     "history_decoder",

grctl/models/directive.py

@@ -54,25 +54,11 @@ class Step(msgspec.Struct):
     timeout_ms: int | None = 3_000  # 3 seconds in nanoseconds (Go time.Duration)
 
 
-class WaitEvent(msgspec.Struct):
-    """Worker directive to wait for events."""
+class Wait(msgspec.Struct):
+    """Worker directive to park the run; optionally times out to a named step."""
 
-    timeout_ms: int = 3000
-    timeout_step_name: str | None = None
-
-
-class Sleep(msgspec.Struct):
-    """Worker directive to sleep for duration."""
-
-    next_step_name: str
-    duration_ms: int = 3000
-
-
-class SleepUntil(msgspec.Struct):
-    """Worker directive to sleep until timestamp."""
-
-    until: datetime
-    next_step_name: str
+    timeout_ms: int = 0
+    timeout_step_name: str = ""
 
 
 class Complete(msgspec.Struct):
@@ -87,6 +73,13 @@ class Fail(msgspec.Struct):
     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"
@@ -95,10 +88,10 @@ class DirectiveKind(StrEnum):
     fail = "fail"
     step = "step"
     event = "event"
-    wait_event = "wait_event"
-    sleep = "sleep"
-    sleep_until = "sleep_until"
+    wait = "wait"
+    wait_timeout = "wait_timeout"
     step_result = "step_result"
+    fail_step = "fail_step"
 
 
 class StepResult(msgspec.Struct):
@@ -115,7 +108,7 @@ class StepResult(msgspec.Struct):
     duration_ms: int = 0
 
 
-DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | WaitEvent | Sleep | SleepUntil | StepResult
+DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | Wait | StepResult
 
 
 # Factory map for kind-based deserialization
@@ -126,9 +119,7 @@ directive_factories: dict[str, type[DirectiveMessage]] = {
     "complete": Complete,
     "fail": Fail,
     "step": Step,
-    "wait_event": WaitEvent,
-    "sleep": Sleep,
-    "sleep_until": SleepUntil,
+    "wait": Wait,
     "step_result": StepResult,
 }
 

grctl/models/history.py

@@ -15,7 +15,8 @@ class HistoryKind(StrEnum):
     run_cancel_scheduled = "run.cancel_scheduled"
     run_cancelled = "run.cancelled"
     run_timeout = "run.timeout"
-    wait_event_started = "wait_event.started"
+    wait_started = "wait.started"
+    wait_timed_out = "wait.timed_out"
     event_received = "event.received"
     step_started = "step.started"
     step_completed = "step.completed"
@@ -110,8 +111,19 @@ class StepTimeout(msgspec.Struct):
     duration_ms: int
 
 
-class WaitEventStarted(msgspec.Struct):
-    """Wait for event started."""
+class WaitStarted(msgspec.Struct):
+    """Run entered Wait state."""
+
+    directive_id: str = ""
+    timeout_ms: int = 0
+    timeout_step_name: str = ""
+
+
+class WaitTimedOut(msgspec.Struct):
+    """Wait timer expired; timeout step dispatched."""
+
+    original_directive_id: str = ""
+    timeout_step_name: str = ""
 
 
 class EventReceived(msgspec.Struct):
@@ -215,7 +227,7 @@ class ParentEventSent(msgspec.Struct):
 
 
 RunEvents = RunCancelScheduled | RunCancelled | RunCompleted | RunFailed | RunScheduled | RunStarted | RunTimeout
-WaitEvents = WaitEventStarted | EventReceived
+WaitEvents = WaitStarted | WaitTimedOut | EventReceived
 StepEvents = StepStarted | StepCompleted | StepFailed | StepCancelled | StepTimeout
 TaskEvents = TaskStarted | TaskCompleted | TaskFailed | TaskAttemptFailed | TaskCancelled
 DeterministicEvents = TimestampRecorded | RandomRecorded | UuidRecorded | SleepRecorded
@@ -232,7 +244,8 @@ HistoryEvents = (
     | StepFailed
     | StepCancelled
     | StepTimeout
-    | WaitEventStarted
+    | WaitStarted
+    | WaitTimedOut
     | EventReceived
     | TaskStarted
     | TaskCompleted
@@ -269,7 +282,8 @@ history_factories: dict[str, type] = {
     "run.cancel_scheduled": RunCancelScheduled,
     "run.cancelled": RunCancelled,
     "run.timeout": RunTimeout,
-    "wait_event.started": WaitEventStarted,
+    "wait.started": WaitStarted,
+    "wait.timed_out": WaitTimedOut,
     "event.received": EventReceived,
     "step.started": StepStarted,
     "step.completed": StepCompleted,

grctl/models/run_info.py

@@ -19,9 +19,7 @@ class RunStatus(StrEnum):
 class RunStateKind(StrEnum):
     start = "start"
     step = "step"
-    sleep = "sleep"
-    sleep_until = "sleep_until"
-    wait_event = "wait_event"
+    wait = "wait"
     complete = "complete"
     fail = "fail"
     cancel = "cancel"

grctl/worker/context.py

@@ -18,6 +18,7 @@ from grctl.models import (
     ErrorDetails,
     EventCmd,
     Fail,
+    FailStep,
     HistoryKind,
     ParentEventSent,
     RandomRecorded,
@@ -27,7 +28,7 @@ from grctl.models import (
     StepResult,
     TimestampRecorded,
     UuidRecorded,
-    WaitEvent,
+    Wait,
 )
 from grctl.worker.logger import ReplayAwareLogger
 from grctl.worker.runtime import get_step_runtime
@@ -82,14 +83,18 @@ class NextBuilder:
             id=str(ULID()), kind=DirectiveKind.step_result, run_info=self._run, timestamp=datetime.now(UTC), msg=res
         )
 
-    def wait_for_event(self, timeout: timedelta | None = None, timeout_step_name: str | None = None) -> Directive:
+    def wait(self, timeout: timedelta | None = None, on_timeout: StepHandler | None = None) -> Directive:
+        if (timeout is None) != (on_timeout is None):
+            raise ValueError("timeout and on_timeout must both be provided or both omitted")
+
+        timeout_step_name = getattr(on_timeout, "__name__", "") if on_timeout is not None else ""
         res = StepResult(
             processed_msg_kind=self._current_directive.kind,
             processed_msg=self._current_directive.msg,
             worker_id=self._worker_id,
             kv_updates=self._store.get_pending_updates() or {},
-            next_msg_kind=DirectiveKind.wait_event,
-            next_msg=WaitEvent(
+            next_msg_kind=DirectiveKind.wait,
+            next_msg=Wait(
                 timeout_ms=int(timeout.total_seconds() * 1000) if timeout else 0,
                 timeout_step_name=timeout_step_name,
             ),
@@ -115,6 +120,27 @@ class NextBuilder:
             id=str(ULID()), kind=DirectiveKind.step_result, run_info=self._run, timestamp=datetime.now(UTC), msg=res
         )
 
+    def fail_step(self, step_name: str, error: ErrorDetails) -> Directive:
+        res = StepResult(
+            processed_msg_kind=self._current_directive.kind,
+            processed_msg=self._current_directive.msg,
+            worker_id=self._worker_id,
+            kv_updates=self._store.get_pending_updates() or {},
+            next_msg_kind=DirectiveKind.fail_step,
+            next_msg=FailStep(
+                step_name=step_name,
+                error=error,
+            ),
+        )
+
+        return Directive(
+            id=str(ULID()),
+            kind=DirectiveKind.step_result,
+            run_info=self._run,
+            timestamp=datetime.now(UTC),
+            msg=res,
+        )
+
     def fail(self, error: ErrorDetails) -> Directive:
         res = StepResult(
             processed_msg_kind=self._current_directive.kind,

grctl/worker/runner.py

@@ -34,8 +34,9 @@ def workflow_error_handler(func):  # noqa: ANN001, ANN201
             logger.exception(f"Workflow execution failed in {func.__name__}")
 
             ctx = self.runtime.get_step_context()
-            fail_directive = ctx.next.fail(
-                ErrorDetails(
+            fail_directive = ctx.next.fail_step(
+                step_name=self.runtime.step_name,
+                error=ErrorDetails(
                     type=type(e).__name__,
                     message=str(e),
                     stack_trace=stack_trace,

grctl/workflow/handle.py

@@ -1,10 +1,11 @@
+import asyncio
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, TypeVar, overload
 
 from ulid import ULID
 
 from grctl.logging_config import get_logger
-from grctl.models import CmdKind, Command, EventCmd, RunInfo, StartCmd
+from grctl.models import CancelCmd, CmdKind, Command, EventCmd, RunInfo, StartCmd
 from grctl.worker.codec import CodecRegistry
 from grctl.workflow.future import WorkflowFuture
 
@@ -13,6 +14,8 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+_T = TypeVar("_T")
+
 
 class WorkflowHandle:
     def __init__(
@@ -21,11 +24,13 @@ class WorkflowHandle:
         payload: Any | None,
         connection: "Connection",
         codec: CodecRegistry | None = None,
+        return_type: type | None = None,
     ) -> None:
         self.run_info = run_info
         self._payload = payload
         self._connection = connection
         self._codec = codec or CodecRegistry()
+        self._return_type = return_type
         self.future = WorkflowFuture(run_info, connection.nc, payload)
 
     async def attach(self) -> None:
@@ -65,6 +70,43 @@ class WorkflowHandle:
         logger.debug("Publishing event command for workflow %s", cmd)
         await self._connection.publisher.publish_cmd(self.run_info, cmd)
 
+    @overload
+    async def result(self, timeout: float | None = ..., return_type: type[_T] = ...) -> _T: ...  # noqa: ASYNC109
+
+    @overload
+    async def result(self, timeout: float | None = ..., return_type: None = ...) -> Any: ...  # noqa: ASYNC109
+
+    async def result(
+        self,
+        timeout: float | None = None,  # noqa: ASYNC109
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
+        """Wait for workflow completion and return its result.
+
+        timeout: client-side wait in seconds, independent of any server-side execution timeout.
+        return_type: overrides the type bound at start time; falls back to handle's bound type.
+        """
+        resolved_type = return_type or self._return_type
+        try:
+            raw = await asyncio.wait_for(self.future, timeout=timeout)
+            if resolved_type is not None:
+                return self._codec.from_primitive(raw, resolved_type)
+            return raw
+        finally:
+            await self.future.stop()
+
+    async def cancel(self, reason: str | None = None) -> None:
+        cmd = Command(
+            id=str(ULID()),
+            kind=CmdKind.run_cancel,
+            timestamp=datetime.now(UTC),
+            msg=CancelCmd(
+                wf_id=self.run_info.wf_id,
+                reason=reason,
+            ),
+        )
+        await self._connection.publisher.publish_cmd(self.run_info, cmd)
+
     async def query(self, query_name: str) -> Any:
         raise NotImplementedError("query() not yet implemented")
 

grctl/workflow/workflow.py

@@ -6,13 +6,20 @@ import logging
 import typing
 from collections.abc import Awaitable, Callable
 from datetime import timedelta
-from typing import Any, TypeVar
+from typing import Any, Protocol, TypeVar
 
 from grctl.models.directive import Directive
 
 logger = logging.getLogger(__name__)
 
-_HandlerF = TypeVar("_HandlerF", bound=Callable[..., Awaitable[Directive]])
+
+class _Handler(Protocol):
+    __name__: str
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Awaitable[Directive]: ...
+
+
+_HandlerF = TypeVar("_HandlerF", bound=_Handler)
 
 
 @dataclasses.dataclass

{grctl_sdk_python-0.1.4.dist-info → grctl_sdk_python-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.4
+Version: 0.2.1
 Summary: The Python SDK for the Ground Control
 Author: Cem Evren Ates
 Author-email: Cem Evren Ates <cemevre@gmail.com>

{grctl_sdk_python-0.1.4.dist-info → grctl_sdk_python-0.2.1.dist-info}/RECORD

@@ -1,15 +1,15 @@
 grctl/__init__.py,sha256=ovSyTyP0DJxBW_jC8CJrwYUs_BfXtMTnJqJ9qScZZyY,41
 grctl/client/__init__.py,sha256=ka0mRHB6DMhHqUJxOh9lJtn9_8-mDliq61dJI0BTb9s,461
-grctl/client/client.py,sha256=sKaJnKNBlVpmaSoS82StFDEBLL5H5HFjKEtWtsTCWf0,5866
+grctl/client/client.py,sha256=4WrHddyEq8-jbeQ6GF5Xg2WLH-921Eys0VyogdQ0SEk,5733
 grctl/logging_config.py,sha256=OMoz3FRnxAwkE9BNDuFxFu8aRzURnXeU9-75xVXiomg,1457
-grctl/models/__init__.py,sha256=-E1nliiY_Esiz-8Pc3WkyT7eYoph0czLsl3Uz8n6P4w,2752
+grctl/models/__init__.py,sha256=i4Q4PkDPTCJz5E_9kU2UtAlj9pWpUc0dZvM3p4e0KB8,2788
 grctl/models/api.py,sha256=xygDA8b0E5BeQSrtfu_RToTW7XB2XWEO3n-zbh4W4S8,288
 grctl/models/command.py,sha256=SgnaAt2JNQOventxDU5C99-BAOB3WFhQADNsNfVhY54,2509
 grctl/models/common.py,sha256=XtqhHrgwIRlQGTEjrnsAfIPqajEpg9-4MkeSk87eemE,174
-grctl/models/directive.py,sha256=9N_v4YvI4Qew-_O4UHeBnQJ2HrDSkqo9uCflrCFltbY,4947
+grctl/models/directive.py,sha256=Z6JQhMpggbj22mcAjK5gaZ_4jgSqFHUPhdJHAM4dm1Q,4755
 grctl/models/errors.py,sha256=6Nc8DVMLD_3UMeN-mMlwZKbqGo0EF66_3xT8hPGdzAY,294
-grctl/models/history.py,sha256=O_DNZcKG70b169dxBFH3HFw8vTKj9BtKeLGHkQDBoO4,8121
-grctl/models/run_info.py,sha256=OFbZ6ms_G4fpNTuScm03VbaYHpmQUwRzofvIIre3Eu8,2134
+grctl/models/history.py,sha256=iV3ee3NKjWEoSGGb0oa1UzkRtRJ-751ng0sSVZlvhOA,8437
+grctl/models/run_info.py,sha256=p6xhbo19rZAMGF9rjxi3pYhSB1MWfCqBlSB2qHS8DdA,2070
 grctl/models/run_info_helper.py,sha256=WG_lydSwkwX8PFxWZ9vMZw18cwFyQks-50x8-vMOlcE,301
 grctl/models/worker.py,sha256=Av8HQoTkkPUjV0ztq_NckC-Rem57g4ssTFyu8JrqsQo,1889
 grctl/nats/__init__.py,sha256=QTrNaWbv4WV1gLKcQlbPufZYDNCkww42edwxBoHVE-8,37
@@ -26,20 +26,20 @@ grctl/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 grctl/settings.py,sha256=8O88vPcVzLHHv8JVxgNbwE3ErDqxjZf2_N4Tj35t7HM,601
 grctl/worker/__init__.py,sha256=dEnavSsxpbvAFonVcZiS-VPxtvgRneAp86XtuXqabiw,256
 grctl/worker/codec.py,sha256=ywioAv30GKxxAcAAbX7a3unFWpz9OBuzNXzy90i9iyw,1642
-grctl/worker/context.py,sha256=IzKZFS0LBQVTwgkiRaGwhUdCZs_YQrcFW3sqz_oqfZs,10439
+grctl/worker/context.py,sha256=ZFyLmDGrAFf-Nwo4R-g0D4IhiyqFNkGsbq9xxh_gOh4,11371
 grctl/worker/errors.py,sha256=9zmDM2dulJTF6tBkS4ZeUAGqfjRIzsZNzrGJSlaH7d8,982
 grctl/worker/logger.py,sha256=vjHxk03ro1rVvDP2l94lfg-2yeN_pUks4tbrEm52YyQ,1364
 grctl/worker/run_manager.py,sha256=F1jdGrt8KS7WoLIacz6uQizfhTLpGP-21NLCgN3P4sA,4751
-grctl/worker/runner.py,sha256=kded9ikBLxGLA_sm0BrtMAayatiDpGwcuMjnWaFbadU,6885
+grctl/worker/runner.py,sha256=IyosvIsyevcn4qtCJPRgv1AgRR2MWVp9C3ln8HJiISY,6946
 grctl/worker/runtime.py,sha256=MfuYfsV0aEhLmRqrPl4vdnOvLDsWhPpWnfp-nFEqgoY,6783
 grctl/worker/store.py,sha256=puLSeVV4RfWibELGsjdiztZcPBRRlIV1iupAaUr0JYs,1750
 grctl/worker/task.py,sha256=XC0mFqo3cKgejKZO5p2f7XdNpd_2uHQHLeYFRgy9_bA,14493
 grctl/worker/worker.py,sha256=RfA2_TdRDEjoTU7Q_5sTnaxgnoZVIiY6wa3G1UiF5RA,6137
 grctl/workflow/__init__.py,sha256=vu0cIFdbSgH6PSU60keXN2jkkkGn4bSG3UyRpIsSJXU,287
 grctl/workflow/future.py,sha256=oIzTArOYTwTpzVZBxxBxBeSNvswVhqE6CvJhd_-ljKE,5585
-grctl/workflow/handle.py,sha256=YPfGELtraB7GH60BCduP98oFCBBd5x-ewKRlYj1PxZY,2679
-grctl/workflow/workflow.py,sha256=jBdDBGjg6gE0t02CTN1-pBLk2DpMGEsk63TAuQXj7tQ,8602
-grctl_sdk_python-0.1.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-grctl_sdk_python-0.1.4.dist-info/WHEEL,sha256=fWriCkzqm-pffF5af4gJC9iI5FMFaJTuN9UxxxzOmdY,81
-grctl_sdk_python-0.1.4.dist-info/METADATA,sha256=WWCWBeGqgUr1UO0xwASlxgjuuT7kWsh4hNjdlUGhoBQ,2309
-grctl_sdk_python-0.1.4.dist-info/RECORD,,
+grctl/workflow/handle.py,sha256=lw3yOcwItTC_82I_acgnMggWDSnuLw9163FYJD2l8ng,4227
+grctl/workflow/workflow.py,sha256=l5yHf3Ne9_3QycEYvUlvwHartDXjbx63O-v0AUF_W8g,8712
+grctl_sdk_python-0.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+grctl_sdk_python-0.2.1.dist-info/WHEEL,sha256=Q9FtwzuR2QE37l-JIkuyklGnJJiCBHKnsPVQ9vzCMzQ,81
+grctl_sdk_python-0.2.1.dist-info/METADATA,sha256=N2lZqYAwGGKHGBhHKw4Qansi3PL3oFD55K1LHNbSv0k,2309
+grctl_sdk_python-0.2.1.dist-info/RECORD,,

{grctl_sdk_python-0.1.4.dist-info → grctl_sdk_python-0.2.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.11.14
+Generator: uv 0.11.17
 Root-Is-Purelib: true
 Tag: py3-none-any