agentmeter-obs 0.1.0__tar.gz

agentmeter_obs-0.1.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

agentmeter_obs-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: agentmeter-obs
+Version: 0.1.0
+Summary: Lightweight SDK to track AI agent tool calls, costs, and latency.
+Project-URL: Homepage, https://github.com/dnorio/agent-meter
+Project-URL: Repository, https://github.com/dnorio/agent-meter
+Author-email: dnorio <dnorio@users.noreply.github.com>
+License-Expression: MIT
+Keywords: agents,ai,llm,observability,telemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# agent-meter
+
+Lightweight Python SDK to track AI agent tool calls, costs, and latency.
+
+## Install
+
+```bash
+# Until the first PyPI release is published:
+cd sdk/python
+python3 -m pip install -e .
+
+# After publication:
+pip install agentmeter-obs
+```
+
+## Quick Start (60 seconds)
+
+```python
+from agent_meter import AgentMeter
+
+# Initialize (picks up AGENT_METER_API_KEY from env)
+am = AgentMeter(api_key="am_live_...")
+
+# Track a tool call
+span = am.track("web_search", model="gpt-4o")
+result = do_web_search(query)
+span.finish()
+
+# Track with tokens/cost
+span = am.track("code_review", model="claude-sonnet-4-20250514")
+span.estimated_input_tokens = 2000
+span.estimated_output_tokens = 500
+span.usd_cost = 0.012
+span.finish()
+
+# Flush happens automatically every 5s, or on exit
+# Force flush:
+am.flush()
+```
+
+## Configuration
+
+| Env Variable | Description | Default |
+|---|---|---|
+| `AGENT_METER_API_KEY` | API key (`am_live_...`) | — |
+| `AGENT_METER_ENDPOINT` | Server URL | `http://localhost:8081` |
+| `AGENT_METER_IDE` | IDE identifier | `python-sdk` |
+| `AGENT_METER_AGENT` | Agent name | — |
+
+Or pass directly:
+
+```python
+am = AgentMeter(
+    api_key="am_live_...",
+    endpoint="http://localhost:3000",
+    ide="my-custom-agent",
+    agent="research-bot",
+)
+```
+
+## Context Manager
+
+```python
+import contextlib
+
+@contextlib.contextmanager
+def tracked(am, tool_name, **kwargs):
+    span = am.track(tool_name, **kwargs)
+    try:
+        yield span
+    except Exception as e:
+        span.finish(ok=False, error=str(e))
+        raise
+    else:
+        span.finish()
+
+# Usage
+with tracked(am, "database_query", model="gpt-4o") as span:
+    results = db.execute(sql)
+    span.estimated_input_tokens = len(sql) // 4
+```
+
+## Conversations & Tasks
+
+Group spans into conversations (sessions) and tasks:
+
+```python
+span = am.track(
+    "generate_code",
+    model="claude-sonnet-4-20250514",
+    conversation_id="conv-abc123",
+    task_id="implement-feature-x",
+)
+```
+
+## Protocol
+
+The SDK sends spans as OTLP-compatible JSON to `POST /v1/traces`. This is the
+same format used by OpenTelemetry, making it compatible with any OTLP collector.

agentmeter_obs-0.1.0/README.md

@@ -0,0 +1,99 @@
+# agent-meter
+
+Lightweight Python SDK to track AI agent tool calls, costs, and latency.
+
+## Install
+
+```bash
+# Until the first PyPI release is published:
+cd sdk/python
+python3 -m pip install -e .
+
+# After publication:
+pip install agentmeter-obs
+```
+
+## Quick Start (60 seconds)
+
+```python
+from agent_meter import AgentMeter
+
+# Initialize (picks up AGENT_METER_API_KEY from env)
+am = AgentMeter(api_key="am_live_...")
+
+# Track a tool call
+span = am.track("web_search", model="gpt-4o")
+result = do_web_search(query)
+span.finish()
+
+# Track with tokens/cost
+span = am.track("code_review", model="claude-sonnet-4-20250514")
+span.estimated_input_tokens = 2000
+span.estimated_output_tokens = 500
+span.usd_cost = 0.012
+span.finish()
+
+# Flush happens automatically every 5s, or on exit
+# Force flush:
+am.flush()
+```
+
+## Configuration
+
+| Env Variable | Description | Default |
+|---|---|---|
+| `AGENT_METER_API_KEY` | API key (`am_live_...`) | — |
+| `AGENT_METER_ENDPOINT` | Server URL | `http://localhost:8081` |
+| `AGENT_METER_IDE` | IDE identifier | `python-sdk` |
+| `AGENT_METER_AGENT` | Agent name | — |
+
+Or pass directly:
+
+```python
+am = AgentMeter(
+    api_key="am_live_...",
+    endpoint="http://localhost:3000",
+    ide="my-custom-agent",
+    agent="research-bot",
+)
+```
+
+## Context Manager
+
+```python
+import contextlib
+
+@contextlib.contextmanager
+def tracked(am, tool_name, **kwargs):
+    span = am.track(tool_name, **kwargs)
+    try:
+        yield span
+    except Exception as e:
+        span.finish(ok=False, error=str(e))
+        raise
+    else:
+        span.finish()
+
+# Usage
+with tracked(am, "database_query", model="gpt-4o") as span:
+    results = db.execute(sql)
+    span.estimated_input_tokens = len(sql) // 4
+```
+
+## Conversations & Tasks
+
+Group spans into conversations (sessions) and tasks:
+
+```python
+span = am.track(
+    "generate_code",
+    model="claude-sonnet-4-20250514",
+    conversation_id="conv-abc123",
+    task_id="implement-feature-x",
+)
+```
+
+## Protocol
+
+The SDK sends spans as OTLP-compatible JSON to `POST /v1/traces`. This is the
+same format used by OpenTelemetry, making it compatible with any OTLP collector.

