steerplane 0.1.0__py3-none-any.whl

steerplane/__init__.py

@@ -0,0 +1,69 @@
+"""
+SteerPlane SDK
+
+Agent Control Plane for Autonomous Systems.
+"Agents don't fail in the dark anymore."
+
+Usage:
+    from steerplane import guard, SteerPlane
+
+    # Decorator API (minimal integration)
+    @guard(max_cost_usd=10, max_steps=50)
+    def run_agent():
+        agent.run()
+
+    # Context Manager API (full control)
+    sp = SteerPlane(agent_id="my_bot")
+    with sp.run(max_cost_usd=10) as run:
+        run.log_step("search", tokens=100)
+
+    # Programmatic API
+    sp = SteerPlane(agent_id="my_bot")
+    run = sp.create_run(max_cost_usd=10)
+    run.start()
+    run.log_step("search", tokens=100)
+    run.end()
+"""
+
+__version__ = "0.1.0"
+
+from .guard import guard, SteerPlane, get_active_run
+from .run_manager import RunManager
+from .loop_detector import LoopDetector, detect_loop
+from .cost_tracker import CostTracker
+from .telemetry import TelemetryCollector, StepEvent
+from .config import configure, get_config
+from .exceptions import (
+    SteerPlaneError,
+    LoopDetectedError,
+    CostLimitExceeded,
+    StepLimitExceeded,
+    RunTerminatedError,
+    APIConnectionError,
+)
+
+__all__ = [
+    # Main APIs
+    "guard",
+    "SteerPlane",
+    "get_active_run",
+    # Core classes
+    "RunManager",
+    "LoopDetector",
+    "CostTracker",
+    "TelemetryCollector",
+    "StepEvent",
+    # Utilities
+    "detect_loop",
+    "configure",
+    "get_config",
+    # Exceptions
+    "SteerPlaneError",
+    "LoopDetectedError",
+    "CostLimitExceeded",
+    "StepLimitExceeded",
+    "RunTerminatedError",
+    "APIConnectionError",
+    # Metadata
+    "__version__",
+]

steerplane/client.py

