straleio 0.1.0__py3-none-any.whl

straleio/__init__.py

@@ -0,0 +1,52 @@
+"""Strale Python SDK — let AI agents buy capabilities at runtime."""
+
+from .client import Strale
+from .errors import (
+    CapabilityUnavailableError,
+    ExecutionFailedError,
+    InsufficientBalanceError,
+    InvalidRequestError,
+    NoMatchingCapabilityError,
+    NotFoundError,
+    RateLimitedError,
+    StraleError,
+    TimeoutExceededError,
+    UnauthorizedError,
+)
+from .types import (
+    BalanceResponse,
+    Capability,
+    DoRequest,
+    DoResponse,
+    DryRunResponse,
+    Provenance,
+    Transaction,
+    TransactionDetail,
+)
+
+__all__ = [
+    # Client
+    "Strale",
+    # Types
+    "DoRequest",
+    "DoResponse",
+    "DryRunResponse",
+    "Provenance",
+    "Capability",
+    "BalanceResponse",
+    "Transaction",
+    "TransactionDetail",
+    # Errors
+    "StraleError",
+    "InsufficientBalanceError",
+    "NoMatchingCapabilityError",
+    "CapabilityUnavailableError",
+    "ExecutionFailedError",
+    "TimeoutExceededError",
+    "InvalidRequestError",
+    "RateLimitedError",
+    "UnauthorizedError",
+    "NotFoundError",
+]
+
+__version__ = "0.1.0"

straleio/client.py

