provision-stack 0.1.0__tar.gz

provision_stack-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+node_modules
+dist
+build
+coverage
+
+.env
+.env.*
+!.env.example
+
+.turbo
+
+.DS_Store
+
+.vscode/settings.json
+
+*.log
+
+# Generated Terraform deployment artifacts (written to user's cwd, not repo)
+terraform/
+
+# Local SQLite state (DATABASE_PATH default location)
+data/
+
+# Local deploy secrets (NEVER commit — deploy-time env lives here)
+.env.local
+deploy/.env
+
+# Host SSH keys + terraform state (local artifacts)
+deploy/hosting/provision-stack-host-key
+deploy/hosting/provision-stack-host-key.pub
+deploy/hosting/.terraform/
+deploy/hosting/terraform.tfstate*
+deploy/hosting/.terraform.lock.hcl
+__pycache__/

provision_stack-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: provision-stack
+Version: 0.1.0
+Summary: Python client for the Provision Stack Execution API — deploy cloud infrastructure via AI agents.
+Project-URL: Homepage, https://provision-stack.com
+Project-URL: Documentation, https://docs.provision-stack.com
+Project-URL: Repository, https://github.com/TravisLinkey/provision-stack
+Author: Provision Stack
+License-Expression: MIT
+Keywords: ai-agents,aws,azure,cloud,gcp,infrastructure,mcp,oracle,terraform
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest-mock>=3.12; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# provision-stack
+
+> Python client for the Provision Stack Execution API — deploy cloud infrastructure via AI agents.
+
+## Install
+
+```bash
+pip install provision-stack
+```
+
+## Quick Start
+
+```python
+from provision_stack import ProvisionStackClient
+
+client = ProvisionStackClient(api_key="your-token", sandbox=True)
+
+# Get suggestions
+suggestions = client.suggest("deploy a production web app")
+
+# Deploy
+result = client.deploy(outcome="deploy a production web app", tier="MVP")
+
+# Check status
+status = client.status(result["deploymentId"])
+```
+
+## Configuration
+
+```python
+client = ProvisionStackClient(
+    api_key="your-token",         # or PROVISION_STACK_API_KEY env var
+    base_url="https://...",       # or PROVISION_STACK_API_URL env var
+    sandbox=True,                 # use sandbox (mock Terraform)
+)
+```
+
+## API
+
+### `suggest(outcome, **kwargs)`
+Get deployment suggestions with tier options and cost estimates.
+
+### `deploy(outcome, **kwargs)`
+Deploy infrastructure. Fee held from balance, captured after verification.
+
+### `status(deployment_id)`
+Check deployment status and verification results.
+
+### `destroy(deployment_id)`
+Destroy all resources owned by a deployment.
+
+### `balance()`
+Check account credit balance.
+
+### `topup_stripe(amount_usd)` / `topup_xrp(amount_usd)`
+Add credits via Stripe or XRP.
+
+## License
+
+MIT

provision_stack-0.1.0/README.md

@@ -0,0 +1,60 @@
+# provision-stack
+
+> Python client for the Provision Stack Execution API — deploy cloud infrastructure via AI agents.
+
+## Install
+
+```bash
+pip install provision-stack
+```
+
+## Quick Start
+
+```python
+from provision_stack import ProvisionStackClient
+
+client = ProvisionStackClient(api_key="your-token", sandbox=True)
+
+# Get suggestions
+suggestions = client.suggest("deploy a production web app")
+
+# Deploy
+result = client.deploy(outcome="deploy a production web app", tier="MVP")
+
+# Check status
+status = client.status(result["deploymentId"])
+```
+
+## Configuration
+
+```python
+client = ProvisionStackClient(
+    api_key="your-token",         # or PROVISION_STACK_API_KEY env var
+    base_url="https://...",       # or PROVISION_STACK_API_URL env var
+    sandbox=True,                 # use sandbox (mock Terraform)
+)
+```
+
+## API
+
+### `suggest(outcome, **kwargs)`
+Get deployment suggestions with tier options and cost estimates.
+
+### `deploy(outcome, **kwargs)`
+Deploy infrastructure. Fee held from balance, captured after verification.
+
+### `status(deployment_id)`
+Check deployment status and verification results.
+
+### `destroy(deployment_id)`
+Destroy all resources owned by a deployment.
+
+### `balance()`
+Check account credit balance.
+
+### `topup_stripe(amount_usd)` / `topup_xrp(amount_usd)`
+Add credits via Stripe or XRP.
+
+## License
+
+MIT

provision_stack-0.1.0/provision_stack/__init__.py