@@ -0,0 +1,129 @@
+"""
+SteerPlane SDK — API Client
+
+HTTP client that communicates with the SteerPlane API server.
+Handles run lifecycle: start → log steps → end.
+"""
+
+import requests
+import logging
+from typing import Any
+
+from .config import get_config
+from .exceptions import APIConnectionError
+
+logger = logging.getLogger("steerplane")
+
+
+class SteerPlaneClient:
+    """
+    HTTP client for the SteerPlane API.
+    
+    Sends run events, step telemetry, and receives commands.
+    Gracefully degrades if API is unavailable (SDK still works locally).
+    """
+
+    def __init__(self, api_url: str | None = None, api_key: str | None = None):
+        config = get_config()
+        self.api_url = (api_url or config.api_url).rstrip("/")
+        self.api_key = api_key or config.api_key
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "User-Agent": "SteerPlane-SDK/0.1.0",
+        })
+        if self.api_key:
+            self.session.headers["Authorization"] = f"Bearer {self.api_key}"
+
+        self._api_available = True
+
+    def _request(self, method: str, path: str, **kwargs) -> dict | None:
+        """Make an HTTP request to the API. Returns None if API unavailable."""
+        if not self._api_available:
+            return None
+
+        url = f"{self.api_url}{path}"
+        try:
+            response = self.session.request(method, url, timeout=5, **kwargs)
+            response.raise_for_status()
+            return response.json()
+        except requests.ConnectionError:
+            self._api_available = False
+            logger.warning(
+                f"⚠️  SteerPlane API not reachable at {self.api_url}. "
+                f"Running in offline mode (guards still active, no dashboard data)."
+            )
+            return None
+        except requests.RequestException as e:
+            logger.warning(f"⚠️  API request failed: {e}")
+            return None
+
+    def start_run(
+        self,
+        run_id: str,
+        agent_name: str,
+        max_cost_usd: float = 0,
+        max_steps: int = 0,
+    ) -> dict | None:
+        """Register a new run with the API."""
+        return self._request("POST", "/runs/start", json={
+            "run_id": run_id,
+            "agent_name": agent_name,
+            "max_cost_usd": max_cost_usd,
+            "max_steps": max_steps,
+        })
+
+    def log_step(
+        self,
+        run_id: str,
+        step_number: int,
+        action: str,
+        tokens: int = 0,
+        cost_usd: float = 0.0,
+        latency_ms: float = 0.0,
+        status: str = "completed",
+        error: str | None = None,
+        metadata: dict | None = None,
+    ) -> dict | None:
+        """Log a step event to the API."""
+        return self._request("POST", "/runs/step", json={
+            "run_id": run_id,
+            "step_number": step_number,
+            "action": action,
+            "tokens": tokens,
+            "cost_usd": cost_usd,
+            "latency_ms": latency_ms,
+            "status": status,
+            "error": error,
+            "metadata": metadata or {},
+        })
+
+    def end_run(
+        self,
+        run_id: str,
+        status: str = "completed",
+        total_cost: float = 0.0,
+        total_steps: int = 0,
+        error: str | None = None,
+    ) -> dict | None:
+        """Finalize a run."""
+        return self._request("POST", "/runs/end", json={
+            "run_id": run_id,
+            "status": status,
+            "total_cost": total_cost,
+            "total_steps": total_steps,
+            "error": error,
+        })
+
+    def get_run(self, run_id: str) -> dict | None:
+        """Fetch run details."""
+        return self._request("GET", f"/runs/{run_id}")
+
+    def list_runs(self, limit: int = 50, offset: int = 0) -> dict | None:
+        """List recent runs."""
+        return self._request("GET", f"/runs?limit={limit}&offset={offset}")
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if API is reachable."""
+        return self._api_available

steerplane/config.py

@@ -0,0 +1,49 @@
+"""
+SteerPlane SDK — Configuration
+
+Default settings and environment variable overrides.
+"""
+
+import os
+
+
+class SteerPlaneConfig:
+    """SDK configuration with environment variable overrides."""
+
+    def __init__(
+        self,
+        api_url: str | None = None,
+        api_key: str | None = None,
+        agent_id: str | None = None,
+        default_max_cost_usd: float = 50.0,
+        default_max_steps: int = 200,
+        default_max_runtime_sec: int = 3600,
+        loop_window_size: int = 8,
+        enable_telemetry: bool = True,
+        log_to_console: bool = True,
+    ):
+        self.api_url = api_url or os.getenv("STEERPLANE_API_URL", "http://localhost:8000")
+        self.api_key = api_key or os.getenv("STEERPLANE_API_KEY", "")
+        self.agent_id = agent_id or os.getenv("STEERPLANE_AGENT_ID", "default_agent")
+        self.default_max_cost_usd = default_max_cost_usd
+        self.default_max_steps = default_max_steps
+        self.default_max_runtime_sec = default_max_runtime_sec
+        self.loop_window_size = loop_window_size
+        self.enable_telemetry = enable_telemetry
+        self.log_to_console = log_to_console
+
+
+# Global default config (can be overridden)
+_config = SteerPlaneConfig()
+
+
+def get_config() -> SteerPlaneConfig:
+    """Get the current global configuration."""
+    return _config
+
+
+def configure(**kwargs) -> SteerPlaneConfig:
+    """Update global SDK configuration."""
+    global _config
+    _config = SteerPlaneConfig(**kwargs)
+    return _config

steerplane/cost_tracker.py

@@ -0,0 +1,171 @@
+"""
+SteerPlane SDK — Cost Tracker
+
+Tracks cumulative token usage and cost per run.
+Enforces cost limits and projects final cost.
+"""
+
+from dataclasses import dataclass, field
+from .exceptions import CostLimitExceeded
+
+
+# Default pricing per token (can be overridden per model)
+DEFAULT_PRICING = {
+    "gpt-4o": {"input": 0.0000025, "output": 0.000010},
+    "gpt-4o-mini": {"input": 0.00000015, "output": 0.0000006},
+    "gpt-4": {"input": 0.00003, "output": 0.00006},
+    "gpt-3.5-turbo": {"input": 0.0000005, "output": 0.0000015},
+    "claude-3-opus": {"input": 0.000015, "output": 0.000075},
+    "claude-3-sonnet": {"input": 0.000003, "output": 0.000015},
+    "claude-3-haiku": {"input": 0.00000025, "output": 0.00000125},
+    "gemini-pro": {"input": 0.00000025, "output": 0.0000005},
+    "default": {"input": 0.000002, "output": 0.000002},
+}
+
+
+@dataclass
+class StepCost:
+    """Cost breakdown for a single step."""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    total_tokens: int = 0
+    cost_usd: float = 0.0
+    model: str = "default"
+
+
+@dataclass
+class CostSummary:
+    """Cumulative cost summary for an entire run."""
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    total_tokens: int = 0
+    total_cost_usd: float = 0.0
+    step_costs: list[StepCost] = field(default_factory=list)
+    projected_final_cost: float = 0.0
+
+
+class CostTracker:
+    """
+    Tracks cumulative cost across an agent run.
+    
+    Enforces cost limits and provides real-time cost projection.
+    """
+
+    def __init__(self, max_cost_usd: float = 50.0, model: str = "default"):
+        """
+        Args:
+            max_cost_usd: Maximum allowed cost before termination.
+            model: Default model name for pricing lookup.
+        """
+        self.max_cost_usd = max_cost_usd
+        self.model = model
+        self.total_cost: float = 0.0
+        self.total_tokens: int = 0
+        self.total_input_tokens: int = 0
+        self.total_output_tokens: int = 0
+        self.step_costs: list[StepCost] = []
+
+    def calculate_step_cost(
+        self,
+        input_tokens: int = 0,
+        output_tokens: int = 0,
+        total_tokens: int = 0,
+        model: str | None = None,
+        cost_override: float | None = None,
+    ) -> StepCost:
+        """
+        Calculate cost for a single step.
+        
+        Args:
+            input_tokens: Number of input/prompt tokens.
+            output_tokens: Number of output/completion tokens.
+            total_tokens: Total tokens (used if input/output not split).
+            model: Model name for pricing (overrides default).
+            cost_override: Directly specify cost (skips calculation).
+            
+        Returns:
+            StepCost with the calculated cost.
+        """
+        use_model = model or self.model
+        pricing = DEFAULT_PRICING.get(use_model, DEFAULT_PRICING["default"])
+
+        if cost_override is not None:
+            cost = cost_override
+        elif input_tokens > 0 or output_tokens > 0:
+            cost = (input_tokens * pricing["input"]) + (output_tokens * pricing["output"])
+            total_tokens = input_tokens + output_tokens
+        elif total_tokens > 0:
+            # If no split, assume 50/50 input/output
+            avg_price = (pricing["input"] + pricing["output"]) / 2
+            cost = total_tokens * avg_price
+        else:
+            cost = 0.0
+
+        step_cost = StepCost(
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            total_tokens=total_tokens,
+            cost_usd=cost,
+            model=use_model,
+        )
+        return step_cost
+
+    def add_step(self, step_cost: StepCost) -> float:
+        """
+        Add a step's cost to the running total and enforce limits.
+        
+        Args:
+            step_cost: The StepCost to add.
+            
+        Returns:
+            The new cumulative cost.
+            
+        Raises:
+            CostLimitExceeded: If cost exceeds the configured limit.
+        """
+        self.total_cost += step_cost.cost_usd
+        self.total_tokens += step_cost.total_tokens
+        self.total_input_tokens += step_cost.input_tokens
+        self.total_output_tokens += step_cost.output_tokens
+        self.step_costs.append(step_cost)
+
+        if self.total_cost > self.max_cost_usd:
+            raise CostLimitExceeded(self.total_cost, self.max_cost_usd)
+
+        return self.total_cost
+
+    def project_final_cost(
+        self, steps_completed: int, expected_total_steps: int
+    ) -> float:
+        """
+        Project the final cost based on current spending rate.
+        
+        Args:
+            steps_completed: Number of steps completed so far.
+            expected_total_steps: Expected total number of steps.
+            
+        Returns:
+            Projected final cost in USD.
+        """
+        if steps_completed <= 0:
+            return 0.0
+        projected = self.total_cost * (expected_total_steps / steps_completed)
+        return projected
+
+    def get_summary(self) -> CostSummary:
+        """Get the current cost summary."""
+        return CostSummary(
+            total_input_tokens=self.total_input_tokens,
+            total_output_tokens=self.total_output_tokens,
+            total_tokens=self.total_tokens,
+            total_cost_usd=self.total_cost,
+            step_costs=list(self.step_costs),
+        )
+
+    def reset(self):
+        """Reset all tracking."""
+        self.total_cost = 0.0
+        self.total_tokens = 0
+        self.total_input_tokens = 0
+        self.total_output_tokens = 0
+        self.step_costs.clear()

steerplane/exceptions.py

@@ -0,0 +1,68 @@
+"""
+SteerPlane SDK — Custom Exceptions
+
+All errors raised by the SteerPlane guard system.
+"""
+
+
+class SteerPlaneError(Exception):
+    """Base exception for all SteerPlane errors."""
+    pass
+
+
+class LoopDetectedError(SteerPlaneError):
+    """Raised when a repeating action pattern is detected."""
+
+    def __init__(self, pattern: list, window_size: int):
+        self.pattern = pattern
+        self.window_size = window_size
+        super().__init__(
+            f"🔄 Loop detected! Repeating pattern {pattern} "
+            f"found in last {window_size} actions. Run terminated."
+        )
+
+
+class CostLimitExceeded(SteerPlaneError):
+    """Raised when cumulative run cost exceeds the configured limit."""
+
+    def __init__(self, current_cost: float, max_cost: float):
+        self.current_cost = current_cost
+        self.max_cost = max_cost
+        super().__init__(
+            f"💰 Cost limit exceeded! Current: ${current_cost:.4f}, "
+            f"Limit: ${max_cost:.2f}. Run terminated."
+        )
+
+
+class StepLimitExceeded(SteerPlaneError):
+    """Raised when the number of steps exceeds the configured limit."""
+
+    def __init__(self, current_steps: int, max_steps: int):
+        self.current_steps = current_steps
+        self.max_steps = max_steps
+        super().__init__(
+            f"🚫 Step limit exceeded! Steps: {current_steps}, "
+            f"Limit: {max_steps}. Run terminated."
+        )
+
+
+class RunTerminatedError(SteerPlaneError):
+    """Raised when a run is forcefully terminated."""
+
+    def __init__(self, run_id: str, reason: str = "Manual termination"):
+        self.run_id = run_id
+        self.reason = reason
+        super().__init__(
+            f"⛔ Run {run_id} terminated. Reason: {reason}"
+        )
+
+
+class APIConnectionError(SteerPlaneError):
+    """Raised when the SDK cannot connect to the SteerPlane API."""
+
+    def __init__(self, url: str, detail: str = ""):
+        self.url = url
+        self.detail = detail
+        super().__init__(
+            f"🔌 Cannot connect to SteerPlane API at {url}. {detail}"
+        )

steerplane/guard.py

@@ -0,0 +1,179 @@
+"""
+SteerPlane SDK — Guard Decorator
+
+The primary developer-facing API. Wrap any agent function with @guard
+to get automatic loop detection, cost limits, step limits, and telemetry.
+
+Usage:
+    from steerplane import guard
+
+    @guard(max_cost_usd=10, max_steps=50)
+    def run_agent():
+        agent.run()
+"""
+
+import functools
+import logging
+from typing import Callable, Any
+
+from .run_manager import RunManager
+from .config import get_config
+
+logger = logging.getLogger("steerplane")
+
+
+# Thread-local storage for the active run manager
+_active_run: RunManager | None = None
+
+
+def get_active_run() -> RunManager | None:
+    """Get the currently active RunManager (if inside a guarded function)."""
+    return _active_run
+
+
+def guard(
+    max_cost_usd: float = 50.0,
+    max_steps: int = 200,
+    max_runtime_sec: int = 3600,
+    agent_name: str | None = None,
+    model: str = "default",
+    loop_window_size: int = 8,
+    log_to_console: bool = True,
+    api_url: str | None = None,
+    api_key: str | None = None,
+) -> Callable:
+    """
+    Guard decorator for agent functions.
+    
+    Wraps an agent function with SteerPlane's guard system:
+    - Loop detection (sliding window)
+    - Cost limit enforcement
+    - Step limit enforcement
+    - Runtime limit enforcement
+    - Full telemetry logging
+    
+    Args:
+        max_cost_usd: Maximum allowed cost in USD.
+        max_steps: Maximum number of steps allowed.
+        max_runtime_sec: Maximum runtime in seconds.
+        agent_name: Name of the agent (defaults to function name).
+        model: Default model for cost calculation.
+        loop_window_size: Window size for loop detection.
+        log_to_console: Whether to print step logs to console.
+        api_url: SteerPlane API URL (overrides config).
+        api_key: API key (overrides config).
+        
+    Returns:
+        Decorated function with guard capabilities.
+        
+    Example:
+        @guard(max_cost_usd=10, max_steps=50)
+        def run_my_agent():
+            # The agent's run manager is available via steerplane.get_active_run()
+            agent.run()
+    """
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            global _active_run
+
+            name = agent_name or func.__name__
+
+            # Create run manager with guard configuration
+            run = RunManager(
+                agent_name=name,
+                max_cost_usd=max_cost_usd,
+                max_steps=max_steps,
+                max_runtime_sec=max_runtime_sec,
+                loop_window_size=loop_window_size,
+                model=model,
+                api_url=api_url,
+                api_key=api_key,
+                log_to_console=log_to_console,
+            )
+
+            # Set as active run
+            _active_run = run
+
+            try:
+                run.start()
+                result = func(*args, **kwargs)
+                run.end(status="completed")
+                return result
+            except Exception as e:
+                run.end(status="failed", error=str(e))
+                raise
+            finally:
+                _active_run = None
+
+        # Attach run manager accessor to the wrapper
+        wrapper._steerplane_guarded = True
+        return wrapper
+
+    return decorator
+
+
+class SteerPlane:
+    """
+    Main SDK entry point for programmatic usage.
+    
+    Provides both context manager and explicit API for run management.
+    
+    Usage (context manager):
+        sp = SteerPlane(agent_id="my_bot")
+        with sp.run() as run:
+            run.log_step("query_db", tokens=380, cost=0.002)
+            run.log_step("generate_response", tokens=1240, cost=0.008)
+    
+    Usage (explicit):
+        sp = SteerPlane(agent_id="my_bot")
+        run = sp.create_run(max_cost_usd=10)
+        run.start()
+        run.log_step("search", tokens=100)
+        run.end()
+    """
+
+    def __init__(
+        self,
+        agent_id: str = "default_agent",
+        api_url: str | None = None,
+        api_key: str | None = None,
+        model: str = "default",
+    ):
+        self.agent_id = agent_id
+        self.api_url = api_url
+        self.api_key = api_key
+        self.model = model
+
+    def run(
+        self,
+        run_id: str | None = None,
+        max_cost_usd: float = 50.0,
+        max_steps: int = 200,
+        max_runtime_sec: int = 3600,
+        loop_window_size: int = 8,
+        log_to_console: bool = True,
+    ) -> RunManager:
+        """
+        Create a new run context manager.
+        
+        Usage:
+            with sp.run(max_cost_usd=10) as run:
+                run.log_step("action", tokens=100)
+        """
+        return RunManager(
+            agent_name=self.agent_id,
+            run_id=run_id,
+            max_cost_usd=max_cost_usd,
+            max_steps=max_steps,
+            max_runtime_sec=max_runtime_sec,
+            loop_window_size=loop_window_size,
+            model=self.model,
+            api_url=self.api_url,
+            api_key=self.api_key,
+            log_to_console=log_to_console,
+        )
+
+    def create_run(self, **kwargs) -> RunManager:
+        """Create a run without starting it (for explicit management)."""
+        return self.run(**kwargs)