stackgen-sdk 0.5.0rc2__tar.gz → 0.5.0rc4__tar.gz

stackgen_sdk-0.5.0rc4/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: stackgen-sdk
+Version: 0.5.0rc4
+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://app.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.5.0rc4/src/stackgen/__init__.py

@@ -0,0 +1,121 @@
+"""StackGen Python SDK.
+
+Public entrypoint::
+
+    from stackgen import StackgenClient, StackgenConfig
+
+    client = StackgenClient(
+        StackgenConfig(
+            base_url="https://app.stackgen.com",
+            api_token="stackgen_…",
+            org_id="<project-uuid>",
+        )
+    )
+"""
+
+from __future__ import annotations
+
+from stackgen.client import StackgenClient
+from stackgen.config import StackgenConfig
+from stackgen.errors import HttpError, NotAllowlistedError, StackgenError, TimeoutError
+from stackgen.logging import configure_logging, get_logger
+from stackgen.aiden.resources import PolicyConflictRule
+from stackgen.aiden.steer import is_steer_response
+from stackgen.aiden.workflow_builder import (
+    AgentDefinition,
+    StageDefinition,
+    WorkflowBuilder,
+    WorkflowDefinition,
+    create_agent,
+    create_stage,
+    create_workflow,
+)
+from stackgen.aiden.workflow_publish import PublishWorkflowResult
+from stackgen.orgs.namespace import OrgUserAssignment, WORKSPACE_ADMIN_ROLE_ID
+from stackgen.types import (
+    AgentInfo,
+    AlertAttention,
+    AlertStatus,
+    AlertV1,
+    AppStack,
+    DocumentProcessingStatus,
+    GuildIntegration,
+    IacType,
+    IngestedDocument,
+    Investigation,
+    InvestigationStatus,
+    ListAlertsResponse,
+    MeOrg,
+    MeResponse,
+    ReasoningEffortSetting,
+    RegisteredModel,
+    VersionStatus,
+)
+
+__all__ = [
+    "AgentDefinition",
+    "AgentInfo",
+    "AlertAttention",
+    "AlertStatus",
+    "AlertV1",
+    "AppStack",
+    "DocumentProcessingStatus",
+    "GuildIntegration",
+    "HttpError",
+    "IacType",
+    "IngestedDocument",
+    "Investigation",
+    "InvestigationStatus",
+    "ListAlertsResponse",
+    "MeOrg",
+    "MeResponse",
+    "NotAllowlistedError",
+    "OrgUserAssignment",
+    "PolicyConflictRule",
+    "PublishWorkflowResult",
+    "ReasoningEffortSetting",
+    "RegisteredModel",
+    "StackgenClient",
+    "StackgenConfig",
+    "StackgenError",
+    "StageDefinition",
+    "TimeoutError",
+    "VersionStatus",
+    "WORKSPACE_ADMIN_ROLE_ID",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "configure_logging",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
+    "get_logger",
+    "is_steer_response",
+]
+
+
+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.5.0rc4/src/stackgen/_http.py

