stackgen-sdk 0.1.1__tar.gz

stackgen_sdk-0.1.1/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.venv/**
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Go
+clients/go/generated/.openapi-generator/
+*.exe
+*.test
+coverage.out
+
+# OpenAPI generator scratch
+**/deleteme/
+**/.openapi-generator-ignore.bak
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Local env
+.env
+.env.*
+
+# hatch-vcs generated version module (written at build time)
+clients/python/src/stackgen/_version.py

stackgen_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.5
+Name: stackgen-sdk
+Version: 0.1.1
+Summary: StackGen SDK — Aiden, SRE, and Vault from one client
+Project-URL: Homepage, https://github.com/appcd-dev/stackgen-sdk
+Project-URL: Documentation, https://github.com/appcd-dev/stackgen-sdk/tree/main/docs
+Project-URL: Repository, https://github.com/appcd-dev/stackgen-sdk
+Project-URL: Issues, 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
+
+Install (PyPI):
+
+```bash
+pip install stackgen-sdk==0.1.1
+```
+
+Developers with private repo access:
+
+```bash
+pip install "git+ssh://git@github.com/appcd-dev/stackgen-sdk.git@v0.1.1#subdirectory=clients/python"
+```
+
+Quick start:
+
+```python
+from stackgen import StackgenClient
+
+client = StackgenClient.from_env()
+result = client.aiden.run_webhook_and_download_report(open("alert.json").read())
+print(result.session_id, result.output_path)
+
+alerts = client.sre.list_alerts()
+```
+
+Environment:
+
+| Variable | Purpose |
+|----------|---------|
+| `STACKGEN_URL` | Mothership URL (no `/guild`) |
+| `STACKGEN_TOKEN` | API token (`stackgen_…`) |
+| `WEBHOOK_TOKEN` | Webhook token (`sg_aios_…`) for triggers |
+| `ORG_ID` | Organization UUID |
+| `WEBHOOK_ID` | Optional; older trigger 202 bodies |
+
+See [docs/PRODUCT.md](../../docs/PRODUCT.md), [docs/python/IMPLEMENTATION.md](../../docs/python/IMPLEMENTATION.md), and [docs/PUBLISH.md](../../docs/PUBLISH.md).
+
+Generated OpenAPI client code lives under `stackgen.generated` (unstable; prefer `StackgenClient`).

stackgen_sdk-0.1.1/README.md

@@ -0,0 +1,39 @@
+# StackGen Python SDK
+
+Install (PyPI):
+
+```bash
+pip install stackgen-sdk==0.1.1
+```
+
+Developers with private repo access:
+
+```bash
+pip install "git+ssh://git@github.com/appcd-dev/stackgen-sdk.git@v0.1.1#subdirectory=clients/python"
+```
+
+Quick start:
+
+```python
+from stackgen import StackgenClient
+
+client = StackgenClient.from_env()
+result = client.aiden.run_webhook_and_download_report(open("alert.json").read())
+print(result.session_id, result.output_path)
+
+alerts = client.sre.list_alerts()
+```
+
+Environment:
+
+| Variable | Purpose |
+|----------|---------|
+| `STACKGEN_URL` | Mothership URL (no `/guild`) |
+| `STACKGEN_TOKEN` | API token (`stackgen_…`) |
+| `WEBHOOK_TOKEN` | Webhook token (`sg_aios_…`) for triggers |
+| `ORG_ID` | Organization UUID |
+| `WEBHOOK_ID` | Optional; older trigger 202 bodies |
+
+See [docs/PRODUCT.md](../../docs/PRODUCT.md), [docs/python/IMPLEMENTATION.md](../../docs/python/IMPLEMENTATION.md), and [docs/PUBLISH.md](../../docs/PUBLISH.md).
+
+Generated OpenAPI client code lives under `stackgen.generated` (unstable; prefer `StackgenClient`).

stackgen_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "stackgen-sdk"
+dynamic = ["version"]
+description = "StackGen SDK — Aiden, SRE, and Vault from one client"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "StackGen" }]
+keywords = ["stackgen", "aiden", "sre", "openapi"]
+dependencies = [
+  "urllib3>=2.0",
+  "pydantic>=2.0",
+  "python-dateutil>=2.8",
+  "typing-extensions>=4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/appcd-dev/stackgen-sdk"
+Documentation = "https://github.com/appcd-dev/stackgen-sdk/tree/main/docs"
+Repository = "https://github.com/appcd-dev/stackgen-sdk"
+Issues = "https://github.com/appcd-dev/stackgen-sdk/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "build>=1.2"]
+
+[project.scripts]
+stackgen-aiden-webhook = "stackgen.cli:main"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+# Repo root is two levels above clients/python/pyproject.toml
+root = "../.."
+# Prefer annotated release tags like v0.1.0 → version 0.1.0
+tag_regex = "^v(?P<version>[0-9].*)$"
+# PyPI rejects local version segments (+gHASH)
+local_scheme = "no-local-version"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/stackgen/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stackgen"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/stackgen",
+  "README.md",
+  "pyproject.toml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+  "unit: fast isolated unit tests",
+  "integration: tests that need network or Docker",
+]

