agentguard-ram 0.1.0__tar.gz

agentguard_ram-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Env files
+.env
+.env.local
+.env*.local
+
+# Next.js
+.next/
+node_modules/
+
+# Logs
+*.log
+logs/
+
+# OS
+.DS_Store
+
+# IDE
+.serena/
+.vscode/

agentguard_ram-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: agentguard-ram
+Version: 0.1.0
+Summary: Real-time cost observability and guardrails for AI agents
+Project-URL: Homepage, https://agent-guard-nine.vercel.app
+Project-URL: Repository, https://github.com/RambabuArabandi/agent-guard
+Project-URL: Bug Tracker, https://github.com/RambabuArabandi/agent-guard/issues
+License: MIT
+Keywords: agents,ai,cost,guardrails,langchain,llm,observability
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.7.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.2.0; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# AgentGuard
+
+Real-time cost observability and guardrails for AI agents.
+
+Track LLM spend, set budget thresholds, and auto-pause agents before they blow up your bill.
+
+## Install
+
+```bash
+pip install agentguard
+```
+
+## Quick Start
+
+```python
+from agentguard import AgentGuard, AgentEvent
+
+guard = AgentGuard(
+    api_key="ag_...",
+    agent_id="my-sales-agent",
+    cost_threshold=10.0,          # auto-pause at $10/day
+    slack_webhook="https://...",  # optional alert
+)
+
+# Custom agent — wrap with decorator
+@guard.track
+def run_my_agent():
+    # your agent logic here
+    alive = guard.send_event(AgentEvent(
+        agent_id="my-sales-agent",
+        event_type="llm_call",
+        model="gpt-4o",
+        input_tokens=500,
+        output_tokens=300,
+    ))
+    if not alive:
+        print("Agent paused — cost threshold reached")
+        return
+```
+
+## LangChain / LangGraph
+
+```python
+from agentguard import AgentGuard
+
+guard = AgentGuard(api_key="ag_...", agent_id="my-agent", cost_threshold=5.0)
+
+# Drop-in callback — tracks every LLM call automatically
+chain = my_chain.with_config(callbacks=[guard.callback])
+result = chain.invoke({"input": "do something"})
+```
+
+## Supported Models
+
+| Model | Input (per 1M) | Output (per 1M) |
+|-------|---------------|----------------|
+| gpt-4o | $2.50 | $10.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+| claude-3-5-sonnet | $3.00 | $15.00 |
+| claude-3-5-haiku | $0.80 | $4.00 |
+| gemini-1.5-pro | $1.25 | $5.00 |
+
+## Dashboard
+
+View live costs, event feed, and manage agents at [agent-guard-nine.vercel.app](https://agent-guard-nine.vercel.app).
+
+## Links
+
+- Dashboard: https://agent-guard-nine.vercel.app
+- Backend API: https://agent-guard-production-dcdd.up.railway.app/docs

agentguard_ram-0.1.0/README.md

@@ -0,0 +1,70 @@
+# AgentGuard
+
+Real-time cost observability and guardrails for AI agents.
+
+Track LLM spend, set budget thresholds, and auto-pause agents before they blow up your bill.
+
+## Install
+
+```bash
+pip install agentguard
+```
+
+## Quick Start
+
+```python
+from agentguard import AgentGuard, AgentEvent
+
+guard = AgentGuard(
+    api_key="ag_...",
+    agent_id="my-sales-agent",
+    cost_threshold=10.0,          # auto-pause at $10/day
+    slack_webhook="https://...",  # optional alert
+)
+
+# Custom agent — wrap with decorator
+@guard.track
+def run_my_agent():
+    # your agent logic here
+    alive = guard.send_event(AgentEvent(
+        agent_id="my-sales-agent",
+        event_type="llm_call",
+        model="gpt-4o",
+        input_tokens=500,
+        output_tokens=300,
+    ))
+    if not alive:
+        print("Agent paused — cost threshold reached")
+        return
+```
+
+## LangChain / LangGraph
+
+```python
+from agentguard import AgentGuard
+
+guard = AgentGuard(api_key="ag_...", agent_id="my-agent", cost_threshold=5.0)
+
+# Drop-in callback — tracks every LLM call automatically
+chain = my_chain.with_config(callbacks=[guard.callback])
+result = chain.invoke({"input": "do something"})
+```
+
+## Supported Models
+
+| Model | Input (per 1M) | Output (per 1M) |
+|-------|---------------|----------------|
+| gpt-4o | $2.50 | $10.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+| claude-3-5-sonnet | $3.00 | $15.00 |
+| claude-3-5-haiku | $0.80 | $4.00 |
+| gemini-1.5-pro | $1.25 | $5.00 |
+
+## Dashboard
+
+View live costs, event feed, and manage agents at [agent-guard-nine.vercel.app](https://agent-guard-nine.vercel.app).
+
+## Links
+
+- Dashboard: https://agent-guard-nine.vercel.app
+- Backend API: https://agent-guard-production-dcdd.up.railway.app/docs

agentguard_ram-0.1.0/agentguard/__init__.py

@@ -0,0 +1,42 @@
+"""AgentGuard — AI agent cost observability SDK."""
+
+from .tracker import AgentGuardTracker
+from .models import AgentEvent
+
+try:
+    from .callbacks import AgentGuardCallback
+except ImportError:
+    AgentGuardCallback = None  # type: ignore
+
+
+class AgentGuard(AgentGuardTracker):
+    """
+    Main entry point.
+
+    Usage::
+
+        guard = AgentGuard(
+            api_key="ag_...",
+            agent_id="my-sales-agent",
+            cost_threshold=10.0,
+            slack_webhook="https://hooks.slack.com/...",
+        )
+
+        # LangChain / LangGraph
+        chain = my_chain.with_config(callbacks=[guard.callback])
+
+        # Custom agent
+        @guard.track
+        def run_my_agent():
+            ...
+    """
+
+    @property
+    def callback(self):
+        if AgentGuardCallback is None:
+            raise ImportError("Install langchain-core to use guard.callback")
+        return AgentGuardCallback(self)
+
+
+__all__ = ["AgentGuard", "AgentGuardTracker", "AgentEvent", "AgentGuardCallback"]
+__version__ = "0.1.0"

agentguard_ram-0.1.0/agentguard/callbacks.py

@@ -0,0 +1,94 @@
+"""LangChain callback handler for AgentGuard."""
+
+from typing import Any
+from uuid import UUID
+
+from .models import AgentEvent
+from .tracker import AgentGuardTracker
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+
+    class AgentGuardCallback(BaseCallbackHandler):
+        """Drop-in LangChain callback that tracks every LLM call."""
+
+        def __init__(self, tracker: AgentGuardTracker):
+            super().__init__()
+            self.tracker = tracker
+
+        # ── LLM events ────────────────────────────────────────────────────────
+
+        def on_llm_end(
+            self,
+            response: LLMResult,
+            *,
+            run_id: UUID,
+            parent_run_id: UUID | None = None,
+            **kwargs: Any,
+        ) -> None:
+            for generations in response.generations:
+                for gen in generations:
+                    usage = getattr(gen, "generation_info", {}) or {}
+                    # Different LLM providers use different keys
+                    input_tokens = (
+                        usage.get("input_tokens")
+                        or usage.get("prompt_tokens")
+                        or usage.get("prompt_token_count")
+                        or 0
+                    )
+                    output_tokens = (
+                        usage.get("output_tokens")
+                        or usage.get("completion_tokens")
+                        or usage.get("candidates_token_count")
+                        or 0
+                    )
+                    model = usage.get("model_name") or kwargs.get("invocation_params", {}).get("model_name", "unknown")
+
+                    self.tracker.send_event(
+                        AgentEvent(
+                            agent_id=self.tracker.agent_id,
+                            event_type="llm_call",
+                            model=model,
+                            input_tokens=input_tokens,
+                            output_tokens=output_tokens,
+                            metadata={"run_id": str(run_id)},
+                        )
+                    )
+
+        # ── Tool events ───────────────────────────────────────────────────────
+
+        def on_tool_start(
+            self,
+            serialized: dict[str, Any],
+            input_str: str,
+            *,
+            run_id: UUID,
+            **kwargs: Any,
+        ) -> None:
+            tool_name = serialized.get("name", "unknown")
+            self.tracker.send_event(
+                AgentEvent(
+                    agent_id=self.tracker.agent_id,
+                    event_type="tool_call",
+                    tool_name=tool_name,
+                    metadata={"run_id": str(run_id)},
+                )
+            )
+
+        # ── Chain/agent lifecycle ─────────────────────────────────────────────
+
+        def on_chain_start(self, *args, **kwargs) -> None:
+            pass  # tracked at decorator level if desired
+
+        def on_chain_end(self, *args, **kwargs) -> None:
+            pass
+
+except ImportError:
+    # langchain not installed — AgentGuardCallback unavailable
+    class AgentGuardCallback:  # type: ignore
+        def __init__(self, *args, **kwargs):
+            raise ImportError(
+                "LangChain is not installed. "
+                "Run: pip install langchain-core"
+            )

agentguard_ram-0.1.0/agentguard/models.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel
+from typing import Literal
+
+
+class AgentEvent(BaseModel):
+    agent_id: str
+    event_type: Literal["llm_call", "tool_call", "agent_start", "agent_end"]
+    model: str | None = None
+    input_tokens: int = 0
+    output_tokens: int = 0
+    tool_name: str | None = None
+    metadata: dict | None = None

agentguard_ram-0.1.0/agentguard/tracker.py

@@ -0,0 +1,92 @@
+"""Core tracking logic — sends events to the AgentGuard backend."""
+
+import httpx
+from .models import AgentEvent
+
+
+class AgentGuardTracker:
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str,
+        backend_url: str = "https://agent-guard-production-dcdd.up.railway.app",
+        cost_threshold: float | None = None,
+        slack_webhook: str | None = None,
+    ):
+        self.api_key = api_key
+        self.agent_id = agent_id
+        self.backend_url = backend_url.rstrip("/")
+        self._paused = False
+
+        # Register config if threshold provided
+        if cost_threshold is not None:
+            self._register_config(cost_threshold, slack_webhook)
+
+    def _register_config(self, threshold: float, slack_webhook: str | None):
+        try:
+            with httpx.Client() as client:
+                client.post(
+                    f"{self.backend_url}/config",
+                    json={
+                        "agent_id": self.agent_id,
+                        "cost_threshold_usd": threshold,
+                        "slack_webhook_url": slack_webhook,
+                    },
+                    headers={"x-api-key": self.api_key},
+                    timeout=5,
+                )
+        except Exception:
+            pass  # Don't block agent startup
+
+    def send_event(self, event: AgentEvent) -> bool:
+        """
+        Send event to backend. Returns False if agent is paused (caller should stop).
+        """
+        if self._paused:
+            return False
+        try:
+            with httpx.Client() as client:
+                resp = client.post(
+                    f"{self.backend_url}/events",
+                    json=event.model_dump(),
+                    headers={"x-api-key": self.api_key},
+                    timeout=5,
+                )
+                data = resp.json()
+                if data.get("paused"):
+                    self._paused = True
+                    return False
+        except Exception:
+            pass  # Don't crash the agent on network errors
+        return True
+
+    @property
+    def is_paused(self) -> bool:
+        return self._paused
+
+    def track(self, fn):
+        """Decorator — wrap any function, emit agent_start/agent_end events."""
+        import functools
+
+        @functools.wraps(fn)
+        def wrapper(*args, **kwargs):
+            self.send_event(
+                AgentEvent(agent_id=self.agent_id, event_type="agent_start")
+            )
+            try:
+                result = fn(*args, **kwargs)
+                self.send_event(
+                    AgentEvent(agent_id=self.agent_id, event_type="agent_end")
+                )
+                return result
+            except Exception as exc:
+                self.send_event(
+                    AgentEvent(
+                        agent_id=self.agent_id,
+                        event_type="agent_end",
+                        metadata={"error": str(exc)},
+                    )
+                )
+                raise
+
+        return wrapper

agentguard_ram-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentguard"]
+
+[project]
+name = "agentguard-ram"
+version = "0.1.0"
+description = "Real-time cost observability and guardrails for AI agents"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["ai", "agents", "llm", "observability", "cost", "guardrails", "langchain"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.7.0",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.2.0"]
+
+[project.urls]
+Homepage = "https://agent-guard-nine.vercel.app"
+Repository = "https://github.com/RambabuArabandi/agent-guard"
+"Bug Tracker" = "https://github.com/RambabuArabandi/agent-guard/issues"

agentguard_ram-0.1.0/test_fake_agent.py

@@ -0,0 +1,59 @@
+"""
+Fake agent test — validates SDK → backend flow without LangChain.
+
+Usage (from agentguard/sdk/ directory):
+    uv pip install -e .
+    AGENTGUARD_API_KEY=ag_test uv run python test_fake_agent.py
+
+Or with custom backend:
+    AGENTGUARD_BACKEND_URL=http://localhost:8000 \
+    AGENTGUARD_API_KEY=ag_test \
+    uv run python test_fake_agent.py
+"""
+
+import os
+import sys
+import time
+
+# Allow running without installing the package (local dev)
+sys.path.insert(0, os.path.dirname(__file__))
+from agentguard import AgentGuard
+
+guard = AgentGuard(
+    api_key=os.environ.get("AGENTGUARD_API_KEY", "ag_test"),
+    agent_id="fake-test-agent",
+    backend_url=os.environ.get("AGENTGUARD_BACKEND_URL", "http://localhost:8000"),
+    cost_threshold=1.0,  # low threshold for testing
+    slack_webhook=os.environ.get("SLACK_WEBHOOK_URL"),
+)
+
+
+@guard.track
+def fake_agent():
+    from agentguard.models import AgentEvent
+
+    # Simulate 3 LLM calls
+    for i in range(3):
+        print(f"  [call {i+1}] sending llm_call event…")
+        alive = guard.send_event(
+            AgentEvent(
+                agent_id="fake-test-agent",
+                event_type="llm_call",
+                model="gpt-4o",
+                input_tokens=500,
+                output_tokens=300,
+                metadata={"step": i + 1},
+            )
+        )
+        if not alive:
+            print("  !! Agent paused by AgentGuard — stopping.")
+            return
+        time.sleep(0.3)
+
+    print("  Agent finished normally.")
+
+
+if __name__ == "__main__":
+    print("Running fake agent…")
+    fake_agent()
+    print(f"Final paused state: {guard.is_paused}")