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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.2
+Version: 0.1.4
 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.2 → grctl_sdk_python-0.1.4}/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.4/grctl/client/__init__.py

@@ -0,0 +1,16 @@
+"""Ground Control Python SDK client package."""
+
+from grctl.client.client import Client
+from grctl.logging_config import get_logger, setup_logging
+from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
+from grctl.nats.connection import Connection
+
+__all__ = [
+    "Client",
+    "Connection",
+    "WorkflowAlreadyRunningError",
+    "WorkflowError",
+    "WorkflowNotFoundError",
+    "get_logger",
+    "setup_logging",
+]

grctl_sdk_python-0.1.4/grctl/client/client.py

@@ -0,0 +1,165 @@
+"""Workflow Engine Client.
+
+Provides a simple interface for interacting with workflows.
+"""
+
+import asyncio
+import logging
+from datetime import UTC, datetime, timedelta
+from typing import Any, TypeVar, overload
+
+import msgspec
+from ulid import ULID
+
+from grctl.models import DescribeCmd, GrctlAPIResponse, HistoryEvent, RunInfo
+from grctl.models.command import CmdKind, Command
+from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
+from grctl.nats.connection import Connection
+from grctl.nats.history_fetch import fetch_run_history
+from grctl.worker.codec import CodecRegistry
+from grctl.workflow.handle import WorkflowHandle
+
+logger = logging.getLogger(__name__)
+
+_T = TypeVar("_T")
+
+ErrWorkflowAlreadyRunningCode = 4001
+ErrWorkflowRunNotFoundCode = 4002
+
+
+class Client:
+    """Client for interacting with the Workflow Engine."""
+
+    def __init__(self, connection: Connection, codec: CodecRegistry | None = None) -> None:
+        self._connection = connection
+        self._codec = codec or CodecRegistry()
+
+    async def describe(self, wf_id: str) -> RunInfo:
+        """Describe the latest run for a workflow ID."""
+        cmd = Command(
+            id=str(ULID()),
+            kind=CmdKind.run_describe,
+            timestamp=datetime.now(UTC),
+            msg=DescribeCmd(wf_id=wf_id),
+        )
+        # Use a routing-only RunInfo — publish_cmd only needs wf_id for subject routing.
+        routing_info = RunInfo(id="", wf_type="", wf_id=wf_id)
+        response_bytes = await self._connection.publisher.publish_cmd(routing_info, cmd)
+
+        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
+        if not response.success:
+            error_msg = response.error.message if response.error else "unknown error"
+            error_code = response.error.code if response.error else 0
+            if error_code == ErrWorkflowRunNotFoundCode:
+                raise WorkflowNotFoundError(f"workflow '{wf_id}' not found: {error_msg}")
+            raise WorkflowError(f"describe failed (code={error_code}): {error_msg}")
+
+        return msgspec.msgpack.decode(response.payload, type=RunInfo)
+
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: type[_T] = ...,
+    ) -> _T: ...
+
+    @overload
+    async def run_workflow(
+        self,
+        type: str,
+        id: str,
+        input: Any | None = ...,
+        timeout: timedelta | None = ...,  # noqa: ASYNC109
+        return_type: None = ...,
+    ) -> Any: ...
+
+    async def run_workflow(
+        self,
+        type: str,  # noqa: A002
+        id: str,  # noqa: A002
+        input: Any | None = None,  # noqa: A002
+        timeout: timedelta | None = None,  # noqa: ASYNC109
+        return_type: type[_T] | None = None,
+    ) -> _T | Any:
+        """Run a workflow and wait for its result."""
+        wf_handle = await self.start_workflow(
+            type=type,
+            id=id,
+            input=input,
+            timeout=timeout,
+        )
+        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()
+
+    async def get_workflow_handle(self, wfid: str) -> WorkflowHandle:
+        """Get a handle for an already-running workflow."""
+        run_info = await self.describe(wfid)
+
+        handle = WorkflowHandle(
+            run_info=run_info,
+            payload=None,
+            connection=self._connection,
+            codec=self._codec,
+        )
+        await handle.attach()
+        return handle
+
+    async def get_history(self, wf_id: str, run_id: str | None = None) -> list[HistoryEvent]:
+        """Return the ordered history events for a workflow run."""
+        resolved_run_id = run_id
+        if resolved_run_id is None:
+            resolved_run_id = (await self.describe(wf_id)).id
+
+        return await fetch_run_history(
+            js=self._connection.js,
+            manifest=self._connection.manifest,
+            wf_id=wf_id,
+            run_id=resolved_run_id,
+        )
+
+    async def start_workflow(
+        self,
+        type: str,  # noqa: A002
+        id: str,  # noqa: A002
+        input: Any | None = None,  # noqa: A002
+        timeout: timedelta | None = None,  # noqa: ASYNC109
+    ) -> WorkflowHandle:
+        """Start a workflow and return a handle to track and interact with it."""
+        workflow_run_id = str(ULID())
+
+        run_info = RunInfo(
+            id=workflow_run_id,
+            wf_type=type,
+            wf_id=id,
+            timeout=int(timeout.total_seconds()) if timeout else None,
+            created_at=datetime.now(UTC),
+        )
+
+        handle = WorkflowHandle(
+            run_info=run_info,
+            payload=input,
+            connection=self._connection,
+            codec=self._codec,
+        )
+
+        # Start the workflow future (subscribe to events and publish run command)
+        response_bytes = await handle.start()
+        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
+        if not response.success:
+            await handle.future.stop()
+            error_msg = response.error.message if response.error else "unknown error"
+            error_code = response.error.code if response.error else 0
+            if error_code == ErrWorkflowAlreadyRunningCode:
+                raise WorkflowAlreadyRunningError(f"workflow '{id}' already has an active run: {error_msg}")
+            raise WorkflowError(f"start_workflow failed (code={error_code}): {error_msg}")
+
+        return handle

