grctl-sdk-python 0.1.1__tar.gz → 0.1.2__tar.gz

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.1
+Version: 0.1.2
 Summary: The Python SDK for the Ground Control
 Author: cemevren
 Author-email: cemevren <cemevren@gmail.com>

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/models/directive.py

@@ -158,11 +158,11 @@ class DirectiveWire(msgspec.Struct, omit_defaults=True):
     kv: dict[str, Any] | None = None  # kv_revs
 
 
-def directive_encoder(directive: Directive) -> bytes:
+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)
+    msg_bytes = msgspec.msgpack.encode(directive.msg, enc_hook=enc_hook)
 
     wire = DirectiveWire(
         id=directive.id,

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/models/history.py

@@ -135,7 +135,7 @@ class TaskCompleted(msgspec.Struct):
 
     task_id: str
     task_name: str
-    output: Any  # Task return value
+    output: dict[str, Any]  # Always {"result": <primitive>}
     step_name: str
     duration_ms: int
 
@@ -297,7 +297,7 @@ class HistoryWire(msgspec.Struct):
     o: str = ""
 
 
-def history_encoder(event: HistoryEvent) -> bytes:
+def history_encoder(event: HistoryEvent, enc_hook: Any = None) -> bytes:
     """Encode history event to msgpack as array: [kind, msg, run_id, timestamp, wf_id, worker_id]."""
     if event.msg is None:
         raise ValueError("HistoryEvent message cannot be None")
@@ -308,7 +308,7 @@ def history_encoder(event: HistoryEvent) -> bytes:
         wo=event.worker_id,
         ts=event.timestamp,
         k=event.kind,
-        m=msgspec.msgpack.encode(event.msg),
+        m=msgspec.msgpack.encode(event.msg, enc_hook=enc_hook),
         o=event.operation_id,
     )
 

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/nats/publisher.py

@@ -1,3 +1,6 @@
+from collections.abc import Callable
+from typing import Any
+
 from nats.aio.client import Client as NATSClient
 from nats.js.client import JetStreamContext
 
@@ -11,22 +14,25 @@ class Publisher:
         self._js = js
         self._manifest = manifest
 
-    async def publish_history(self, run_info: RunInfo, event: HistoryEvent) -> None:
+    async def publish_history(
+        self, run_info: RunInfo, event: HistoryEvent, enc_hook: Callable[[Any], Any] | None = None
+    ) -> None:
         subject = self._manifest.history_subject(wf_id=run_info.wf_id, run_id=run_info.id)
-        data = history_encoder(event)
+        data = history_encoder(event, enc_hook=enc_hook)
         await self._js.publish(subject, data)
 
     async def publish_next_directive(
         self,
         run: RunInfo,
         directive: Directive,
+        enc_hook: Callable[[Any], Any] | None = None,
     ) -> None:
         subject = self._manifest.directive_subject(
             wf_type=run.wf_type,
             wf_id=run.wf_id,
             run_id=run.id,
         )
-        data = directive_encoder(directive)
+        data = directive_encoder(directive, enc_hook=enc_hook)
         await self._js.publish(subject, data)
 
     async def publish_cmd(

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/worker/codec.py

@@ -1,6 +1,7 @@
 from collections.abc import Callable
 from typing import Any
 
+import msgspec
 import msgspec.msgpack
 from pydantic import BaseModel
 
@@ -35,6 +36,12 @@ class CodecRegistry:
                 return decode(tp, obj)
         raise TypeError(f"Unsupported type: {tp}")
 
+    def to_primitive(self, value: Any) -> Any:
+        return msgspec.to_builtins(value, enc_hook=self.enc_hook)
+
+    def from_primitive(self, raw: Any, tp: type) -> Any:
+        return msgspec.convert(raw, tp, dec_hook=self.dec_hook)
+
     def encode(self, value: Any) -> bytes:
         return msgspec.msgpack.encode(value, enc_hook=self.enc_hook)
 

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/worker/context.py

@@ -33,7 +33,7 @@ from grctl.worker.logger import ReplayAwareLogger
 from grctl.worker.runtime import get_step_runtime
 from grctl.worker.store import Store
 from grctl.workflow import WorkflowHandle
-from grctl.workflow.workflow import StepConfig
+from grctl.workflow.workflow import HandlerConfig
 
 StepHandler = Callable[..., Awaitable[Directive]]
 
@@ -50,7 +50,7 @@ class NextBuilder:
         worker_id: str,
         store: Store,
         current_directive: Directive,
-        step_configs: dict[str, StepConfig] | None = None,
+        step_configs: dict[str, HandlerConfig] | None = None,
     ) -> None:
         self._run = run
         self._worker_id = worker_id