@@ -0,0 +1,38 @@
+"""
+Provision Stack — Python client and tool wrappers.
+
+This package provides a thin Python client for the Provision Stack
+Execution API, plus framework-specific integrations (LangChain,
+CrewAI, Composio).
+
+Branding
+--------
+All user-visible strings (product name, package name, URLs) are
+defined in ``config.py``. To rebrand:
+
+1. Edit ``config.py`` — change ``PRODUCT_NAME``, ``PYPI_PACKAGE``,
+   ``API_BASE_URL_DEFAULT``, and the description strings.
+2. Rename this directory and update ``pyproject.toml`` name/description.
+3. Search-replace the old name in README files.
+
+That's it. All runtime strings flow from ``config.py``.
+"""
+
+from provision_stack.config import (
+    PRODUCT_NAME,
+    API_BASE_URL_DEFAULT,
+    SANDBOX_URL,
+)
+from provision_stack.client import ProvisionStackClient
+from provision_stack.tools import BaseTool, ToolResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PRODUCT_NAME",
+    "API_BASE_URL_DEFAULT",
+    "SANDBOX_URL",
+    "ProvisionStackClient",
+    "BaseTool",
+    "ToolResult",
+]

provision_stack-0.1.0/provision_stack/client.py

@@ -0,0 +1,435 @@
+"""
+Thin Python client for the Provision Stack Execution API.
+
+All API methods return parsed dicts. No third-party dependencies
+beyond ``requests`` (or ``httpx`` if available).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+
+from provision_stack.config import (
+    API_BASE_URL_DEFAULT,
+    SANDBOX_URL,
+    DEFAULT_REGION,
+    DEFAULT_TIER,
+)
+
+
+def _http_post(
+    url: str,
+    json: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """POST with requests, falling back to httpx, then urllib."""
+    try:
+        import requests
+
+        resp = requests.post(url, json=json, headers=headers or {}, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+    except ImportError:
+        pass
+
+    try:
+        import httpx
+
+        with httpx.Client(timeout=30) as client:
+            resp = client.post(url, json=json, headers=headers or {})
+            resp.raise_for_status()
+            return resp.json()
+    except ImportError:
+        pass
+
+    import urllib.request
+    import json as _json
+
+    req = urllib.request.Request(
+        url,
+        data=_json.dumps(json or {}).encode(),
+        headers={"Content-Type": "application/json", **(headers or {})},
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return _json.loads(resp.read())
+
+
+def _http_get(
+    url: str,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """GET with requests, falling back to httpx, then urllib."""
+    try:
+        import requests
+
+        resp = requests.get(url, headers=headers or {}, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+    except ImportError:
+        pass
+
+    try:
+        import httpx
+
+        with httpx.Client(timeout=30) as client:
+            resp = client.get(url, headers=headers or {})
+            resp.raise_for_status()
+            return resp.json()
+    except ImportError:
+        pass
+
+    import urllib.request
+    import json as _json
+
+    req = urllib.request.Request(
+        url,
+        headers=headers or {},
+        method="GET",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return _json.loads(resp.read())
+
+
+def _http_delete(
+    url: str,
+    headers: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    """DELETE with requests, falling back to httpx, then urllib."""
+    try:
+        import requests
+
+        resp = requests.delete(url, headers=headers or {}, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+    except ImportError:
+        pass
+
+    try:
+        import httpx
+
+        with httpx.Client(timeout=30) as client:
+            resp = client.delete(url, headers=headers or {})
+            resp.raise_for_status()
+            return resp.json()
+    except ImportError:
+        pass
+
+    import urllib.request
+    import json as _json
+
+    req = urllib.request.Request(
+        url,
+        headers=headers or {},
+        method="DELETE",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return _json.loads(resp.read())
+
+
+class ProvisionStackClient:
+    """
+    Python client for the Provision Stack Execution API.
+
+    Usage::
+
+        from provision_stack import ProvisionStackClient
+
+        client = ProvisionStackClient(api_key="your-token")
+
+        # Get suggestions
+        suggestions = client.suggest("deploy a production web app")
+
+        # Deploy
+        deploy = client.deploy(
+            outcome="deploy a production web app",
+            resources=suggestions["options"][0]["resources"],
+            tier="MVP",
+        )
+
+        # Check status
+        status = client.status(deploy["deploymentId"])
+
+        # Check balance
+        balance = client.balance()
+
+    Parameters
+    ----------
+    api_key : str, optional
+        Bearer token for authentication. Falls back to
+        ``PROVISION_STACK_API_KEY`` env var, then ``PS_API_KEY``.
+    base_url : str, optional
+        API base URL. Falls back to ``PROVISION_STACK_API_URL`` env var,
+        then the default production URL.
+    sandbox : bool, optional
+        If True, use the sandbox URL (mock Terraform, no real deploys).
+        Defaults to False.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        sandbox: bool = False,
+    ) -> None:
+        self.api_key = (
+            api_key
+            or os.environ.get("PROVISION_STACK_API_KEY")
+            or os.environ.get("PS_API_KEY")
+            or ""
+        )
+        if sandbox:
+            self.base_url = SANDBOX_URL
+        else:
+            self.base_url = (
+                base_url
+                or os.environ.get("PROVISION_STACK_API_URL")
+                or API_BASE_URL_DEFAULT
+            )
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url.rstrip('/')}{path}"
+
+    # ── Auth ──────────────────────────────────────────────────────
+
+    def signup(self, agent_id: str, scopes: list[str] | None = None) -> dict:
+        """
+        Create a new API token (self-serve signup).
+
+        Returns the token and next-step guidance.
+        """
+        return _http_post(
+            self._url("/auth/tokens"),
+            json={"agentId": agent_id, "scopes": scopes or []},
+        )
+
+    # ── Suggestions ───────────────────────────────────────────────
+
+    def suggest(
+        self,
+        outcome: str,
+        region: str | None = None,
+        provider: str | None = None,
+        cross_provider: bool = False,
+        max_monthly_cost_usd: float | None = None,
+        requirements: dict[str, Any] | None = None,
+    ) -> dict:
+        """
+        Get deployment suggestions for a desired outcome.
+
+        Parameters
+        ----------
+        outcome : str
+            Natural language description (e.g. "deploy a production web app").
+        region : str, optional
+            AWS/GCP/Azure region (e.g. "us-east-1").
+        provider : str, optional
+            Restrict to one provider ("aws", "gcp", "azure", "oracle").
+        cross_provider : bool
+            If True, compare across all providers.
+        max_monthly_cost_usd : float, optional
+            Filter out options above this monthly cost.
+        requirements : dict, optional
+            Business requirements: budget, availability, compliance,
+            trafficPattern, computePreference.
+
+        Returns
+        -------
+        dict
+            Suggestions with options, cost estimates, and optional
+            clarificationRequest.
+        """
+        body: dict[str, Any] = {"outcome": outcome}
+        if region:
+            body["region"] = region
+        if provider:
+            body["provider"] = provider
+        if cross_provider:
+            body["crossProvider"] = True
+        if max_monthly_cost_usd is not None:
+            body["maxMonthlyCostUsd"] = max_monthly_cost_usd
+        if requirements:
+            body["requirements"] = requirements
+
+        return _http_post(
+            self._url("/api/v1/suggestions"),
+            json=body,
+            headers=self._headers(),
+        )
+
+    # ── Quote ─────────────────────────────────────────────────────
+
+    def quote(
+        self,
+        outcome: str,
+        region: str | None = None,
+        tier: str | None = None,
+        max_monthly_cost_usd: float | None = None,
+    ) -> dict:
+        """
+        Get a pricing quote for a deployment.
+
+        Returns a quote ID and estimated monthly cost.
+        """
+        body: dict[str, Any] = {"outcome": outcome}
+        if region:
+            body["region"] = region
+        if tier:
+            body["tier"] = tier
+        if max_monthly_cost_usd is not None:
+            body["maxMonthlyCostUsd"] = max_monthly_cost_usd
+
+        return _http_post(
+            self._url("/api/v1/quote"),
+            json=body,
+            headers=self._headers(),
+        )
+
+    # ── Deploy ────────────────────────────────────────────────────
+
+    def deploy(
+        self,
+        outcome: str,
+        resources: list[dict[str, Any]] | None = None,
+        tier: str | None = None,
+        region: str | None = None,
+        max_monthly_cost_usd: float | None = None,
+        requirements: dict[str, Any] | None = None,
+    ) -> dict:
+        """
+        Deploy infrastructure for a desired outcome.
+
+        The deploy fee is held from your balance and captured only
+        after verification passes (failed deployments are free).
+
+        Parameters
+        ----------
+        outcome : str
+            Natural language description.
+        resources : list[dict], optional
+            Resource configs from a suggestion option.
+        tier : str, optional
+            Deployment tier (Starter/MVP/Startup/Enterprise).
+        region : str, optional
+            Target region.
+        max_monthly_cost_usd : float, optional
+            Monthly cost cap.
+        requirements : dict, optional
+            Business requirements for pattern selection.
+
+        Returns
+        -------
+        dict
+            Deployment ID, status, and provider info.
+        """
+        body: dict[str, Any] = {
+            "outcome": outcome,
+        }
+        if resources:
+            body["resources"] = resources
+        if tier:
+            body["tier"] = tier
+        if region:
+            body["region"] = region
+        if max_monthly_cost_usd is not None:
+            body["maxMonthlyCostUsd"] = max_monthly_cost_usd
+        if requirements:
+            body["requirements"] = requirements
+
+        return _http_post(
+            self._url("/api/v1/deployments"),
+            json=body,
+            headers=self._headers(),
+        )
+
+    # ── Status ────────────────────────────────────────────────────
+
+    def status(self, deployment_id: str) -> dict:
+        """
+        Check deployment status and verification results.
+
+        Returns status (pending/provisioning/active/failed),
+        verification details, and terraform files.
+        """
+        return _http_get(
+            self._url(f"/api/v1/deployments/{deployment_id}"),
+            headers=self._headers(),
+        )
+
+    # ── Destroy ───────────────────────────────────────────────────
+
+    def destroy(self, deployment_id: str) -> dict:
+        """
+        Destroy all resources owned by a deployment.
+        """
+        return _http_delete(
+            self._url(f"/api/v1/deployments/{deployment_id}"),
+            headers=self._headers(),
+        )
+
+    # ── List deployments ──────────────────────────────────────────
+
+    def list_deployments(self) -> dict:
+        """
+        List all tracked deployments.
+        """
+        return _http_get(
+            self._url("/api/v1/deployments"),
+            headers=self._headers(),
+        )
+
+    # ── Billing ───────────────────────────────────────────────────
+
+    def balance(self) -> dict:
+        """
+        Check account credit balance.
+
+        Returns total, held, and available USD.
+        """
+        return _http_get(
+            self._url("/api/v1/billing/balance"),
+            headers=self._headers(),
+        )
+
+    def topup_stripe(self, amount_usd: float) -> dict:
+        """
+        Create a Stripe Checkout session for adding credits.
+
+        Returns a checkout URL for the user to complete payment.
+        """
+        return _http_post(
+            self._url("/api/v1/billing/topup/stripe"),
+            json={"amountUsd": amount_usd},
+            headers=self._headers(),
+        )
+
+    def topup_xrp(self, amount_usd: float) -> dict:
+        """
+        Get XRP deposit instructions for adding credits.
+
+        Returns deposit address, destination tag, and exact amount.
+        """
+        return _http_post(
+            self._url("/api/v1/billing/topup/xrp"),
+            json={"amountUsd": amount_usd},
+            headers=self._headers(),
+        )
+
+    def topup_sandbox(self, amount_usd: float) -> dict:
+        """
+        Add free sandbox credits (sandbox mode only).
+
+        Returns the credited amount.
+        """
+        return _http_post(
+            self._url("/api/v1/billing/topup/sandbox"),
+            json={"amountUsd": amount_usd},
+            headers=self._headers(),
+        )