{grctl_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/grctl/models/history.py

@@ -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

grctl_sdk_python-0.1.4/grctl/nats/history_fetch.py

@@ -0,0 +1,78 @@
+import logging
+
+from nats.js.api import AckPolicy, ConsumerConfig, DeliverPolicy
+from nats.js.client import JetStreamContext
+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
+
+
+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:
+        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(
+    js: JetStreamContext,
+    manifest: NatsManifest,
+    wf_id: str,
+    run_id: str,
+    history_seq_id: int,
+) -> list[HistoryEvent]:
+    if history_seq_id <= 0:
+        return []
+
+    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.BY_START_SEQUENCE,
+            opt_start_seq=history_seq_id,
+            ack_policy=AckPolicy.NONE,
+            inactive_threshold=1.0,
+        ),
+    )
+
+    events: list[HistoryEvent] = []
+    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):
+        pass
+    finally:
+        await subscription.unsubscribe()
+    return [event for event in events if event.operation_id]

{grctl_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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.2 → grctl_sdk_python-0.1.4}/grctl/worker/context.py

@@ -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.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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_sdk_python-0.1.2 → grctl_sdk_python-0.1.4}/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.2 → grctl_sdk_python-0.1.4}/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.2 → grctl_sdk_python-0.1.4}/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.2 → grctl_sdk_python-0.1.4}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "grctl-sdk-python"
-version = "0.1.2"
+version = "0.1.4"
 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

grctl_sdk_python-0.1.2/grctl/client/__init__.py

@@ -1,7 +0,0 @@
-"""Ground Control Python SDK client package."""
-
-from grctl.client.client import Client
-from grctl.logging_config import get_logger, setup_logging
-from grctl.nats.connection import Connection
-
-__all__ = ["Client", "Connection", "get_logger", "setup_logging"]

grctl_sdk_python-0.1.2/grctl/client/client.py

