stackgen-sdk 0.1.6__tar.gz → 0.1.7__tar.gz

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.1.6
+Version: 0.1.7
 Summary: StackGen SDK — Aiden, SRE, and Vault from one client
 Project-URL: Homepage, https://appcd-dev.github.io/stackgen-sdk/
 Project-URL: Documentation, https://appcd-dev.github.io/stackgen-sdk/

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/src/stackgen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.6'
-__version_tuple__ = version_tuple = (0, 1, 6)
+__version__ = version = '0.1.7'
+__version_tuple__ = version_tuple = (0, 1, 7)
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/src/stackgen/aiden/__init__.py

@@ -2,6 +2,7 @@
 
 from stackgen.aiden.ask import AskArtifactResult
 from stackgen.aiden.namespace import AidenNamespace
+from stackgen.aiden.run_status import ExecutionStatus, RunPhase, RunStatus
 from stackgen.aiden.webhook import WebhookReportResult
 from stackgen.aiden.workflow_builder import (
     AgentDefinition,
@@ -18,7 +19,10 @@ __all__ = [
     "AgentDefinition",
     "AidenNamespace",
     "AskArtifactResult",
+    "ExecutionStatus",
     "PublishWorkflowResult",
+    "RunPhase",
+    "RunStatus",
     "StageDefinition",
     "WebhookReportResult",
     "WorkflowBuilder",

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/src/stackgen/aiden/ask.py

@@ -10,11 +10,10 @@ from typing import Any
 
 from stackgen import _http
 from stackgen.aiden import sessions as session_helpers
+from stackgen.aiden.run_status import ExecutionStatus
 from stackgen.config import StackgenConfig
 from stackgen.errors import StackgenError, TimeoutError
 
-_TERMINAL_STATUSES = frozenset({"completed", "error"})
-
 
 @dataclass(frozen=True)
 class AskArtifactResult:
@@ -156,16 +155,20 @@ class AskArtifactJourney:
             if not isinstance(data, dict):
                 raise StackgenError(f"unexpected getExecutionTrace payload: {data!r}")
             execution = data.get("execution") or {}
-            status = _http.text(execution.get("status")).casefold()
+            status = ExecutionStatus.parse(_http.text(execution.get("status")))
             # Prefer explicit settle when the mothership sends it. Some builds
             # omit trace_settled on the thin getExecutionTrace summary; treat
             # terminal status alone as done so callers are not stuck forever.
             settled = execution.get("trace_settled")
-            ready = status in _TERMINAL_STATUSES and settled is not False
+            ready = (
+                status is not None
+                and status.is_terminal()
+                and settled is not False
+            )
             if ready:
-                if status == "error":
+                if status in {ExecutionStatus.ERROR, ExecutionStatus.FAILED}:
                     raise StackgenError(
-                        f"execution {trace_id} ended with status error"
+                        f"execution {trace_id} ended with status {status.value}"
                     )
                 return data
             time.sleep(cfg.poll_interval_seconds)

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/src/stackgen/aiden/namespace.py

@@ -6,11 +6,13 @@ from pathlib import Path
 from typing import Any
 
 from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
+from stackgen.aiden.run_status import RunStatus, build_run_status, require_run_ids
 from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
 from stackgen.aiden.webhook_ops import WebhookOps
 from stackgen.aiden.workflow_builder import AgentDefinition, WorkflowDefinition
 from stackgen.aiden.workflow_publish import PublishWorkflowResult, WorkflowPublishJourney
 from stackgen.config import StackgenConfig
+from stackgen import _http
 
 
 class AidenNamespace:
@@ -142,7 +144,12 @@ class AidenNamespace:
         source_app: str | None = None,
         source_metadata: dict[str, str] | None = None,
     ) -> dict[str, Any]:
-        """POST /guild/api/v1/guild/ask/start (advanced callers)."""
+        """POST /guild/api/v1/guild/ask/start (fire-and-forget).
+
+        Returns ``session_id`` / ``trace_id`` immediately. Persist those ids and
+        call :meth:`get_run_status` from a separate scheduler — this method does
+        not wait for completion.
+        """
         return self._ask.start_ask(
             message,
             entity_refs=entity_refs,
@@ -152,8 +159,72 @@ class AidenNamespace:
             source_metadata=source_metadata,
         )
 
+    def start_workflow_run(
+        self,
+        workflow_name: str,
+        *,
+        input: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """POST /guild/api/v1/workflows/{name}/run (fire-and-forget).
+
+        Returns ``session_id`` / ``trace_id`` immediately. Does not wait.
+        """
+        return self._webhook_ops.start_workflow_run(workflow_name, input=input)
+
+    def get_run_status(
+        self,
+        *,
+        session_id: str | None = None,
+        trace_id: str | None = None,
+        ready_artifact: str | None = None,
+    ) -> RunStatus:
+        """Stateless status for a run started elsewhere (queue / scheduler).
+
+        One HTTP round-trip set only — never blocks or polls. Use from a
+        separate process that holds ``session_id`` and/or ``trace_id`` in your
+        own store.
+
+        When ``ready_artifact`` is set (e.g. ``session-report.md``), ``ready`` is
+        true only once that artifact appears on the session.
+        """
+        require_run_ids(session_id=session_id, trace_id=trace_id)
+        sid = _http.text(session_id)
+        tid = _http.text(trace_id)
+        session: dict[str, Any] = {}
+        trace: dict[str, Any] = {}
+        names: list[str] = []
+
+        if tid:
+            trace = self.get_execution_trace(tid)
+            if not sid:
+                sid = _http.text(trace.get("session_id"))
+                execution = trace.get("execution") or {}
+                if isinstance(execution, dict) and not sid:
+                    sid = _http.text(execution.get("session_id"))
+
+        if sid:
+            session = self.get_session(sid)
+            arts = self.list_session_artifacts(sid)
+            for a in arts:
+                if isinstance(a, dict):
+                    name = _http.text(a.get("name"))
+                    if name:
+                        names.append(name)
+
+        return build_run_status(
+            session_id=sid,
+            trace_id=tid,
+            session=session,
+            trace=trace,
+            artifact_names=names,
+            ready_artifact=ready_artifact or "",
+        )
+
     def wait_for_execution(self, trace_id: str) -> dict[str, Any]:
-        """Poll GET /guild/api/v1/executions/{traceId} until settled."""
+        """Poll GET /guild/api/v1/executions/{traceId} until settled (blocking).
+
+        Prefer :meth:`get_run_status` for queue/scheduler architectures.
+        """
         return self._ask.wait_for_execution(trace_id)
 
     def publish_workflow(

stackgen_sdk-0.1.7/src/stackgen/aiden/run_status.py

@@ -0,0 +1,202 @@
+"""Stateless run status for queue / scheduler architectures.
+
+Callers that submit work on one process and poll from another should persist
+``session_id`` / ``trace_id``, then use :meth:`AidenNamespace.get_run_status`.
+These helpers never block.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from stackgen import _http
+from stackgen.errors import StackgenError
+
+
+class ExecutionStatus(str, Enum):
+    """Raw Guild execution ``status`` values (OpenAPI ExecutionMeta.status).
+
+    OpenAPI documents ``running``, ``completed``, and ``error``; Guild also
+    emits cancel variants. Unknown wire values are left as strings on
+    :attr:`RunStatus.execution_status` rather than forced into this enum.
+    """
+
+    RUNNING = "running"
+    COMPLETED = "completed"
+    ERROR = "error"
+    FAILED = "failed"
+    CANCELLING = "cancelling"
+    CANCELLED = "cancelled"
+    QUEUED = "queued"
+    PENDING = "pending"
+
+    @classmethod
+    def parse(cls, value: str) -> ExecutionStatus | None:
+        key = (value or "").strip().casefold()
+        if not key:
+            return None
+        aliases = {
+            "canceled": cls.CANCELLED,
+            "in_progress": cls.RUNNING,
+            "active": cls.RUNNING,
+            "started": cls.RUNNING,
+            "success": cls.COMPLETED,
+            "succeeded": cls.COMPLETED,
+            "terminated": cls.CANCELLED,
+        }
+        if key in aliases:
+            return aliases[key]
+        try:
+            return cls(key)
+        except ValueError:
+            return None
+
+    def is_terminal(self) -> bool:
+        return self in {
+            ExecutionStatus.COMPLETED,
+            ExecutionStatus.ERROR,
+            ExecutionStatus.FAILED,
+            ExecutionStatus.CANCELLED,
+        }
+
+    def is_active(self) -> bool:
+        return self in {
+            ExecutionStatus.RUNNING,
+            ExecutionStatus.CANCELLING,
+            ExecutionStatus.QUEUED,
+            ExecutionStatus.PENDING,
+        }
+
+
+class RunPhase(str, Enum):
+    """Normalized scheduler-facing phase from :meth:`AidenNamespace.get_run_status`."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    ERROR = "error"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True)
+class RunStatus:
+    """Normalized one-shot status for a previously started run."""
+
+    phase: RunPhase
+    session_id: str = ""
+    trace_id: str = ""
+    run_id: str = ""
+    execution_status: str = ""
+    session_status: str = ""
+    artifact_names: tuple[str, ...] = ()
+    ready: bool = False
+    ready_artifact: str = ""
+    session: dict[str, Any] = field(default_factory=dict)
+    execution: dict[str, Any] = field(default_factory=dict)
+    trace: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "phase": self.phase.value,
+            "session_id": self.session_id,
+            "trace_id": self.trace_id,
+            "run_id": self.run_id,
+            "execution_status": self.execution_status,
+            "session_status": self.session_status,
+            "artifact_names": list(self.artifact_names),
+            "ready": self.ready,
+            "ready_artifact": self.ready_artifact,
+        }
+
+
+def _phase_from_status(status: str) -> RunPhase:
+    parsed = ExecutionStatus.parse(status)
+    if parsed is None:
+        return RunPhase.UNKNOWN if not status else RunPhase.RUNNING
+    if parsed is ExecutionStatus.COMPLETED:
+        return RunPhase.COMPLETED
+    if parsed in {
+        ExecutionStatus.ERROR,
+        ExecutionStatus.FAILED,
+        ExecutionStatus.CANCELLED,
+    }:
+        return RunPhase.ERROR
+    if parsed in {ExecutionStatus.QUEUED, ExecutionStatus.PENDING}:
+        return RunPhase.PENDING
+    if parsed.is_active():
+        return RunPhase.RUNNING
+    return RunPhase.RUNNING
+
+
+def build_run_status(
+    *,
+    session_id: str = "",
+    trace_id: str = "",
+    session: dict[str, Any] | None = None,
+    trace: dict[str, Any] | None = None,
+    artifact_names: list[str] | tuple[str, ...] = (),
+    ready_artifact: str = "",
+) -> RunStatus:
+    """Derive :class:`RunStatus` from optional session + execution payloads."""
+    session = session or {}
+    trace = trace or {}
+    execution = trace.get("execution") if isinstance(trace.get("execution"), dict) else {}
+    if not execution and isinstance(trace, dict):
+        # Some thin responses put status at the top level.
+        if "status" in trace and "execution" not in trace:
+            execution = trace
+
+    sid = session_id or _http.text(session.get("id") or session.get("session_id") or trace.get("session_id"))
+    tid = trace_id or _http.text(trace.get("trace_id") or execution.get("trace_id"))
+    run_id = _http.text(
+        execution.get("run_id")
+        or session.get("run_id")
+        or trace.get("run_id")
+    )
+    exec_status = _http.text(execution.get("status"))
+    sess_status = _http.text(session.get("status") or session.get("state"))
+    names = tuple(n for n in artifact_names if n)
+    ready_name = ready_artifact.strip()
+    ready = bool(ready_name and ready_name in names)
+
+    phase = RunPhase.UNKNOWN
+    if ready:
+        phase = RunPhase.COMPLETED
+    else:
+        exec_phase = _phase_from_status(exec_status)
+        sess_phase = _phase_from_status(sess_status)
+        if exec_phase is RunPhase.ERROR or sess_phase is RunPhase.ERROR:
+            phase = RunPhase.ERROR
+        elif exec_phase is RunPhase.COMPLETED or sess_phase is RunPhase.COMPLETED:
+            # Terminal execution without the caller's ready artifact yet —
+            # still running from a report-consumer perspective when a
+            # ready_artifact was requested; otherwise completed.
+            phase = RunPhase.RUNNING if ready_name else RunPhase.COMPLETED
+        elif exec_phase in {RunPhase.RUNNING, RunPhase.PENDING}:
+            phase = exec_phase
+        elif sess_phase in {RunPhase.RUNNING, RunPhase.PENDING}:
+            phase = sess_phase
+        elif sid or tid:
+            phase = RunPhase.RUNNING
+
+    return RunStatus(
+        phase=phase,
+        session_id=sid,
+        trace_id=tid,
+        run_id=run_id,
+        execution_status=exec_status,
+        session_status=sess_status,
+        artifact_names=names,
+        ready=ready,
+        ready_artifact=ready_name,
+        session=dict(session),
+        execution=dict(execution) if isinstance(execution, dict) else {},
+        trace=dict(trace),
+    )
+
+
+def require_run_ids(*, session_id: str | None, trace_id: str | None) -> None:
+    if not (session_id or trace_id):
+        raise StackgenError("get_run_status requires session_id and/or trace_id")

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.7}/src/stackgen/aiden/webhook_ops.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import urllib.parse
 from pathlib import Path
 from typing import Any
@@ -170,3 +171,32 @@ class WebhookOps:
         if not isinstance(data, dict):
             raise StackgenError(f"unexpected terminate session payload: {data!r}")
         return data
+
+    def start_workflow_run(
+        self,
+        workflow_name: str,
+        *,
+        input: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """POST /guild/api/v1/workflows/{name}/run (fire-and-forget).
+
+        Returns the start body (typically ``session_id`` + ``trace_id``). Does
+        not wait for completion — persist those ids and call
+        :meth:`AidenNamespace.get_run_status` from a scheduler.
+        """
+        name = urllib.parse.quote(workflow_name, safe="")
+        url = (
+            f"{self._config.aiden_url()}/api/v1/workflows/{name}/run"
+            f"{_http.query(self._config.org_id)}"
+        )
+        body: dict[str, Any] = {"input": input or {}}
+        data = _http.request(
+            url,
+            self._config.api_token,
+            method="POST",
+            body=json.dumps(body).encode("utf-8"),
+            content_type="application/json",
+        )
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected workflow run start payload: {data!r}")
+        return data