agentpulse-py 0.0.1__py3-none-any.whl

agentpulse/__init__.py

@@ -0,0 +1,264 @@
+"""
+AgentPulse Python SDK — /agent-metrics ingestion
+
+Zero-config setup via environment variables:
+    AGENTPULSE_API_KEY="at_xxx"
+    AGENTPULSE_URL="https://agentpulse-backend.up.railway.app"   # optional
+    AGENTPULSE_SERVICE="my-agent"            # optional
+
+── Sync usage ────────────────────────────────────────────────────────────────
+
+    import agentpulse
+    import time
+
+    with agentpulse.track_run("my-agent", model="llama-3.3-70b") as run:
+        t0 = time.time_ns()
+        result = llm.call(prompt)
+        run.add_step(
+            "llm_response",
+            input=prompt,
+            output=result.text,
+            tokens=result.usage.total_tokens,
+            latency=(time.time_ns() - t0) // 1_000_000,
+        )
+
+    agentpulse.flush()  # call before process exit
+
+── Async usage ───────────────────────────────────────────────────────────────
+
+    async with agentpulse.async_track_run("my-agent") as run:
+        run.add_step(...)
+
+── Decorator usage ───────────────────────────────────────────────────────────
+
+    @agentpulse.traced_run("my-agent")
+    def handle_query(query: str) -> str:
+        ...
+
+── Manual init (optional, overrides env vars) ────────────────────────────────
+
+    agentpulse.init(
+        api_key="at_xxx",
+        base_url="https://api.agentpulse.io",
+        batch_size=30,
+        flush_interval=3.0,
+    )
+"""
+
+import logging
+import os
+from contextlib import asynccontextmanager, contextmanager
+from functools import wraps
+from typing import Optional, List
+
+from ._config import Config, set_config
+from ._run import AgentRun
+from ._worker import IngestionWorker
+from ._client import send_batch
+from ._wrap_anthropic import wrap_anthropic
+from ._wrap_openai    import wrap_openai
+from ._wrap_gemini    import wrap_gemini
+from ._wrap_grok      import wrap_grok
+from ._wrap_bedrock   import wrap_bedrock
+
+logger = logging.getLogger("agentpulse")
+
+# ── Module-level singleton (set by init / _auto_init) ─────────────────────────
+# These are the ONLY module-level variables. They are written once at startup
+# and then read-only. All per-run state lives in AgentRun instances on the stack.
+
+_worker: Optional[IngestionWorker] = None
+_config: Optional[Config] = None
+
+
+# ── Initialisation ────────────────────────────────────────────────────────────
+
+def init(
+    api_key: str,
+    base_url: str = "https://agentpulse-backend.up.railway.app",
+    service_name: str = "agent",
+    batch_size: int = 20,
+    flush_interval: float = 2.0,
+    max_queue_size: int = 1000,
+    max_retries: int = 4,
+    retry_base_delay: float = 0.5,
+) -> None:
+    """
+    Explicitly initialise the SDK.
+    Optional — env vars (AGENTPULSE_API_KEY etc.) trigger auto-init on import.
+    Calling init() again replaces the worker and config.
+    """
+    global _worker, _config
+
+    _config = Config(
+        api_key=api_key,
+        base_url=base_url.rstrip("/"),
+        service_name=service_name,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+        max_queue_size=max_queue_size,
+        max_retries=max_retries,
+        retry_base_delay=retry_base_delay,
+    )
+    set_config(_config)
+
+    _worker = IngestionWorker(
+        send_fn=lambda batch: send_batch(
+            batch,
+            api_key=_config.api_key,
+            base_url=_config.base_url,
+            max_retries=_config.max_retries,
+            base_delay=_config.retry_base_delay,
+        ),
+        batch_size=_config.batch_size,
+        flush_interval=_config.flush_interval,
+        max_queue_size=_config.max_queue_size,
+    )
+
+
+def configure(
+    api_key: str,
+    base_url: str = "https://agentpulse-backend.up.railway.app",
+    service_name: str = "agent",
+    **kwargs,
+) -> None:
+    """Alias for init() — same API as the agentpulse JS SDK."""
+    init(api_key=api_key, base_url=base_url, service_name=service_name, **kwargs)
+
+
+def _auto_init() -> None:
+    """Called on import. No-op if AGENTPULSE_API_KEY is not set."""
+    key = os.getenv("AGENTPULSE_API_KEY")
+    if not key:
+        return
+    init(
+        api_key=key,
+        base_url=os.getenv("AGENTPULSE_URL", "https://agentpulse-backend.up.railway.app"),
+        service_name=os.getenv("AGENTPULSE_SERVICE", "agent"),
+    )
+
+
+# ── Core: enqueue a finished run ──────────────────────────────────────────────
+
+def _enqueue(run: AgentRun) -> None:
+    """Serialize the run and push it onto the worker queue (non-blocking)."""
+    if _worker is None:
+        # SDK not initialised — silently skip. Don't crash the agent.
+        return
+    _worker.enqueue(run.to_payload())
+
+
+# ── Context managers ──────────────────────────────────────────────────────────
+
+@contextmanager
+def track_run(
+    agent_name: str,
+    *,
+    model: Optional[str] = None,
+    user_id: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+):
+    """
+    Sync context manager for tracking a single agent run.
+
+    - Creates a fresh AgentRun (no shared state).
+    - On success: enqueues the run payload.
+    - On exception: marks the run failed, then enqueues before re-raising.
+
+    Example:
+        with agentpulse.track_run("hotel-search", model="llama-3.3-70b") as run:
+            run.add_step("llm_response", input="...", output="...", tokens=200, latency=350)
+    """
+    run = AgentRun(agent_name, model=model, user_id=user_id, tags=tags)
+    try:
+        yield run
+    except Exception as exc:
+        run.fail(str(exc))
+        raise
+    finally:
+        # Always enqueue — even on failure — so the backend can record the error.
+        _enqueue(run)
+
+
+@asynccontextmanager
+async def async_track_run(
+    agent_name: str,
+    *,
+    model: Optional[str] = None,
+    user_id: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+):
+    """
+    Async context manager. Behaves identically to track_run but works inside
+    async def functions and coroutines.
+
+    The enqueue() call is synchronous and non-blocking (queue.put_nowait),
+    so it is safe to call from async code without await.
+
+    Example:
+        async with agentpulse.async_track_run("my-agent") as run:
+            run.add_step(...)
+    """
+    run = AgentRun(agent_name, model=model, user_id=user_id, tags=tags)
+    try:
+        yield run
+    except Exception as exc:
+        run.fail(str(exc))
+        raise
+    finally:
+        _enqueue(run)
+
+
+# ── Decorator ─────────────────────────────────────────────────────────────────
+
+def traced_run(fn_or_name=None):
+    """
+    Decorator version of track_run. Wraps a function in a tracked run.
+    The first positional string argument (if any) is treated as user input.
+
+    @agentpulse.traced_run                     # uses function name as agent name
+    def my_agent(query): ...
+
+    @agentpulse.traced_run("hotel-search")     # explicit agent name
+    def handle_hotels(query): ...
+    """
+    def _decorator(fn, name: str):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            with track_run(name) as _run:
+                return fn(*args, **kwargs)
+        return wrapper
+
+    if callable(fn_or_name):
+        # Used as @traced_run without arguments
+        return _decorator(fn_or_name, fn_or_name.__name__)
+
+    # Used as @traced_run("name") with an explicit agent name
+    agent_name = fn_or_name or ""
+    def wrapper_factory(fn):
+        return _decorator(fn, agent_name or fn.__name__)
+    return wrapper_factory
+
+
+# ── Shutdown helpers ──────────────────────────────────────────────────────────
+
+def flush(timeout: float = 10.0) -> None:
+    """
+    Block until all queued runs have been sent (or timeout expires).
+
+    Call this at the end of short-lived scripts to ensure nothing is lost:
+
+        if __name__ == "__main__":
+            run_agent(query)
+            agentpulse.flush()
+
+    Long-running services (servers, workers) don't need this — the background
+    thread sends continuously. The atexit handler also provides a best-effort
+    flush on normal process exit.
+    """
+    if _worker:
+        _worker.flush(timeout)
+
+
+# ── Bootstrap (runs once on import) ───────────────────────────────────────────
+_auto_init()

