agentmetrics 0.1.0__tar.gz

agentmetrics-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: agentmetrics
+Version: 0.1.0
+Summary: Real-time cost visibility & optimization for AI agents.
+License: Apache-2.0
+Project-URL: Homepage, https://agentmetrics.dev
+Project-URL: Repository, https://github.com/agentmetrics/agentmetrics
+Project-URL: Documentation, https://agentmetrics.dev/docs
+Keywords: ai,agents,observability,cost,langchain,crewai,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# AgentMetrics SDK
+
+Real-time cost tracking for AI agents. One decorator. Full visibility.
+
+## Install
+
+```bash
+pip install agentmetrics
+```
+
+## Quick Start
+
+```python
+from agentmetrics import sentinel
+
+# Configure once at startup
+sentinel.configure(api_key="am_your_key_here")
+
+# Decorate any agent function
+@sentinel.track(agent_id="customer_support")
+def my_agent(task: str) -> str:
+    # Your agent logic here
+    return result
+```
+
+## Async Support
+
+```python
+@sentinel.track(agent_id="async_agent")
+async def my_async_agent(task: str) -> str:
+    result = await some_llm_call(task)
+    return result
+```
+
+## With LangGraph
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="langgraph_agent")
+def run_graph(state: dict) -> dict:
+    return graph.invoke(state)
+```
+
+## With CrewAI
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="research_crew")
+def run_crew(topic: str) -> str:
+    return crew.kickoff(inputs={"topic": topic})
+```
+
+## Self-Hosted
+
+Point the SDK at your own server:
+
+```python
+sentinel.configure(
+    api_key="am_your_key_here",
+    base_url="https://your-server.com/v1",
+)
+```
+
+## Graceful Degradation
+
+If the AgentMetrics server is unreachable, your agent keeps running normally.
+The SDK never raises exceptions or blocks execution.
+
+## License
+
+Apache 2.0

agentmetrics-0.1.0/README.md

@@ -0,0 +1,75 @@
+# AgentMetrics SDK
+
+Real-time cost tracking for AI agents. One decorator. Full visibility.
+
+## Install
+
+```bash
+pip install agentmetrics
+```
+
+## Quick Start
+
+```python
+from agentmetrics import sentinel
+
+# Configure once at startup
+sentinel.configure(api_key="am_your_key_here")
+
+# Decorate any agent function
+@sentinel.track(agent_id="customer_support")
+def my_agent(task: str) -> str:
+    # Your agent logic here
+    return result
+```
+
+## Async Support
+
+```python
+@sentinel.track(agent_id="async_agent")
+async def my_async_agent(task: str) -> str:
+    result = await some_llm_call(task)
+    return result
+```
+
+## With LangGraph
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="langgraph_agent")
+def run_graph(state: dict) -> dict:
+    return graph.invoke(state)
+```
+
+## With CrewAI
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="research_crew")
+def run_crew(topic: str) -> str:
+    return crew.kickoff(inputs={"topic": topic})
+```
+
+## Self-Hosted
+
+Point the SDK at your own server:
+
+```python
+sentinel.configure(
+    api_key="am_your_key_here",
+    base_url="https://your-server.com/v1",
+)
+```
+
+## Graceful Degradation
+
+If the AgentMetrics server is unreachable, your agent keeps running normally.
+The SDK never raises exceptions or blocks execution.
+
+## License
+
+Apache 2.0

agentmetrics-0.1.0/agentmetrics/__init__.py

@@ -0,0 +1,4 @@
+from agentmetrics.sentinel import Sentinel, sentinel
+
+__all__ = ["sentinel", "Sentinel"]
+__version__ = "0.1.0"

agentmetrics-0.1.0/agentmetrics/http_client.py

@@ -0,0 +1,50 @@
+import json
+import logging
+import threading
+import time
+from typing import Optional
+
+import requests
+
+logger = logging.getLogger("agentmetrics")
+
+
+class HttpClient:
+    def __init__(self, api_key: str, base_url: str):
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self._pending_threads: list[threading.Thread] = []
+        self._lock = threading.Lock()
+
+    def fire_and_forget(self, payload: dict) -> None:
+        """Post event in a background thread. Never blocks. Never raises."""
+        t = threading.Thread(target=self._post_with_retry, args=(payload,), daemon=True)
+        with self._lock:
+            self._pending_threads.append(t)
+        t.start()
+
+    def _post_with_retry(self, payload: dict, retries: int = 3) -> None:
+        url = f"{self.base_url}/events"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+        for attempt in range(retries):
+            try:
+                resp = requests.post(url, json=payload, headers=headers, timeout=5)
+                if resp.status_code in (200, 201):
+                    return
+                logger.debug("AgentMetrics: non-2xx response %s", resp.status_code)
+            except Exception as exc:
+                logger.debug("AgentMetrics: send failed (attempt %d): %s", attempt + 1, exc)
+                if attempt < retries - 1:
+                    time.sleep(1)
+
+    def flush(self, timeout: float = 10.0) -> None:
+        """Wait for all in-flight events to complete. Useful in tests and shutdown."""
+        with self._lock:
+            threads = list(self._pending_threads)
+        for t in threads:
+            t.join(timeout=timeout)
+        with self._lock:
+            self._pending_threads = [t for t in self._pending_threads if t.is_alive()]