@@ -149,7 +149,7 @@ class Context:
         worker_id: str,
         directive: Directive,
         parent_run: RunInfo | None = None,
-        step_configs: dict[str, StepConfig] | None = None,
+        step_configs: dict[str, HandlerConfig] | None = None,
         workflow_logger: logging.Logger | None = None,
     ) -> None:
         self.run = run_info

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/worker/runner.py

@@ -1,11 +1,8 @@
 import functools
 import traceback
-from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 from typing import Any
 
-import msgspec
-
 from grctl.logging_config import get_logger
 from grctl.models import (
     Directive,
@@ -18,11 +15,9 @@ from grctl.models import (
 )
 from grctl.models.directive import StepResult
 from grctl.models.run_info_helper import RunInfoManager
-from grctl.worker.codec import CodecRegistry
-from grctl.worker.context import Context
 from grctl.worker.errors import NextDirectiveMissingError
 from grctl.worker.runtime import StepRuntime, set_step_runtime
-from grctl.workflow.workflow import HandlerSpec
+from grctl.workflow.workflow import HandlerConfig
 
 logger = get_logger(__name__)
 
@@ -46,7 +41,9 @@ def workflow_error_handler(func):  # noqa: ANN001, ANN201
                     stack_trace=stack_trace,
                 ),
             )
-            await self.runtime.publisher.publish_next_directive(self.runtime.run_info, fail_directive)
+            await self.runtime.publisher.publish_next_directive(
+                self.runtime.run_info, fail_directive, enc_hook=self.runtime.codec.enc_hook
+            )
             raise
 
     return wrapper
@@ -60,20 +57,13 @@ But it's okay for now as we are focusing on correctness and not efficiency.
 
 
 class WorkflowRunner:
-    """Orchestrates workflow run lifecycle.
-
-    Manages the complete workflow run lifecycle including:
-    - Validating run requests
-    - Publishing lifecycle events (started, completed/failed/timeout)
-    - Executing workflow with timeout enforcement
-    - Tracking execution duration
-    """
+    """Orchestrates workflow run lifecycle."""
 
     _result = None
 
     def __init__(self, runtime: StepRuntime) -> None:
         self.runtime = runtime
-        set_step_runtime(runtime)
+        self._runtime_token = set_step_runtime(runtime)
         self.workflow = runtime.workflow
 
     async def handle_directive(self, directive: Directive) -> None:
@@ -90,102 +80,96 @@ class WorkflowRunner:
 
     @workflow_error_handler
     async def handle_start(self, payload: Any | None) -> None:
-        start_config = self.workflow._start_handler  # noqa: SLF001
-        if start_config is None:
+        handler_config = self.workflow._start_handler  # noqa: SLF001
+        if handler_config is None:
             raise ValueError("Workflow start handler is not defined.")
 
         self.runtime.run_info = RunInfoManager.start(self.runtime.run_info, datetime.now(UTC))
         self.runtime.step_name = "start"
-        await _execute_step(self.runtime, start_config.handler, start_config.spec, payload)
+        await self._execute_step(handler_config, payload)
 
     @workflow_error_handler
     async def handle_event(self, event_name: str, payload: Any | None) -> None:
-        """Handle an event by executing its corresponding handler."""
         handler_config = self.workflow._on_event_handlers.get(event_name)  # noqa: SLF001
         if handler_config is None:
             logger.warning(f"No handler registered for event '{event_name}'")
             return
 
         self.runtime.step_name = event_name
-        await _execute_step(self.runtime, handler_config.handler, handler_config.spec, payload)
+        await self._execute_step(handler_config, payload)
 
     @workflow_error_handler
     async def handle_step(self, step: Step) -> None:
-        """Execute workflow step."""
         logger.debug(f"Executing step: {step.step_name} for run {self.runtime.run_info.id}")
 
         step_config = self.workflow._step_handlers.get(step.step_name)  # noqa: SLF001
         if step_config is None:
             raise ValueError(f"Step handler '{step.step_name}' is not defined.")
         self.runtime.step_name = step.step_name
-        await _execute_step(self.runtime, step_config.handler, step_config.spec, None)
+        await self._execute_step(step_config, None)
 
     def _get_event_name(self, handler: Any) -> str | None:
-        """Check if handler is an @on_event handler and return its event name."""
         for event_name, event_config in self.workflow._on_event_handlers.items():  # noqa: SLF001
             if handler == event_config.handler:
                 return event_name
         return None
 
