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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.1
+Version: 0.1.3
 Summary: The Python SDK for the Ground Control
-Author: cemevren
-Author-email: cemevren <cemevren@gmail.com>
+Author: Cem Evren Ates
+Author-email: Cem Evren Ates <cemevre@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Classifier: Development Status :: 3 - Alpha
@@ -25,18 +25,18 @@ Requires-Dist: pydantic-settings>=2.11.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: pydantic>=2.12.5
 Requires-Python: >=3.13
-Project-URL: Homepage, https://github.com/cemevren/grctl
-Project-URL: Documentation, https://cemevren.github.io/grctl/
-Project-URL: Repository, https://github.com/cemevren/grctl
-Project-URL: Issues, https://github.com/cemevren/grctl/issues
-Project-URL: Changelog, https://github.com/cemevren/grctl/blob/main/sdk_python/CHANGELOG.md
+Project-URL: Homepage, https://github.com/grctl/sdk-python
+Project-URL: Documentation, https://grctl.github.io/grctl/
+Project-URL: Repository, https://github.com/grctl/sdk-python
+Project-URL: Issues, https://github.com/grctl/sdk-python/issues
+Project-URL: Changelog, https://github.com/grctl/sdk-python/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # Ground Control Python SDK
 
-The official Python SDK for [Ground Control](https://github.com/cemevren/grctl) — a lightweight workflow orchestration engine built for fail-safe execution.
+The official Python SDK for [Ground Control](https://github.com/grctl/grctl) — a lightweight workflow orchestration engine built for fail-safe execution.
 
-**[Documentation](https://cemevren.github.io/grctl/)**
+**[Documentation](https://grctl.github.io/grctl/)**
 
 > [!WARNING]
 > **Status: Pre-alpha**
@@ -55,12 +55,12 @@ pip install grctl-sdk-python
 
 ## Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](https://github.com/cemevren/grctl/blob/main/CONTRIBUTING.md) for more information.
+Contributions are welcome! Please read our [Contributing Guide](https://github.com/grctl/grctl/blob/main/CONTRIBUTING.md) for more information.
 
 ## Security
 
-Please see our [Security Policy](https://github.com/cemevren/grctl/blob/main/SECURITY.md) for reporting vulnerabilities.
+Please see our [Security Policy](https://github.com/grctl/grctl/blob/main/SECURITY.md) for reporting vulnerabilities.
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/cemevren/grctl/blob/main/LICENSE) file for details.
+This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/grctl/grctl/blob/main/LICENSE) file for details.

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/README.md

@@ -1,8 +1,8 @@
 # Ground Control Python SDK
 
-The official Python SDK for [Ground Control](https://github.com/cemevren/grctl) — a lightweight workflow orchestration engine built for fail-safe execution.
+The official Python SDK for [Ground Control](https://github.com/grctl/grctl) — a lightweight workflow orchestration engine built for fail-safe execution.
 
-**[Documentation](https://cemevren.github.io/grctl/)**
+**[Documentation](https://grctl.github.io/grctl/)**
 
 > [!WARNING]
 > **Status: Pre-alpha**
@@ -21,12 +21,12 @@ pip install grctl-sdk-python
 
 ## Contributing
 
-Contributions are welcome! Please read our [Contributing Guide](https://github.com/cemevren/grctl/blob/main/CONTRIBUTING.md) for more information.
+Contributions are welcome! Please read our [Contributing Guide](https://github.com/grctl/grctl/blob/main/CONTRIBUTING.md) for more information.
 
 ## Security
 
-Please see our [Security Policy](https://github.com/cemevren/grctl/blob/main/SECURITY.md) for reporting vulnerabilities.
+Please see our [Security Policy](https://github.com/grctl/grctl/blob/main/SECURITY.md) for reporting vulnerabilities.
 
 ## License
 
-This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/cemevren/grctl/blob/main/LICENSE) file for details.
+This project is licensed under the Apache License 2.0 - see the [LICENSE](https://github.com/grctl/grctl/blob/main/LICENSE) file for details.

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/grctl/client/client.py

@@ -11,10 +11,11 @@ from typing import Any
 import msgspec
 from ulid import ULID
 
-from grctl.models import DescribeCmd, GrctlAPIResponse, RunInfo
+from grctl.models import DescribeCmd, GrctlAPIResponse, HistoryEvent, RunInfo
 from grctl.models.command import CmdKind, Command
 from grctl.models.errors import 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
 
@@ -30,36 +31,16 @@ class Client:
         self._connection = connection
         self._codec = codec or CodecRegistry()
 
-    async def run_workflow(
-        self,
-        workflow_type: str,
-        workflow_id: str,
-        workflow_input: Any | None = None,
-        workflow_timeout: timedelta | None = None,
-    ) -> Any:
-        """Run a workflow and wait for its result."""
-        wf_handle = await self.start_workflow(
-            workflow_type=workflow_type,
-            workflow_id=workflow_id,
-            workflow_input=workflow_input,
-            workflow_timeout=workflow_timeout,
-        )
-        timeout = workflow_timeout.total_seconds() if workflow_timeout else None
-        try:
-            return await asyncio.wait_for(wf_handle.future, timeout=timeout)
-        finally:
-            await wf_handle.future.stop()
-
-    async def get_workflow_handle(self, workflow_id: str) -> WorkflowHandle:
-        """Get a handle for an already-running workflow."""
+    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=workflow_id),
+            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=workflow_id)
+        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)
@@ -67,10 +48,34 @@ class Client:
             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 '{workflow_id}' not found: {error_msg}")
+                raise WorkflowNotFoundError(f"workflow '{wf_id}' not found: {error_msg}")
             raise WorkflowError(f"describe failed (code={error_code}): {error_msg}")
 
-        run_info = msgspec.msgpack.decode(response.payload, type=RunInfo)
+        return msgspec.msgpack.decode(response.payload, type=RunInfo)
+
+    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
+    ) -> Any:
+        """Run a workflow and wait for its result."""
+        wf_handle = await self.start_workflow(
+            type=type,
+            id=id,
+            input=input,
+            timeout=timeout,
+        )
+        wait_timeout = timeout.total_seconds() if timeout else None
+        try:
+            return await asyncio.wait_for(wf_handle.future, timeout=wait_timeout)
+        finally:
+            await wf_handle.future.stop()
+
+    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,
@@ -81,27 +86,40 @@ class Client:
         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,
-        workflow_type: str,
-        workflow_id: str,
-        workflow_input: Any | None = None,
-        workflow_timeout: timedelta | None = None,
+        type: str,  # noqa: A002
+        id: str,  # noqa: A002
+        input: Any | None = None,  # noqa: A002
+        timeout: timedelta | None = None,  # noqa: ASYNC109
     ) -> 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=workflow_type,
-            wf_id=workflow_id,
-            timeout=int(workflow_timeout.total_seconds()) if workflow_timeout else None,
+            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=workflow_input,
+            payload=input,
             connection=self._connection,
             codec=self._codec,
         )

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/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
 
@@ -202,6 +202,7 @@ class ChildWorkflowStarted(msgspec.Struct):
     run_id: str
     wf_type: str
     wf_id: str
+    input: Any | None = None
 
 
 class ParentEventSent(msgspec.Struct):
@@ -209,6 +210,8 @@ class ParentEventSent(msgspec.Struct):
 
     event_name: str
     payload: Any
+    parent_wf_type: str
+    parent_wf_id: str
 
 
 RunEvents = RunCancelScheduled | RunCancelled | RunCompleted | RunFailed | RunScheduled | RunStarted | RunTimeout
@@ -297,7 +300,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 +311,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.3}/grctl/nats/history_fetch.py

@@ -9,6 +9,36 @@ _FETCH_BATCH_SIZE = 256
 _FETCH_TIMEOUT_SECONDS = 0.25
 
 
+async def fetch_run_history(
+    js: JetStreamContext,
+    manifest: NatsManifest,
+    wf_id: str,
+    run_id: str,
+) -> list[HistoryEvent]:
+    history_subject = manifest.history_subject(wf_id=wf_id, run_id=run_id)
+    history_stream = manifest.history_stream_name()
+    subscription = await js.pull_subscribe(
+        subject=history_subject,
+        stream=history_stream,
+        config=ConsumerConfig(
+            deliver_policy=DeliverPolicy.ALL,
+            ack_policy=AckPolicy.NONE,
+            inactive_threshold=1.0,
+        ),
+    )
+
+    events: list[HistoryEvent] = []
+    try:
+        try:
+            while True:
+                messages = await subscription.fetch(batch=_FETCH_BATCH_SIZE, timeout=_FETCH_TIMEOUT_SECONDS)
+                events.extend(history_decoder(msg.data) for msg in messages if msg.data)
+        except (TimeoutError, FetchTimeoutError):
+            return events
+    finally:
+        await subscription.unsubscribe()
+
+
 async def fetch_step_history(
     js: JetStreamContext,
     manifest: NatsManifest,

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/grctl/nats/subscriber.py

@@ -1,6 +1,7 @@
 import asyncio
 import contextlib
 import json
+from typing import Any
 
 import msgspec
 from nats.aio.msg import Msg
@@ -11,7 +12,6 @@ from grctl.logging_config import get_logger
 from grctl.models import directive_decoder
 from grctl.nats.manifest import NatsManifest
 from grctl.settings import get_settings
-from grctl.worker.run_manager import RunManager
 
 logger = get_logger(__name__)
 
@@ -24,7 +24,7 @@ class Subscriber:
         js: JetStreamContext,
         manifest: NatsManifest,
         wf_types: list[str],
-        run_manager: RunManager,
+        run_manager: Any,
     ) -> None:
         self._js = js
         self._manifest = manifest

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/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
@@ -198,7 +198,12 @@ class Context:
         )
         await runtime.record(
             HistoryKind.parent_event_sent,
-            ParentEventSent(event_name=event_name, payload=payload),
+            ParentEventSent(
+                event_name=event_name,
+                payload=payload,
+                parent_wf_type=self._parent_run.wf_type,
+                parent_wf_id=self._parent_run.wf_id,
+            ),
             operation_id,
         )
 
@@ -244,7 +249,7 @@ class Context:
             await handle.start()
             await runtime.record(
                 HistoryKind.child_started,
-                ChildWorkflowStarted(run_id=run_id, wf_type=workflow_type, wf_id=workflow_id),
+                ChildWorkflowStarted(run_id=run_id, wf_type=workflow_type, wf_id=workflow_id, input=workflow_input),
                 operation_id,
             )
         return handle

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/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.3}/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.3}/grctl/worker/worker.py

@@ -19,6 +19,7 @@ from grctl.workflow.workflow import Workflow
 
 logger = get_logger(__name__)
 
+
 # Constants
 DEFAULT_WORKFLOW_TIMEOUT_SECONDS: float = 30.0
 WORKER_HEARTBEAT_INTERVAL_SECONDS: int = 1
@@ -54,8 +55,10 @@ class Worker:
         self._connection = connection
         self._workflow_logger = workflow_logger
         self._stop_event = asyncio.Event()
+        self._startup_event = asyncio.Event()
         self._subscriber: Subscriber | None = None
         self._run_manager: RunManager | None = None
+        self._startup_error: Exception | None = None
 
     @cached_property
     def worker_name(self) -> str:
@@ -81,31 +84,48 @@ class Worker:
 
         Creates RunManager for workflow execution and subscribes to workflow subjects.
         """
+        self._startup_event.clear()
+        self._startup_error = None
+
         logger.info(
             f"Starting worker with {len(self._workflows)} registered workflows",
         )
 
-        self._run_manager = RunManager(
-            worker_name=self.worker_name,
-            worker_id=self.worker_id,
-            workflows=self._workflows,
-            connection=self._connection,
-            workflow_logger=self._workflow_logger,
-        )
-
-        wf_types = [wf.workflow_type for wf in self._workflows]
-        self._subscriber = Subscriber(
-            js=self._connection.js,
-            manifest=self._connection.manifest,
-            wf_types=wf_types,
-            run_manager=self._run_manager,
-        )
-        await self._subscriber.start()
-
-        logger.info(f"Worker {self.worker_name} ({self.worker_id}) started and ready to process messages")
-
-        # Keep worker alive
-        await self._process_messages()
+        try:
+            self._run_manager = RunManager(
+                worker_name=self.worker_name,
+                worker_id=self.worker_id,
+                workflows=self._workflows,
+                connection=self._connection,
+                workflow_logger=self._workflow_logger,
+            )
+
+            wf_types = [wf.workflow_type for wf in self._workflows]
+            self._subscriber = Subscriber(
+                js=self._connection.js,
+                manifest=self._connection.manifest,
+                wf_types=wf_types,
+                run_manager=self._run_manager,
+            )
+            await self._subscriber.start()
+            self._startup_event.set()
+
+            logger.info(f"Worker {self.worker_name} ({self.worker_id}) started and ready to process messages")
+
+            # Keep worker alive
+            await self._process_messages()
+        except Exception as exc:
+            self._startup_error = exc
+            self._startup_event.set()
+            raise
+
+    async def wait_until_ready(self, timeout_ms: float = 5.0) -> None:
+        """Wait until worker startup succeeds or fails."""
+        await asyncio.wait_for(self._startup_event.wait(), timeout=timeout_ms)
+        if self._startup_error is not None:
+            raise self._startup_error
+        if self._subscriber is None:
+            raise RuntimeError("Worker startup completed without creating a subscriber")
 
     async def _process_messages(self) -> None:
         """Keep worker alive to process commands."""

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/grctl/workflow/future.py

@@ -41,6 +41,8 @@ class WorkflowFuture(asyncio.Future[Any]):
             run_id=run_info.id,
             handler=self._handle_history_event,
         )
+        self._subscriber_stopped = False
+        self.add_done_callback(self._schedule_subscriber_stop)
         self._history_update_handlers: dict[HistoryKind, Callable[[HistoryEvent], None]] = {
             HistoryKind.run_scheduled: self._on_non_terminal_event,
             HistoryKind.run_started: self._on_non_terminal_event,
@@ -54,9 +56,18 @@ class WorkflowFuture(asyncio.Future[Any]):
         """Start listening for events and publish run command."""
         await self._subscriber.start()
 
+    def _schedule_subscriber_stop(self, _: asyncio.Future) -> None:
+        # done_callback must be sync, so we schedule the async stop as a task.
+        if self._subscriber_stopped:
+            return
+        self._subscriber_stopped = True
+        asyncio.ensure_future(self._subscriber.stop())  # noqa: RUF006
+
     async def stop(self) -> None:
         """Stop listening for events and cleanup."""
-        await self._subscriber.stop()
+        if not self._subscriber_stopped:
+            self._subscriber_stopped = True
+            await self._subscriber.stop()
 
         if not self.done():
             self.cancel()

{grctl_sdk_python-0.1.1 → grctl_sdk_python-0.1.3}/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.3}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "grctl-sdk-python"
-version = "0.1.1"
+version = "0.1.3"
 description = "The Python SDK for the Ground Control"
 readme = "README.md"
 requires-python = ">=3.13"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [
-    { name = "cemevren", email = "cemevren@gmail.com" },
+    { name = "Cem Evren Ates", email = "cemevre@gmail.com" },
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -33,11 +33,11 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/cemevren/grctl"
-Documentation = "https://cemevren.github.io/grctl/"
-Repository = "https://github.com/cemevren/grctl"
-Issues = "https://github.com/cemevren/grctl/issues"
-Changelog = "https://github.com/cemevren/grctl/blob/main/sdk_python/CHANGELOG.md"
+Homepage = "https://github.com/grctl/sdk-python"
+Documentation = "https://grctl.github.io/grctl/"
+Repository = "https://github.com/grctl/sdk-python"
+Issues = "https://github.com/grctl/sdk-python/issues"
+Changelog = "https://github.com/grctl/sdk-python/blob/main/CHANGELOG.md"
 
 [build-system]
 requires = ["uv_build>=0.11.6,<0.12"]
@@ -60,7 +60,7 @@ module-name = "grctl"
 module-root = ""
 
 [tool.pytest.ini_options]
-addopts = "--ignore=tests/examples --ignore=tests/e2e"
+addopts = "--ignore=tests/examples --ignore=tests/e2e --ignore=tests/spec"
 testpaths = ["tests"]
 log_cli = true
 log_cli_level = "DEBUG"
@@ -107,6 +107,7 @@ lint.ignore = [
     "ANN204", # Allow missing type annotations for self and cls in tests
     "ARG",    # Unused function args for fixtures
     "COM812",
+    "D104", # Missing docstring in public package
     "FBT",    # Don't care about booleans as positional arguments in tests for @pytest.mark.parametrize
     "INP001", # Ignore that its not in a real python module. Doesn't matter for tests
     # The below are debateable