provision_stack-0.1.0/provision_stack/config.py

@@ -0,0 +1,101 @@
+"""
+Branding and configuration — single source of truth.
+
+This is the ONLY file you need to edit when rebranding.
+All user-visible strings (product name, package name, URLs,
+descriptions) are defined here.
+
+Current brand: **Provision Stack** (finalized 2026-07-20).
+
+If the brand ever changes again:
+
+1. Update PRODUCT_NAME below
+2. Update PYPI_PACKAGE to match the new PyPI package name
+3. Update API_BASE_URL_DEFAULT and SANDBOX_URL to the new domain
+4. Update the description strings (short_description, long_description)
+5. Rename the plugin directories:
+     plugins/python/provision-stack/           → plugins/python/<new-name>-sdk/
+     plugins/python/provision-stack-langchain/ → plugins/python/<new-name>-langchain/
+     plugins/python/provision-stack-crewai/    → plugins/python/<new-name>-crewai/
+     plugins/python/provision-stack-composio/  → plugins/python/<new-name>-composio/
+6. Rename Python package directories:
+     provision_stack/           → <new_name>/
+     provision_stack_langchain/ → <new_name>_langchain/
+     provision_stack_crewai/    → <new_name>_crewai/
+     provision_stack_composio/  → <new_name>_composio/
+7. Update pyproject.toml name/description in each package
+8. Update all import statements across the plugin packages
+
+This is the ONLY file that needs to change for steps 1-4.
+Steps 5-8 are mechanical find-replace.
+"""
+
+# ── Product identity ──────────────────────────────────────────────
+# Change these when rebranding. Everything else derives from them.
+
+PRODUCT_NAME = "Provision Stack"
+PYPI_PACKAGE = "provision-stack"  # PyPI distribution name
+
+# ── API endpoints ─────────────────────────────────────────────────
+# These are the live API URLs. Sandbox uses SANDBOX_URL.
+
+API_BASE_URL_DEFAULT = "https://api.provision-stack.com"
+SANDBOX_URL = "https://sandbox.provision-stack.com"
+
+# ── User-visible strings ──────────────────────────────────────────
+# Used in tool descriptions, error messages, and docs.
+
+SHORT_DESCRIPTION = (
+    "Deploy production infrastructure via AI agents — "
+    "AWS, GCP, Azure, and Oracle Cloud."
+)
+
+LONG_DESCRIPTION = (
+    "{product} lets AI agents provision and manage cloud "
+    "infrastructure through natural language. Describe your outcome "
+    "(e.g. 'deploy a production web application') and receive "
+    "verified, best-practice infrastructure on your own cloud account. "
+    "Supports AWS, Google Cloud, Azure, and Oracle Cloud."
+)
+
+TOOL_DESCRIPTION_SUGGEST = (
+    "Get deployment suggestions for a desired outcome. "
+    "Returns tier options (Starter/MVP/Startup/Enterprise) with "
+    "monthly cost estimates across multiple cloud providers."
+)
+
+TOOL_DESCRIPTION_DEPLOY = (
+    "Deploy infrastructure for a selected suggestion. "
+    "The deploy fee is held from your account balance and captured "
+    "only after verification passes (failed deployments are free)."
+)
+
+TOOL_DESCRIPTION_STATUS = (
+    "Check the status and verification results of a deployment."
+)
+
+TOOL_DESCRIPTION_DESTROY = (
+    "Destroy all resources owned by a deployment."
+)
+
+TOOL_DESCRIPTION_BALANCE = (
+    "Check your account credit balance."
+)
+
+TOOL_DESCRIPTION_TOPUP = (
+    "Add credits to your account via Stripe (card) or XRP (crypto)."
+)
+
+# ── Defaults ──────────────────────────────────────────────────────
+
+DEFAULT_REGION = "us-east-1"
+DEFAULT_TIER = "MVP"
+
+# ── Sandbox note ──────────────────────────────────────────────────
+# Shown to users when connecting to the sandbox.
+
+SANDBOX_NOTE = (
+    "Sandbox mode: infrastructure is mocked (no real cloud resources "
+    "are created). Top up with POST /api/v1/billing/topup/sandbox "
+    "to get free credits."
+)