+    async def _execute_step(self, handler_config: HandlerConfig, payload: Any | None) -> None:
+        ctx = self.runtime.get_step_context()
+        start_time = datetime.now(UTC)
 
-async def _dispatch_handler(
-    codec: CodecRegistry,
-    spec: HandlerSpec,
-    ctx: Context,
-    handler: Callable[..., Awaitable[Directive]],
-    payload: Any | None,
-) -> Directive:
-    if not spec.params:
-        return await handler(ctx)
-    if not isinstance(payload, dict):
-        raise TypeError(f"Handler expects params {list(spec.params)} but payload is not a dict: {type(payload)}")
-    typed_kwargs = {
-        name: msgspec.convert(payload[name], param_type, dec_hook=codec.dec_hook)
-        for name, param_type in spec.params.items()
-    }
-    return await handler(ctx, **typed_kwargs)
-
-
-async def _execute_step(
-    runtime: StepRuntime,
-    handler: Callable[..., Awaitable[Directive]],
-    spec: HandlerSpec,
-    payload: Any | None,
-) -> None:
-    ctx = runtime.get_step_context()
-    start_time = datetime.now(UTC)
-
-    await _publish_step_started_event(runtime)
-
-    directive = await _dispatch_handler(runtime.codec, spec, ctx, handler, payload)
-
-    await _publish_next_directive(runtime, directive, start_time)
-
-
-async def _publish_step_started_event(runtime: StepRuntime) -> None:
-    # Step started event will be send by the worker
-    if runtime.step_history is None or len(runtime.step_history) == 0:
-        await runtime.record(
-            kind=HistoryKind.step_started,
-            payload=StepStarted(step_name=runtime.step_name),
-            operation_id="",
-        )
+        await self._publish_step_started_event()
 
+        spec = handler_config.spec
+        handler = handler_config.handler
+        if not spec.params:
+            directive = await handler(ctx)
 
-async def _publish_next_directive(
-    runtime: StepRuntime,
-    directive: Directive,
-    step_start_time: datetime | None = None,
-) -> None:
-    """Process Directive returned by a handler."""
-    if not isinstance(directive, Directive):
-        raise NextDirectiveMissingError(f"Step did not return a Directive. {directive=}", runtime.step_name)
+        # Single param: if payload is already keyed by param name use the value,
+        # otherwise treat payload itself as the value (e.g. bare Pydantic model).
+        elif len(spec.params) == 1:
+            name, param_type = next(iter(spec.params.items()))
+            raw = payload[name] if isinstance(payload, dict) and name in payload else payload
+            typed_value = self.runtime.codec.from_primitive(raw, param_type)
+            directive = await handler(ctx, **{name: typed_value})
 
-    if step_start_time is not None and isinstance(directive.msg, StepResult):
-        directive.msg.duration_ms = int((datetime.now(UTC) - step_start_time).total_seconds() * 1000)
+        # Multi param: convert each param from the payload dict and pass as kwargs
+        else:
+            if not isinstance(payload, dict):
+                raise TypeError(
+                    f"Handler expects params {list(spec.params)} but payload is not a dict: {type(payload)}"
+                )
+            typed_kwargs = {
+                name: self.runtime.codec.from_primitive(payload[name], param_type)
+                for name, param_type in spec.params.items()
+            }
+            directive = await handler(ctx, **typed_kwargs)
+
+        await self._publish_next_directive(directive, start_time)
+
+    async def _publish_step_started_event(self) -> None:
+        if self.runtime.step_history is None or len(self.runtime.step_history) == 0:
+            await self.runtime.record(
+                kind=HistoryKind.step_started,
+                payload=StepStarted(step_name=self.runtime.step_name),
+                operation_id="",
+            )
+
+    async def _publish_next_directive(
+        self,
+        directive: Directive,
+        step_start_time: datetime | None = None,
+    ) -> None:
+        if not isinstance(directive, Directive):
+            raise NextDirectiveMissingError(f"Step did not return a Directive. {directive=}", self.runtime.step_name)
 
-    pending_updates = runtime.store.get_pending_updates()
-    if pending_updates:
-        directive.kv_revs = pending_updates
+        if step_start_time is not None and isinstance(directive.msg, StepResult):
+            directive.msg.duration_ms = int((datetime.now(UTC) - step_start_time).total_seconds() * 1000)
 
-    await runtime.publisher.publish_next_directive(runtime.run_info, directive)
+        pending_updates = self.runtime.store.get_pending_updates()
+        if pending_updates:
+            directive.kv_revs = pending_updates
+
+        await self.runtime.publisher.publish_next_directive(
+            self.runtime.run_info, directive, enc_hook=self.runtime.codec.enc_hook
+        )

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/worker/runtime.py

