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

{stackgen_sdk-0.1.2 → stackgen_sdk-0.1.5}/.gitignore

@@ -32,5 +32,11 @@ coverage.out
 .env
 .env.*
 
+# Jekyll (only if native Ruby was used by mistake)
+docs/_site/
+docs/.jekyll-cache/
+docs/.bundle/
+docs/vendor/
+
 # hatch-vcs generated version module (written at build time)
 clients/python/src/stackgen/_version.py

stackgen_sdk-0.1.5/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: stackgen-sdk
+Version: 0.1.5
+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/
+Project-URL: Repository, https://github.com/appcd-dev/stackgen-sdk
+Project-URL: Bug Tracker, https://github.com/appcd-dev/stackgen-sdk/issues
+Author: StackGen
+License-Expression: Apache-2.0
+Keywords: aiden,openapi,sre,stackgen
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dateutil>=2.8
+Requires-Dist: typing-extensions>=4.0
+Requires-Dist: urllib3>=2.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# StackGen Python SDK
+
+**Documentation:** [https://appcd-dev.github.io/stackgen-sdk/](https://appcd-dev.github.io/stackgen-sdk/) — Aiden guide, code samples, FAQ, and CI integration.
+
+Install:
+
+```bash
+pip install stackgen-sdk
+```
+
+Import package name is `stackgen`. Construct the client with an explicit config:
+
+```python
+from pathlib import Path
+from stackgen import StackgenClient, StackgenConfig
+
+client = StackgenClient(
+    StackgenConfig(
+        base_url="https://azure-eu.cloud.stackgen.com",
+        api_token="stackgen_…",
+        org_id="<project-uuid>",
+        webhook_token="sg_aios_…",  # webhook journeys only
+    )
+)
+
+result = client.aiden.run_webhook_and_download_report(
+    Path("alert.json").read_text(encoding="utf-8")
+)
+print(result.session_id, result.output_path)
+
+ask = client.aiden.run_ask_and_download_artifact(
+    message="Run triage for checkout CPU alert",
+    entity_refs=[{"name": "observe-uber-triage", "type": "workflow"}],
+)
+print(ask.trace_id, ask.output_path)
+
+alerts = client.sre.list_alerts()
+```
+
+## Default environment variables
+
+`StackgenConfig.from_env()` reads **only** these (optional convenience):
+
+| Variable | Purpose |
+|----------|---------|
+| `STACKGEN_URL` | Mothership URL (no path suffix) |
+| `STACKGEN_TOKEN` | API token (`stackgen_…`) |
+| `STACKGEN_PROJECT` | Project / org UUID (`orgId`) |
+
+Pass `webhook_token`, `webhook_id`, timeouts, and artifact paths as `StackgenConfig` fields — not via env.
+
+```python
+from dataclasses import replace
+from stackgen import StackgenClient, StackgenConfig
+
+client = StackgenClient(
+    replace(StackgenConfig.from_env(), webhook_token="sg_aios_…")
+)
+```
+
+## Namespaces
+
+- `client.aiden` — webhooks, Ask Guild, sessions, artifact download
+- `client.sre` — alerts and investigations
+- `client.vault` — secrets (not enabled in this release)
+
+Prefer `StackgenClient` over `stackgen.generated`.
+
+Pin versions in CI: `pip install stackgen-sdk==0.1.5`.
+
+**Documentation:** [https://appcd-dev.github.io/stackgen-sdk/](https://appcd-dev.github.io/stackgen-sdk/) (Aiden guide, [FAQ](https://appcd-dev.github.io/stackgen-sdk/faq/), [code samples](https://appcd-dev.github.io/stackgen-sdk/code-samples/))

stackgen_sdk-0.1.5/README.md

@@ -0,0 +1,71 @@
+# StackGen Python SDK
+
+**Documentation:** [https://appcd-dev.github.io/stackgen-sdk/](https://appcd-dev.github.io/stackgen-sdk/) — Aiden guide, code samples, FAQ, and CI integration.
+
+Install:
+
+```bash
+pip install stackgen-sdk
+```
+
+Import package name is `stackgen`. Construct the client with an explicit config:
+
+```python
+from pathlib import Path
+from stackgen import StackgenClient, StackgenConfig
+
+client = StackgenClient(
+    StackgenConfig(
+        base_url="https://azure-eu.cloud.stackgen.com",
+        api_token="stackgen_…",
+        org_id="<project-uuid>",
+        webhook_token="sg_aios_…",  # webhook journeys only
+    )
+)
+
+result = client.aiden.run_webhook_and_download_report(
+    Path("alert.json").read_text(encoding="utf-8")
+)
+print(result.session_id, result.output_path)
+
+ask = client.aiden.run_ask_and_download_artifact(
+    message="Run triage for checkout CPU alert",
+    entity_refs=[{"name": "observe-uber-triage", "type": "workflow"}],
+)
+print(ask.trace_id, ask.output_path)
+
+alerts = client.sre.list_alerts()
+```
+
+## Default environment variables
+
+`StackgenConfig.from_env()` reads **only** these (optional convenience):
+
+| Variable | Purpose |
+|----------|---------|
+| `STACKGEN_URL` | Mothership URL (no path suffix) |
+| `STACKGEN_TOKEN` | API token (`stackgen_…`) |
+| `STACKGEN_PROJECT` | Project / org UUID (`orgId`) |
+
+Pass `webhook_token`, `webhook_id`, timeouts, and artifact paths as `StackgenConfig` fields — not via env.
+
+```python
+from dataclasses import replace
+from stackgen import StackgenClient, StackgenConfig
+
+client = StackgenClient(
+    replace(StackgenConfig.from_env(), webhook_token="sg_aios_…")
+)
+```
+
+## Namespaces
+
+- `client.aiden` — webhooks, Ask Guild, sessions, artifact download
+- `client.sre` — alerts and investigations
+- `client.vault` — secrets (not enabled in this release)
+
+Prefer `StackgenClient` over `stackgen.generated`.
+
+Pin versions in CI: `pip install stackgen-sdk==0.1.5`.
+
+**Documentation:** [https://appcd-dev.github.io/stackgen-sdk/](https://appcd-dev.github.io/stackgen-sdk/) (Aiden guide, [FAQ](https://appcd-dev.github.io/stackgen-sdk/faq/), [code samples](https://appcd-dev.github.io/stackgen-sdk/code-samples/))

{stackgen_sdk-0.1.2 → stackgen_sdk-0.1.5}/pyproject.toml

@@ -19,7 +19,10 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://pypi.org/project/stackgen-sdk/"
+Homepage = "https://appcd-dev.github.io/stackgen-sdk/"
+Documentation = "https://appcd-dev.github.io/stackgen-sdk/"
+Repository = "https://github.com/appcd-dev/stackgen-sdk"
+"Bug Tracker" = "https://github.com/appcd-dev/stackgen-sdk/issues"
 
 [project.optional-dependencies]
 dev = ["pytest>=8.0", "build>=1.2"]

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

@@ -4,8 +4,13 @@ Public entrypoint::
 
     from stackgen import StackgenClient, StackgenConfig
 
-    client = StackgenClient.from_env()
-    result = client.aiden.run_webhook_and_download_report(payload)
+    client = StackgenClient(
+        StackgenConfig(
+            base_url="https://azure-eu.cloud.stackgen.com",
+            api_token="stackgen_…",
+            org_id="<project-uuid>",
+        )
+    )
 """
 
 from __future__ import annotations

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

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

@@ -1,9 +1,11 @@
-"""Aiden (platform) namespace — webhooks, sessions, artifacts."""
+"""Aiden (platform) namespace — webhooks, sessions, artifacts, Ask Guild."""
 
+from stackgen.aiden.ask import AskArtifactResult
 from stackgen.aiden.namespace import AidenNamespace
 from stackgen.aiden.webhook import WebhookReportResult
 
 __all__ = [
     "AidenNamespace",
+    "AskArtifactResult",
     "WebhookReportResult",
 ]

stackgen_sdk-0.1.5/src/stackgen/aiden/ask.py

@@ -0,0 +1,168 @@
+"""Aiden Ask → execution poll → artifact download journey."""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.aiden import sessions as session_helpers
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError, TimeoutError
+
+_TERMINAL_STATUSES = frozenset({"completed", "error"})
+
+
+@dataclass(frozen=True)
+class AskArtifactResult:
+    """Result of Ask start → wait → download session artifact."""
+
+    trace_id: str
+    run_id: str
+    session_id: str
+    artifacts: tuple[dict[str, Any], ...]
+    output_path: Path
+    candidates: tuple[dict[str, Any], ...] = ()
+    plan: str = ""
+
+
+class AskArtifactJourney:
+    """Start Ask Guild, poll execution trace, wait for artifact, download it.
+
+    Uses ``api_token`` and ``org_id`` only (no webhook token).
+    """
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def run(
+        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:
+        cfg = self._config
+        artifact = artifact_name or cfg.artifact_name
+        dest = output_path or cfg.output_path
+
+        start = self.start_ask(
+            message,
+            entity_refs=entity_refs,
+            inputs=inputs,
+            session_id=session_id,
+            source_app=source_app,
+            source_metadata=source_metadata,
+        )
+        trace_id = _http.text(start.get("trace_id"))
+        if not trace_id:
+            raise StackgenError(
+                "startAskGuild did not return trace_id; "
+                f"body={json.dumps(start)}"
+            )
+
+        run_id = _http.text(start.get("run_id"))
+        resolved_session = _http.text(start.get("session_id")) or _http.text(session_id)
+        plan = _http.text(start.get("plan"))
+        candidates = tuple(start.get("candidates") or ())
+
+        trace = self.wait_for_execution(trace_id)
+        if not resolved_session:
+            resolved_session = _http.text(trace.get("session_id"))
+        execution = trace.get("execution") or {}
+        if not resolved_session:
+            raise StackgenError(
+                f"execution {trace_id} settled without session_id; "
+                "cannot download artifacts"
+            )
+        if not run_id:
+            run_id = _http.text(execution.get("run_id"))
+
+        artifacts = session_helpers.wait_for_artifact(cfg, resolved_session, artifact)
+        path = session_helpers.download_artifact(cfg, resolved_session, artifact, dest)
+        return AskArtifactResult(
+            trace_id=trace_id,
+            run_id=run_id,
+            session_id=resolved_session,
+            artifacts=tuple(artifacts),
+            output_path=path,
+            candidates=candidates,
+            plan=plan,
+        )
+
+    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."""
+        body: dict[str, Any] = {"message": message}
+        if entity_refs:
+            body["entity_refs"] = entity_refs
+        if inputs:
+            body["inputs"] = inputs
+        if session_id:
+            body["session_id"] = session_id
+        if source_app:
+            body["source_app"] = source_app
+        if source_metadata:
+            body["source_metadata"] = source_metadata
+
+        url = (
+            f"{self._config.aiden_url()}/api/v1/guild/ask/start"
+            f"{_http.query(self._config.org_id)}"
+        )
+        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 startAskGuild payload: {data!r}")
+
+        inputs_required = data.get("inputs_required") or []
+        if inputs_required:
+            raise StackgenError(
+                "Ask requires additional inputs before execution can start: "
+                f"{inputs_required}"
+            )
+        return data
+
+    def wait_for_execution(self, trace_id: str) -> dict[str, Any]:
+        """Poll GET /guild/api/v1/executions/{traceId} until settled."""
+        cfg = self._config
+        deadline = time.monotonic() + cfg.timeout_seconds
+        url = (
+            f"{cfg.aiden_url()}/api/v1/executions/{trace_id}"
+            f"{_http.query(cfg.org_id)}"
+        )
+        while time.monotonic() < deadline:
+            data = _http.request(url, cfg.api_token)
+            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":
+                    raise StackgenError(
+                        f"execution {trace_id} ended with status error"
+                    )
+                return data
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError("execution", cfg.timeout_seconds)

stackgen_sdk-0.1.5/src/stackgen/aiden/namespace.py

@@ -0,0 +1,78 @@
+"""Aiden namespace — public methods for platform APIs."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
+from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
+from stackgen.config import StackgenConfig
+
+
+class AidenNamespace:
+    """Aiden platform APIs (sessions, webhooks, artifacts, Ask Guild)."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._webhook = WebhookReportJourney(config)
+        self._ask = AskArtifactJourney(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 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 (advanced callers)."""
+        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 wait_for_execution(self, trace_id: str) -> dict[str, Any]:
+        """Poll GET /guild/api/v1/executions/{traceId} until settled."""
+        return self._ask.wait_for_execution(trace_id)

{stackgen_sdk-0.1.2 → stackgen_sdk-0.1.5}/src/stackgen/aiden/runs.py

@@ -17,7 +17,7 @@ def pick_run(
     Preference order:
       1. Exact match on ``id`` / ``run_id`` to ``dispatch_run_id``
       2. First run whose id is not in ``known_run_ids`` (new since pre-trigger snapshot)
-      3. If no known ids and runs exist, the first run (best-effort on older motherships)
+      3. If no known ids and runs exist, the first run (best-effort fallback)
     """
     if dispatch_run_id:
         for item in runs:

stackgen_sdk-0.1.5/src/stackgen/aiden/sessions.py

@@ -0,0 +1,46 @@
+"""Shared session artifact wait/download helpers."""
+
+from __future__ import annotations
+
+import time
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.config import StackgenConfig
+from stackgen.errors import TimeoutError
+
+
+def wait_for_artifact(
+    config: StackgenConfig, session_id: str, artifact_name: str
+) -> list[dict[str, Any]]:
+    """Poll session artifacts until ``artifact_name`` appears (case-insensitive)."""
+    deadline = time.monotonic() + config.timeout_seconds
+    url = (
+        f"{config.aiden_url()}/api/v1/sessions/{session_id}/artifacts"
+        f"{_http.query(config.org_id)}"
+    )
+    want = artifact_name.casefold()
+    artifacts: list[dict[str, Any]] = []
+    while time.monotonic() < deadline:
+        artifacts = _http.as_list(_http.request(url, config.api_token))
+        if any(_http.text(item.get("name")).casefold() == want for item in artifacts):
+            return artifacts
+        time.sleep(config.poll_interval_seconds)
+    raise TimeoutError(artifact_name, config.timeout_seconds)
+
+
+def download_artifact(
+    config: StackgenConfig, session_id: str, artifact_name: str, output_path: str
+) -> Path:
+    """Download a session artifact to ``output_path``."""
+    encoded = urllib.parse.quote(artifact_name, safe="")
+    url = (
+        f"{config.aiden_url()}/api/v1/sessions/{session_id}/artifacts/"
+        f"{encoded}/download{_http.query(config.org_id)}"
+    )
+    raw = _http.request(url, config.api_token, expect_json=False)
+    dest = Path(output_path)
+    dest.write_bytes(raw)
+    return dest

stackgen_sdk-0.1.5/src/stackgen/aiden/webhook.py

@@ -0,0 +1,81 @@
+"""Aiden webhook → session-report journey."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.aiden import sessions as session_helpers
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+
+
+@dataclass(frozen=True)
+class WebhookReportResult:
+    """Result of trigger → wait → download session-report."""
+
+    webhook_id: str
+    invocation_id: str
+    session_id: str
+    artifacts: tuple[dict[str, Any], ...]
+    output_path: Path
+
+
+class WebhookReportJourney:
+    """Trigger a webhook, wait for the session artifact, and download it.
+
+    Uses ``webhook_token`` for POST trigger and ``api_token`` for poll/download.
+    """
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def run(
+        self,
+        payload: str,
+        *,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+    ) -> WebhookReportResult:
+        cfg = self._config
+        if not cfg.webhook_token:
+            raise ValueError("webhook_token is required for run_webhook_and_download_report")
+
+        artifact = artifact_name or cfg.artifact_name
+        dest = output_path or cfg.output_path
+
+        trigger = self._trigger(payload)
+        webhook_id = _http.text(trigger.get("webhook_id")) or _http.text(cfg.webhook_id)
+        invocation_id = _http.text(trigger.get("invocation_id"))
+        session_id = _http.text(trigger.get("session_id"))
+
+        if not session_id:
+            raise StackgenError(
+                f"trigger response missing session_id; body={json.dumps(trigger)}"
+            )
+
+        artifacts = session_helpers.wait_for_artifact(cfg, session_id, artifact)
+        path = session_helpers.download_artifact(cfg, session_id, artifact, dest)
+        return WebhookReportResult(
+            webhook_id=webhook_id,
+            invocation_id=invocation_id,
+            session_id=session_id,
+            artifacts=tuple(artifacts),
+            output_path=path,
+        )
+
+    def _trigger(self, payload: str) -> dict[str, Any]:
+        url = f"{self._config.aiden_url()}/api/v1/webhooks/trigger{_http.query(self._config.org_id)}"
+        data = _http.request(
+            url,
+            self._config.webhook_token,
+            method="POST",
+            body=payload.encode("utf-8"),
+            content_type="text/plain",
+        )
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected trigger payload: {data!r}")
+        return data

{stackgen_sdk-0.1.2 → stackgen_sdk-0.1.5}/src/stackgen/cli.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
+import os
 import sys
+from dataclasses import replace
 from pathlib import Path
 
 from stackgen.client import StackgenClient
@@ -20,7 +22,13 @@ def main(argv: list[str] | None = None) -> None:
             sys.exit(1)
         payload = path.read_text(encoding="utf-8")
     try:
-        client = StackgenClient(StackgenConfig.from_env())
+        # CLI-only: webhook fields may be supplied alongside the three default env vars.
+        cfg = replace(
+            StackgenConfig.from_env(),
+            webhook_token=os.environ.get("WEBHOOK_TOKEN", "").strip(),
+            webhook_id=os.environ.get("WEBHOOK_ID", "").strip(),
+        )
+        client = StackgenClient(cfg)
         result = client.aiden.run_webhook_and_download_report(payload)
     except (StackgenError, ValueError) as err:
         print(f"error: {err}", file=sys.stderr)