agentmeter_obs-0.1.0/agent_meter/__init__.py

@@ -0,0 +1,7 @@
+"""Agent Meter Python SDK — track AI agent tool calls in 60 seconds."""
+
+from agent_meter.client import AgentMeter
+from agent_meter.types import ToolCall
+
+__all__ = ["AgentMeter", "ToolCall"]
+__version__ = "0.1.0"

agentmeter_obs-0.1.0/agent_meter/client.py

@@ -0,0 +1,192 @@
+"""Agent Meter client — batches and flushes tool calls via OTLP JSON."""
+
+from __future__ import annotations
+
+import atexit
+import os
+import threading
+import time
+from typing import Optional
+
+import httpx
+
+from agent_meter.types import ToolCall
+
+_DEFAULT_ENDPOINT = "http://localhost:8081"
+_FLUSH_INTERVAL = 5.0  # seconds
+_MAX_BATCH = 100
+
+
+class AgentMeter:
+    """Lightweight client that buffers tool calls and flushes to agent-meter.
+
+    Usage::
+
+        from agent_meter import AgentMeter
+
+        am = AgentMeter(api_key="am_live_...")
+        span = am.track("my_tool", model="gpt-4o")
+        # ... do work ...
+        span.finish()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        endpoint: Optional[str] = None,
+        ide: Optional[str] = None,
+        agent: Optional[str] = None,
+        flush_interval: float = _FLUSH_INTERVAL,
+    ):
+        self._api_key = api_key or os.environ.get("AGENT_METER_API_KEY", "")
+        self._endpoint = (
+            endpoint or os.environ.get("AGENT_METER_ENDPOINT", _DEFAULT_ENDPOINT)
+        ).rstrip("/")
+        self._ide = ide or os.environ.get("AGENT_METER_IDE", "python-sdk")
+        self._agent = agent or os.environ.get("AGENT_METER_AGENT")
+        self._buffer: list[ToolCall] = []
+        self._lock = threading.Lock()
+        self._flush_interval = flush_interval
+        self._closed = False
+
+        # Background flush thread
+        self._timer: Optional[threading.Timer] = None
+        self._schedule_flush()
+        atexit.register(self.shutdown)
+
+    def track(
+        self,
+        tool_name: str,
+        *,
+        model: Optional[str] = None,
+        mcp_server: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        task_id: Optional[str] = None,
+        parent_span_id: Optional[str] = None,
+    ) -> ToolCall:
+        """Start tracking a tool call. Call .finish() when done."""
+        span = ToolCall(
+            tool_name=tool_name,
+            model=model,
+            mcp_server=mcp_server,
+            ide=self._ide,
+            agent=self._agent,
+            conversation_id=conversation_id,
+            task_id=task_id,
+            parent_span_id=parent_span_id,
+        )
+        with self._lock:
+            self._buffer.append(span)
+        return span
+
+    def flush(self) -> int:
+        """Flush buffered spans to the server. Returns count sent."""
+        with self._lock:
+            if not self._buffer:
+                return 0
+            batch = self._buffer[:_MAX_BATCH]
+            self._buffer = self._buffer[_MAX_BATCH:]
+
+        payload = self._build_otlp_payload(batch)
+        try:
+            resp = httpx.post(
+                f"{self._endpoint}/v1/traces",
+                json=payload,
+                headers=self._headers(),
+                timeout=10.0,
+            )
+            resp.raise_for_status()
+        except httpx.HTTPError:
+            # Re-queue on failure (best-effort)
+            with self._lock:
+                self._buffer = batch + self._buffer
+            return 0
+        return len(batch)
+
+    def shutdown(self) -> None:
+        """Flush remaining spans and stop background thread."""
+        self._closed = True
+        if self._timer:
+            self._timer.cancel()
+        # Flush all remaining
+        while True:
+            sent = self.flush()
+            if sent == 0:
+                break
+
+    def _schedule_flush(self) -> None:
+        if self._closed:
+            return
+        self._timer = threading.Timer(self._flush_interval, self._tick)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _tick(self) -> None:
+        self.flush()
+        self._schedule_flush()
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"Content-Type": "application/json"}
+        if self._api_key:
+            h["Authorization"] = f"Bearer {self._api_key}"
+        return h
+
+    def _build_otlp_payload(self, spans: list[ToolCall]) -> dict:
+        """Build OTLP-compatible JSON payload."""
+        otlp_spans = []
+        for s in spans:
+            attrs = [{"key": "tool.name", "value": {"stringValue": s.tool_name}}]
+            if s.model:
+                attrs.append({"key": "gen_ai.request.model", "value": {"stringValue": s.model}})
+            if s.mcp_server:
+                attrs.append({"key": "mcp.server", "value": {"stringValue": s.mcp_server}})
+            if s.ide:
+                attrs.append({"key": "ide", "value": {"stringValue": s.ide}})
+            if s.agent:
+                attrs.append({"key": "agent", "value": {"stringValue": s.agent}})
+            if s.conversation_id:
+                attrs.append({"key": "session.id", "value": {"stringValue": s.conversation_id}})
+            if s.task_id:
+                attrs.append({"key": "task.id", "value": {"stringValue": s.task_id}})
+            if s.estimated_input_tokens is not None:
+                attrs.append({"key": "gen_ai.usage.input_tokens", "value": {"intValue": str(s.estimated_input_tokens)}})
+            if s.estimated_output_tokens is not None:
+                attrs.append({"key": "gen_ai.usage.output_tokens", "value": {"intValue": str(s.estimated_output_tokens)}})
+            if s.usd_cost is not None:
+                attrs.append({"key": "cost.usd", "value": {"doubleValue": s.usd_cost}})
+            if s.error:
+                attrs.append({"key": "error.message", "value": {"stringValue": s.error}})
+
+            end_ns = s.ended_at_ns or s.started_at_ns
+            status_code = 1 if s.ok else 2
+            status_msg = s.error or "" if not s.ok else ""
+
+            otlp_spans.append({
+                "traceId": s.trace_id,
+                "spanId": s.span_id,
+                "parentSpanId": s.parent_span_id or "",
+                "name": s.tool_name,
+                "kind": 3,  # INTERNAL
+                "startTimeUnixNano": str(s.started_at_ns),
+                "endTimeUnixNano": str(end_ns),
+                "attributes": attrs,
+                "status": {"code": status_code, "message": status_msg},
+            })
+
+        return {
+            "resourceSpans": [
+                {
+                    "resource": {
+                        "attributes": [
+                            {"key": "service.name", "value": {"stringValue": "agent-meter-sdk-python"}},
+                        ]
+                    },
+                    "scopeSpans": [
+                        {
+                            "scope": {"name": "agent-meter-python", "version": "0.1.0"},
+                            "spans": otlp_spans,
+                        }
+                    ],
+                }
+            ]
+        }

agentmeter_obs-0.1.0/agent_meter/types.py

@@ -0,0 +1,77 @@
+"""Data types for Agent Meter spans/events."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class ToolCall:
+    """A single tool call (span) to be reported."""
+
+    tool_name: str
+    started_at_ns: int = field(default_factory=lambda: time.time_ns())
+    ended_at_ns: Optional[int] = None
+    duration_ms: Optional[int] = None
+    ok: bool = True
+    error: Optional[str] = None
+    model: Optional[str] = None
+    mcp_server: Optional[str] = None
+    ide: Optional[str] = None
+    agent: Optional[str] = None
+    conversation_id: Optional[str] = None
+    task_id: Optional[str] = None
+    trace_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    span_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    parent_span_id: Optional[str] = None
+    estimated_input_tokens: Optional[int] = None
+    estimated_output_tokens: Optional[int] = None
+    usd_cost: Optional[float] = None
+
+    def finish(self, ok: bool = True, error: Optional[str] = None) -> None:
+        """Mark the tool call as finished."""
+        self.ended_at_ns = time.time_ns()
+        self.duration_ms = (self.ended_at_ns - self.started_at_ns) // 1_000_000
+        self.ok = ok
+        if error:
+            self.error = error
+
+    def to_dict(self) -> dict:
+        """Serialize to the ingest payload format."""
+        d: dict = {
+            "tool_name": self.tool_name,
+            "started_at": self.started_at_ns,
+            "ok": self.ok,
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+        }
+        if self.ended_at_ns:
+            d["ended_at"] = self.ended_at_ns
+        if self.duration_ms is not None:
+            d["duration_ms"] = self.duration_ms
+        if self.error:
+            d["error"] = self.error
+        if self.model:
+            d["model"] = self.model
+        if self.mcp_server:
+            d["mcp_server"] = self.mcp_server
+        if self.ide:
+            d["ide"] = self.ide
+        if self.agent:
+            d["agent"] = self.agent
+        if self.conversation_id:
+            d["conversation_id"] = self.conversation_id
+        if self.task_id:
+            d["task_id"] = self.task_id
+        if self.parent_span_id:
+            d["parent_span_id"] = self.parent_span_id
+        if self.estimated_input_tokens is not None:
+            d["estimated_input_tokens"] = self.estimated_input_tokens
+        if self.estimated_output_tokens is not None:
+            d["estimated_output_tokens"] = self.estimated_output_tokens
+        if self.usd_cost is not None:
+            d["usd_cost"] = self.usd_cost
+        return d

agentmeter_obs-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentmeter-obs"
+version = "0.1.0"
+description = "Lightweight SDK to track AI agent tool calls, costs, and latency."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "dnorio", email = "dnorio@users.noreply.github.com" }]
+keywords = ["ai", "agents", "observability", "telemetry", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://github.com/dnorio/agent-meter"
+Repository = "https://github.com/dnorio/agent-meter"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_meter"]

agentmeter_obs-0.1.0/tests/test_sdk.py

@@ -0,0 +1,69 @@
+"""Tests for agent_meter SDK."""
+
+import json
+from unittest.mock import patch, MagicMock
+
+from agent_meter import AgentMeter, ToolCall
+
+
+def test_tool_call_finish():
+    tc = ToolCall(tool_name="test_tool")
+    assert tc.ok is True
+    tc.finish(ok=False, error="timeout")
+    assert tc.ok is False
+    assert tc.error == "timeout"
+    assert tc.duration_ms is not None
+    assert tc.duration_ms >= 0
+
+
+def test_tool_call_to_dict():
+    tc = ToolCall(tool_name="search", model="gpt-4o")
+    tc.finish()
+    d = tc.to_dict()
+    assert d["tool_name"] == "search"
+    assert d["model"] == "gpt-4o"
+    assert d["ok"] is True
+    assert "duration_ms" in d
+
+
+def test_client_track():
+    am = AgentMeter(api_key="test", endpoint="http://localhost:3000", ide="python-sdk", flush_interval=999)
+    span = am.track("my_tool", model="gpt-4o")
+    assert span.tool_name == "my_tool"
+    assert span.ide == "python-sdk"
+    span.finish()
+    am._closed = True  # prevent flush timer
+    if am._timer:
+        am._timer.cancel()
+
+
+def test_client_build_payload():
+    am = AgentMeter(api_key="test", endpoint="http://localhost:3000", flush_interval=999)
+    span = ToolCall(tool_name="code_gen", model="claude-sonnet-4-20250514")
+    span.finish()
+    payload = am._build_otlp_payload([span])
+    assert "resourceSpans" in payload
+    rs = payload["resourceSpans"][0]
+    assert rs["scopeSpans"][0]["spans"][0]["name"] == "code_gen"
+    am._closed = True
+    if am._timer:
+        am._timer.cancel()
+
+
+@patch("agent_meter.client.httpx.post")
+def test_flush_sends_to_server(mock_post):
+    mock_resp = MagicMock()
+    mock_resp.raise_for_status = MagicMock()
+    mock_post.return_value = mock_resp
+
+    am = AgentMeter(api_key="am_live_test", endpoint="http://localhost:3000", flush_interval=999)
+    span = am.track("tool_a")
+    span.finish()
+    sent = am.flush()
+    assert sent == 1
+    mock_post.assert_called_once()
+    call_kwargs = mock_post.call_args
+    assert "/v1/traces" in call_kwargs.args[0] or "/v1/traces" in str(call_kwargs)
+    am._closed = True
+    if am._timer:
+        am._timer.cancel()