metergraph 0.1.0__py3-none-any.whl

metergraph/_config.py

@@ -0,0 +1,144 @@
+"""ETag-aware, fail-open canary configuration polling."""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any
+
+
+log = logging.getLogger("metergraph")
+
+
+def _bucket(seed: str) -> float:
+    """FNV-1a/64 over UTF-8; kept byte-identical to the TypeScript SDK."""
+    value = 0xCBF29CE484222325
+    for byte in seed.encode():
+        value ^= byte
+        value = (value * 0x100000001B3) & 0xFFFF_FFFF_FFFF_FFFF
+    return value / 2**64 * 100
+
+
+def choose_model(
+    route: str,
+    default: str,
+    session_key: str | None,
+    route_config: Mapping[str, Any] | None,
+) -> str:
+    """Deterministically assign a session to a canary arm."""
+    if not route_config or route_config.get("enabled", True) is False:
+        return default
+    incumbent = str(route_config.get("incumbent_model") or default)
+    challenger = route_config.get("challenger_model") or route_config.get("model")
+    if not challenger or not session_key:
+        return incumbent
+    try:
+        percent = float(
+            route_config.get(
+                "traffic_percent",
+                route_config.get("percentage", route_config.get("allocation", 0)),
+            )
+        )
+    except (TypeError, ValueError):
+        return incumbent
+    percent = max(0.0, min(percent, 100.0))
+    seed = ":".join(
+        (
+            route,
+            str(route_config.get("version", "")),
+            str(route_config.get("salt", "")),
+            str(session_key),
+        )
+    )
+    return str(challenger) if _bucket(seed) < percent else incumbent
+
+
+class ConfigPoller:
+    def __init__(
+        self,
+        token: str,
+        base_url: str,
+        *,
+        poll_seconds: float = 30.0,
+        hard_ttl_seconds: float = 120.0,
+    ) -> None:
+        self._token = token
+        self._url = f"{base_url.rstrip('/')}/v1/config"
+        self._poll_seconds = max(1.0, poll_seconds)
+        self._hard_ttl = max(self._poll_seconds, hard_ttl_seconds)
+        self._etag: str | None = None
+        self._routes: dict[str, dict[str, Any]] = {}
+        self._last_success = 0.0
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._run, name="metergraph-config", daemon=True
+        )
+        self._thread.start()
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            self.poll_once()
+            self._stop.wait(self._poll_seconds)
+
+    def poll_once(self) -> bool:
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Accept": "application/json",
+        }
+        if self._etag:
+            headers["If-None-Match"] = self._etag
+        request = urllib.request.Request(self._url, headers=headers)
+        try:
+            with urllib.request.urlopen(request, timeout=5) as response:
+                if response.status == 304:
+                    with self._lock:
+                        self._last_success = time.monotonic()
+                    return True
+                doc = json.loads(response.read())
+                routes = doc.get("routes", {}) if isinstance(doc, dict) else {}
+                if not isinstance(routes, dict):
+                    return False
+                with self._lock:
+                    self._routes = {
+                        str(k): dict(v)
+                        for k, v in routes.items()
+                        if isinstance(v, dict)
+                    }
+                    self._etag = response.headers.get("ETag")
+                    self._last_success = time.monotonic()
+                return True
+        except urllib.error.HTTPError as exc:
+            # urllib raises for 304 even though it is a successful revalidation.
+            if exc.code == 304:
+                with self._lock:
+                    self._last_success = time.monotonic()
+                return True
+            if exc.code in (401, 403):
+                log.warning(
+                    "Metergraph config authentication failed; using default models"
+                )
+                self._stop.set()
+            return False
+        except Exception:
+            return False
+
+    def model_for(self, route: str, default: str, session_key: str | None) -> str:
+        with self._lock:
+            if (
+                not self._last_success
+                or time.monotonic() - self._last_success > self._hard_ttl
+            ):
+                return default
+            config = self._routes.get(route)
+        return choose_model(route, default, session_key, config)
+
+    def stop(self) -> None:
+        self._stop.set()
+        if threading.current_thread() is not self._thread:
+            self._thread.join(timeout=1)

metergraph/_context.py