stackgen_sdk-0.1.1/src/stackgen/__init__.py

@@ -0,0 +1,52 @@
+"""StackGen Python SDK.
+
+Public entrypoint::
+
+    from stackgen import StackgenClient, StackgenConfig
+
+    client = StackgenClient.from_env()
+    result = client.aiden.run_webhook_and_download_report(payload)
+"""
+
+from __future__ import annotations
+
+from stackgen.client import StackgenClient
+from stackgen.config import StackgenConfig
+from stackgen.errors import HttpError, NotAllowlistedError, StackgenError, TimeoutError
+
+__all__ = [
+    "HttpError",
+    "NotAllowlistedError",
+    "StackgenClient",
+    "StackgenConfig",
+    "StackgenError",
+    "TimeoutError",
+]
+
+
+def _resolve_version() -> str:
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+    except ImportError:  # pragma: no cover
+        from importlib_metadata import PackageNotFoundError, version  # type: ignore
+
+    try:
+        return version("stackgen-sdk")
+    except PackageNotFoundError:
+        try:
+            return version("stackgen")
+        except PackageNotFoundError:
+            try:
+                from stackgen._version import __version__ as vcs_version
+
+                return vcs_version
+            except ImportError:
+                try:
+                    from stackgen._version import version as vcs_version
+
+                    return vcs_version
+                except ImportError:
+                    return "0.0.0"
+
+
+__version__ = _resolve_version()

stackgen_sdk-0.1.1/src/stackgen/_http.py

