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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: grctl-sdk-python
-Version: 0.1.2
+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.2 → 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.2 → 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.2 → grctl_sdk_python-0.1.3}/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.2 → 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.2 → 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.2 → grctl_sdk_python-0.1.3}/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.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.2 → 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.2 → grctl_sdk_python-0.1.3}/pyproject.toml

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