@@ -0,0 +1,314 @@
+"""Strale Python SDK client."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import httpx
+
+from .errors import StraleError, create_error
+from .types import (
+    BalanceResponse,
+    Capability,
+    DoRequest,
+    DoResponse,
+    DryRunResponse,
+    Provenance,
+    Transaction,
+    TransactionDetail,
+)
+
+DEFAULT_BASE_URL = "https://strale-production.up.railway.app"
+DEFAULT_TIMEOUT = 60.0
+DEFAULT_POLL_INTERVAL = 2.0
+DEFAULT_MAX_POLL_WAIT = 120.0
+
+
+class Strale:
+    """Strale API client.
+
+    Args:
+        api_key: API key (starts with sk_).
+        base_url: Base URL of the Strale API.
+        default_max_price_cents: Default max_price_cents for do() calls.
+        timeout: HTTP request timeout in seconds. Defaults to 60.
+        poll_interval: Poll interval in seconds for async responses. Defaults to 2.
+        max_poll_wait: Max wait in seconds for async polling. Defaults to 120.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        default_max_price_cents: Optional[int] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        poll_interval: float = DEFAULT_POLL_INTERVAL,
+        max_poll_wait: float = DEFAULT_MAX_POLL_WAIT,
+    ):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._default_max_price_cents = default_max_price_cents
+        self._timeout = timeout
+        self._poll_interval = poll_interval
+        self._max_poll_wait = max_poll_wait
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers={"Authorization": f"Bearer {self._api_key}"},
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "Strale":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # ─── Core: execute a capability ────────────────────────────────────────────
+
+    def do(self, request: DoRequest) -> Union[DoResponse, DryRunResponse]:
+        """Execute a capability.
+
+        If the server returns status "executing" (async), auto-polls until
+        completed or failed.
+        """
+        body: Dict[str, Any] = {
+            "max_price_cents": request.max_price_cents
+            or self._default_max_price_cents,
+        }
+
+        if request.task is not None:
+            body["task"] = request.task
+        if request.capability_slug is not None:
+            body["capability_slug"] = request.capability_slug
+        if request.inputs is not None:
+            body["inputs"] = request.inputs
+        if request.timeout_seconds is not None:
+            body["timeout_seconds"] = request.timeout_seconds
+        if request.dry_run:
+            body["dry_run"] = True
+
+        headers: Dict[str, str] = {}
+        if request.idempotency_key:
+            headers["Idempotency-Key"] = request.idempotency_key
+
+        data = self._request("POST", "/v1/do", json=body, extra_headers=headers)
+
+        # Dry run returns immediately
+        if data.get("dry_run"):
+            return DryRunResponse(
+                dry_run=True,
+                would_execute=data["would_execute"],
+                price_cents=data["price_cents"],
+                wallet_balance_cents=data["wallet_balance_cents"],
+                wallet_sufficient=data["wallet_sufficient"],
+            )
+
+        response = self._parse_do_response(data)
+
+        # If async (status: "executing"), auto-poll until terminal state
+        if response.status == "executing":
+            return self._poll_transaction(response)
+
+        return response
+
+    # ─── Capabilities ──────────────────────────────────────────────────────────
+
+    def capabilities(self) -> List[Capability]:
+        """List all available capabilities."""
+        data = self._request("GET", "/v1/capabilities")
+        return [self._parse_capability(c) for c in data["capabilities"]]
+
+    def capability(self, slug: str) -> Capability:
+        """Get details for a specific capability."""
+        data = self._request("GET", f"/v1/capabilities/{slug}")
+        return self._parse_capability(data)
+
+    # ─── Wallet ────────────────────────────────────────────────────────────────
+
+    def balance(self) -> BalanceResponse:
+        """Get current wallet balance."""
+        data = self._request("GET", "/v1/wallet/balance")
+        return BalanceResponse(
+            balance_cents=data["balance_cents"],
+            currency=data["currency"],
+        )
+
+    # ─── Transactions ──────────────────────────────────────────────────────────
+
+    def transactions(self) -> List[Transaction]:
+        """List recent transactions."""
+        data = self._request("GET", "/v1/transactions")
+        return [
+            Transaction(
+                id=t["id"],
+                status=t["status"],
+                capability_slug=t["capability_slug"],
+                price_cents=t["price_cents"],
+                latency_ms=t["latency_ms"],
+                created_at=t["created_at"],
+                completed_at=t.get("completed_at"),
+            )
+            for t in data["transactions"]
+        ]
+
+    def transaction(self, id: str) -> TransactionDetail:
+        """Get details for a specific transaction."""
+        data = self._request("GET", f"/v1/transactions/{id}")
+        prov = data.get("provenance")
+        return TransactionDetail(
+            id=data["id"],
+            status=data["status"],
+            capability_slug=data["capability_slug"],
+            input=data.get("input", {}),
+            output=data.get("output"),
+            error=data.get("error"),
+            price_cents=data["price_cents"],
+            latency_ms=data["latency_ms"],
+            provenance=Provenance(
+                source=prov["source"], fetched_at=prov["fetched_at"]
+            )
+            if prov
+            else None,
+            created_at=data["created_at"],
+            completed_at=data.get("completed_at"),
+        )
+
+    # ─── Auto-poll for async responses ─────────────────────────────────────────
+
+    def _poll_transaction(self, initial: DoResponse) -> DoResponse:
+        deadline = time.monotonic() + self._max_poll_wait
+        last_status = initial.status
+
+        while time.monotonic() < deadline:
+            time.sleep(self._poll_interval)
+
+            detail = self.transaction(initial.transaction_id)
+
+            if detail.status == "completed":
+                return DoResponse(
+                    transaction_id=detail.id,
+                    status="completed",
+                    capability_used=detail.capability_slug,
+                    price_cents=detail.price_cents,
+                    latency_ms=detail.latency_ms,
+                    wallet_balance_cents=initial.wallet_balance_cents,
+                    output=detail.output or {},
+                    provenance=detail.provenance
+                    or Provenance(source="unknown", fetched_at=""),
+                )
+
+            if detail.status == "failed":
+                raise StraleError(
+                    "execution_failed",
+                    detail.error or "Capability execution failed",
+                    500,
+                    {"transaction_id": detail.id},
+                )
+
+            last_status = detail.status
+
+        raise StraleError(
+            "timeout_exceeded",
+            f"Timed out waiting for transaction {initial.transaction_id} "
+            f"(last status: {last_status})",
+            408,
+            {"transaction_id": initial.transaction_id},
+        )
+
+    # ─── HTTP layer ────────────────────────────────────────────────────────────
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        extra_headers: Optional[Dict[str, str]] = None,
+    ) -> Dict[str, Any]:
+        try:
+            response = self._client.request(
+                method,
+                path,
+                json=json,
+                headers=extra_headers,
+            )
+        except httpx.TimeoutException:
+            raise StraleError(
+                "timeout_exceeded",
+                f"Request timed out after {self._timeout}s",
+                408,
+            )
+        except httpx.HTTPError as e:
+            raise StraleError(
+                "execution_failed",
+                f"Network error: {e}",
+                0,
+            )
+
+        try:
+            data = response.json()
+        except Exception:
+            raise StraleError(
+                "execution_failed",
+                f"Invalid JSON response (HTTP {response.status_code})",
+                response.status_code,
+            )
+
+        if not response.is_success:
+            if isinstance(data, dict) and "error_code" in data:
+                raise create_error(
+                    data["error_code"],
+                    data.get("message", "Unknown error"),
+                    response.status_code,
+                    data.get("details"),
+                )
+            raise StraleError(
+                "execution_failed",
+                f"HTTP {response.status_code}: {data}",
+                response.status_code,
+            )
+
+        return data
+
+    # ─── Parsers ───────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_do_response(data: Dict[str, Any]) -> DoResponse:
+        prov = data.get("provenance")
+        return DoResponse(
+            transaction_id=data["transaction_id"],
+            status=data["status"],
+            capability_used=data.get("capability_used", ""),
+            price_cents=data.get("price_cents", 0),
+            latency_ms=data.get("latency_ms", 0),
+            wallet_balance_cents=data.get("wallet_balance_cents", 0),
+            output=data.get("output", {}),
+            provenance=Provenance(
+                source=prov["source"], fetched_at=prov["fetched_at"]
+            )
+            if prov
+            else Provenance(source="unknown", fetched_at=""),
+        )
+
+    @staticmethod
+    def _parse_capability(data: Dict[str, Any]) -> Capability:
+        return Capability(
+            slug=data["slug"],
+            name=data["name"],
+            description=data["description"],
+            category=data["category"],
+            price_cents=data["price_cents"],
+            input_schema=data.get("input_schema"),
+            output_schema=data.get("output_schema"),
+            avg_latency_ms=data.get("avg_latency_ms", 0),
+            success_rate=data.get("success_rate", 0.0),
+        )