agentpulse/_client.py

@@ -0,0 +1,102 @@
+"""
+HTTP client for /agent-metrics ingestion.
+
+Design decisions:
+- Stdlib only (urllib.request) — no extra dependencies.
+- Each payload is sent as a separate POST. A future batch endpoint on the
+  backend could collapse this into one request per flush cycle.
+- Retries use exponential backoff with jitter to avoid thundering herd when
+  the backend recovers from a blip.
+- Never raises — failure is logged and the payload is discarded. The agent
+  process must never crash due to observability errors.
+"""
+
+import json
+import logging
+import random
+import time
+import urllib.error
+import urllib.request
+from typing import List
+
+logger = logging.getLogger("agentpulse")
+
+
+def send_batch(
+    payloads: List[dict],
+    api_key: str,
+    base_url: str,
+    max_retries: int = 4,
+    base_delay: float = 0.5,
+) -> None:
+    """
+    Send a list of run payloads to /agent-metrics.
+
+    Each payload is sent individually because the current backend endpoint
+    accepts one run per request. The loop is intentionally sequential so we
+    don't hammer the backend with parallel requests from a single worker thread.
+    """
+    url = f"{base_url.rstrip('/')}/agent-metrics"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {api_key}",
+    }
+
+    for payload in payloads:
+        _send_one_with_retry(payload, url, headers, max_retries, base_delay)
+
+
+def _send_one_with_retry(
+    payload: dict,
+    url: str,
+    headers: dict,
+    max_retries: int,
+    base_delay: float,
+) -> bool:
+    """
+    POST a single payload, retrying on transient failures.
+
+    Retryable: network errors, 429, 5xx responses.
+    Non-retryable: 4xx (except 429) — bad payload, wrong key, etc.
+
+    Returns True on success, False after all retries exhausted.
+    """
+    data = json.dumps(payload).encode()
+
+    for attempt in range(max_retries + 1):
+        try:
+            req = urllib.request.Request(url, data=data, method="POST", headers=headers)
+            with urllib.request.urlopen(req, timeout=10):
+                return True  # 2xx — done
+
+        except urllib.error.HTTPError as e:
+            if e.code < 500 and e.code != 429:
+                # 4xx (not rate-limit) — no point retrying, payload is bad
+                logger.error(
+                    "[agentpulse] Permanent error %d for run '%s' — dropping.",
+                    e.code,
+                    payload.get("agentName", "?"),
+                )
+                return False
+
+            # 5xx or 429 — transient, fall through to retry
+            err_msg = f"HTTP {e.code}"
+
+        except Exception as e:
+            err_msg = str(e)
+
+        if attempt < max_retries:
+            # Exponential backoff + small random jitter to spread retries
+            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.1)
+            logger.warning(
+                "[agentpulse] Send failed (attempt %d/%d): %s. Retrying in %.2fs.",
+                attempt + 1, max_retries + 1, err_msg, delay,
+            )
+            time.sleep(delay)
+        else:
+            logger.error(
+                "[agentpulse] Gave up sending run '%s' after %d attempts: %s",
+                payload.get("agentName", "?"), max_retries + 1, err_msg,
+            )
+
+    return False

agentpulse/_config.py

@@ -0,0 +1,34 @@
+"""
+Configuration dataclass for the AgentPulse SDK.
+
+Populated either via agentpulse.init() or auto-read from environment variables.
+Kept as a plain dataclass — no global mutation after init.
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+_active: Optional["Config"] = None
+
+
+@dataclass
+class Config:
+    api_key: str
+    base_url: str = "https://agentpulse-backend.up.railway.app"
+    service_name: str = "agent"
+
+    # Worker tuning
+    batch_size: int = 20          # max runs per flush cycle
+    flush_interval: float = 2.0   # seconds between forced flushes
+    max_queue_size: int = 1000    # drop runs (with warning) if queue exceeds this
+    max_retries: int = 4          # per-run retry attempts (exponential backoff)
+    retry_base_delay: float = 0.5 # seconds — doubles each retry
+
+
+def set_config(cfg: Config) -> None:
+    global _active
+    _active = cfg
+
+
+def get_config() -> Optional[Config]:
+    return _active

agentpulse/_run.py

@@ -0,0 +1,152 @@
+"""
+AgentRun — per-run context object.
+
+One instance is created per agent invocation. It lives entirely on the call
+stack (via context manager / decorator), so there is NO shared mutable state
+between concurrent runs.
+
+Design decisions:
+- Plain object, no threading primitives needed — each run is owned by exactly
+  one coroutine/thread until it's enqueued as an immutable dict payload.
+- Duration is computed at finalization time (on __exit__), not at creation,
+  so the clock starts the moment the context is entered.
+- Steps are appended in order. The caller is responsible for latency timing
+  around individual steps (see example in agent.py).
+"""
+
+import time
+from typing import Optional, List
+
+
+class Step:
+    __slots__ = ("step_type", "input", "output", "tokens", "latency", "cost", "status")
+
+    def __init__(
+        self,
+        step_type: str,
+        input: str = "",
+        output: str = "",
+        tokens: int = 0,
+        latency: int = 0,
+        cost: float = 0.0,
+        status: str = "success",
+    ) -> None:
+        self.step_type = step_type
+        self.input = input
+        self.output = output
+        self.tokens = tokens
+        self.latency = latency   # milliseconds
+        self.cost = cost
+        self.status = status
+
+
+class AgentRun:
+    """
+    Tracks a single agent run. Use via context manager:
+
+        with track_run("my-agent") as run:
+            run.add_step("llm_response", input="...", output="...", tokens=120, latency=400)
+
+    Or async:
+
+        async with async_track_run("my-agent") as run:
+            run.add_step(...)
+
+    Calling run.fail("message") marks the run as failed — useful for explicit
+    error paths. The context manager also catches unhandled exceptions and marks
+    the run failed automatically.
+    """
+
+    def __init__(
+        self,
+        agent_name: str,
+        *,
+        model: Optional[str] = None,
+        user_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        self.agent_name = agent_name
+        self.model = model
+        self.user_id = user_id
+        self.tags = tags or []
+
+        self._steps: List[Step] = []
+        self._total_tokens: int = 0
+        self._total_cost: float = 0.0
+        self._status: str = "success"
+        self._error: Optional[str] = None
+        self._start_ns: int = time.time_ns()  # set at construction = context entry
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def add_step(
+        self,
+        step_type: str,
+        *,
+        input: str = "",
+        output: str = "",
+        tokens: int = 0,
+        latency: int = 0,
+        cost: float = 0.0,
+        status: str = "success",
+    ) -> None:
+        """
+        Record one step (LLM call, tool call, etc.).
+
+        Tip: measure latency yourself around the operation:
+            t0 = time.time_ns()
+            result = llm.call(...)
+            run.add_step("llm_response", latency=(time.time_ns() - t0) // 1_000_000, ...)
+        """
+        self._steps.append(Step(step_type, input, output, tokens, latency, cost, status))
+        self._total_tokens += tokens
+        self._total_cost += cost
+        if status == "failed":
+            # A failed step marks the whole run failed unless already set
+            self._status = "failed"
+
+    def fail(self, error: str) -> None:
+        """Explicitly mark this run as failed with an error message."""
+        self._status = "failed"
+        self._error = error
+
+    # ── Serialization ──────────────────────────────────────────────────────────
+
+    def to_payload(self) -> dict:
+        """
+        Build the /agent-metrics request body.
+        Called once at run end — duration is computed here.
+        """
+        duration_ms = (time.time_ns() - self._start_ns) // 1_000_000
+
+        payload: dict = {
+            "agentName": self.agent_name,
+            "status": self._status,
+            "duration": duration_ms,
+            "tokens": self._total_tokens,
+            "cost": self._total_cost,
+        }
+
+        if self.model:
+            payload["model"] = self.model
+        if self._error:
+            payload["error"] = self._error
+        if self.user_id:
+            payload["userId"] = self.user_id
+        if self.tags:
+            payload["tags"] = self.tags
+        if self._steps:
+            payload["steps"] = [
+                {
+                    "stepType": s.step_type,
+                    "input":    s.input,
+                    "output":   s.output,
+                    "tokens":   s.tokens,
+                    "latency":  s.latency,
+                    "cost":     s.cost,
+                    "status":   s.status,
+                }
+                for s in self._steps
+            ]
+
+        return payload

agentpulse/_send.py

@@ -0,0 +1,87 @@
+"""
+_send.py — Fire-and-forget POST to AgentPulse backend /agent-metrics.
+Uses stdlib only (urllib) — no extra dependencies.
+"""
+
+import json
+import threading
+import urllib.request
+from typing import Any, Dict, Optional
+
+
+def _post(url: str, api_key: str, payload: Dict[str, Any]) -> None:
+    try:
+        data = json.dumps(payload).encode()
+        req  = urllib.request.Request(
+            url,
+            data=data,
+            headers={
+                "Content-Type":  "application/json",
+                "Authorization": f"Bearer {api_key}",
+            },
+            method="POST",
+        )
+        urllib.request.urlopen(req, timeout=10)
+    except Exception:
+        pass  # Never crash the agent
+
+
+def send_to_backend(payload: Dict[str, Any]) -> None:
+    """Fire-and-forget: sends payload in a background thread."""
+    from agentpulse._config import get_config
+    cfg = get_config()
+    if not cfg:
+        return
+    url = f"{cfg.base_url}/agent-metrics"
+    t = threading.Thread(target=_post, args=(url, cfg.api_key, payload), daemon=False)
+    t.start()
+
+
+async def async_send_to_backend(payload: Dict[str, Any]) -> None:
+    """Async fire-and-forget: schedules a background thread via asyncio."""
+    import asyncio
+    from agentpulse._config import get_config
+    cfg = get_config()
+    if not cfg:
+        return
+    url  = f"{cfg.base_url}/agent-metrics"
+    loop = asyncio.get_event_loop()
+    loop.run_in_executor(None, _post, url, cfg.api_key, payload)
+
+
+def build_payload(
+    agent_name:    str,
+    model:         str,
+    prompt:        str,
+    output:        str,
+    input_tokens:  int,
+    output_tokens: int,
+    latency:       int,
+    status:        str,
+    error:         Optional[str] = None,
+) -> Dict[str, Any]:
+    tokens = input_tokens + output_tokens
+    step2: Dict[str, Any] = {
+        "stepType": "llm_response",
+        "input":    "",
+        "output":   output,
+        "tokens":   tokens,
+        "latency":  latency,
+        "status":   status,
+    }
+    if error:
+        step2["error"] = error
+    return {
+        "agentName":    agent_name,
+        "model":        model,
+        "status":       status,
+        "duration":     latency,
+        "tokens":       tokens,
+        "inputTokens":  input_tokens,
+        "outputTokens": output_tokens,
+        "tags":         [],
+        "steps": [
+            {"stepType": "user_prompt", "input": prompt, "output": "", "tokens": 0, "latency": 0, "status": "success"},
+            step2,
+        ],
+    }