agentmetrics-shared 0.2.0__py3-none-any.whl

agentmetrics_shared/__init__.py

@@ -0,0 +1,17 @@
+from .events import (
+    AgentEndEvent,
+    LlmOutputEvent,
+    ToolEndEvent,
+    SessionStartEvent,
+    SessionMetricsEvent,
+    AuditEvent,
+)
+from .pricing import estimate_cost, MODEL_PRICING
+from .redact import scrub_event, RedactionMode
+
+__all__ = [
+    "AgentEndEvent", "LlmOutputEvent", "ToolEndEvent",
+    "SessionStartEvent", "SessionMetricsEvent", "AuditEvent",
+    "estimate_cost", "MODEL_PRICING",
+    "scrub_event", "RedactionMode",
+]

agentmetrics_shared/events.py

@@ -0,0 +1,283 @@
+from __future__ import annotations
+
+import socket
+import time
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _new_id() -> str:
+    return str(uuid.uuid4())
+
+
+def _hostname() -> str:
+    try:
+        return socket.gethostname()
+    except Exception:
+        return ""
+
+
+@dataclass
+class AgentEndEvent:
+    """Canonical agent_end event. Call to_payload() to get the wire dict."""
+
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = field(default_factory=_new_id)
+    ts: int = field(default_factory=_now_ms)
+    event_name: str = "agent_end"
+    redaction_policy_version: str = "v1-strict"
+
+    # Caller must supply these
+    agent_id: str = ""
+    platform: str = ""
+
+    # Auto-detected
+    host_id: str | None = field(default_factory=_hostname)
+
+    status: str = "success"
+    duration_ms: float = 0.0
+
+    model: str | None = None
+    model_provider: str | None = None
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    llm_calls: int = 0
+    tool_calls: int = 0
+    tool_errors: int = 0
+    tool_names: list[str] = field(default_factory=list)
+
+    estimated_cost_usd: float | None = None
+
+    step_count: int = 0
+    loop_count: int = 0
+
+    skills_loaded_count: int = 0
+    skill_names_hash: str | None = None
+    memory_writes_count: int = 0
+    session_search_calls: int = 0
+    delegation_depth: int = 0
+
+    run_id: str | None = None
+    session_id: str | None = None
+    span_id: str | None = None
+    parent_span_id: str | None = None
+    parent_trace_id: str | None = None
+
+    cronjob_id: str | None = None
+    cron_run_id: str | None = None
+
+    error: str | None = None
+
+    secrets_blocked_count: int = 0
+    pii_detected_count: int = 0
+
+    workflow_id: str | None = None
+    skill_name: str | None = None
+    toolset: str | None = None
+    sdk_version: str | None = None
+
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_payload(self) -> dict[str, Any]:
+        """Return a wire-format dict for this event.
+
+        Always-included fields: event_id, trace_id, ts, event_name, agent_id,
+        platform, status, redaction_policy_version, tool_calls, tool_errors,
+        tool_names, input_tokens, output_tokens, duration_ms.
+
+        Optional fields are included only when non-None / non-empty / non-zero.
+        total_tokens is computed when any token count > 0.
+        """
+        payload: dict[str, Any] = {
+            "event_id":                 self.event_id,
+            "trace_id":                 self.trace_id,
+            "ts":                       self.ts,
+            "event_name":               self.event_name,
+            "agent_id":                 self.agent_id,
+            "platform":                 self.platform,
+            "status":                   self.status,
+            "redaction_policy_version": self.redaction_policy_version,
+            "tool_calls":               self.tool_calls,
+            "tool_errors":              self.tool_errors,
+            "tool_names":               list(self.tool_names),
+            "input_tokens":             self.input_tokens,
+            "output_tokens":            self.output_tokens,
+            "duration_ms":              self.duration_ms,
+        }
+
+        # Compute total_tokens when any token count is positive
+        total = (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_read_tokens
+            + self.cache_write_tokens
+        )
+        if total > 0:
+            payload["total_tokens"] = total
+
+        # Optional fields — include only when meaningful
+        if self.model:
+            payload["model"] = self.model
+        if self.model_provider:
+            payload["model_provider"] = self.model_provider
+        if self.error:
+            payload["error"] = self.error
+        if self.cache_read_tokens:
+            payload["cache_read_tokens"] = self.cache_read_tokens
+        if self.cache_write_tokens:
+            payload["cache_write_tokens"] = self.cache_write_tokens
+        if self.llm_calls:
+            payload["llm_calls"] = self.llm_calls
+        if self.step_count:
+            payload["step_count"] = self.step_count
+        if self.loop_count:
+            payload["loop_count"] = self.loop_count
+        if self.estimated_cost_usd is not None:
+            payload["estimated_cost_usd"] = self.estimated_cost_usd
+        if self.host_id:
+            payload["host_id"] = self.host_id
+        if self.workflow_id:
+            payload["workflow_id"] = self.workflow_id
+        if self.skill_name:
+            payload["skill_name"] = self.skill_name
+        if self.toolset:
+            payload["toolset"] = self.toolset
+        if self.secrets_blocked_count:
+            payload["secrets_blocked_count"] = self.secrets_blocked_count
+        if self.pii_detected_count:
+            payload["pii_detected_count"] = self.pii_detected_count
+        if self.run_id:
+            payload["run_id"] = self.run_id
+        if self.session_id:
+            payload["session_id"] = self.session_id
+        if self.span_id:
+            payload["span_id"] = self.span_id
+        if self.parent_span_id:
+            payload["parent_span_id"] = self.parent_span_id
+        if self.parent_trace_id:
+            payload["parent_trace_id"] = self.parent_trace_id
+        if self.skills_loaded_count:
+            payload["skills_loaded_count"] = self.skills_loaded_count
+        if self.skill_names_hash:
+            payload["skill_names_hash"] = self.skill_names_hash
+        if self.memory_writes_count:
+            payload["memory_writes_count"] = self.memory_writes_count
+        if self.session_search_calls:
+            payload["session_search_calls"] = self.session_search_calls
+        if self.delegation_depth:
+            payload["delegation_depth"] = self.delegation_depth
+        if self.cronjob_id:
+            payload["cronjob_id"] = self.cronjob_id
+        if self.cron_run_id:
+            payload["cron_run_id"] = self.cron_run_id
+        if self.sdk_version:
+            payload["sdk_version"] = self.sdk_version
+        if self.metadata:
+            payload["metadata"] = self.metadata
+
+        return payload
+
+
+@dataclass
+class SessionStartEvent:
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = ""
+    session_id: str = ""
+    agent_id: str = ""
+    platform: str = ""
+    event_name: str = "session_start"
+    ts: int = field(default_factory=_now_ms)
+    redaction_policy_version: str = "v1-strict"
+
+
+@dataclass
+class SessionMetricsEvent:
+    """Fired once at session end — aggregates all runs in the session."""
+
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = ""
+    session_id: str = ""
+    agent_id: str = ""
+    platform: str = ""
+    event_name: str = "session_metrics"
+    ts: int = field(default_factory=_now_ms)
+    redaction_policy_version: str = "v1-strict"
+
+    duration_ms: int = 0
+    run_count: int = 0
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    total_cache_read_tokens: int = 0
+    total_cache_write_tokens: int = 0
+    total_tool_calls: int = 0
+    total_estimated_cost_usd: float = 0.0
+    compactions: int = 0
+    resets: int = 0
+
+
+@dataclass
+class LlmOutputEvent:
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = ""
+    session_id: str = ""
+    run_id: str = ""
+    agent_id: str = ""
+    platform: str = ""
+    event_name: str = "llm_output"
+    ts: int = field(default_factory=_now_ms)
+    redaction_policy_version: str = "v1-strict"
+
+    model: str = ""
+    provider: str = ""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+    finish_reason: str = ""
+    estimated_cost_usd: float = 0.0
+    span_id: str = ""
+
+
+@dataclass
+class ToolEndEvent:
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = ""
+    session_id: str = ""
+    run_id: str = ""
+    agent_id: str = ""
+    platform: str = ""
+    event_name: str = "tool_end"
+    ts: int = field(default_factory=_now_ms)
+    redaction_policy_version: str = "v1-strict"
+
+    tool_name: str = ""
+    tool_call_id: str = ""
+    duration_ms: int = 0
+    status: str = "success"
+    error: str = ""
+    span_id: str = ""
+    parent_span_id: str = ""
+
+
+@dataclass
+class AuditEvent:
+    """Security/config audit events — redaction changes, access denials, WAL recovery."""
+
+    event_id: str = field(default_factory=_new_id)
+    trace_id: str = ""
+    session_id: str = ""
+    agent_id: str = ""
+    platform: str = ""
+    event_name: str = "audit"
+    ts: int = field(default_factory=_now_ms)
+    status: str = "success"
+    metadata: dict[str, Any] = field(default_factory=dict)

