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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.1.5
+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/
@@ -37,7 +37,7 @@ from stackgen import StackgenClient, StackgenConfig
 
 client = StackgenClient(
     StackgenConfig(
-        base_url="https://azure-eu.cloud.stackgen.com",
+        base_url="https://app.stackgen.com",
         api_token="stackgen_…",
         org_id="<project-uuid>",
         webhook_token="sg_aios_…",  # webhook journeys only

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.7}/README.md

@@ -16,7 +16,7 @@ from stackgen import StackgenClient, StackgenConfig
 
 client = StackgenClient(
     StackgenConfig(
-        base_url="https://azure-eu.cloud.stackgen.com",
+        base_url="https://app.stackgen.com",
         api_token="stackgen_…",
         org_id="<project-uuid>",
         webhook_token="sg_aios_…",  # webhook journeys only

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

@@ -6,7 +6,7 @@ Public entrypoint::
 
     client = StackgenClient(
         StackgenConfig(
-            base_url="https://azure-eu.cloud.stackgen.com",
+            base_url="https://app.stackgen.com",
             api_token="stackgen_…",
             org_id="<project-uuid>",
         )
@@ -18,14 +18,32 @@ from __future__ import annotations
 from stackgen.client import StackgenClient
 from stackgen.config import StackgenConfig
 from stackgen.errors import HttpError, NotAllowlistedError, StackgenError, TimeoutError
+from stackgen.aiden.workflow_builder import (
+    AgentDefinition,
+    StageDefinition,
+    WorkflowBuilder,
+    WorkflowDefinition,
+    create_agent,
+    create_stage,
+    create_workflow,
+)
+from stackgen.aiden.workflow_publish import PublishWorkflowResult
 
 __all__ = [
+    "AgentDefinition",
     "HttpError",
     "NotAllowlistedError",
+    "PublishWorkflowResult",
     "StackgenClient",
     "StackgenConfig",
     "StackgenError",
+    "StageDefinition",
     "TimeoutError",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
 ]
 
 

{stackgen_sdk-0.1.5 → 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.5'
-__version_tuple__ = version_tuple = (0, 1, 5)
+__version__ = version = '0.1.7'
+__version_tuple__ = version_tuple = (0, 1, 7)
 
 __commit_id__ = commit_id = None

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

@@ -0,0 +1,33 @@
+"""Aiden (platform) namespace — webhooks, sessions, artifacts, Ask Guild, workflows."""
+
+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,
+    StageDefinition,
+    WorkflowBuilder,
+    WorkflowDefinition,
+    create_agent,
+    create_stage,
+    create_workflow,
+)
+from stackgen.aiden.workflow_publish import PublishWorkflowResult
+
+__all__ = [
+    "AgentDefinition",
+    "AidenNamespace",
+    "AskArtifactResult",
+    "ExecutionStatus",
+    "PublishWorkflowResult",
+    "RunPhase",
+    "RunStatus",
+    "StageDefinition",
+    "WebhookReportResult",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
+]

{stackgen_sdk-0.1.5 → 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,12 +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()
-            trace_settled = execution.get("trace_settled") is True
-            if trace_settled and status in _TERMINAL_STATUSES:
-                if status == "error":
+            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 is not None
+                and status.is_terminal()
+                and settled is not False
+            )
+            if ready:
+                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.7/src/stackgen/aiden/namespace.py

@@ -0,0 +1,241 @@
+"""Aiden namespace — public methods for platform APIs."""
+
+from __future__ import annotations
+
+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:
+    """Aiden platform APIs (sessions, webhooks, artifacts, Ask Guild, workflows)."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._webhook = WebhookReportJourney(config)
+        self._ask = AskArtifactJourney(config)
+        self._workflows = WorkflowPublishJourney(config)
+        self._webhook_ops = WebhookOps(config)
+
+    def run_webhook_and_download_report(
+        self,
+        payload: str,
+        *,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+    ) -> WebhookReportResult:
+        """Trigger a webhook, wait for the session artifact, download it."""
+        return self._webhook.run(
+            payload, artifact_name=artifact_name, output_path=output_path
+        )
+
+    def trigger_webhook(self, payload: str) -> dict[str, Any]:
+        """POST /guild/api/v1/webhooks/trigger (stateless; returns 202 body)."""
+        return self._webhook_ops.trigger_webhook(payload)
+
+    def get_webhook_run(self, webhook_id: str, invocation_id: str) -> dict[str, Any]:
+        """GET webhook invocation detail by invocation UUID."""
+        return self._webhook_ops.get_webhook_run(webhook_id, invocation_id)
+
+    def list_webhook_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        """List webhook invocations for a webhook id."""
+        return self._webhook_ops.list_webhook_runs(webhook_id)
+
+    def wait_for_webhook_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        *,
+        dispatch_run_id: str = "",
+        known_run_ids: frozenset[str] | None = None,
+    ) -> str:
+        """Poll webhook run detail until session_id is set."""
+        return self._webhook_ops.wait_for_webhook_session(
+            webhook_id,
+            invocation_id,
+            dispatch_run_id=dispatch_run_id,
+            known_run_ids=known_run_ids,
+        )
+
+    def get_execution_trace(self, trace_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/executions/{traceId}."""
+        return self._webhook_ops.get_execution_trace(trace_id)
+
+    def list_executions(self, **params: Any) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/executions (optional session_id filter)."""
+        return self._webhook_ops.list_executions(**params)
+
+    def list_sessions(self, **params: Any) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions (search with q / source_app)."""
+        return self._webhook_ops.list_sessions(**params)
+
+    def get_session(self, session_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}."""
+        return self._webhook_ops.get_session(session_id)
+
+    def list_session_artifacts(self, session_id: str) -> list[dict[str, Any]]:
+        """GET session artifact metadata list."""
+        return self._webhook_ops.list_session_artifacts(session_id)
+
+    def download_session_artifact(
+        self,
+        session_id: str,
+        artifact_name: str,
+        output_path: str,
+    ) -> Path:
+        """Download one session artifact to a local path."""
+        return self._webhook_ops.download_session_artifact(
+            session_id, artifact_name, output_path
+        )
+
+    def export_session(
+        self,
+        session_id: str,
+        *,
+        parts: str | None = None,
+        format: str = "json",
+    ) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}/export (report / notes / evidence)."""
+        return self._webhook_ops.export_session(session_id, parts=parts, format=format)
+
+    def terminate_session(self, session_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        """POST /guild/api/v1/sessions/{sessionId}/terminate."""
+        return self._webhook_ops.terminate_session(session_id, reason=reason)
+
+    def run_ask_and_download_artifact(
+        self,
+        message: str,
+        *,
+        entity_refs: list[dict[str, str]] | None = None,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+        inputs: dict[str, str] | None = None,
+        session_id: str | None = None,
+        source_app: str | None = None,
+        source_metadata: dict[str, str] | None = None,
+    ) -> AskArtifactResult:
+        """Start Ask Guild, poll execution, wait for artifact, download it."""
+        return self._ask.run(
+            message,
+            entity_refs=entity_refs,
+            artifact_name=artifact_name,
+            output_path=output_path,
+            inputs=inputs,
+            session_id=session_id,
+            source_app=source_app,
+            source_metadata=source_metadata,
+        )
+
+    def start_ask(
+        self,
+        message: str,
+        *,
+        entity_refs: list[dict[str, str]] | None = None,
+        inputs: dict[str, str] | None = None,
+        session_id: str | None = None,
+        source_app: str | None = None,
+        source_metadata: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """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,
+            inputs=inputs,
+            session_id=session_id,
+            source_app=source_app,
+            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 (blocking).
+
+        Prefer :meth:`get_run_status` for queue/scheduler architectures.
+        """
+        return self._ask.wait_for_execution(trace_id)
+
+    def publish_workflow(
+        self,
+        workflow: WorkflowDefinition,
+        *,
+        agents: list[AgentDefinition] | None = None,
+        approve: bool = True,
+    ) -> PublishWorkflowResult:
+        """Register/update agents and create/update a workflow, optionally approving it.
+
+        Pass a committed builder from ``create_workflow(...).then(...).commit()``.
+        """
+        return self._workflows.publish(workflow, agents=agents, approve=approve)

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")