provision_stack-0.1.0/provision_stack/tools.py

@@ -0,0 +1,161 @@
+"""
+Base tool definitions for the Provision Stack client.
+
+These are framework-agnostic tool definitions that can be wrapped
+by LangChain, CrewAI, Composio, or any other agent framework.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from provision_stack.client import ProvisionStackClient
+from provision_stack.config import (
+    PRODUCT_NAME,
+    TOOL_DESCRIPTION_SUGGEST,
+    TOOL_DESCRIPTION_DEPLOY,
+    TOOL_DESCRIPTION_STATUS,
+    TOOL_DESCRIPTION_DESTROY,
+    TOOL_DESCRIPTION_BALANCE,
+    TOOL_DESCRIPTION_TOPUP,
+)
+
+
+@dataclass
+class ToolResult:
+    """Standardized result from a tool call."""
+
+    success: bool
+    data: dict[str, Any]
+    error: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result = {"success": self.success, **self.data}
+        if self.error:
+            result["error"] = self.error
+        return result
+
+
+@dataclass
+class BaseTool:
+    """
+    Base class for framework-specific tool wrappers.
+
+    Each tool has a name, description, and a ``run`` method that
+    delegates to the ProvisionStackClient.
+
+    Framework plugins (LangChain, CrewAI, Composio) subclass this
+    and add framework-specific metadata (args schemas, return types).
+    """
+
+    name: str
+    description: str
+    client: ProvisionStackClient
+    _run: Callable[..., Any]
+
+    def run(self, **kwargs: Any) -> ToolResult:
+        """Execute the tool with the given arguments."""
+        try:
+            data = self._run(**kwargs)
+            return ToolResult(success=True, data=data)
+        except Exception as e:
+            return ToolResult(success=False, data={}, error=str(e))
+
+
+def create_suggest_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'suggest' tool bound to the given client."""
+    return BaseTool(
+        name="suggest",
+        description=TOOL_DESCRIPTION_SUGGEST,
+        client=client,
+        _run=lambda outcome, region=None, provider=None,
+        cross_provider=False, max_monthly_cost_usd=None,
+        requirements=None, **kw: client.suggest(
+            outcome=outcome,
+            region=region,
+            provider=provider,
+            cross_provider=cross_provider,
+            max_monthly_cost_usd=max_monthly_cost_usd,
+            requirements=requirements,
+        ),
+    )
+
+
+def create_deploy_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'deploy' tool bound to the given client."""
+    return BaseTool(
+        name="deploy",
+        description=TOOL_DESCRIPTION_DEPLOY,
+        client=client,
+        _run=lambda outcome, resources=None, tier=None,
+        region=None, max_monthly_cost_usd=None,
+        requirements=None, **kw: client.deploy(
+            outcome=outcome,
+            resources=resources,
+            tier=tier,
+            region=region,
+            max_monthly_cost_usd=max_monthly_cost_usd,
+            requirements=requirements,
+        ),
+    )
+
+
+def create_status_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'status' tool bound to the given client."""
+    return BaseTool(
+        name="status",
+        description=TOOL_DESCRIPTION_STATUS,
+        client=client,
+        _run=lambda deployment_id, **kw: client.status(deployment_id),
+    )
+
+
+def create_destroy_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'destroy' tool bound to the given client."""
+    return BaseTool(
+        name="destroy",
+        description=TOOL_DESCRIPTION_DESTROY,
+        client=client,
+        _run=lambda deployment_id, **kw: client.destroy(deployment_id),
+    )
+
+
+def create_balance_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'balance' tool bound to the given client."""
+    return BaseTool(
+        name="balance",
+        description=TOOL_DESCRIPTION_BALANCE,
+        client=client,
+        _run=lambda **kw: client.balance(),
+    )
+
+
+def create_topup_tool(client: ProvisionStackClient) -> BaseTool:
+    """Create a 'topup' tool bound to the given client."""
+    return BaseTool(
+        name="topup",
+        description=TOOL_DESCRIPTION_TOPUP,
+        client=client,
+        _run=lambda amount_usd, rail="stripe", **kw: (
+            client.topup_stripe(amount_usd) if rail == "stripe"
+            else client.topup_xrp(amount_usd)
+        ),
+    )
+
+
+def get_all_tools(client: ProvisionStackClient) -> list[BaseTool]:
+    """
+    Get all available tools bound to the given client.
+
+    Returns a list of BaseTool instances that can be used by any
+    framework plugin.
+    """
+    return [
+        create_suggest_tool(client),
+        create_deploy_tool(client),
+        create_status_tool(client),
+        create_destroy_tool(client),
+        create_balance_tool(client),
+        create_topup_tool(client),
+    ]

provision_stack-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "provision-stack"
+version = "0.1.0"
+description = "Python client for the Provision Stack Execution API — deploy cloud infrastructure via AI agents."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Provision Stack" },
+]
+keywords = [
+    "ai-agents",
+    "infrastructure",
+    "aws",
+    "gcp",
+    "azure",
+    "oracle",
+    "terraform",
+    "mcp",
+    "cloud",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Systems Administration",
+]
+
+[project.urls]
+Homepage = "https://provision-stack.com"
+Documentation = "https://docs.provision-stack.com"
+Repository = "https://github.com/TravisLinkey/provision-stack"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+    "pytest-mock>=3.12",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

provision_stack-0.1.0/tests/__init__.py

@@ -0,0 +1 @@
+"""Shared test fixtures for provision-stack tests."""

provision_stack-0.1.0/tests/test_client.py

@@ -0,0 +1,238 @@
+"""Tests for provision_stack.client — REST API client."""
+
+from __future__ import annotations
+
+import json
+import urllib.request
+from unittest.mock import MagicMock, patch, MagicMock
+import pytest
+
+from provision_stack.client import ProvisionStackClient, _http_post, _http_get, _http_delete
+from provision_stack.config import API_BASE_URL_DEFAULT, SANDBOX_URL
+
+
+# ── Fixtures ──────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def client():
+    return ProvisionStackClient(api_key="test-token-123")
+
+
+@pytest.fixture
+def sandbox_client():
+    return ProvisionStackClient(api_key="test-token-123", sandbox=True)
+
+
+@pytest.fixture
+def mock_response():
+    """Create a mock response object for requests/httpx."""
+    resp = MagicMock()
+    resp.json.return_value = {"success": True, "data": "test"}
+    resp.raise_for_status = MagicMock()
+    return resp
+
+
+# ── Client initialization ─────────────────────────────────────────
+
+
+class TestClientInit:
+    def test_default_url(self, client):
+        assert client.base_url == API_BASE_URL_DEFAULT
+
+    def test_sandbox_url(self, sandbox_client):
+        assert sandbox_client.base_url == SANDBOX_URL
+
+    def test_custom_url(self):
+        c = ProvisionStackClient(base_url="https://custom.api.com")
+        assert c.base_url == "https://custom.api.com"
+
+    def test_api_key_from_param(self):
+        c = ProvisionStackClient(api_key="my-key")
+        assert c.api_key == "my-key"
+
+    def test_api_key_from_env(self, monkeypatch):
+        monkeypatch.setenv("PROVISION_STACK_API_KEY", "env-key")
+        c = ProvisionStackClient()
+        assert c.api_key == "env-key"
+
+    def test_api_key_legacy_env(self, monkeypatch):
+        monkeypatch.setenv("PS_API_KEY", "legacy-key")
+        c = ProvisionStackClient()
+        assert c.api_key == "legacy-key"
+
+    def test_param_overrides_env(self, monkeypatch):
+        monkeypatch.setenv("PROVISION_STACK_API_KEY", "env-key")
+        c = ProvisionStackClient(api_key="param-key")
+        assert c.api_key == "param-key"
+
+    def test_sandbox_overrides_custom_url(self):
+        c = ProvisionStackClient(base_url="https://custom.api.com", sandbox=True)
+        assert c.base_url == SANDBOX_URL
+
+
+# ── Headers ───────────────────────────────────────────────────────
+
+
+class TestHeaders:
+    def test_auth_header(self, client):
+        headers = client._headers()
+        assert headers["Authorization"] == "Bearer test-token-123"
+
+    def test_no_auth_without_key(self):
+        c = ProvisionStackClient()
+        headers = c._headers()
+        assert "Authorization" not in headers
+
+
+# ── URL construction ──────────────────────────────────────────────
+
+
+class TestUrl:
+    def test_url_path(self, client):
+        assert client._url("/api/v1/test") == f"{API_BASE_URL_DEFAULT}/api/v1/test"
+
+    def test_url_strips_trailing_slash(self):
+        c = ProvisionStackClient(base_url="https://api.example.com/")
+        assert c._url("/test") == "https://api.example.com/test"
+
+
+# ── Suggest ───────────────────────────────────────────────────────
+
+
+class TestSuggest:
+    @patch("provision_stack.client._http_post")
+    def test_suggest_minimal(self, mock_post, client):
+        mock_post.return_value = {"options": []}
+        result = client.suggest("deploy a web app")
+        mock_post.assert_called_once()
+        call_args = mock_post.call_args
+        assert "suggestions" in call_args[0][0]
+        assert call_args[1]["json"]["outcome"] == "deploy a web app"
+
+    @patch("provision_stack.client._http_post")
+    def test_suggest_with_options(self, mock_post, client):
+        mock_post.return_value = {"options": []}
+        client.suggest(
+            "deploy a web app",
+            region="us-west-2",
+            provider="aws",
+            cross_provider=True,
+            max_monthly_cost_usd=50.0,
+            requirements={"budget": 100},
+        )
+        call_args = mock_post.call_args
+        body = call_args[1]["json"]
+        assert body["region"] == "us-west-2"
+        assert body["provider"] == "aws"
+        assert body["crossProvider"] is True
+        assert body["maxMonthlyCostUsd"] == 50.0
+        assert body["requirements"] == {"budget": 100}
+
+
+# ── Deploy ────────────────────────────────────────────────────────
+
+
+class TestDeploy:
+    @patch("provision_stack.client._http_post")
+    def test_deploy_minimal(self, mock_post, client):
+        mock_post.return_value = {"deploymentId": "d-123"}
+        result = client.deploy("deploy a web app")
+        body = mock_post.call_args[1]["json"]
+        assert body["outcome"] == "deploy a web app"
+
+    @patch("provision_stack.client._http_post")
+    def test_deploy_with_tier(self, mock_post, client):
+        mock_post.return_value = {"deploymentId": "d-123"}
+        client.deploy("deploy a web app", tier="MVP", region="eu-west-1")
+        body = mock_post.call_args[1]["json"]
+        assert body["tier"] == "MVP"
+        assert body["region"] == "eu-west-1"
+
+
+# ── Status ────────────────────────────────────────────────────────
+
+
+class TestStatus:
+    @patch("provision_stack.client._http_get")
+    def test_status(self, mock_get, client):
+        mock_get.return_value = {"status": "active"}
+        result = client.status("d-123")
+        mock_get.assert_called_once()
+        assert "d-123" in mock_get.call_args[0][0]
+        assert result["status"] == "active"
+
+
+# ── Destroy ───────────────────────────────────────────────────────
+
+
+class TestDestroy:
+    @patch("provision_stack.client._http_delete")
+    def test_destroy(self, mock_delete, client):
+        mock_delete.return_value = {"status": "destroyed"}
+        result = client.destroy("d-123")
+        mock_delete.assert_called_once()
+        assert "d-123" in mock_delete.call_args[0][0]
+
+
+# ── Balance ───────────────────────────────────────────────────────
+
+
+class TestBalance:
+    @patch("provision_stack.client._http_get")
+    def test_balance(self, mock_get, client):
+        mock_get.return_value = {"availableUsd": 25.0}
+        result = client.balance()
+        assert "billing/balance" in mock_get.call_args[0][0]
+
+
+# ── Topup ─────────────────────────────────────────────────────────
+
+
+class TestTopup:
+    @patch("provision_stack.client._http_post")
+    def test_topup_stripe(self, mock_post, client):
+        mock_post.return_value = {"checkoutUrl": "https://checkout.stripe.com/..."}
+        result = client.topup_stripe(20.0)
+        body = mock_post.call_args[1]["json"]
+        assert body["amountUsd"] == 20.0
+        assert "topup/stripe" in mock_post.call_args[0][0]
+
+    @patch("provision_stack.client._http_post")
+    def test_topup_xrp(self, mock_post, client):
+        mock_post.return_value = {"address": "rXXX", "tag": 123}
+        result = client.topup_xrp(10.0)
+        body = mock_post.call_args[1]["json"]
+        assert body["amountUsd"] == 10.0
+        assert "topup/xrp" in mock_post.call_args[0][0]
+
+    @patch("provision_stack.client._http_post")
+    def test_topup_sandbox(self, mock_post, sandbox_client):
+        mock_post.return_value = {"creditedUsd": 25.0}
+        result = sandbox_client.topup_sandbox(25.0)
+        body = mock_post.call_args[1]["json"]
+        assert body["amountUsd"] == 25.0
+        assert "topup/sandbox" in mock_post.call_args[0][0]
+
+
+# ── Signup ────────────────────────────────────────────────────────
+
+
+class TestSignup:
+    @patch("provision_stack.client._http_post")
+    def test_signup(self, mock_post, client):
+        mock_post.return_value = {"token": "new-token"}
+        result = client.signup("my-agent")
+        body = mock_post.call_args[1]["json"]
+        assert body["agentId"] == "my-agent"
+
+
+# ── List deployments ──────────────────────────────────────────────
+
+
+class TestListDeployments:
+    @patch("provision_stack.client._http_get")
+    def test_list_deployments(self, mock_get, client):
+        mock_get.return_value = {"items": []}
+        result = client.list_deployments()
+        assert "deployments" in mock_get.call_args[0][0]

provision_stack-0.1.0/tests/test_config.py

@@ -0,0 +1,43 @@
+"""Tests for provision_stack.config — branding configuration."""
+
+from provision_stack.config import (
+    PRODUCT_NAME,
+    PYPI_PACKAGE,
+    API_BASE_URL_DEFAULT,
+    SANDBOX_URL,
+    SHORT_DESCRIPTION,
+    LONG_DESCRIPTION,
+    TOOL_DESCRIPTION_SUGGEST,
+    DEFAULT_REGION,
+    DEFAULT_TIER,
+)
+
+
+class TestConfig:
+    def test_product_name_is_string(self):
+        assert isinstance(PRODUCT_NAME, str)
+        assert len(PRODUCT_NAME) > 0
+
+    def test_pypi_package_is_string(self):
+        assert isinstance(PYPI_PACKAGE, str)
+        assert len(PYPI_PACKAGE) > 0
+
+    def test_urls_are_valid(self):
+        assert API_BASE_URL_DEFAULT.startswith("https://")
+        assert SANDBOX_URL.startswith("https://")
+
+    def test_descriptions_are_strings(self):
+        assert isinstance(SHORT_DESCRIPTION, str)
+        assert isinstance(LONG_DESCRIPTION, str)
+        assert len(SHORT_DESCRIPTION) > 10
+        assert len(LONG_DESCRIPTION) > 50
+
+    def test_tool_descriptions_exist(self):
+        assert isinstance(TOOL_DESCRIPTION_SUGGEST, str)
+        assert len(TOOL_DESCRIPTION_SUGGEST) > 10
+
+    def test_defaults_are_set(self):
+        assert isinstance(DEFAULT_REGION, str)
+        assert isinstance(DEFAULT_TIER, str)
+        assert len(DEFAULT_REGION) > 0
+        assert len(DEFAULT_TIER) > 0