agentmetrics_shared/pricing.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ── Types ─────────────────────────────────────────────────────────────────────
+
+# (input_per_M, output_per_M, cache_read_per_M | None, cache_write_per_M | None)
+_T = tuple[float, float, float | None, float | None]
+
+# ── Method 1: Static table — official provider docs ───────────────────────────
+#
+# Prefix matching: "claude-opus-4-20250514" matches "claude-opus-4".
+# Keys sorted by length (longest first) so "gpt-4o-mini" matches before "gpt-4o".
+#
+# Sources:
+#   Anthropic  : https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching
+#   OpenAI     : https://openai.com/api/pricing/
+#   Google     : https://ai.google.dev/pricing
+#   DeepSeek   : https://api-docs.deepseek.com/quick_start/pricing
+#   AWS Bedrock: https://aws.amazon.com/bedrock/pricing/
+
+MODEL_PRICING: dict[str, _T] = {
+    # ── Anthropic ────────────────────────────────────────────────────────────
+    "claude-opus-4":               (15.00, 75.00,  1.50, 18.75),
+    "claude-sonnet-4":             ( 3.00, 15.00,  0.30,  3.75),
+    "claude-haiku-4":              ( 0.80,  4.00,  0.08,  1.00),
+    "claude-3-7-sonnet":           ( 3.00, 15.00,  0.30,  3.75),
+    "claude-3-5-sonnet":           ( 3.00, 15.00,  0.30,  3.75),
+    "claude-3-5-haiku":            ( 0.80,  4.00,  0.08,  1.00),
+    "claude-3-opus":               (15.00, 75.00,  1.50, 18.75),
+    "claude-3-haiku":              ( 0.25,  1.25,  0.03,  0.30),
+    "claude-3-sonnet":             ( 3.00, 15.00,  None,  None),
+    # ── OpenAI ───────────────────────────────────────────────────────────────
+    "gpt-4.1-nano":                ( 0.10,  0.40,  0.025, None),
+    "gpt-4.1-mini":                ( 0.40,  1.60,  0.10,  None),
+    "gpt-4.1":                     ( 2.00,  8.00,  0.50,  None),
+    "gpt-4o-mini":                 ( 0.15,  0.60,  0.075, None),
+    "gpt-4o":                      ( 2.50, 10.00,  1.25,  None),
+    "gpt-4-turbo":                 (10.00, 30.00,  None,  None),
+    "gpt-4":                       (30.00, 60.00,  None,  None),
+    "gpt-3.5-turbo":               ( 0.50,  1.50,  None,  None),
+    "o3-mini":                     ( 1.10,  4.40,  0.55,  None),
+    "o3":                          (10.00, 40.00,  2.50,  None),
+    "o1-mini":                     ( 1.10,  4.40,  0.55,  None),
+    "o1":                          (15.00, 60.00,  7.50,  None),
+    # ── Google Gemini ─────────────────────────────────────────────────────────
+    "gemini-2.5-pro":              ( 1.25, 10.00,  None,  None),
+    "gemini-2.5-flash":            ( 0.15,  0.60,  None,  None),
+    "gemini-2.0-flash":            ( 0.10,  0.40,  None,  None),
+    "gemini-1.5-pro":              ( 1.25,  5.00,  None,  None),
+    "gemini-1.5-flash":            ( 0.075, 0.30,  None,  None),
+    # ── DeepSeek ─────────────────────────────────────────────────────────────
+    "deepseek-reasoner":           ( 0.55,  2.19,  None,  None),
+    "deepseek-chat":               ( 0.14,  0.28,  None,  None),
+    "deepseek-coder":              ( 0.14,  0.28,  None,  None),
+    # ── Meta / Llama ─────────────────────────────────────────────────────────
+    "llama-4-maverick":            ( 0.27,  0.85,  None,  None),
+    "llama-4-scout":               ( 0.18,  0.59,  None,  None),
+    "llama-3.3-70b":               ( 0.88,  0.88,  None,  None),
+    "llama-3-70b":                 ( 0.65,  2.75,  None,  None),
+    "llama-3-8b":                  ( 0.05,  0.20,  None,  None),
+    # ── Alibaba / Qwen ───────────────────────────────────────────────────────
+    "qwen3-235b":                  ( 4.00, 16.00,  None,  None),
+    "qwen3-32b":                   ( 0.30,  1.20,  None,  None),
+    "qwen3-4b":                    ( 0.02,  0.08,  None,  None),
+    # ── Arcee ────────────────────────────────────────────────────────────────
+    "trinity-large":               ( 0.25,  1.00,  0.25,  0.25),
+    "trinity-mini":                ( 0.045, 0.15,  0.045, 0.045),
+    # ── Together AI / HuggingFace (namespace-stripped prefix keys) ────────────
+    "kimi-k2":                     ( 0.50,  2.80,  None,  None),
+    "deepseek-v3":                 ( 0.60,  1.25,  None,  None),
+    "deepseek-r1":                 ( 3.00,  7.00,  None,  None),
+    # ── Vercel AI Gateway ────────────────────────────────────────────────────
+    "gpt-5.4-pro":                 (30.00, 180.00, None,  None),
+    "gpt-5.4":                     ( 2.50, 15.00,  None,  None),
+    # ── AWS Bedrock ──────────────────────────────────────────────────────────
+    "anthropic.claude-opus-4":     (15.00, 75.00,  None,  None),
+    "anthropic.claude-sonnet-4":   ( 3.00, 15.00,  None,  None),
+    "anthropic.claude-haiku-4":    ( 0.80,  4.00,  None,  None),
+    "anthropic.claude-3-5-sonnet": ( 3.00, 15.00,  None,  None),
+    "anthropic.claude-3-5-haiku":  ( 0.80,  4.00,  None,  None),
+    "amazon.nova-pro":             ( 0.80,  3.20,  None,  None),
+    "amazon.nova-lite":            ( 0.06,  0.24,  None,  None),
+    "amazon.nova-micro":           ( 0.035, 0.14,  None,  None),
+}
+
+_SORTED_KEYS: list[str] = sorted(MODEL_PRICING, key=len, reverse=True)
+
+# ── Method 2: Runtime registry — platforms register their own catalog ─────────
+
+_RUNTIME_REGISTRY: dict[str, _T] = {}
+_SORTED_RUNTIME:   list[str]     = []
+
+
+def register_prices(
+    catalog: dict[str, dict[str, float | None] | _T],
+) -> None:
+    """Register platform-specific model prices at startup.
+
+    Each entry maps a model ID (or prefix) to pricing:
+      { "model-id": {"input": 1.25, "output": 5.00, "cache_read": 0.12, "cache_write": None} }
+    or a 4-tuple: { "model-id": (1.25, 5.00, 0.12, None) }
+
+    Registered prices take precedence over the static table but are overridden
+    by cost_overrides passed directly to estimate_cost().
+    """
+    global _SORTED_RUNTIME
+    for model, pricing in catalog.items():
+        key = model.lower()
+        if isinstance(pricing, dict):
+            entry: _T = (
+                float(pricing.get("input") or 0),
+                float(pricing.get("output") or 0),
+                float(pricing["cache_read"]) if pricing.get("cache_read") is not None else None,
+                float(pricing["cache_write"]) if pricing.get("cache_write") is not None else None,
+            )
+        else:
+            entry = pricing
+        _RUNTIME_REGISTRY[key] = entry
+    _SORTED_RUNTIME = sorted(_RUNTIME_REGISTRY, key=len, reverse=True)
+    logger.debug("agentmetrics: registered %d model price entries", len(_RUNTIME_REGISTRY))
+
+
+# ── Method 3: LiteLLM — optional import, 300+ models ─────────────────────────
+
+def _try_litellm(
+    model_lower: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int,
+    cache_write_tokens: int,
+) -> float | None:
+    """Try litellm's model cost database. Returns None if litellm is not installed
+    or the model is not in its database."""
+    try:
+        import litellm  # type: ignore[import-not-found]
+        cost_map: dict[str, Any] = getattr(litellm, "model_cost", None) or {}
+        if not cost_map:
+            return None
+
+        # litellm uses exact model IDs; try exact, then strip date suffix
+        import re
+        entry = (
+            cost_map.get(model_lower)
+            or cost_map.get(re.sub(r"-\d{8}$", "", model_lower))
+        )
+        if not entry:
+            return None
+
+        in_per_m  = (entry.get("input_cost_per_token")  or 0) * 1_000_000
+        out_per_m = (entry.get("output_cost_per_token") or 0) * 1_000_000
+        cr_raw = entry.get("cache_read_input_token_cost")
+        cw_raw = entry.get("cache_creation_input_token_cost")
+        cr_per_m: float | None = float(cr_raw) * 1_000_000 if cr_raw is not None else None
+        cw_per_m: float | None = float(cw_raw) * 1_000_000 if cw_raw is not None else None
+
+        return _compute((in_per_m, out_per_m, cr_per_m, cw_per_m), input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+    except Exception:
+        return None
+
+
+# ── Method 4: OpenRouter API — explicit opt-in, covers everything OR routes ───
+
+_OPENROUTER_CACHE: dict[str, _T] = {}
+_SORTED_OPENROUTER: list[str]    = []
+
+
+def populate_from_openrouter(
+    api_key: str,
+    base_url: str = "https://openrouter.ai",
+    timeout: int = 15,
+) -> int:
+    """Fetch live model pricing from OpenRouter's /api/v1/models endpoint.
+
+    Call once at application startup. Results are cached in memory for the
+    process lifetime. Returns the number of models successfully loaded.
+
+    Requires network access and a valid OpenRouter API key.
+    """
+    global _SORTED_OPENROUTER
+    url = f"{base_url.rstrip('/')}/api/v1/models"
+    req = urllib.request.Request(
+        url,
+        headers={
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type":  "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data: dict = json.loads(resp.read())
+    except Exception as exc:
+        logger.warning("agentmetrics: populate_from_openrouter failed: %s", exc)
+        return 0
+
+    loaded = 0
+    for m in data.get("data", []):
+        model_id = (m.get("id") or "").lower()
+        if not model_id:
+            continue
+        p = m.get("pricing") or {}
+        prompt     = p.get("prompt")
+        completion = p.get("completion")
+        if prompt is None and completion is None:
+            continue
+        in_per_m  = float(prompt or 0)     * 1_000_000
+        out_per_m = float(completion or 0) * 1_000_000
+        cr_raw = p.get("cache_read") or p.get("cached_prompt") or p.get("input_cache_read")
+        cw_raw = p.get("cache_write") or p.get("cache_creation") or p.get("input_cache_write")
+        cr_per_m: float | None = float(cr_raw) * 1_000_000 if cr_raw is not None else None
+        cw_per_m: float | None = float(cw_raw) * 1_000_000 if cw_raw is not None else None
+        # Store with stripped namespace so lookups work (estimate_cost strips before lookup)
+        key = model_id.split("/", 1)[1] if "/" in model_id else model_id
+        _OPENROUTER_CACHE[key] = (in_per_m, out_per_m, cr_per_m, cw_per_m)
+        loaded += 1
+
+    _SORTED_OPENROUTER = sorted(_OPENROUTER_CACHE, key=len, reverse=True)
+    logger.info("agentmetrics: loaded %d model prices from OpenRouter", loaded)
+    return loaded
+
+
+# ── Core estimation — tries all methods in priority order ─────────────────────
+
+def estimate_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_tokens: int = 0,
+    cache_write_tokens: int = 0,
+    cost_overrides: dict[str, _T] | None = None,
+) -> float | None:
+    """Return USD cost for the given model and token counts, or None if unknown.
+
+    Resolution order:
+      1. cost_overrides  — caller-supplied explicit prices (highest priority)
+      2. Runtime registry — registered via register_prices() at startup
+      3. Static table    — official provider docs (40+ known models)
+      4. LiteLLM         — if litellm is installed (300+ models)
+      5. OpenRouter cache — if populate_from_openrouter() was called
+      6. None            — unknown model, never guesses
+
+    Strips provider namespace: "openai/gpt-4o" → "gpt-4o".
+    Prefix matches versioned IDs: "claude-opus-4-20250514" → "claude-opus-4".
+    """
+    if not any([input_tokens, output_tokens, cache_read_tokens, cache_write_tokens]):
+        return 0.0
+
+    model_lower = (model or "").lower().strip()
+    if not model_lower:
+        return None
+
+    # Strip provider namespace: "openai/gpt-4o" → "gpt-4o"
+    if "/" in model_lower:
+        model_lower = model_lower.split("/", 1)[1]
+
+    # 1. Explicit overrides
+    if cost_overrides:
+        for key in sorted(cost_overrides, key=len, reverse=True):
+            if model_lower.startswith(key.lower()):
+                return _compute(cost_overrides[key], input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+
+    # 2. Runtime registry (platforms register at startup)
+    for key in _SORTED_RUNTIME:
+        if model_lower.startswith(key):
+            return _compute(_RUNTIME_REGISTRY[key], input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+
+    # 3. Static table (official docs, pre-sorted by length)
+    for key in _SORTED_KEYS:
+        if model_lower.startswith(key):
+            return _compute(MODEL_PRICING[key], input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+
+    # 4. LiteLLM (optional import)
+    litellm_result = _try_litellm(model_lower, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+    if litellm_result is not None:
+        return litellm_result
+
+    # 5. OpenRouter cache (if populated at startup)
+    for key in _SORTED_OPENROUTER:
+        if model_lower.startswith(key) or model_lower == key:
+            return _compute(_OPENROUTER_CACHE[key], input_tokens, output_tokens, cache_read_tokens, cache_write_tokens)
+
+    return None  # unknown model — never guesses
+
+
+def _compute(
+    prices: _T,
+    in_t: int,
+    out_t: int,
+    cache_read: int,
+    cache_write: int,
+) -> float:
+    in_p:  float       = prices[0] or 0.0
+    out_p: float       = prices[1] or 0.0
+    cr_p:  float | None = prices[2] if len(prices) > 2 else None
+    cw_p:  float | None = prices[3] if len(prices) > 3 else None
+
+    cost = (in_t / 1_000_000.0) * in_p + (out_t / 1_000_000.0) * out_p
+    if cache_read  and cr_p is not None:
+        cost += (cache_read  / 1_000_000.0) * cr_p
+    if cache_write and cw_p is not None:
+        cost += (cache_write / 1_000_000.0) * cw_p
+    return round(cost, 6)

agentmetrics_shared/redact.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import logging
+import re
+import time
+from enum import Enum
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .config import AgentMetricsConfig
+
+logger = logging.getLogger(__name__)
+
+# Patterns that identify secrets in free-form text.
+# Order matters — more specific patterns first.
+_SECRET_PATTERNS: list[tuple[str, str]] = [
+    (r"sk-[A-Za-z0-9\-_]{20,}", "[REDACTED]"),
+    (r"am_[A-Za-z0-9\-_]{16,}", "[REDACTED]"),
+    # JWT-like tokens (two base64 segments separated by a dot)
+    (r"\bey[A-Za-z0-9\-_]{20,}\.[A-Za-z0-9\-_]{20,}", "[REDACTED]"),
+    # Key-value patterns: api_key=<value>, password: <value>, etc.
+    (
+        r"(?i)(?:api[-_]?key|apikey|api[-_]?token|access[-_]?token|"
+        r"secret|password|passwd|auth)[=:\s\"']+([^\s\"'&,\]\}\n]{8,})",
+        r"\1=[REDACTED]",
+    ),
+]
+
+_COMPILED_PATTERNS: list[tuple[re.Pattern[str], str]] = [
+    (re.compile(p), r) for p, r in _SECRET_PATTERNS
+]
+
+# FNV-1a 32-bit constants for tool name hashing (matches npm package implementation).
+_FNV_OFFSET = 2166136261
+_FNV_PRIME = 16777619
+
+
+class RedactionMode(str, Enum):
+    STRICT = "strict"
+    MODERATE = "moderate"
+    DEBUG = "debug"
+
+
+def active_mode(cfg: AgentMetricsConfig) -> RedactionMode:
+    """Return current redaction mode, honouring debug auto-expiry."""
+    try:
+        mode = RedactionMode(cfg.redaction_mode)
+    except ValueError:
+        mode = RedactionMode.STRICT
+
+    if mode == RedactionMode.DEBUG and cfg.debug_expires_at is not None:
+        if time.time() > cfg.debug_expires_at:
+            logger.info("agentmetrics: debug mode expired — reverting to strict")
+            return RedactionMode.STRICT
+
+    return mode
+
+
+def scrub_secrets(text: str, mode: RedactionMode) -> str:
+    """Remove API keys, tokens, and passwords from a string."""
+    scrubbed, _ = scrub_secrets_and_count(text, mode)
+    return scrubbed
+
+
+def scrub_secrets_and_count(text: str, mode: RedactionMode) -> tuple[str, int]:
+    """Scrub secrets and return (scrubbed_text, replacement_count).
+
+    Counts how many secret patterns were redacted. Used to populate
+    secrets_blocked_count on agent_end events.
+    Always runs in strict and moderate modes; skips in debug mode.
+    """
+    if not text or mode == RedactionMode.DEBUG:
+        return text, 0
+    result = text
+    total = 0
+    for pattern, replacement in _COMPILED_PATTERNS:
+        result, n = pattern.subn(replacement, result)
+        total += n
+    return result, total
+
+
+def redact_tool_name(name: str, cfg: AgentMetricsConfig) -> str | None:
+    """Apply tool name export policy. Returns None when the name must not be sent."""
+    policy = cfg.exported_tool_names
+
+    if policy == "off":
+        return None
+
+    if policy == "blocklist":
+        if name in (cfg.redact_tool_names or []):
+            return _hash_name(name)
+        return name
+
+    if policy == "allowlist":
+        # Only names explicitly in redact_tool_names are exported.
+        if name in (cfg.redact_tool_names or []):
+            return name
+        return None
+
+    if policy == "hash":
+        return _hash_name(name)
+
+    return name
+
+
+def scrub_event(payload: dict[str, Any], mode: RedactionMode) -> dict[str, Any]:
+    """Scrub secrets from all string fields in an event payload dict."""
+    if mode == RedactionMode.DEBUG:
+        return payload
+    result, _ = _scrub_dict_and_count(payload, mode)
+    return result  # type: ignore[return-value]
+
+
+def scrub_event_and_count(payload: dict[str, Any], mode: RedactionMode) -> tuple[dict[str, Any], int]:
+    """Scrub secrets from all string fields, returning (scrubbed_payload, total_blocked).
+
+    Used by _enqueue() to populate secrets_blocked_count on agent_end events.
+    """
+    if mode == RedactionMode.DEBUG:
+        return payload, 0
+    result, total = _scrub_dict_and_count(payload, mode)
+    return result, total  # type: ignore[return-value]
+
+
+def _scrub_dict(obj: Any, mode: RedactionMode) -> Any:  # noqa: ANN401 — recursive Any is intentional
+    result, _ = _scrub_dict_and_count(obj, mode)
+    return result
+
+
+def _scrub_dict_and_count(obj: Any, mode: RedactionMode) -> tuple[Any, int]:  # noqa: ANN401
+    if isinstance(obj, str):
+        return scrub_secrets_and_count(obj, mode)
+    if isinstance(obj, dict):
+        result_dict: dict[str, Any] = {}
+        total = 0
+        for k, v in obj.items():
+            scrubbed_v, n = _scrub_dict_and_count(v, mode)
+            result_dict[k] = scrubbed_v
+            total += n
+        return result_dict, total
+    if isinstance(obj, list):
+        result_list = []
+        total = 0
+        for v in obj:
+            scrubbed_v, n = _scrub_dict_and_count(v, mode)
+            result_list.append(scrubbed_v)
+            total += n
+        return result_list, total
+    return obj, 0
+
+
+def _hash_name(name: str) -> str:
+    """FNV-1a 32-bit hash for tool name pseudonymisation. Same algorithm as npm package."""
+    h = _FNV_OFFSET
+    for byte in name.encode():
+        h = (h ^ byte) * _FNV_PRIME & 0xFFFFFFFF
+    return f"t_{h:08x}"
+
+
+def redaction_policy_version(mode: RedactionMode) -> str:
+    return f"v1-{mode.value}"

agentmetrics_shared-0.2.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: agentmetrics-shared
+Version: 0.2.0
+Summary: Shared event schema, pricing, and redaction for all agentmetrics integrations
+Requires-Python: >=3.11

agentmetrics_shared-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+agentmetrics_shared/__init__.py,sha256=ccB0r1KVmx090UUAY4P17T7Hn7sMTbJaY_zdhP95YYw,448
+agentmetrics_shared/events.py,sha256=8MMH8sTFc8gJDZvCZdANuPssYBPr7-NFMWtwkaI-Hu0,8804
+agentmetrics_shared/pricing.py,sha256=dCwfbwTGoJo_wS5ldiWoaKnn-1RbHp0ZtH7yQ6bKeHo,15097
+agentmetrics_shared/redact.py,sha256=BVgrR68ZnkOoo4Ai-GIPoTf9I51hdYyGZ8zLYj5Or7E,5164
+agentmetrics_shared-0.2.0.dist-info/METADATA,sha256=NkKglAc41DgMkAAZgNwB0ETRQjW91cCZCy4LW0cyE5Q,174
+agentmetrics_shared-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+agentmetrics_shared-0.2.0.dist-info/RECORD,,

agentmetrics_shared-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any