steerplane 0.1.0__tar.gz

steerplane-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: steerplane
+Version: 0.1.0
+Summary: Agent Control Plane for Autonomous Systems
+Home-page: https://github.com/vijaym2k6/SteerPlane
+Author: SteerPlane
+Author-email: SteerPlane <hello@steerplane.ai>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: requires-python
+
+# SteerPlane SDK
+
+**Agent Control Plane for Autonomous Systems**
+
+> "Agents don't fail in the dark anymore."
+
+## Quick Start
+
+```bash
+pip install steerplane
+```
+
+### Decorator API (Minimal Integration)
+
+```python
+from steerplane import guard
+
+@guard(max_cost_usd=10, max_steps=50)
+def run_agent():
+    agent.run()
+```
+
+### Context Manager API (Full Control)
+
+```python
+from steerplane import SteerPlane
+
+sp = SteerPlane(agent_id="my_bot")
+
+with sp.run(max_cost_usd=10) as run:
+    run.log_step("query_db", tokens=380, cost=0.002)
+    run.log_step("generate_response", tokens=1240, cost=0.008)
+```
+
+## Features
+
+- 🔄 **Loop Detection** — Automatically detects repeating agent behavior
+- 💰 **Cost Limits** — Stop expensive agent runs before they blow budgets
+- 🚫 **Step Limits** — Prevent runaway execution
+- 📊 **Telemetry** — Full step-by-step execution tracking
+- 🖥️ **Dashboard** — Visual execution monitoring
+
+## Documentation
+
+See [docs.steerplane.ai](https://docs.steerplane.ai) for full documentation.

steerplane-0.1.0/README.md

@@ -0,0 +1,45 @@
+# SteerPlane SDK
+
+**Agent Control Plane for Autonomous Systems**
+
+> "Agents don't fail in the dark anymore."
+
+## Quick Start
+
+```bash
+pip install steerplane
+```
+
+### Decorator API (Minimal Integration)
+
+```python
+from steerplane import guard
+
+@guard(max_cost_usd=10, max_steps=50)
+def run_agent():
+    agent.run()
+```
+
+### Context Manager API (Full Control)
+
+```python
+from steerplane import SteerPlane
+
+sp = SteerPlane(agent_id="my_bot")
+
+with sp.run(max_cost_usd=10) as run:
+    run.log_step("query_db", tokens=380, cost=0.002)
+    run.log_step("generate_response", tokens=1240, cost=0.008)
+```
+
+## Features
+
+- 🔄 **Loop Detection** — Automatically detects repeating agent behavior
+- 💰 **Cost Limits** — Stop expensive agent runs before they blow budgets
+- 🚫 **Step Limits** — Prevent runaway execution
+- 📊 **Telemetry** — Full step-by-step execution tracking
+- 🖥️ **Dashboard** — Visual execution monitoring
+
+## Documentation
+
+See [docs.steerplane.ai](https://docs.steerplane.ai) for full documentation.

steerplane-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=65.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "steerplane"
+version = "0.1.0"
+description = "Agent Control Plane for Autonomous Systems"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "SteerPlane", email = "hello@steerplane.ai"}
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

steerplane-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

steerplane-0.1.0/setup.py

@@ -0,0 +1,41 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="steerplane",
+    version="0.1.0",
+    description="Agent Control Plane for Autonomous Systems — Runtime guards, loop detection, cost limits, and telemetry for AI agents.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="SteerPlane",
+    author_email="hello@steerplane.ai",
+    url="https://github.com/vijaym2k6/SteerPlane",
+    project_urls={
+        "Homepage": "https://steerplane.ai",
+        "Documentation": "https://docs.steerplane.ai",
+        "Repository": "https://github.com/vijaym2k6/SteerPlane",
+        "Issues": "https://github.com/vijaym2k6/SteerPlane/issues",
+    },
+    packages=find_packages(),
+    python_requires=">=3.10",
+    install_requires=[
+        "requests>=2.28.0",
+    ],
+    extras_require={
+        "dev": [
+            "pytest>=7.0",
+            "pytest-cov",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "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",
+        "Topic :: Software Development :: Libraries",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+    keywords="ai agents guard safety monitoring telemetry llm",
+)

steerplane-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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}"
+        )