@@ -1,6 +1,6 @@
 import asyncio
 import hashlib
-from contextvars import ContextVar
+from contextvars import ContextVar, Token
 from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
@@ -29,10 +29,10 @@ def _generate_operation_id(fn_name: str, args: dict[str, Any], seq: int) -> str:
 
 
 class NonDeterminismError(Exception):
-    """Raised when replay journal doesn't match current execution order."""
+    """Raised when replay history doesn't match current execution order."""
 
 
-# Only these kinds participate in replay journal matching — everything else is observability-only
+# Only these kinds participate in replay history matching — everything else is observability-only
 _REPLAY_KINDS = frozenset(
     {
         HistoryKind.task_completed,
@@ -86,6 +86,8 @@ class StepRuntime:
     async def next(
         self, acceptable_kinds: HistoryKind | frozenset[HistoryKind], operation_id: str
     ) -> asyncio.Future[HistoryEvents] | None:
+
+        # Check if we have a step history and the cursor is within bounds. If not, we are not replaying — return None.
         if not self.step_history or self._cursor >= len(self.step_history):
             return None
 
@@ -101,7 +103,7 @@ class StepRuntime:
         if not future.done():
             if self._cursor >= len(self.step_history):
                 self._pending.pop(operation_id, None)
-                return None  # journal exhausted — live execution
+                return None  # history exhausted — live execution
             raise NonDeterminismError(
                 f"Unresolved operation {operation_id} ({acceptable_kinds}) after yield — "
                 f"cursor at {self._cursor}, pending: {list(self._pending.keys())}"
@@ -124,7 +126,7 @@ class StepRuntime:
             if entry.kind not in acceptable_kinds:
                 future.set_exception(
                     NonDeterminismError(
-                        f"Expected one of {acceptable_kinds} but journal has {entry.kind} "
+                        f"Expected one of {acceptable_kinds} but history has {entry.kind} "
                         f"at cursor {self._cursor} for {entry.operation_id}"
                     )
                 )
@@ -134,7 +136,7 @@ class StepRuntime:
 
     async def record(self, kind: HistoryKind, payload: HistoryEvents, operation_id: str) -> None:
         event = self._create_history_event(kind, payload, operation_id)
-        await self.publisher.publish_history(run_info=self.run_info, event=event)
+        await self.publisher.publish_history(run_info=self.run_info, event=event, enc_hook=self.codec.enc_hook)
 
     def get_step_context(self) -> "Context":
         from grctl.worker.context import Context  # noqa: PLC0415
@@ -179,5 +181,5 @@ def get_step_runtime() -> StepRuntime:
     return _step_run_time.get()
 
 
-def set_step_runtime(runtime: StepRuntime) -> None:
-    _step_run_time.set(runtime)
+def set_step_runtime(runtime: StepRuntime) -> Token:
+    return _step_run_time.set(runtime)

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/worker/task.py

@@ -7,7 +7,7 @@ import traceback
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar, cast, overload
+from typing import TYPE_CHECKING, Any, ParamSpec, TypeVar, cast, get_type_hints, overload
 
 from grctl.logging_config import get_logger
 from grctl.models.directive import RetryPolicy
@@ -43,8 +43,7 @@ def _capture_args(fn: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[st
 
 
 def _normalize_args(args_dict: dict[str, Any], codec: CodecRegistry) -> dict[str, Any]:
-    """Normalize task args to msgspec-encodable primitives via codec round-trip."""
-    return {k: codec.decode(codec.encode(v)) for k, v in args_dict.items()}
+    return {k: codec.to_primitive(v) for k, v in args_dict.items()}
 
 
 def _calculate_backoff_delay(policy: RetryPolicy, attempt: int) -> int:
@@ -80,20 +79,17 @@ def _is_error_retryable(error: Exception, policy: RetryPolicy) -> bool:
     """Check if an error should be retried based on the retry policy filters."""
     error_type = type(error).__name__
 
-    has_retryable = policy.retryable_errors is not None
-    has_non_retryable = policy.non_retryable_errors is not None
-
-    if not has_retryable and not has_non_retryable:
+    if policy.retryable_errors is None and policy.non_retryable_errors is None:
         return True
 
-    if has_retryable and not has_non_retryable:
-        return error_type in policy.retryable_errors  # type: ignore[operator]  # ty:ignore[unsupported-operator]
+    if policy.retryable_errors is not None and policy.non_retryable_errors is None:
+        return error_type in policy.retryable_errors
 
-    if not has_retryable and has_non_retryable:
-        return error_type not in policy.non_retryable_errors  # type: ignore[operator]  # ty:ignore[unsupported-operator]
+    if policy.retryable_errors is None and policy.non_retryable_errors is not None:
+        return error_type not in policy.non_retryable_errors
 
     # Both set: must be in retryable AND not in non_retryable
-    return error_type in policy.retryable_errors and error_type not in policy.non_retryable_errors  # type: ignore[operator]  # ty:ignore[unsupported-operator]
+    return error_type in policy.retryable_errors and error_type not in policy.non_retryable_errors  # ty:ignore[unsupported-operator]
 
 
 @dataclass
@@ -139,8 +135,8 @@ class RetryRunner:
                 can_retry = (
                     self._policy is not None and attempt < self._max_attempts and _is_error_retryable(e, self._policy)
                 )
-                if can_retry:
-                    delay_ms = _calculate_backoff_delay(self._policy, attempt)  # type: ignore[arg-type]  # ty:ignore[invalid-argument-type]
+                if can_retry and self._policy is not None:
+                    delay_ms = _calculate_backoff_delay(self._policy, attempt)
                     yield AttemptFailed(
                         attempt=attempt,
                         max_attempts=self._max_attempts,
@@ -349,6 +345,8 @@ async def _execute_task(
     normalized_args = _normalize_args(args_dict, runtime.codec)
     operation_id = runtime.generate_operation_id(task_name, normalized_args)
 
+    # If it's a replaying run, wait for the task outcome from the step history (in-memory).
+    # Otherwise, execute the task live.
     future = await runtime.next(
         frozenset({HistoryKind.task_completed, HistoryKind.task_failed, HistoryKind.task_cancelled}),
         operation_id,
@@ -357,7 +355,14 @@ async def _execute_task(
         logger.info(f"Replaying outcome for task {task_name} ({operation_id}) in step {step_name}")
         event = await future
         if isinstance(event, TaskCompleted):
-            return event.output
+            raw = event.output["result"]
+            try:
+                return_type = get_type_hints(fn).get("return")
+            except Exception:
+                return_type = None
+            if return_type is not None:
+                return runtime.codec.from_primitive(raw, return_type)
+            return raw
         if isinstance(event, TaskFailed):
             raise _reconstruct_error(event.error)
         # TaskCancelled — task didn't finish; fall through to execute it live
@@ -391,7 +396,7 @@ async def _execute_task(
             task_id=operation_id,
             task_name=task_name,
             step_name=step_name,
-            output=result,
+            output={"result": runtime.codec.to_primitive(result)},
             duration_ms=duration_ms,
         ),
         operation_id,

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/workflow/__init__.py

@@ -2,11 +2,11 @@
 
 from grctl.models.directive import Directive
 from grctl.workflow.handle import WorkflowHandle
-from grctl.workflow.workflow import StepConfig, Workflow
+from grctl.workflow.workflow import HandlerConfig, Workflow
 
 __all__ = [
     "Directive",
-    "StepConfig",
+    "HandlerConfig",
     "Workflow",
     "WorkflowHandle",
 ]

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/grctl/workflow/workflow.py

@@ -44,12 +44,6 @@ def inspect_handler(fn: Callable[..., Any]) -> HandlerSpec:
 class HandlerConfig:
     handler: Callable[..., Awaitable[Directive]]
     spec: HandlerSpec
-
-
-@dataclasses.dataclass
-class StepConfig:
-    handler: Callable[..., Awaitable[Directive]]
-    spec: HandlerSpec
     timeout: timedelta | None = None
 
 
@@ -82,7 +76,7 @@ class Workflow:
         self._type = workflow_type
         self._start_handler: HandlerConfig | None = None
         self._run_handler: Callable[..., Any] | None = None
-        self._step_handlers: dict[str, StepConfig] = {}
+        self._step_handlers: dict[str, HandlerConfig] = {}
         self._on_event_handlers: dict[str, HandlerConfig] = {}
         self._update_handlers: dict[str, Callable[..., Any]] = {}
         self._query_handlers: dict[str, Callable[..., Any]] = {}
@@ -170,7 +164,7 @@ class Workflow:
             step_timeout = timeout if timeout is not None else timedelta(seconds=10)
             spec = inspect_handler(func)
 
-            self._step_handlers[func.__name__] = StepConfig(
+            self._step_handlers[func.__name__] = HandlerConfig(
                 handler=func,
                 spec=spec,
                 timeout=step_timeout,

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "grctl-sdk-python"
-version = "0.1.1"
+version = "0.1.2"
 description = "The Python SDK for the Ground Control"
 readme = "README.md"
 requires-python = ">=3.13"