@@ -0,0 +1,96 @@
+"""Shared HTTP helpers (stdlib)."""
+
+from __future__ import annotations
+
+import json
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+from stackgen.errors import HttpError, TimeoutError
+
+_RETRYABLE = {429, 502, 503, 504}
+
+
+def query(org_id: str) -> str:
+    if not org_id:
+        return ""
+    return "?" + urllib.parse.urlencode({"orgId": org_id})
+
+
+def request(
+    url: str,
+    token: str,
+    *,
+    method: str = "GET",
+    body: bytes | None = None,
+    content_type: str | None = None,
+    expect_json: bool = True,
+    retries: int = 3,
+) -> Any:
+    """Bearer HTTP call with bounded retries on transient GET failures."""
+    headers = {"Authorization": f"Bearer {token}"}
+    if content_type:
+        headers["Content-Type"] = content_type
+
+    attempt = 0
+    while True:
+        attempt += 1
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, context=ssl.create_default_context()) as resp:
+                raw = resp.read()
+                if not expect_json:
+                    return raw
+                if not raw:
+                    return {}
+                return json.loads(raw.decode("utf-8"))
+        except urllib.error.HTTPError as err:
+            detail = err.read().decode("utf-8", errors="replace")
+            if method == "GET" and err.code in _RETRYABLE and attempt < retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            raise HttpError(
+                f"{method} {url} -> HTTP {err.code}: {detail}",
+                status_code=err.code,
+            ) from err
+        except urllib.error.URLError as err:
+            if method == "GET" and attempt < retries:
+                time.sleep(min(2**attempt, 8))
+                continue
+            raise HttpError(f"{method} {url} -> {err}") from err
+
+
+def as_list(payload: Any) -> list[dict[str, Any]]:
+    if isinstance(payload, list):
+        return [item for item in payload if isinstance(item, dict)]
+    if isinstance(payload, dict):
+        items = payload.get("items")
+        if isinstance(items, list):
+            return [item for item in items if isinstance(item, dict)]
+    return []
+
+
+def text(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def poll_until(
+    deadline: float,
+    interval: float,
+    tick: Callable[[], Any | None],
+    *,
+    label: str,
+    timeout_seconds: int,
+) -> Any:
+    while time.monotonic() < deadline:
+        result = tick()
+        if result is not None:
+            return result
+        time.sleep(interval)
+    raise TimeoutError(label, timeout_seconds)

stackgen_sdk-0.1.1/src/stackgen/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None

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

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

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

@@ -0,0 +1,26 @@
+"""Aiden namespace — public methods for platform APIs."""
+
+from __future__ import annotations
+
+from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
+from stackgen.config import StackgenConfig
+
+
+class AidenNamespace:
+    """Aiden platform APIs (sessions, webhooks, artifacts)."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._webhook = WebhookReportJourney(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
+        )

stackgen_sdk-0.1.1/src/stackgen/aiden/runs.py

@@ -0,0 +1,36 @@
+"""Pure helpers for webhook run selection (unit-testable without HTTP)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stackgen import _http
+
+
+def pick_run(
+    runs: list[dict[str, Any]],
+    dispatch_run_id: str,
+    known_run_ids: frozenset[str],
+) -> dict[str, Any] | None:
+    """Choose the webhook run that corresponds to a new trigger.
+
+    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)
+    """
+    if dispatch_run_id:
+        for item in runs:
+            if dispatch_run_id in {
+                _http.text(item.get("id")),
+                _http.text(item.get("run_id")),
+            }:
+                return item
+    for item in runs:
+        if _http.text(item.get("id")) not in known_run_ids:
+            return item
+    if not runs:
+        return None
+    if not known_run_ids:
+        return runs[0]
+    return None

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

@@ -0,0 +1,185 @@
+"""Aiden webhook → session-report journey."""
+
+from __future__ import annotations
+
+import json
+import time
+import urllib.parse
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.aiden.runs import pick_run
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError, TimeoutError
+
+
+@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
+
+        known_run_ids: frozenset[str] = frozenset()
+        if cfg.webhook_id:
+            known_run_ids = frozenset(
+                _http.text(item.get("id"))
+                for item in self._list_runs(cfg.webhook_id)
+                if _http.text(item.get("id"))
+            )
+
+        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 and not webhook_id:
+            raise StackgenError(
+                "trigger 202 did not include session_id or webhook_id; "
+                "set webhook_id for older motherships. "
+                f"body={json.dumps(trigger)}"
+            )
+
+        if not session_id:
+            session_id = self._wait_for_session(
+                webhook_id,
+                invocation_id,
+                _http.text(trigger.get("run_id")),
+                known_run_ids,
+            )
+
+        artifacts = self._wait_for_artifact(session_id, artifact)
+        path = self._download_artifact(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
+
+    def _list_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs"
+            f"{_http.query(self._config.org_id)}"
+        )
+        return _http.as_list(_http.request(url, self._config.api_token))
+
+    def _get_run(self, webhook_id: str, run_id: str) -> dict[str, Any]:
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs/{run_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected run payload: {data!r}")
+        return data
+
+    def _wait_for_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        dispatch_run_id: str,
+        known_run_ids: frozenset[str],
+    ) -> str:
+        cfg = self._config
+        deadline = time.monotonic() + cfg.timeout_seconds
+        run_id_hint = invocation_id or dispatch_run_id
+        while time.monotonic() < deadline:
+            run: dict[str, Any] | None = None
+            if run_id_hint:
+                try:
+                    run = self._get_run(webhook_id, run_id_hint)
+                except StackgenError:
+                    run = None
+            if run is None:
+                run = pick_run(self._list_runs(webhook_id), dispatch_run_id, known_run_ids)
+            if run is None:
+                time.sleep(cfg.poll_interval_seconds)
+                continue
+            if not run_id_hint:
+                run_id_hint = _http.text(run.get("id")) or _http.text(run.get("run_id"))
+            status = _http.text(run.get("status")).casefold()
+            session_id = _http.text(run.get("session_id"))
+            if status in {"failed", "skipped"}:
+                raise StackgenError(
+                    f"webhook invocation ended with status {status}: "
+                    f"{run.get('error') or 'no error detail'}"
+                )
+            if session_id:
+                return session_id
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError("webhook session", cfg.timeout_seconds)
+
+    def _wait_for_artifact(
+        self, session_id: str, artifact_name: str
+    ) -> list[dict[str, Any]]:
+        cfg = self._config
+        deadline = time.monotonic() + cfg.timeout_seconds
+        url = (
+            f"{cfg.aiden_url()}/api/v1/sessions/{session_id}/artifacts"
+            f"{_http.query(cfg.org_id)}"
+        )
+        want = artifact_name.casefold()
+        artifacts: list[dict[str, Any]] = []
+        while time.monotonic() < deadline:
+            artifacts = _http.as_list(_http.request(url, cfg.api_token))
+            if any(_http.text(item.get("name")).casefold() == want for item in artifacts):
+                return artifacts
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError(artifact_name, cfg.timeout_seconds)
+
+    def _download_artifact(
+        self, session_id: str, artifact_name: str, output_path: str
+    ) -> Path:
+        encoded = urllib.parse.quote(artifact_name, safe="")
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/artifacts/"
+            f"{encoded}/download{_http.query(self._config.org_id)}"
+        )
+        raw = _http.request(url, self._config.api_token, expect_json=False)
+        dest = Path(output_path)
+        dest.write_bytes(raw)
+        return dest

stackgen_sdk-0.1.1/src/stackgen/cli.py

@@ -0,0 +1,33 @@
+"""CLI: trigger webhook and download session-report.md."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from stackgen.client import StackgenClient
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = list(sys.argv[1:] if argv is None else argv)
+    payload = "{}"
+    if args:
+        path = Path(args[0])
+        if not path.is_file():
+            print(f"error: payload file does not exist: {path}", file=sys.stderr)
+            sys.exit(1)
+        payload = path.read_text(encoding="utf-8")
+    try:
+        client = StackgenClient(StackgenConfig.from_env())
+        result = client.aiden.run_webhook_and_download_report(payload)
+    except (StackgenError, ValueError) as err:
+        print(f"error: {err}", file=sys.stderr)
+        sys.exit(1)
+    print(f"session_id={result.session_id}")
+    print(f"output_path={result.output_path}")
+
+
+if __name__ == "__main__":
+    main()