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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.1.6
+Version: 0.1.8
 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.8}/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.8'
+__version_tuple__ = version_tuple = (0, 1, 8)
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.8}/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.8}/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.8/src/stackgen/aiden/models.py

@@ -0,0 +1,225 @@
+"""Aiden model registry — providers and registered models.
+
+Hand-written facade over Guild ``/guild/api/v1/model-providers`` and
+``/guild/api/v1/models`` (see stackgen-guild ``api-docs/openapi.yml``).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Any
+
+from stackgen import _http
+from stackgen.config import StackgenConfig
+from stackgen.errors import HttpError
+
+
+class ModelRegistry:
+    """CRUD helpers for OpenAI-compatible (and other) model providers/models."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def _org(self) -> str:
+        org = (self._config.org_id or "").strip()
+        if not org:
+            raise ValueError("org_id is required for model registry calls")
+        return org
+
+    def _url(self, path: str) -> str:
+        return f"{self._config.aiden_url()}/api/v1{path}{_http.query(self._org())}"
+
+    def _json(
+        self,
+        method: str,
+        path: str,
+        body: dict[str, Any] | None = None,
+    ) -> Any:
+        payload = None
+        content_type = None
+        if body is not None:
+            payload = json.dumps(body).encode("utf-8")
+            content_type = "application/json"
+        return _http.request(
+            self._url(path),
+            self._config.api_token,
+            method=method,
+            body=payload,
+            content_type=content_type,
+        )
+
+    def list_providers(self) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/model-providers."""
+        return _http.as_list(self._json("GET", "/model-providers"))
+
+    def get_provider(self, name: str) -> dict[str, Any]:
+        """GET /guild/api/v1/model-providers/{name}."""
+        enc = urllib.parse.quote(name, safe="")
+        out = self._json("GET", f"/model-providers/{enc}")
+        if not isinstance(out, dict):
+            raise HttpError(f"unexpected provider payload for {name!r}")
+        return out
+
+    def create_provider(
+        self,
+        *,
+        name: str,
+        provider_type: str = "openai",
+        host: str = "",
+        token_reference: str = "",
+    ) -> dict[str, Any]:
+        """POST /guild/api/v1/model-providers."""
+        body: dict[str, Any] = {"name": name, "provider_type": provider_type}
+        if host:
+            body["host"] = host.rstrip("/")
+        if token_reference:
+            body["token_reference"] = token_reference
+        out = self._json("POST", "/model-providers", body)
+        if not isinstance(out, dict):
+            raise HttpError(f"unexpected create provider payload for {name!r}")
+        return out
+
+    def update_provider(
+        self,
+        name: str,
+        *,
+        host: str | None = None,
+        token_reference: str | None = None,
+        provider_type: str | None = None,
+    ) -> dict[str, Any]:
+        """PUT /guild/api/v1/model-providers/{name}."""
+        body: dict[str, Any] = {}
+        if host is not None:
+            body["host"] = host.rstrip("/")
+        if token_reference is not None:
+            body["token_reference"] = token_reference
+        if provider_type is not None:
+            body["provider_type"] = provider_type
+        enc = urllib.parse.quote(name, safe="")
+        out = self._json("PUT", f"/model-providers/{enc}", body)
+        if not isinstance(out, dict):
+            raise HttpError(f"unexpected update provider payload for {name!r}")
+        return out
+
+    def ensure_provider(
+        self,
+        *,
+        name: str,
+        host: str,
+        provider_type: str = "openai",
+        token_reference: str = "",
+    ) -> dict[str, Any]:
+        """Create provider if missing, then set host (and optional token_reference)."""
+        try:
+            self.create_provider(
+                name=name,
+                provider_type=provider_type,
+                host=host,
+                token_reference=token_reference,
+            )
+        except HttpError as err:
+            if err.status_code != 409:
+                raise
+        return self.update_provider(
+            name,
+            host=host,
+            token_reference=token_reference or None,
+            provider_type=provider_type,
+        )
+
+    def list_models(self, *, provider_name: str = "") -> list[dict[str, Any]]:
+        """GET /guild/api/v1/models."""
+        base = f"{self._config.aiden_url()}/api/v1/models"
+        params: dict[str, str] = {"orgId": self._org()}
+        if provider_name:
+            params["provider_name"] = provider_name
+        q = urllib.parse.urlencode(params)
+        return _http.as_list(
+            _http.request(
+                f"{base}?{q}",
+                self._config.api_token,
+                method="GET",
+            )
+        )
+
+    def get_model(self, name: str) -> dict[str, Any]:
+        """GET /guild/api/v1/models/{name}."""
+        enc = urllib.parse.quote(name, safe="")
+        out = self._json("GET", f"/models/{enc}")
+        if not isinstance(out, dict):
+            raise HttpError(f"unexpected model payload for {name!r}")
+        return out
+
+    def create_model(
+        self,
+        *,
+        name: str,
+        provider_name: str,
+        model_id: str,
+        thinking: bool = False,
+    ) -> dict[str, Any]:
+        """POST /guild/api/v1/models (live-probes the provider host)."""
+        body: dict[str, Any] = {
+            "name": name,
+            "provider_name": provider_name,
+            "model_id": model_id,
+            "thinking": thinking,
+        }
+        out = self._json("POST", "/models", body)
+        if not isinstance(out, dict):
+            raise HttpError(f"unexpected create model payload for {name!r}")
+        return out
+
+    def ensure_model(
+        self,
+        *,
+        name: str,
+        provider_name: str,
+        model_id: str,
+        thinking: bool = False,
+    ) -> dict[str, Any]:
+        """Return existing model or create it (requires reachable provider host)."""
+        try:
+            return self.get_model(name)
+        except HttpError as err:
+            if err.status_code != 404:
+                raise
+        try:
+            return self.create_model(
+                name=name,
+                provider_name=provider_name,
+                model_id=model_id,
+                thinking=thinking,
+            )
+        except HttpError as err:
+            if err.status_code == 409:
+                return self.get_model(name)
+            raise
+
+    def ensure_openai_peft_model(
+        self,
+        *,
+        serve_url: str,
+        model_name: str = "sre-slm-qwen3-32b",
+        provider_name: str = "sre-slm-peft",
+        model_id: str = "sre-slm-qwen3-32b",
+        token_reference: str = "",
+    ) -> dict[str, Any]:
+        """Ensure OpenAI-compatible provider + model pointed at a PEFT serve URL.
+
+        ``serve_url`` should look like ``http://<ip>:8000/v1``. Create model
+        live-probes the host, so PEFT serve must already be up.
+        """
+        provider = self.ensure_provider(
+            name=provider_name,
+            host=serve_url,
+            provider_type="openai",
+            token_reference=token_reference,
+        )
+        model = self.ensure_model(
+            name=model_name,
+            provider_name=provider_name,
+            model_id=model_id,
+        )
+        return {"provider": provider, "model": model}

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

@@ -6,11 +6,14 @@ from pathlib import Path
 from typing import Any
 
 from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
+from stackgen.aiden.models import ModelRegistry
+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:
@@ -22,6 +25,7 @@ class AidenNamespace:
         self._ask = AskArtifactJourney(config)
         self._workflows = WorkflowPublishJourney(config)
         self._webhook_ops = WebhookOps(config)
+        self.models = ModelRegistry(config)
 
     def run_webhook_and_download_report(
         self,
@@ -142,7 +146,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 +161,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.8/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.8}/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

{stackgen_sdk-0.1.6 → stackgen_sdk-0.1.8}/src/stackgen/config.py

@@ -58,7 +58,10 @@ class StackgenConfig:
         """
         base = os.environ.get("STACKGEN_URL", "").strip()
         token = os.environ.get("STACKGEN_TOKEN", "").strip()
-        project = os.environ.get("STACKGEN_PROJECT", "").strip()
+        project = (
+            os.environ.get("STACKGEN_PROJECT", "").strip()
+            or os.environ.get("STACKGEN_ORG_ID", "").strip()
+        )
         if not base:
             raise ValueError("STACKGEN_URL is required")
         if not token: