agentfences 0.1.0__py3-none-any.whl

agentfences-0.1.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: agentfences
+Version: 0.1.0
+Summary: Runtime governance for AI agents — budget limits, loop protection, token limits, audit trail
+Home-page: https://github.com/bhaviksardar/fences
+Author: Bhavik Sardar
+Keywords: ai,agents,governance,llm,budget,safety,token
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# Fences
+
+Runtime governance for AI agents. Give any agent budget limits, loop protection, and a decision audit trail in three lines of code.
+
+```python
+import fences
+fences.init(local_only=True)
+
+@fences.governed(budget_usd=0.50, max_iterations=20, max_duration_ms=60_000)
+async def run_agent(query: str):
+    response = call_llm(query)
+    fences.log_decision(reasoning="searching for sources", action="web_search")
+    await fences.checkpoint(cost_delta_usd=compute_cost(response))
+    return response
+```
+
+If the agent exceeds its budget, loops past the iteration limit, or runs too long, `checkpoint()` raises and execution stops immediately.
+
+## Install
+
+```bash
+pip install fences
+```
+
+## Quickstart — no backend needed
+
+```python
+import fences
+from fences import governed, checkpoint, log_decision
+from fences import BudgetExceeded, IterationLimitReached
+
+fences.init(local_only=True)
+
+@governed(budget_usd=0.10, max_iterations=10)
+async def my_agent(query: str):
+    for step in range(100):
+        log_decision(reasoning=f"step {step}: searching", action="search")
+        await checkpoint(cost_delta_usd=0.01)
+    return "done"
+```
+
+## What gets enforced
+
+| Limit | Parameter | Raises |
+|---|---|---|
+| Spend | `budget_usd` | `BudgetExceeded` |
+| Iterations | `max_iterations` | `IterationLimitReached` |
+| Duration | `max_duration_ms` | `TimeLimitReached` |
+
+## Handling breaches
+
+```python
+from fences import BudgetExceeded, IterationLimitReached, TimeLimitReached
+
+try:
+    result = await my_agent("research this topic")
+except BudgetExceeded as e:
+    print(f"Stopped: spent ${e.spent_usd:.4f} of ${e.budget_usd:.4f}")
+except IterationLimitReached as e:
+    print(f"Stopped: {e.iterations} iterations reached")
+except TimeLimitReached as e:
+    print(f"Stopped: ran for {e.duration_ms}ms")
+```
+
+## Cloud mode
+
+Connect to a Fences backend for persistent audit trails, a dashboard, and server-authoritative enforcement across distributed agents.
+
+```python
+fences.init(api_key="fc_...", endpoint="https://your-fences-instance.com")
+```
+
+Everything else stays the same — same decorator, same `checkpoint()` calls.
+
+## License
+
+MIT

agentfences-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+fences/__init__.py,sha256=qQg57Xvqjr3Kni_MIpHrXj74gUR-cq6KoxbvfAuOJok,376
+fences/client.py,sha256=eR9xjN42xeOPlJwp1x6XYLy4dV_SIGKQyuCVv38Ewbg,2242
+fences/core.py,sha256=Jk09NrxLLPr_LfXkK2_aOMLtrliBNyjgcGcK5gJd5eI,8077
+fences/exceptions.py,sha256=5nn8VgqYso7hxODr9Eebrp8HGbw_aUb1JfKBZdpz7Qo,1249
+agentfences-0.1.0.dist-info/METADATA,sha256=jag8Y93jLhsZaBj4kg68xEf_Vm_Bb0lrW5D32rC_iFw,2941
+agentfences-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+agentfences-0.1.0.dist-info/top_level.txt,sha256=uwq9QgEQVJftVRH4_d3gzxYkOSWL0Vb_D4CImXVrPCI,7
+agentfences-0.1.0.dist-info/RECORD,,

agentfences-0.1.0.dist-info/WHEEL

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

agentfences-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fences

fences/__init__.py

@@ -0,0 +1,7 @@
+from .core import init, governed, checkpoint, log_decision, get_active_run
+from .exceptions import FencesError, BudgetExceeded, IterationLimitReached, TimeLimitReached, TokenLimitReached
+
+__all__ = [
+    "init", "governed", "checkpoint", "log_decision", "get_active_run",
+    "FencesError", "BudgetExceeded", "IterationLimitReached", "TimeLimitReached", "TokenLimitReached",
+]

fences/client.py

@@ -0,0 +1,60 @@
+import requests
+from typing import Optional
+
+
+class GovClient:
+    def __init__(self, api_key: str, endpoint: str, timeout: float = 3.0):
+        self.api_key = api_key
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+
+    def start_run(self, run_id: str, agent_name: str, budget_usd: float, max_iterations: int, max_duration_ms: int, max_tokens: int) -> dict:
+        return self._post("/api/runs/start", {
+            "run_id": run_id,
+            "agent_name": agent_name,
+            "budget_usd": budget_usd,
+            "max_iterations": max_iterations,
+            "max_duration_ms": max_duration_ms,
+            "max_tokens": max_tokens,
+        })
+
+    def checkpoint(self, run_id: str, cost_delta_usd: float, iterations: int, duration_ms: int, tokens_used: int) -> dict:
+        return self._post(f"/api/runs/{run_id}/checkpoint", {
+            "cost_delta_usd": cost_delta_usd,
+            "iterations": iterations,
+            "duration_ms": duration_ms,
+            "tokens_used": tokens_used,
+        })
+
+    def log_decision(self, run_id: str, iteration: int, reasoning: str, action: Optional[str]) -> dict:
+        try:
+            return self._post(f"/api/runs/{run_id}/decisions", {
+                "iteration": iteration,
+                "reasoning": reasoning,
+                "action": action,
+            })
+        except Exception:
+            return {}
+
+    def end_run(self, run_id: str, status: str, error: Optional[str] = None) -> dict:
+        return self._post(f"/api/runs/{run_id}/end", {
+            "status": status,
+            "error": error,
+        })
+
+    def _post(self, path: str, payload: dict) -> dict:
+        try:
+            resp = requests.post(
+                f"{self.endpoint}{path}",
+                json=payload,
+                headers={"X-API-Key": self.api_key},
+                timeout=self.timeout,
+            )
+            if resp.status_code in (401, 403):
+                raise PermissionError(f"Fences API key rejected: {resp.text}")
+            resp.raise_for_status()
+            return resp.json()
+        except PermissionError:
+            raise
+        except requests.RequestException as e:
+            return {"ok": True, "network_error": str(e)}

fences/core.py

@@ -0,0 +1,267 @@
+import time
+import uuid
+import asyncio
+import functools
+import threading
+from dataclasses import dataclass, field
+from typing import Optional, Callable
+
+from .exceptions import BudgetExceeded, IterationLimitReached, TimeLimitReached, TokenLimitReached
+from .client import GovClient
+
+_local = threading.local()
+
+
+@dataclass
+class RunState:
+    run_id: str
+    agent_name: str
+    budget_usd: float
+    max_iterations: int
+    max_duration_ms: int
+    max_tokens: int
+    cost_usd: float = 0.0
+    iterations: int = 0
+    tokens_used: int = 0
+    started_at: float = field(default_factory=time.time)
+    decisions: list = field(default_factory=list)
+
+    @property
+    def duration_ms(self) -> int:
+        return int((time.time() - self.started_at) * 1000)
+
+
+def get_active_run() -> Optional[RunState]:
+    return getattr(_local, "run", None)
+
+
+def _set_active_run(run: Optional[RunState]):
+    _local.run = run
+
+
+_client: Optional[GovClient] = None
+_local_only: bool = False
+
+
+def init(
+    api_key: Optional[str] = None,
+    endpoint: str = "http://localhost:8000",
+    local_only: bool = False,
+):
+    """
+    Initialize Fences. Call once at startup before using @governed.
+
+    Local mode — no backend required:
+        fences.init(local_only=True)
+
+    Cloud mode — connects to a Fences backend:
+        fences.init(api_key="fc_...", endpoint="https://...")
+    """
+    global _client, _local_only
+    _local_only = local_only
+
+    if local_only:
+        _client = None
+        return
+
+    if not api_key:
+        raise ValueError(
+            "api_key is required unless local_only=True. "
+            "Use fences.init(local_only=True) for local usage."
+        )
+    _client = GovClient(api_key=api_key, endpoint=endpoint)
+
+
+def _get_client() -> Optional[GovClient]:
+    return _client
+
+
+def _require_init():
+    if not _local_only and _client is None:
+        raise RuntimeError(
+            "Call fences.init() before using Fences. "
+            "For local usage: fences.init(local_only=True)"
+        )
+
+
+def governed(
+    budget_usd: float,
+    max_iterations: int = 100,
+    max_duration_ms: int = 300_000,
+    max_tokens: int = 0,
+):
+    """
+    Decorator that applies governance policy to an agent function.
+
+    Args:
+        budget_usd: Maximum spend allowed for this run in USD.
+        max_iterations: Maximum number of checkpoint() calls allowed.
+        max_duration_ms: Maximum wall-clock duration in milliseconds.
+        max_tokens: Maximum total tokens (input + output) allowed. 0 = no limit.
+
+    Raises BudgetExceeded, IterationLimitReached, TimeLimitReached, or
+    TokenLimitReached when limits are crossed.
+
+    Usage:
+        @fences.governed(budget_usd=0.50, max_iterations=20, max_tokens=50000)
+        async def run_agent(query: str):
+            response = call_llm(query)
+            await fences.checkpoint(
+                cost_delta_usd=0.02,
+                tokens_used=response.usage.total_tokens,
+            )
+            return response
+    """
+    def decorator(func: Callable) -> Callable:
+        is_async = asyncio.iscoroutinefunction(func)
+
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            _require_init()
+            run = _start_run(func.__name__, budget_usd, max_iterations, max_duration_ms, max_tokens)
+            _set_active_run(run)
+            try:
+                result = await func(*args, **kwargs)
+                _end_run(run, status="success")
+                return result
+            except (BudgetExceeded, IterationLimitReached, TimeLimitReached, TokenLimitReached):
+                _end_run(run, status="breached")
+                raise
+            except Exception as e:
+                _end_run(run, status="error", error=str(e))
+                raise
+            finally:
+                _set_active_run(None)
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            _require_init()
+            run = _start_run(func.__name__, budget_usd, max_iterations, max_duration_ms, max_tokens)
+            _set_active_run(run)
+            try:
+                result = func(*args, **kwargs)
+                _end_run(run, status="success")
+                return result
+            except (BudgetExceeded, IterationLimitReached, TimeLimitReached, TokenLimitReached):
+                _end_run(run, status="breached")
+                raise
+            except Exception as e:
+                _end_run(run, status="error", error=str(e))
+                raise
+            finally:
+                _set_active_run(None)
+
+        return async_wrapper if is_async else sync_wrapper
+
+    return decorator
+
+
+def _start_run(agent_name, budget_usd, max_iterations, max_duration_ms, max_tokens) -> RunState:
+    run_id = str(uuid.uuid4())
+    run = RunState(
+        run_id=run_id,
+        agent_name=agent_name,
+        budget_usd=budget_usd,
+        max_iterations=max_iterations,
+        max_duration_ms=max_duration_ms,
+        max_tokens=max_tokens,
+    )
+    client = _get_client()
+    if client:
+        client.start_run(run_id, agent_name, budget_usd, max_iterations, max_duration_ms, max_tokens)
+    return run
+
+
+def _end_run(run: RunState, status: str, error: Optional[str] = None):
+    client = _get_client()
+    if client:
+        client.end_run(run.run_id, status=status, error=error)
+
+
+async def checkpoint(cost_delta_usd: float = 0.0, tokens_used: int = 0):
+    """
+    Report spend and token usage, then check all governance limits.
+
+    Call this after each LLM call in your agent loop.
+    Raises BudgetExceeded, IterationLimitReached, TimeLimitReached,
+    or TokenLimitReached if any limit is crossed.
+
+    Args:
+        cost_delta_usd: Amount spent since the last checkpoint call.
+        tokens_used: Total tokens (input + output) consumed by this step.
+    """
+    run = get_active_run()
+    if run is None:
+        return
+
+    run.cost_usd    += cost_delta_usd
+    run.tokens_used += tokens_used
+    run.iterations  += 1
+
+    # Local checks — instant, no network
+    if run.cost_usd >= run.budget_usd:
+        raise BudgetExceeded(run.cost_usd, run.budget_usd)
+
+    if run.iterations >= run.max_iterations:
+        raise IterationLimitReached(run.iterations, run.max_iterations)
+
+    if run.duration_ms >= run.max_duration_ms:
+        raise TimeLimitReached(run.duration_ms, run.max_duration_ms)
+
+    if run.max_tokens > 0 and run.tokens_used >= run.max_tokens:
+        raise TokenLimitReached(run.tokens_used, run.max_tokens)
+
+    # Server check — cloud mode only
+    client = _get_client()
+    if client is None:
+        return
+
+    result = client.checkpoint(
+        run.run_id, cost_delta_usd, run.iterations, run.duration_ms, run.tokens_used
+    )
+
+    if result.get("ok", True):
+        return
+
+    breach = result.get("breach")
+    if breach == "budget_exceeded":
+        raise BudgetExceeded(result.get("spent_usd", run.cost_usd), result.get("budget_usd", run.budget_usd))
+    elif breach == "iteration_limit":
+        raise IterationLimitReached(run.iterations, run.max_iterations)
+    elif breach == "time_limit":
+        raise TimeLimitReached(run.duration_ms, run.max_duration_ms)
+    elif breach == "token_limit":
+        raise TokenLimitReached(run.tokens_used, run.max_tokens)
+
+
+def log_decision(reasoning: str, action: Optional[str] = None):
+    """
+    Record the agent's reasoning at this step.
+
+    Call this before any significant action to build an audit trail
+    of why the agent did what it did.
+
+    Args:
+        reasoning: Why the agent is taking this action.
+        action: Short label for the action being taken (e.g. "web_search").
+    """
+    run = get_active_run()
+    if run is None:
+        return
+
+    entry = {
+        "timestamp": time.time(),
+        "iteration": run.iterations,
+        "reasoning": reasoning,
+        "action": action,
+    }
+    run.decisions.append(entry)
+
+    client = _get_client()
+    if client:
+        client.log_decision(
+            run_id=run.run_id,
+            iteration=run.iterations,
+            reasoning=reasoning,
+            action=action,
+        )

fences/exceptions.py

@@ -0,0 +1,38 @@
+class FencesError(Exception):
+    pass
+
+
+class BudgetExceeded(FencesError):
+    def __init__(self, spent_usd: float, budget_usd: float):
+        self.spent_usd = spent_usd
+        self.budget_usd = budget_usd
+        super().__init__(
+            f"Run exceeded budget: spent ${spent_usd:.4f} of ${budget_usd:.4f} limit"
+        )
+
+
+class IterationLimitReached(FencesError):
+    def __init__(self, iterations: int, max_iterations: int):
+        self.iterations = iterations
+        self.max_iterations = max_iterations
+        super().__init__(
+            f"Run exceeded iteration limit: {iterations} of {max_iterations} allowed"
+        )
+
+
+class TimeLimitReached(FencesError):
+    def __init__(self, duration_ms: int, max_duration_ms: int):
+        self.duration_ms = duration_ms
+        self.max_duration_ms = max_duration_ms
+        super().__init__(
+            f"Run exceeded time limit: {duration_ms}ms of {max_duration_ms}ms allowed"
+        )
+
+
+class TokenLimitReached(FencesError):
+    def __init__(self, tokens_used: int, max_tokens: int):
+        self.tokens_used = tokens_used
+        self.max_tokens = max_tokens
+        super().__init__(
+            f"Run exceeded token limit: {tokens_used} of {max_tokens} tokens allowed"
+        )