@@ -0,0 +1,136 @@
+"""Ambient route/session metadata, safe across async call trees."""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+from concurrent.futures import Executor
+from dataclasses import dataclass, field, replace
+from typing import Any, Callable, Mapping
+
+
+@dataclass(frozen=True)
+class CaptureContext:
+    route: str | None = None
+    session_id: str | None = None
+    tags: Mapping[str, str] = field(default_factory=dict)
+    unit_name: str | None = None
+    unit_count: float | None = None
+    capture_text: bool | None = None
+    func_name: str | None = None
+    func_module: str | None = None
+
+
+_current: contextvars.ContextVar[CaptureContext] = contextvars.ContextVar(
+    "metergraph_context", default=CaptureContext()
+)
+
+
+def snapshot() -> CaptureContext:
+    return _current.get()
+
+
+class route:
+    """Route context manager and sync/async decorator."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        unit: str | None = None,
+        unit_count: float | None = None,
+        tags: Mapping[str, Any] | None = None,
+        capture_text: bool | None = None,
+    ) -> None:
+        self.name = str(name)
+        self.unit = str(unit) if unit is not None else None
+        self.unit_count = (
+            float(unit_count) if unit_count is not None else (1.0 if unit else None)
+        )
+        self.tags = {str(k): str(v) for k, v in (tags or {}).items()}
+        self.capture_text = (
+            bool(capture_text) if capture_text is not None else None
+        )
+        self._token: contextvars.Token[CaptureContext] | None = None
+
+    def __enter__(self) -> "route":
+        current = snapshot()
+        merged = {**current.tags, **self.tags}
+        self._token = _current.set(
+            replace(
+                current,
+                route=self.name,
+                tags=merged,
+                unit_name=self.unit if self.unit is not None else current.unit_name,
+                unit_count=self.unit_count
+                if self.unit is not None
+                else current.unit_count,
+                capture_text=self.capture_text
+                if self.capture_text is not None
+                else current.capture_text,
+            )
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._token is not None:
+            _current.reset(self._token)
+            self._token = None
+
+    def __call__(self, fn: Callable):
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapped(*args, **kwargs):
+                with type(self)(
+                    self.name,
+                    unit=self.unit,
+                    unit_count=self.unit_count,
+                    tags=self.tags,
+                    capture_text=self.capture_text,
+                ):
+                    return await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @functools.wraps(fn)
+        def wrapped(*args, **kwargs):
+            with type(self)(
+                self.name,
+                unit=self.unit,
+                unit_count=self.unit_count,
+                tags=self.tags,
+                capture_text=self.capture_text,
+            ):
+                return fn(*args, **kwargs)
+
+        return wrapped
+
+
+def set_session(session_id: str | None) -> None:
+    _current.set(
+        replace(snapshot(), session_id=str(session_id) if session_id else None)
+    )
+
+
+def set_tags(**tags: Any) -> None:
+    current = snapshot()
+    merged = {**current.tags, **{str(k): str(v) for k, v in tags.items()}}
+    _current.set(replace(current, tags=merged))
+
+
+def wrap_executor(executor: Executor) -> Executor:
+    """Propagate the current context into executor submissions."""
+    if getattr(executor, "__metergraph__", False):
+        return executor
+    original_submit = executor.submit
+
+    @functools.wraps(original_submit)
+    def submit(fn, /, *args, **kwargs):
+        ctx = contextvars.copy_context()
+        return original_submit(ctx.run, fn, *args, **kwargs)
+
+    executor.submit = submit  # type: ignore[method-assign]
+    executor.__metergraph__ = True  # type: ignore[attr-defined]
+    return executor

metergraph/_template.py

@@ -0,0 +1,58 @@
+"""Stable, privacy-conscious request fingerprinting for untagged traffic."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+_UUID = re.compile(r"\b[0-9a-f]{8}-[0-9a-f-]{27,}\b", re.I)
+_EMAIL = re.compile(r"\b[^\s@]+@[^\s@]+\.[^\s@]+\b")
+_URL = re.compile(r"\bhttps?://\S+")
+_NUMBER = re.compile(r"(?<![A-Za-z])[-+]?\d+(?:\.\d+)?(?![A-Za-z])")
+_LONG_TOKEN = re.compile(r"\b[A-Za-z0-9_-]{24,}\b")
+_SENSITIVE_KEYS = {"api_key", "apikey", "authorization", "headers", "token", "secret"}
+
+
+def _normalize_text(value: str) -> str:
+    value = _UUID.sub("<uuid>", value)
+    value = _EMAIL.sub("<email>", value)
+    value = _URL.sub("<url>", value)
+    value = _LONG_TOKEN.sub("<token>", value)
+    value = _NUMBER.sub("<n>", value)
+    return " ".join(value.split())
+
+
+def scrub(value: Any) -> Any:
+    if isinstance(value, Mapping):
+        return {
+            str(k): scrub(v)
+            for k, v in value.items()
+            if str(k).lower() not in _SENSITIVE_KEYS
+        }
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
+        return [scrub(item) for item in value]
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
+def template_hash(request: Mapping[str, Any]) -> str:
+    def skeleton(value: Any) -> Any:
+        if isinstance(value, Mapping):
+            return {str(k): skeleton(v) for k, v in sorted(value.items())}
+        if isinstance(value, list):
+            return [skeleton(item) for item in value]
+        if isinstance(value, str):
+            return _normalize_text(value)
+        return value
+
+    encoded = json.dumps(
+        skeleton(scrub(request)), sort_keys=True, separators=(",", ":")
+    )
+    return hashlib.sha256(encoded.encode()).hexdigest()

