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

grctl/client/__init__.py

@@ -2,6 +2,15 @@
 
 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", "get_logger", "setup_logging"]
+__all__ = [
+    "Client",
+    "Connection",
+    "WorkflowAlreadyRunningError",
+    "WorkflowError",
+    "WorkflowNotFoundError",
+    "get_logger",
+    "setup_logging",
+]

grctl/client/client.py

@@ -6,14 +6,14 @@ Provides a simple interface for interacting with workflows.
 import asyncio
 import logging
 from datetime import UTC, datetime, timedelta
-from typing import Any
+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 WorkflowError, WorkflowNotFoundError
+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
@@ -21,6 +21,9 @@ from grctl.workflow.handle import WorkflowHandle
 
 logger = logging.getLogger(__name__)
 
+_T = TypeVar("_T")
+
+ErrWorkflowAlreadyRunningCode = 4001
 ErrWorkflowRunNotFoundCode = 4002
 
 
@@ -53,13 +56,34 @@ class Client:
 
         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
-    ) -> Any:
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
         """Run a workflow and wait for its result."""
         wf_handle = await self.start_workflow(
             type=type,
@@ -69,7 +93,10 @@ class Client:
         )
         wait_timeout = timeout.total_seconds() if timeout else None
         try:
-            return await asyncio.wait_for(wf_handle.future, timeout=wait_timeout)
+            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()
 
@@ -125,5 +152,14 @@ class Client:
         )
 
         # Start the workflow future (subscribe to events and publish run command)
-        await handle.start()
+        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/errors.py