@@ -1,111 +0,0 @@
-"""Workflow Engine Client.
-
-Provides a simple interface for interacting with workflows.
-"""
-
-import asyncio
-import logging
-from datetime import UTC, datetime, timedelta
-from typing import Any
-
-import msgspec
-from ulid import ULID
-
-from grctl.models import DescribeCmd, GrctlAPIResponse, RunInfo
-from grctl.models.command import CmdKind, Command
-from grctl.models.errors import WorkflowError, WorkflowNotFoundError
-from grctl.nats.connection import Connection
-from grctl.worker.codec import CodecRegistry
-from grctl.workflow.handle import WorkflowHandle
-
-logger = logging.getLogger(__name__)
-
-ErrWorkflowRunNotFoundCode = 4002
-
-
-class Client:
-    """Client for interacting with the Workflow Engine."""
-
-    def __init__(self, connection: Connection, codec: CodecRegistry | None = None) -> None:
-        self._connection = connection
-        self._codec = codec or CodecRegistry()
-
-    async def 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."""
-        cmd = Command(
-            id=str(ULID()),
-            kind=CmdKind.run_describe,
-            timestamp=datetime.now(UTC),
-            msg=DescribeCmd(wf_id=workflow_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)
-        response_bytes = await self._connection.publisher.publish_cmd(routing_info, cmd)
-
-        response = msgspec.msgpack.decode(response_bytes, type=GrctlAPIResponse)
-        if not response.success:
-            error_msg = response.error.message if response.error else "unknown error"
-            error_code = response.error.code if response.error else 0
-            if error_code == ErrWorkflowRunNotFoundCode:
-                raise WorkflowNotFoundError(f"workflow '{workflow_id}' not found: {error_msg}")
-            raise WorkflowError(f"describe failed (code={error_code}): {error_msg}")
-
-        run_info = msgspec.msgpack.decode(response.payload, type=RunInfo)
-
-        handle = WorkflowHandle(
-            run_info=run_info,
-            payload=None,
-            connection=self._connection,
-            codec=self._codec,
-        )
-        await handle.attach()
-        return handle
-
-    async def start_workflow(
-        self,
-        workflow_type: str,
-        workflow_id: str,
-        workflow_input: Any | None = None,
-        workflow_timeout: timedelta | None = None,
-    ) -> WorkflowHandle:
-        """Start a workflow and return a handle to track and interact with it."""
-        workflow_run_id = str(ULID())
-
-        run_info = RunInfo(
-            id=workflow_run_id,
-            wf_type=workflow_type,
-            wf_id=workflow_id,
-            timeout=int(workflow_timeout.total_seconds()) if workflow_timeout else None,
-            created_at=datetime.now(UTC),
-        )
-
-        handle = WorkflowHandle(
-            run_info=run_info,
-            payload=workflow_input,
-            connection=self._connection,
-            codec=self._codec,
-        )
-
-        # Start the workflow future (subscribe to events and publish run command)
-        await handle.start()
-        return handle

grctl_sdk_python-0.1.2/grctl/nats/history_fetch.py

@@ -1,44 +0,0 @@
-from nats.js.api import AckPolicy, ConsumerConfig, DeliverPolicy
-from nats.js.client import JetStreamContext
-from nats.js.errors import FetchTimeoutError
-
-from grctl.models import HistoryEvent, history_decoder
-from grctl.nats.manifest import NatsManifest
-
-_FETCH_BATCH_SIZE = 256
-_FETCH_TIMEOUT_SECONDS = 0.25
-
-
-async def fetch_step_history(
-    js: JetStreamContext,
-    manifest: NatsManifest,
-    wf_id: str,
-    run_id: str,
-    history_seq_id: int,
-) -> list[HistoryEvent]:
-    if history_seq_id <= 0:
-        return []
-
-    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.BY_START_SEQUENCE,
-            opt_start_seq=history_seq_id,
-            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 [event for event in events if event.operation_id]
-    finally:
-        await subscription.unsubscribe()