metergraph/_track.py

@@ -0,0 +1,61 @@
+"""Explicit call-site attribution, overriding the default stack-walk."""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+from dataclasses import replace
+from typing import Callable
+
+from ._context import CaptureContext, _current, snapshot
+
+
+class track:
+    """Attribution context manager and sync/async decorator."""
+
+    def __new__(
+        cls, name: Callable | str | None = None, *, module: str | None = None
+    ):
+        if callable(name):
+            instance = super().__new__(cls)
+            instance.__init__(module=module)
+            return instance(name)
+        return super().__new__(cls)
+
+    def __init__(
+        self, name: str | None = None, *, module: str | None = None
+    ) -> None:
+        self.name = str(name) if name is not None else None
+        self.module = str(module) if module is not None else None
+        self._token: contextvars.Token[CaptureContext] | None = None
+
+    def __enter__(self) -> "track":
+        self._token = _current.set(
+            replace(snapshot(), func_name=self.name, func_module=self.module)
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._token is not None:
+            _current.reset(self._token)
+            self._token = None
+
+    def __call__(self, fn: Callable):
+        name = self.name or f"{fn.__module__}:{fn.__qualname__}"
+        module = self.module or fn.__module__
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapped(*args, **kwargs):
+                with type(self)(name, module=module):
+                    return await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @functools.wraps(fn)
+        def wrapped(*args, **kwargs):
+            with type(self)(name, module=module):
+                return fn(*args, **kwargs)
+
+        return wrapped

metergraph/_transport.py

@@ -0,0 +1,171 @@
+"""Bounded, fire-and-forget HTTP transport using only the stdlib."""
+
+from __future__ import annotations
+
+import gzip
+import json
+import logging
+import os
+import queue
+import threading
+import time
+import urllib.error
+import urllib.request
+from typing import Any
+
+from ._version import SDK_VERSION
+
+
+log = logging.getLogger("metergraph")
+MAX_BATCH_BYTES = 512 * 1024
+
+
+class Writer:
+    def __init__(
+        self,
+        token: str,
+        base_url: str,
+        *,
+        queue_size: int = 2000,
+        batch_size: int = 100,
+        flush_seconds: float = 5.0,
+    ) -> None:
+        self._token = token
+        self._url = f"{base_url.rstrip('/')}/v1/ingest"
+        self._queue_size = max(1, queue_size)
+        self._batch_size = max(1, min(batch_size, 1000))
+        self._flush_seconds = max(0.05, flush_seconds)
+        self._queue: queue.Queue[dict[str, Any]] = queue.Queue(self._queue_size)
+        self._stop = threading.Event()
+        self._flush_now = threading.Event()
+        self._fatal = False
+        self._dropped = 0
+        self._errors = 0
+        self._backoff = 1.0
+        self._retry_at = 0.0
+        self._thread = self._new_thread()
+        self._thread.start()
+        if hasattr(os, "register_at_fork"):
+            os.register_at_fork(after_in_child=self._after_fork)
+
+    @property
+    def dropped(self) -> int:
+        return self._dropped
+
+    def _new_thread(self) -> threading.Thread:
+        return threading.Thread(target=self._run, name="metergraph-writer", daemon=True)
+
+    def _after_fork(self) -> None:
+        # Inherited Queue locks and threads are not safe in the child. Pending
+        # parent rows stay with the parent; the child starts a clean writer.
+        self._queue = queue.Queue(self._queue_size)
+        self._stop = threading.Event()
+        self._flush_now = threading.Event()
+        self._thread = self._new_thread()
+        self._thread.start()
+
+    def enqueue(self, row: dict[str, Any]) -> bool:
+        if self._fatal or self._stop.is_set():
+            self._dropped += 1
+            return False
+        try:
+            self._queue.put_nowait(row)
+            return True
+        except queue.Full:
+            self._dropped += 1
+            return False
+
+    def _run(self) -> None:
+        while not self._stop.is_set() or not self._queue.empty():
+            try:
+                first = self._queue.get(timeout=min(self._flush_seconds, 0.1))
+            except queue.Empty:
+                continue
+            batch = [first]
+            deadline = time.monotonic() + self._flush_seconds
+            while len(batch) < self._batch_size:
+                if self._flush_now.is_set():
+                    break
+                try:
+                    batch.append(self._queue.get_nowait())
+                except queue.Empty:
+                    remaining = deadline - time.monotonic()
+                    if remaining <= 0 or self._stop.is_set():
+                        break
+                    try:
+                        batch.append(self._queue.get(timeout=min(remaining, 0.05)))
+                    except queue.Empty:
+                        continue
+            try:
+                self._deliver(batch)
+            finally:
+                self._flush_now.clear()
+                for _ in batch:
+                    self._queue.task_done()
+
+    def _deliver(self, rows: list[dict[str, Any]]) -> bool:
+        if self._fatal or time.monotonic() < self._retry_at:
+            self._dropped += len(rows)
+            return False
+        meta = {"dropped": self._dropped, "transport_errors": self._errors}
+        body = json.dumps(
+            {"schema_version": 1, "rows": rows, "meta": meta},
+            separators=(",", ":"),
+        ).encode()
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+            "User-Agent": f"metergraph-python/{SDK_VERSION}",
+        }
+        if len(body) > 32 * 1024:
+            body = gzip.compress(body)
+            headers["Content-Encoding"] = "gzip"
+        if len(body) > MAX_BATCH_BYTES:
+            if len(rows) == 1:
+                self._dropped += 1
+                return False
+            midpoint = len(rows) // 2
+            left = self._deliver(rows[:midpoint])
+            right = self._deliver(rows[midpoint:])
+            return left and right
+        request = urllib.request.Request(
+            self._url, data=body, headers=headers, method="POST"
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=5) as response:
+                if response.status != 202:
+                    raise OSError(f"unexpected ingest status {response.status}")
+            self._backoff = 1.0
+            self._retry_at = 0.0
+            return True
+        except urllib.error.HTTPError as exc:
+            if exc.code in (401, 403):
+                self._fatal = True
+                log.warning(
+                    "Metergraph authentication failed; capture disabled for this process"
+                )
+            else:
+                self._failed(len(rows))
+            return False
+        except Exception:
+            self._failed(len(rows))
+            return False
+
+    def _failed(self, count: int) -> None:
+        self._errors += 1
+        self._dropped += count
+        self._retry_at = time.monotonic() + self._backoff
+        self._backoff = min(self._backoff * 2, 60.0)
+
+    def flush(self, timeout: float = 3.0) -> bool:
+        deadline = time.monotonic() + max(0.0, timeout)
+        self._flush_now.set()
+        while self._queue.unfinished_tasks and time.monotonic() < deadline:
+            time.sleep(0.01)
+        return self._queue.unfinished_tasks == 0
+
+    def shutdown(self) -> None:
+        self.flush(3.0)
+        self._stop.set()
+        if threading.current_thread() is not self._thread:
+            self._thread.join(timeout=max(1.0, self._flush_seconds + 0.5))