agentmetrics-0.1.0/agentmetrics/sentinel.py

@@ -0,0 +1,143 @@
+import asyncio
+import functools
+import logging
+import time
+import uuid
+from typing import Optional
+
+from agentmetrics.http_client import HttpClient
+
+logger = logging.getLogger("agentmetrics")
+
+
+class Sentinel:
+    """
+    Core tracking class. Use the module-level `sentinel` singleton.
+
+    Usage:
+        from agentmetrics import sentinel
+        sentinel.configure(api_key="am_...")
+
+        @sentinel.track(agent_id="my_agent")
+        def my_agent(task):
+            return result
+    """
+
+    def __init__(self):
+        self._api_key: Optional[str] = None
+        self._client: Optional[HttpClient] = None
+
+    def configure(
+        self,
+        api_key: str,
+        base_url: str = "https://api.agentmetrics.dev/v1",
+    ) -> None:
+        """Call once at app startup before using @track."""
+        self._api_key = api_key
+        self._client = HttpClient(api_key=api_key, base_url=base_url)
+
+    @property
+    def is_configured(self) -> bool:
+        return self._api_key is not None
+
+    def track(self, agent_id: str):
+        """
+        Decorator that wraps a function (sync or async) and sends
+        execution metrics to AgentMetrics. Graceful no-op if not configured.
+
+        Args:
+            agent_id: Unique identifier for this agent in the dashboard.
+
+        Example:
+            @sentinel.track(agent_id="customer_support")
+            def handle_ticket(ticket):
+                ...
+        """
+        def decorator(func):
+            if asyncio.iscoroutinefunction(func):
+                @functools.wraps(func)
+                async def async_wrapper(*args, **kwargs):
+                    if not self.is_configured:
+                        return await func(*args, **kwargs)
+                    return await self._run_async(func, agent_id, args, kwargs)
+                return async_wrapper
+            else:
+                @functools.wraps(func)
+                def sync_wrapper(*args, **kwargs):
+                    if not self.is_configured:
+                        return func(*args, **kwargs)
+                    return self._run_sync(func, agent_id, args, kwargs)
+                return sync_wrapper
+        return decorator
+
+    def _run_sync(self, func, agent_id: str, args, kwargs):
+        trace_id = str(uuid.uuid4())
+        start = time.monotonic()
+        status = "success"
+        error_msg = None
+        try:
+            result = func(*args, **kwargs)
+            return result
+        except Exception as exc:
+            status = "failed"
+            error_msg = str(exc)
+            raise
+        finally:
+            duration_ms = (time.monotonic() - start) * 1000
+            self._send(trace_id, agent_id, status, duration_ms, error_msg)
+
+    async def _run_async(self, func, agent_id: str, args, kwargs):
+        trace_id = str(uuid.uuid4())
+        start = time.monotonic()
+        status = "success"
+        error_msg = None
+        try:
+            result = await func(*args, **kwargs)
+            return result
+        except Exception as exc:
+            status = "failed"
+            error_msg = str(exc)
+            raise
+        finally:
+            duration_ms = (time.monotonic() - start) * 1000
+            self._send(trace_id, agent_id, status, duration_ms, error_msg)
+
+    def _send(
+        self,
+        trace_id: str,
+        agent_id: str,
+        status: str,
+        duration_ms: float,
+        error_msg: Optional[str],
+        cost_usd: float = 0.0,
+        model: Optional[str] = None,
+        input_tokens: Optional[int] = None,
+        output_tokens: Optional[int] = None,
+    ) -> None:
+        if not self._client:
+            return
+        payload = {
+            "trace_id": trace_id,
+            "agent_id": agent_id,
+            "status": status,
+            "duration_ms": duration_ms,
+            "cost_usd": cost_usd,
+            "error": error_msg,
+        }
+        if model:
+            payload["model"] = model
+        if input_tokens is not None:
+            payload["input_tokens"] = input_tokens
+        if output_tokens is not None:
+            payload["output_tokens"] = output_tokens
+
+        self._client.fire_and_forget(payload)
+
+    def flush(self, timeout: float = 10.0) -> None:
+        """Wait for all pending events to be sent. Call before process exit."""
+        if self._client:
+            self._client.flush(timeout=timeout)
+
+
+# Module-level singleton
+sentinel = Sentinel()