straleio/errors.py

@@ -0,0 +1,95 @@
+"""Error classes for the Strale Python SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class StraleError(Exception):
+    """Base error class for all Strale API errors."""
+
+    def __init__(
+        self,
+        error_code: str,
+        message: str,
+        status_code: int,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message)
+        self.error_code = error_code
+        self.status_code = status_code
+        self.details = details or {}
+
+
+class InsufficientBalanceError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("insufficient_balance", message, 402, details)
+        self.wallet_balance_cents: int = (details or {}).get("wallet_balance_cents", 0)
+        self.required_cents: int = (details or {}).get("required_cents", 0)
+
+
+class NoMatchingCapabilityError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("no_matching_capability", message, 404, details)
+
+
+class CapabilityUnavailableError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("capability_unavailable", message, 503, details)
+
+
+class ExecutionFailedError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("execution_failed", message, 500, details)
+        self.transaction_id: Optional[str] = (details or {}).get("transaction_id")
+
+
+class TimeoutExceededError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("timeout_exceeded", message, 408, details)
+
+
+class InvalidRequestError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("invalid_request", message, 400, details)
+
+
+class RateLimitedError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("rate_limited", message, 429, details)
+
+
+class UnauthorizedError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("unauthorized", message, 401, details)
+
+
+class NotFoundError(StraleError):
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__("not_found", message, 404, details)
+
+
+_ERROR_MAP = {
+    "insufficient_balance": InsufficientBalanceError,
+    "no_matching_capability": NoMatchingCapabilityError,
+    "capability_unavailable": CapabilityUnavailableError,
+    "execution_failed": ExecutionFailedError,
+    "timeout_exceeded": TimeoutExceededError,
+    "invalid_request": InvalidRequestError,
+    "rate_limited": RateLimitedError,
+    "unauthorized": UnauthorizedError,
+    "not_found": NotFoundError,
+}
+
+
+def create_error(
+    error_code: str,
+    message: str,
+    status_code: int,
+    details: Optional[Dict[str, Any]] = None,
+) -> StraleError:
+    """Create a typed error from an API error response."""
+    cls = _ERROR_MAP.get(error_code, StraleError)
+    if cls is StraleError:
+        return StraleError(error_code, message, status_code, details)
+    return cls(message, details)

straleio/types.py

@@ -0,0 +1,118 @@
+"""Type definitions for the Strale Python SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional
+
+
+@dataclass
+class DoRequest:
+    """Request payload for POST /v1/do."""
+
+    max_price_cents: int
+    """Maximum price in EUR cents you're willing to pay."""
+
+    task: Optional[str] = None
+    """Natural language description of what you need done."""
+
+    capability_slug: Optional[str] = None
+    """Direct capability slug override (bypasses matching)."""
+
+    inputs: Optional[Dict[str, Any]] = None
+    """Structured input for the capability."""
+
+    timeout_seconds: Optional[int] = None
+    """Execution timeout in seconds (max 60)."""
+
+    dry_run: bool = False
+    """If True, returns what would execute without charging."""
+
+    idempotency_key: Optional[str] = None
+    """Idempotency key for safe retries."""
+
+
+@dataclass
+class Provenance:
+    """Provenance metadata for a capability execution."""
+
+    source: str
+    fetched_at: str
+
+
+@dataclass
+class DoResponse:
+    """Response from POST /v1/do (completed or executing)."""
+
+    transaction_id: str
+    status: str
+    capability_used: str
+    price_cents: int
+    latency_ms: int
+    wallet_balance_cents: int
+    output: Dict[str, Any]
+    provenance: Provenance
+
+
+@dataclass
+class DryRunResponse:
+    """Response from POST /v1/do with dry_run=True."""
+
+    dry_run: bool
+    would_execute: str
+    price_cents: int
+    wallet_balance_cents: int
+    wallet_sufficient: bool
+
+
+@dataclass
+class Capability:
+    """A capability available on the Strale platform."""
+
+    slug: str
+    name: str
+    description: str
+    category: str
+    price_cents: int
+    input_schema: Any
+    output_schema: Any
+    avg_latency_ms: int
+    success_rate: float
+
+
+@dataclass
+class BalanceResponse:
+    """Wallet balance response."""
+
+    balance_cents: int
+    currency: str
+
+
+@dataclass
+class Transaction:
+    """Transaction summary from list endpoint."""
+
+    id: str
+    status: str
+    capability_slug: str
+    price_cents: int
+    latency_ms: int
+    created_at: str
+    completed_at: Optional[str]
+
+
+@dataclass
+class TransactionDetail:
+    """Full transaction detail."""
+
+    id: str
+    status: str
+    capability_slug: str
+    input: Dict[str, Any]
+    output: Optional[Dict[str, Any]]
+    error: Optional[str]
+    price_cents: int
+    latency_ms: int
+    provenance: Optional[Provenance]
+    created_at: str
+    completed_at: Optional[str]