metergraph/_version.py

@@ -0,0 +1,11 @@
+"""Installed SDK version, resolved once from package metadata."""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+
+try:
+    SDK_VERSION = importlib.metadata.version("metergraph")
+except Exception:
+    SDK_VERSION = "0.1.0"

metergraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: metergraph
+Version: 0.1.0
+Summary: Fire-and-forget LLM spend capture for Metergraph
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+
+# metergraph (Python)
+
+Zero-runtime-dependency capture for OpenAI, Anthropic, and Gemini clients.
+`wrap()` initializes capture from the environment, so setup is one line per
+client; call `metergraph.init(...)` before the first `wrap()` only to pass
+options in code.
+
+```python
+import metergraph
+from openai import OpenAI
+
+# Anthropic() and google-genai's genai.Client() wrap the same way.
+client = metergraph.wrap(OpenAI())
+metergraph.set_session("ticket-123")
+
+with metergraph.route("ticket-classifier", unit="answer", capture_text=True):
+    model = metergraph.model_for("ticket-classifier", default="gpt-4.1-mini")
+    client.chat.completions.create(model=model, messages=[...])
+
+# Emit this after the user-visible task resolves. It shares the bounded async
+# transport and contains no prompt or output content.
+metergraph.record_outcome(
+    "ticket-classifier",
+    model=model,
+    task_completed=True,
+    feedback_score=1,
+    turns_to_resolution=2,
+    escalated=False,
+)
+```
+
+Configuration:
+
+- `METERGRAPH_APP_TOKEN` — required bearer token
+- `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
+- `METERGRAPH_CAPTURE_TEXT=1` — opt in to content capture globally; default is metadata-only
+- `METERGRAPH_DISABLED=1` — process kill switch
+- `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
+
+Delivery is bounded and off the request path. Queue overflow or a collector
+outage drops capture and increments internal counters; it never changes the
+provider call. Each wire batch is bounded to 512 KiB after optional gzip.
+`capture_text=True` or `False` on `route()` overrides the global content policy
+for that route. Config reads are ETag-aware and fail open to the default model.
+`record_outcome` requires a stable session ID and the model actually used so a
+session-sticky canary can compare task completion and optional feedback,
+turn-count, escalation, abandonment, edit-distance, and regeneration signals.
+
+OpenAI Batch API output JSONL is captured per inference when a wrapped
+`client.files.content()` / `retrieve_content()` result is read. Anthropic
+message batches are captured per inference while iterating a wrapped
+`client.messages.batches.results()` result. Run result consumption inside a
+`route()` context so the asynchronous batch retains its product route. Batch
+rows carry real per-result usage and the batch pricing flag; job-management
+polls themselves are not miscounted as model calls.
+
+## Set up with an AI coding agent
+
+Paste this into Claude Code, Codex, Cursor, or any coding agent inside the
+codebase you want instrumented:
+
+```text
+Instrument this codebase's LLM API costs with the `metergraph` PyPI package
+(https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
+then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
+genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
+wrap() returns the same client and initializes itself from the environment:
+METERGRAPH_APP_TOKEN is required (capture is silently off without it) and
+METERGRAPH_INGEST_URL is only for self-hosted servers. Add both to
+.env.example, and never commit a real token. Capture is metadata-only (tokens,
+latency, model, no prompt/completion content) and fail-open, so do not change
+call sites, arguments, or error handling; sync, async, and streaming work
+unchanged. Attribution to the calling function is automatic; optionally pin
+stable names on key LLM-calling functions with @metergraph.track. On
+serverless, call metergraph.flush() before the handler returns. When done,
+list every client you wrapped and flag LLM calls made outside the official
+openai / anthropic / google-genai SDKs, since those are not captured.
+```

metergraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+metergraph/__init__.py,sha256=S7r5T2d92vW16oFXZe1snYzVbWcRny__sTIpxogZHs0,7242
+metergraph/_capture.py,sha256=TLl45sI_7quu5KuJrqb-XH8GELthDjBN5t4u-TTksFQ,38265
+metergraph/_config.py,sha256=6esfubFNAl-Sd9TGlI3WuDCA9iHZFLZfAYqN240pb-8,4820
+metergraph/_context.py,sha256=csWDvHJD6jZbyPv_eRo6SMTl2AQr66tG0u7obbtnYOk,4182
+metergraph/_template.py,sha256=KD5ClwacgrkBnXy7eoOECsZkOduGtiMHuDtrxE6lG7I,1921
+metergraph/_track.py,sha256=kquEubKHOtjRlvvREooPebz0q-1NzXvRJv_w1NAZ7_w,1892
+metergraph/_transport.py,sha256=KVx1ulAwY8chBI_TrPbflVw71idYXXoj3ro4THt6bQU,5921
+metergraph/_version.py,sha256=M4KyFTC7UfwqnN6Sz9tqRIVDCN8lqnWhWmbAtJm4LR8,239
+metergraph-0.1.0.dist-info/METADATA,sha256=cobBY3Xq9hMbLPtqeZxwKUodprtbBn9PsZgKBoBewrw,4022
+metergraph-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+metergraph-0.1.0.dist-info/top_level.txt,sha256=g-B1703jmqYqbs8HfEd41NaGufAL-e95rhe2rU_iyzc,11
+metergraph-0.1.0.dist-info/RECORD,,

metergraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metergraph-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metergraph