agentmetrics-0.1.0/agentmetrics.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: agentmetrics
+Version: 0.1.0
+Summary: Real-time cost visibility & optimization for AI agents.
+License: Apache-2.0
+Project-URL: Homepage, https://agentmetrics.dev
+Project-URL: Repository, https://github.com/agentmetrics/agentmetrics
+Project-URL: Documentation, https://agentmetrics.dev/docs
+Keywords: ai,agents,observability,cost,langchain,crewai,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+
+# AgentMetrics SDK
+
+Real-time cost tracking for AI agents. One decorator. Full visibility.
+
+## Install
+
+```bash
+pip install agentmetrics
+```
+
+## Quick Start
+
+```python
+from agentmetrics import sentinel
+
+# Configure once at startup
+sentinel.configure(api_key="am_your_key_here")
+
+# Decorate any agent function
+@sentinel.track(agent_id="customer_support")
+def my_agent(task: str) -> str:
+    # Your agent logic here
+    return result
+```
+
+## Async Support
+
+```python
+@sentinel.track(agent_id="async_agent")
+async def my_async_agent(task: str) -> str:
+    result = await some_llm_call(task)
+    return result
+```
+
+## With LangGraph
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="langgraph_agent")
+def run_graph(state: dict) -> dict:
+    return graph.invoke(state)
+```
+
+## With CrewAI
+
+```python
+from agentmetrics import sentinel
+sentinel.configure(api_key="am_your_key_here")
+
+@sentinel.track(agent_id="research_crew")
+def run_crew(topic: str) -> str:
+    return crew.kickoff(inputs={"topic": topic})
+```
+
+## Self-Hosted
+
+Point the SDK at your own server:
+
+```python
+sentinel.configure(
+    api_key="am_your_key_here",
+    base_url="https://your-server.com/v1",
+)
+```
+
+## Graceful Degradation
+
+If the AgentMetrics server is unreachable, your agent keeps running normally.
+The SDK never raises exceptions or blocks execution.
+
+## License
+
+Apache 2.0

agentmetrics-0.1.0/agentmetrics.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+agentmetrics/__init__.py
+agentmetrics/http_client.py
+agentmetrics/sentinel.py
+agentmetrics.egg-info/PKG-INFO
+agentmetrics.egg-info/SOURCES.txt
+agentmetrics.egg-info/dependency_links.txt
+agentmetrics.egg-info/requires.txt
+agentmetrics.egg-info/top_level.txt
+tests/test_sentinel.py

agentmetrics-0.1.0/agentmetrics.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agentmetrics-0.1.0/agentmetrics.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

agentmetrics-0.1.0/agentmetrics.egg-info/top_level.txt

@@ -0,0 +1 @@
+agentmetrics

agentmetrics-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentmetrics"
+version = "0.1.0"
+description = "Real-time cost visibility & optimization for AI agents."
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.8"
+dependencies = ["requests>=2.28"]
+keywords = ["ai", "agents", "observability", "cost", "langchain", "crewai", "langgraph"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://agentmetrics.dev"
+Repository = "https://github.com/agentmetrics/agentmetrics"
+Documentation = "https://agentmetrics.dev/docs"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["agentmetrics*"]

agentmetrics-0.1.0/setup.cfg

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

agentmetrics-0.1.0/tests/test_sentinel.py

@@ -0,0 +1,81 @@
+import pytest
+from unittest.mock import patch, MagicMock
+from agentmetrics import sentinel, Sentinel
+
+
+def setup_function():
+    sentinel._api_key = None
+    sentinel._client = None
+
+
+def test_no_op_when_not_configured():
+    """Agent runs normally when sentinel is not configured."""
+    @sentinel.track(agent_id="test")
+    def my_agent():
+        return "result"
+
+    assert my_agent() == "result"
+
+
+def test_tracks_success():
+    sentinel.configure(api_key="test_key", base_url="http://localhost:8000/v1")
+
+    sent = []
+    sentinel._client.fire_and_forget = lambda payload: sent.append(payload)
+
+    @sentinel.track(agent_id="test_agent")
+    def my_agent():
+        return "ok"
+
+    result = my_agent()
+    assert result == "ok"
+    assert len(sent) == 1
+    assert sent[0]["status"] == "success"
+    assert sent[0]["agent_id"] == "test_agent"
+    assert sent[0]["duration_ms"] >= 0
+
+
+def test_tracks_failure():
+    sentinel.configure(api_key="test_key", base_url="http://localhost:8000/v1")
+
+    sent = []
+    sentinel._client.fire_and_forget = lambda payload: sent.append(payload)
+
+    @sentinel.track(agent_id="failing_agent")
+    def my_agent():
+        raise ValueError("something broke")
+
+    with pytest.raises(ValueError):
+        my_agent()
+
+    assert len(sent) == 1
+    assert sent[0]["status"] == "failed"
+    assert "something broke" in sent[0]["error"]
+
+
+@pytest.mark.asyncio
+async def test_async_agent():
+    sentinel.configure(api_key="test_key", base_url="http://localhost:8000/v1")
+
+    sent = []
+    sentinel._client.fire_and_forget = lambda payload: sent.append(payload)
+
+    @sentinel.track(agent_id="async_agent")
+    async def my_async_agent():
+        return "async_result"
+
+    result = await my_async_agent()
+    assert result == "async_result"
+    assert sent[0]["status"] == "success"
+
+
+def test_never_raises_on_send_failure():
+    sentinel.configure(api_key="test_key", base_url="http://unreachable:9999/v1")
+
+    @sentinel.track(agent_id="test")
+    def my_agent():
+        return "fine"
+
+    # Should not raise even though server is unreachable
+    result = my_agent()
+    assert result == "fine"