@@ -0,0 +1,307 @@
+"""Shared HTTP helpers (stdlib)."""
+
+from __future__ import annotations
+
+import json
+import os
+import socket
+import ssl
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Callable
+
+from stackgen.errors import HttpError, TimeoutError as SdkTimeoutError
+from stackgen.logging import log_http_error, log_http_request, log_http_response, log_http_retry
+
+
+def _ceil_seconds(timeout_seconds: float) -> int:
+    whole = int(timeout_seconds)
+    return max(1, whole if timeout_seconds == whole else whole + 1)
+
+
+def _is_timeout_failure(err: BaseException) -> bool:
+    if isinstance(err, socket.timeout):
+        return True
+    if isinstance(err, TimeoutError) and not isinstance(err, SdkTimeoutError):
+        return True
+    reason = getattr(err, "reason", None)
+    if isinstance(reason, socket.timeout):
+        return True
+    if isinstance(reason, TimeoutError) and not isinstance(reason, SdkTimeoutError):
+        return True
+    text = f"{reason if reason is not None else ''} {err}".lower()
+    return "timed out" in text
+
+
+DEFAULT_TRANSIENT_RETRY_BUDGET_MS = 120_000
+TRANSIENT_RETRY_MAX_BACKOFF_SECONDS = 15.0
+
+
+def is_retryable_http_status(status: int) -> bool:
+    """Statuses that self-heal: rate limit and any 5xx (rollout blips, gateway errors)."""
+    return status == 429 or status == 499 or 500 <= status <= 599
+
+
+def is_gateway_outage_status(status: int) -> bool:
+    """Gateway / edge outage statuses that get a time-budgeted retry."""
+    return status in (502, 503, 504)
+
+
+def resolve_transient_retry_budget_ms(override: float | int | None = None) -> int:
+    """Resolve the gateway-outage retry budget (ms)."""
+    if override is not None:
+        value = float(override)
+        if value < 0 or value != value:  # NaN check
+            raise ValueError("transient_retry_budget_ms must be a non-negative number")
+        return int(value)
+    raw = os.environ.get("STACKGEN_TRANSIENT_RETRY_BUDGET_MS", "").strip()
+    if raw:
+        try:
+            parsed = float(raw)
+        except ValueError:
+            parsed = -1
+        if parsed >= 0:
+            return int(parsed)
+    return DEFAULT_TRANSIENT_RETRY_BUDGET_MS
+
+
+def is_idempotent_http_method(method: str) -> bool:
+    return method.upper() in {"GET", "HEAD", "PUT", "DELETE"}
+
+
+def is_transient_http_error(err: BaseException) -> bool:
+    """True for retryable HTTP statuses and transport failures wrapped as HttpError."""
+    if not isinstance(err, HttpError):
+        return False
+    if err.status_code is None:
+        return True
+    return is_retryable_http_status(err.status_code)
+
+
+def is_gateway_outage_error(err: BaseException) -> bool:
+    """True for gateway 502/503/504 or statusless transport HttpError."""
+    if not isinstance(err, HttpError):
+        return False
+    if err.status_code is None:
+        return True
+    return is_gateway_outage_status(err.status_code)
+
+
+def http_status_snippet(err: BaseException | None) -> str:
+    """Label fragment for TimeoutError / subscribe snippets."""
+    if isinstance(err, HttpError) and err.status_code is not None:
+        return f"status={err.status_code}"
+    return "status=network_error"
+
+
+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,
+    timeout_seconds: float | None = None,
+    transient_retry_budget_ms: float | int | None = None,
+    retry_gateway_outage: bool = True,
+    org_id: str | None = None,
+    headers: dict[str, str] | None = None,
+) -> Any:
+    """Bearer HTTP call with retries on transient failures.
+
+    Gateway 502/503/504 and network errors retry until
+    ``transient_retry_budget_ms`` elapses (default 120s) for every method —
+    a CloudFront drop means the edge never delivered the request. Pass
+    ``retry_gateway_outage=False`` to fail fast on POST/PATCH instead.
+    Other retryable statuses (429, 499, application 500, …) still use the
+    short ``retries`` attempt budget and only for idempotent methods.
+
+    ``timeout_seconds`` is an optional per-call abort budget. When the deadline
+    expires, raises :class:`~stackgen.errors.TimeoutError`. Omit to wait until
+    the platform responds.
+    """
+    if timeout_seconds is not None and (
+        not isinstance(timeout_seconds, (int, float)) or timeout_seconds <= 0
+    ):
+        raise ValueError("timeout_seconds must be a positive number of seconds")
+    method = method.upper()
+    budget_ms = resolve_transient_retry_budget_ms(transient_retry_budget_ms)
+    idempotent = is_idempotent_http_method(method)
+    retry_outage = bool(retry_gateway_outage)
+    req_headers = {"Authorization": f"Bearer {token}"}
+    if content_type:
+        req_headers["Content-Type"] = content_type
+    if org_id:
+        req_headers["X-Appcd-Org"] = org_id
+    if headers:
+        req_headers.update(headers)
+    headers = req_headers
+
+    started = time.monotonic()
+    attempt = 0
+    announced_outage = False
+
+    def within_outage_budget() -> bool:
+        return budget_ms > 0 and (time.monotonic() - started) * 1000 < budget_ms
+
+    def announce_outage(status: object) -> None:
+        nonlocal announced_outage
+        if announced_outage:
+            return
+        announced_outage = True
+        log_http_retry(
+            method,
+            url,
+            status=f"outage:{status}",
+            attempt=attempt,
+            retries=retries,
+        )
+
+    while True:
+        attempt += 1
+        log_http_request(method, url, attempt=attempt)
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(
+                req,
+                context=ssl.create_default_context(),
+                timeout=timeout_seconds,
+            ) as resp:
+                raw = resp.read()
+                log_http_response(method, url, status=resp.status, attempt=attempt)
+                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")
+            log_http_response(method, url, status=err.code, attempt=attempt)
+            if (
+                retry_outage
+                and is_gateway_outage_status(err.code)
+                and within_outage_budget()
+            ):
+                announce_outage(err.code)
+                log_http_retry(
+                    method, url, status=err.code, attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**min(attempt, 4), TRANSIENT_RETRY_MAX_BACKOFF_SECONDS))
+                continue
+            if idempotent and is_retryable_http_status(err.code) and attempt < retries:
+                log_http_retry(
+                    method, url, status=err.code, attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**attempt, 8))
+                continue
+            log_http_error(method, url, detail=detail, status=err.code)
+            raise HttpError(
+                f"{method} {url} -> HTTP {err.code}: {detail}",
+                status_code=err.code,
+            ) from err
+        except SdkTimeoutError:
+            raise
+        except (socket.timeout, urllib.error.URLError, TimeoutError) as err:
+            if timeout_seconds is not None and _is_timeout_failure(err):
+                seconds = _ceil_seconds(float(timeout_seconds))
+                log_http_error(method, url, detail=f"timed out after {timeout_seconds}s")
+                raise SdkTimeoutError(f"HTTP {method}", seconds) from err
+            if isinstance(err, (socket.timeout, TimeoutError)):
+                raise HttpError(f"{method} {url} -> {err}") from err
+            log_http_response(method, url, status=None, attempt=attempt)
+            if retry_outage and within_outage_budget():
+                announce_outage("network_error")
+                log_http_retry(
+                    method, url, status="network_error", attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**min(attempt, 4), TRANSIENT_RETRY_MAX_BACKOFF_SECONDS))
+                continue
+            if idempotent and attempt < retries:
+                log_http_retry(
+                    method, url, status="network_error", attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**attempt, 8))
+                continue
+            log_http_error(method, url, detail=str(err))
+            raise HttpError(f"{method} {url} -> {err}") from err
+
+
+def build_multipart_body(
+    fields: dict[str, str],
+    files: list[dict[str, Any]] | None = None,
+) -> tuple[bytes, str]:
+    """Build a ``multipart/form-data`` body by hand (stdlib has no encoder).
+
+    ``files`` entries look like ``{"field_name", "filename", "content",
+    "content_type"}`` (``content_type`` optional, defaults to
+    ``application/octet-stream``). Returns ``(body_bytes, content_type)``.
+    """
+    boundary = f"----stackgenSdk{time.time_ns():x}{os.getpid():x}"
+    crlf = b"\r\n"
+    parts: list[bytes] = []
+    for name, value in fields.items():
+        if value is None:
+            continue
+        parts.append(
+            f'--{boundary}\r\nContent-Disposition: form-data; name="{name}"\r\n\r\n{value}\r\n'.encode(
+                "utf-8"
+            )
+        )
+    for file in files or []:
+        content_type = file.get("content_type") or "application/octet-stream"
+        header = (
+            f"--{boundary}\r\n"
+            f'Content-Disposition: form-data; name="{file["field_name"]}"; '
+            f'filename="{file["filename"]}"\r\n'
+            f"Content-Type: {content_type}\r\n\r\n"
+        ).encode("utf-8")
+        content = file["content"]
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        parts.append(header)
+        parts.append(content)
+        parts.append(crlf)
+    parts.append(f"--{boundary}--\r\n".encode("utf-8"))
+    return b"".join(parts), f"multipart/form-data; boundary={boundary}"
+
+
+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 SdkTimeoutError(label, timeout_seconds)

stackgen_sdk-0.5.0rc4/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.5.0rc4'
+__version_tuple__ = version_tuple = (0, 5, 0, 'rc4')
+
+__commit_id__ = commit_id = None