@@ -4,3 +4,7 @@ class WorkflowError(Exception):
 
 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."""

grctl/nats/history_fetch.py

@@ -1,10 +1,14 @@
+import logging
+
 from nats.js.api import AckPolicy, ConsumerConfig, DeliverPolicy
 from nats.js.client import JetStreamContext
-from nats.js.errors import FetchTimeoutError
+from nats.js.errors import FetchTimeoutError, ServiceUnavailableError
 
 from grctl.models import HistoryEvent, history_decoder
 from grctl.nats.manifest import NatsManifest
 
+logger = logging.getLogger(__name__)
+
 _FETCH_BATCH_SIZE = 256
 _FETCH_TIMEOUT_SECONDS = 0.25
 
@@ -29,14 +33,14 @@ async def fetch_run_history(
 
     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
+        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, ServiceUnavailableError):
+        pass
     finally:
         await subscription.unsubscribe()
+    return events
 
 
 async def fetch_step_history(
@@ -64,11 +68,11 @@ async def fetch_step_history(
 
     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 [event for event in events if event.operation_id]
+        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):
+        pass
     finally:
         await subscription.unsubscribe()
+    return [event for event in events if event.operation_id]

grctl/nats/kv_store.py

@@ -37,7 +37,8 @@ class KVStore:
                 return None
 
         except Exception as e:
-            if "key not found" in str(e).lower():
+            msg = str(e).lower()
+            if "key not found" in msg or "no message found" in msg:
                 return None
             raise
         else:

grctl/nats/publisher.py

@@ -42,5 +42,5 @@ class Publisher:
     ) -> bytes:
         subject = self._manifest.api_subject(wf_id=run.wf_id)
         data = command_encoder(cmd)
-        msg = await self._nc.request(subject, data)
+        msg = await self._nc.request(subject, data, timeout=5.0)
         return msg.data

grctl/worker/errors.py

@@ -12,13 +12,6 @@ class WorkflowRunnerNotFoundError(Exception):
         super().__init__(f"WorkflowRunner not found for WorkflowRun ID '{run_id}'.")
 
 
-class WorkflowAlreadyRunningError(Exception):
-    """Exception raised when attempting to start a workflow that is already running."""
-
-    def __init__(self, run_id: str) -> None:
-        super().__init__(f"WorkflowRun ID '{run_id}' is already running.")
-
-
 class NextDirectiveMissingError(Exception):
     """Exception raised when a workflow handler does not return a NextDirective."""
 

grctl/worker/runner.py

@@ -122,7 +122,7 @@ class WorkflowRunner:
 
         spec = handler_config.spec
         handler = handler_config.handler
-        if not spec.params:
+        if not spec.params or payload is None:
             directive = await handler(ctx)
 
         # Single param: if payload is already keyed by param name use the value,

grctl/worker/task.py

@@ -365,7 +365,8 @@ async def _execute_task(
             return raw
         if isinstance(event, TaskFailed):
             raise _reconstruct_error(event.error)
-        # TaskCancelled — task didn't finish; fall through to execute it live
+        if isinstance(event, TaskCancelled):
+            raise asyncio.CancelledError
 
     previous_attempts = sum(
         1

grctl/workflow/handle.py

@@ -33,7 +33,7 @@ class WorkflowHandle:
         logger.debug("Attaching to existing workflow %s", self.run_info.wf_id)
         await self.future.start()
 
-    async def start(self) -> None:
+    async def start(self) -> bytes:
         """Start the workflow future (subscribe to events and publish run command)."""
         input_value = self._codec.decode(self._codec.encode(self._payload)) if self._payload is not None else None
         cmd = Command(
@@ -48,7 +48,7 @@ class WorkflowHandle:
         logger.debug("Starting workflow history listener")
         await self.future.start()
         logger.debug("Publishing start command for workflow %s ", cmd)
-        await self._connection.publisher.publish_cmd(self.run_info, cmd)
+        return await self._connection.publisher.publish_cmd(self.run_info, cmd)
 
     async def send(self, event_name: str, payload: Any | None = None) -> None:
         normalized = self._codec.decode(self._codec.encode(payload)) if payload is not None else None

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.3
+Version: 0.1.4
 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.3.dist-info → grctl_sdk_python-0.1.4.dist-info}/RECORD

@@ -1,45 +1,45 @@
 grctl/__init__.py,sha256=ovSyTyP0DJxBW_jC8CJrwYUs_BfXtMTnJqJ9qScZZyY,41
-grctl/client/__init__.py,sha256=FxY4a__J1SciqPTtouzQP8e76yRInchtrv_5OT9XoXc,259
-grctl/client/client.py,sha256=0ozm-sRz0kiV0U1VWJjNTCnd14uQJ4U_3Uk66JxGLZw,4510
+grctl/client/__init__.py,sha256=ka0mRHB6DMhHqUJxOh9lJtn9_8-mDliq61dJI0BTb9s,461
+grctl/client/client.py,sha256=sKaJnKNBlVpmaSoS82StFDEBLL5H5HFjKEtWtsTCWf0,5866
 grctl/logging_config.py,sha256=OMoz3FRnxAwkE9BNDuFxFu8aRzURnXeU9-75xVXiomg,1457
 grctl/models/__init__.py,sha256=-E1nliiY_Esiz-8Pc3WkyT7eYoph0czLsl3Uz8n6P4w,2752
 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/errors.py,sha256=ckFlCRgmiYYWXqi22pY9cOIGRCgGXiG4FknhxjD4oqU,179
+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/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
 grctl/nats/connection.py,sha256=DIQ7jz0XXRGlTeuuvV-cq4iNDj06V397vGo44Pnyqdg,1878
-grctl/nats/history_fetch.py,sha256=UuCWSe9jPP0Ry8HDePN_VOx0B07JNMxQmKpuxSxNTKY,2398
+grctl/nats/history_fetch.py,sha256=QH7tsXhHmuwISWQezJ3MXGoOLFDvGavpncsSKkwtzAA,2454
 grctl/nats/history_sub.py,sha256=E-t5loBTYNU5OH_8Xr4WFGFo3jrU9URbvBc-TxGSmxw,2198
-grctl/nats/kv_store.py,sha256=fYoigg3_GHryYrphf9OoA-3uyffPr-YDz4Dt5G1u5OQ,1307
+grctl/nats/kv_store.py,sha256=o4hXC_DxPa-Jg5OFeT5srVvLYgP-9LBDqL4_FY9zpXM,1358
 grctl/nats/manifest.py,sha256=NMxeuw5_j8WKqGdOp3DInGBLrYriye9RD3y4Ymr0mW8,9222
 grctl/nats/nats_client.py,sha256=3XK8K3_ix-3vcGnMXo_LAY2fn-14y8JVSjbFCF_6OC4,343
 grctl/nats/nats_manifest.yaml,sha256=FZXsJY3wqSNp3mhzh2awA_7NDq8OV8Mz0b2VK03T_dM,2661
-grctl/nats/publisher.py,sha256=-PCkfd4OIyjHa645oLuAGQyL3dy2bw0serMtmyF4f1o,1561
+grctl/nats/publisher.py,sha256=5lqsXJ7rDP2Lis9cvniBygxdB-43OOjvuhWaVAw7PyA,1574
 grctl/nats/subscriber.py,sha256=0LG1CkR--fxPe5PuFTuFNEA1UoXupRvqvek2T0fpUQA,4436
 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/errors.py,sha256=QFFruX23v1r-Xnc6gihRfLaapnUSY9HMBPWq5lwjB_U,1239
+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=icz-Q9SY3u4bma1iwzUaq6ifAo0E1QrWYBJknI495Ec,6866
+grctl/worker/runner.py,sha256=kded9ikBLxGLA_sm0BrtMAayatiDpGwcuMjnWaFbadU,6885
 grctl/worker/runtime.py,sha256=MfuYfsV0aEhLmRqrPl4vdnOvLDsWhPpWnfp-nFEqgoY,6783
 grctl/worker/store.py,sha256=puLSeVV4RfWibELGsjdiztZcPBRRlIV1iupAaUr0JYs,1750
-grctl/worker/task.py,sha256=3FFbMiLdBTXAV2L6DI3kRfqYxXxu-0_mLUvieovh0TU,14487
+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=3dRhwLHRSfO7-wvka3YL_JEkUJLvy2Lnr1dMXWwAsuE,2671
+grctl/workflow/handle.py,sha256=YPfGELtraB7GH60BCduP98oFCBBd5x-ewKRlYj1PxZY,2679
 grctl/workflow/workflow.py,sha256=jBdDBGjg6gE0t02CTN1-pBLk2DpMGEsk63TAuQXj7tQ,8602
-grctl_sdk_python-0.1.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-grctl_sdk_python-0.1.3.dist-info/WHEEL,sha256=q5IF0q2xCp3ktUFRCVWsQLjl2ChNlWXBJtnI1LCGdJ8,80
-grctl_sdk_python-0.1.3.dist-info/METADATA,sha256=tK61B6ZhJKVHMZURivXut8gXVajyAj7iFaeOMsk5m9g,2309
-grctl_sdk_python-0.1.3.dist-info/RECORD,,
+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_sdk_python-0.1.3.dist-info → grctl_sdk_python-0.1.4.dist-info}/WHEEL

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