straleio-0.1.0.dist-info/METADATA

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: straleio
+Version: 0.1.0
+Summary: Python SDK for the Strale API — let AI agents buy capabilities at runtime
+License: MIT
+Project-URL: Homepage, https://strale.io
+Project-URL: Repository, https://github.com/petter_lindstrom/strale
+Keywords: strale,ai,agent,capabilities,api,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.24.0

straleio-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+straleio/__init__.py,sha256=NPUkHpRhvZ80M7ZUaGSJscxxdXbrD0LFcT_QZdCKLSI,1062
+straleio/client.py,sha256=S_hksPH4g3xdsoMLWbdHqTWfAfFu9-XEgkr4Ns5wAZE,11506
+straleio/errors.py,sha256=ih9lcomtC0fw2iirJ2qiknvG0pWZBDYjwrxY3bSpR2w,3302
+straleio/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+straleio/types.py,sha256=e6KmjcGwwxHUG4OIhkYxgk0BAnI-fbE2V_SdGoQo-44,2481
+straleio-0.1.0.dist-info/METADATA,sha256=Z-Mk-NebyMUlKcOUL5onUeLIv4shSJvsUw3zXkIL1eI,863
+straleio-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+straleio-0.1.0.dist-info/top_level.txt,sha256=eg29jWr-cP60VBezo-hzPrt9wKWiELqIommJfmSTuGM,9
+straleio-0.1.0.dist-info/RECORD,,

straleio-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

straleio-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+straleio