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

{stackgen_sdk-0.1.3 → stackgen_sdk-0.1.6}/.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.6/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: stackgen-sdk
+Version: 0.1.6
+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.1.6/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://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.1.3 → stackgen_sdk-0.1.6}/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.3 → stackgen_sdk-0.1.6}/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://app.stackgen.com",
+            api_token="stackgen_…",
+            org_id="<project-uuid>",
+        )
+    )
 """
 
 from __future__ import annotations
@@ -13,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.3 → stackgen_sdk-0.1.6}/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.3'
-__version_tuple__ = version_tuple = (0, 1, 3)
+__version__ = version = '0.1.6'
+__version_tuple__ = version_tuple = (0, 1, 6)
 
 __commit_id__ = commit_id = None

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

@@ -0,0 +1,29 @@
+"""Aiden (platform) namespace — webhooks, sessions, artifacts, Ask Guild, workflows."""
+
+from stackgen.aiden.ask import AskArtifactResult
+from stackgen.aiden.namespace import AidenNamespace
+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",
+    "PublishWorkflowResult",
+    "StageDefinition",
+    "WebhookReportResult",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
+]

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

@@ -0,0 +1,172 @@
+"""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()
+            # 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
+            if ready:
+                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.6/src/stackgen/aiden/namespace.py

@@ -0,0 +1,170 @@
+"""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.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
+
+
+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 (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)
+
+    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)