provision_stack-0.1.0/tests/test_tools.py

@@ -0,0 +1,109 @@
+"""Tests for provision_stack.tools — framework-agnostic tool definitions."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+import pytest
+
+from provision_stack.tools import (
+    BaseTool,
+    ToolResult,
+    create_suggest_tool,
+    create_deploy_tool,
+    create_status_tool,
+    create_destroy_tool,
+    create_balance_tool,
+    create_topup_tool,
+    get_all_tools,
+)
+from provision_stack.client import ProvisionStackClient
+
+
+# ── Fixtures ──────────────────────────────────────────────────────
+
+
+@pytest.fixture
+def client():
+    return ProvisionStackClient(api_key="test-token")
+
+
+# ── ToolResult ────────────────────────────────────────────────────
+
+
+class TestToolResult:
+    def test_success(self):
+        r = ToolResult(success=True, data={"key": "value"})
+        d = r.to_dict()
+        assert d["success"] is True
+        assert d["key"] == "value"
+        assert "error" not in d
+
+    def test_failure(self):
+        r = ToolResult(success=False, data={}, error="something broke")
+        d = r.to_dict()
+        assert d["success"] is False
+        assert d["error"] == "something broke"
+
+
+# ── BaseTool ──────────────────────────────────────────────────────
+
+
+class TestBaseTool:
+    def test_run_success(self, client):
+        def my_fn(x):
+            return {"result": x * 2}
+
+        tool = BaseTool(name="test", description="desc", client=client, _run=my_fn)
+        result = tool.run(x=5)
+        assert result.success is True
+        assert result.data["result"] == 10
+
+    def test_run_exception(self, client):
+        def my_fn():
+            raise ValueError("bad input")
+
+        tool = BaseTool(name="test", description="desc", client=client, _run=my_fn)
+        result = tool.run()
+        assert result.success is False
+        assert "bad input" in result.error
+
+
+# ── Factory functions ─────────────────────────────────────────────
+
+
+class TestFactoryFunctions:
+    def test_suggest_tool(self, client):
+        tool = create_suggest_tool(client)
+        assert tool.name == "suggest"
+        assert tool.client is client
+
+    def test_deploy_tool(self, client):
+        tool = create_deploy_tool(client)
+        assert tool.name == "deploy"
+
+    def test_status_tool(self, client):
+        tool = create_status_tool(client)
+        assert tool.name == "status"
+
+    def test_destroy_tool(self, client):
+        tool = create_destroy_tool(client)
+        assert tool.name == "destroy"
+
+    def test_balance_tool(self, client):
+        tool = create_balance_tool(client)
+        assert tool.name == "balance"
+
+    def test_topup_tool(self, client):
+        tool = create_topup_tool(client)
+        assert tool.name == "topup"
+
+    def test_get_all_tools(self, client):
+        tools = get_all_tools(client)
+        assert len(tools) == 6
+        names = {t.name for t in tools}
+        assert names == {"suggest", "deploy", "status", "destroy", "balance", "topup"}
+
+    def test_all_tools_share_client(self, client):
+        tools = get_all_tools(client)
+        for tool in tools:
+            assert tool.client is client