metergraph 0.1.0__tar.gz

metergraph-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,78 @@
+# 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/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "metergraph"
+version = "0.1.0"
+description = "Fire-and-forget LLM spend capture for Metergraph"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

metergraph-0.1.0/setup.cfg

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

metergraph-0.1.0/src/metergraph/__init__.py

@@ -0,0 +1,219 @@
+"""Public Metergraph Python SDK."""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from ._capture import Options, Runtime, set_runtime
+from ._capture import wrap as _wrap
+from ._config import ConfigPoller
+from ._context import route, set_session, set_tags, snapshot, wrap_executor
+from ._track import track
+from ._transport import Writer
+from ._version import SDK_VERSION
+
+
+__version__ = SDK_VERSION
+DEFAULT_INGEST_URL = "https://d2xus7mp8zdv6t.cloudfront.net"
+log = logging.getLogger("metergraph")
+_writer: Writer | None = None
+_config: ConfigPoller | None = None
+_initialized = False
+_warned_no_token = False
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.lower() not in {"0", "false", "no", "off"}
+
+
+def init(
+    *,
+    token: str | None = None,
+    ingest_url: str | None = None,
+    capture_text: bool | None = None,
+    redact: Callable[[str, str], str] | None = None,
+    app_root: str | None = None,
+    skip_frames: list[str] | None = None,
+    environment: str | None = None,
+    disabled: bool | None = None,
+) -> None:
+    """Initialize capture. This function is idempotent and never raises."""
+    global _initialized, _warned_no_token, _writer, _config
+    if _initialized:
+        return
+    if os.getenv("METERGRAPH_DISABLED") == "1" or disabled:
+        _initialized = True
+        return
+    token = token or os.getenv("METERGRAPH_APP_TOKEN")
+    ingest_url = ingest_url or os.getenv("METERGRAPH_INGEST_URL") or DEFAULT_INGEST_URL
+    if not token or not ingest_url:
+        # Stay uninitialized so a later init() that supplies a token succeeds.
+        if not _warned_no_token:
+            _warned_no_token = True
+            log.warning(
+                "Metergraph capture disabled: token and ingest URL are required"
+            )
+        return
+    _initialized = True
+    try:
+        _writer = Writer(
+            token,
+            ingest_url,
+            queue_size=int(os.getenv("METERGRAPH_QUEUE_SIZE", "2000")),
+            batch_size=int(os.getenv("METERGRAPH_BATCH_SIZE", "100")),
+            flush_seconds=float(os.getenv("METERGRAPH_FLUSH_SECONDS", "5")),
+        )
+        options = Options(
+            capture_text=(
+                _env_bool("METERGRAPH_CAPTURE_TEXT", False)
+                if capture_text is None
+                else capture_text
+            ),
+            redact=redact,
+            app_root=os.path.realpath(app_root or os.getcwd()),
+            skip_frames=tuple(skip_frames or ()),
+            environment=environment or os.getenv("METERGRAPH_ENV"),
+            text_max_bytes=int(os.getenv("METERGRAPH_TEXT_MAX_BYTES", "100000")),
+        )
+        set_runtime(Runtime(_writer, options))
+        _config = ConfigPoller(
+            token,
+            ingest_url,
+            poll_seconds=float(os.getenv("METERGRAPH_CONFIG_POLL_SECONDS", "30")),
+            hard_ttl_seconds=float(
+                os.getenv("METERGRAPH_CONFIG_HARD_TTL_SECONDS", "120")
+            ),
+        )
+        atexit.register(shutdown)
+    except Exception:
+        set_runtime(None)
+        if _writer:
+            _writer.shutdown()
+        _writer = None
+        _config = None
+        log.warning(
+            "Metergraph initialization failed; application is running uninstrumented"
+        )
+
+
+def wrap(client: Any, *, provider: str | None = None) -> Any:
+    """Wrap an OpenAI, Anthropic, or Google client for capture.
+
+    Calls init() automatically, so with env-var configuration this is the
+    only setup line needed. Call init(...) first to pass options in code.
+    """
+    init()
+    return _wrap(client, provider=provider)
+
+
+def model_for(route_name: str, *, default: str, session_key: str | None = None) -> str:
+    """Return a sticky canary model, or the incumbent on every failure path."""
+    if _config is None:
+        return default
+    return _config.model_for(route_name, default, session_key or snapshot().session_id)
+
+
+def record_outcome(
+    route_name: str,
+    *,
+    model: str,
+    task_completed: bool,
+    session_key: str | None = None,
+    feedback_score: float | None = None,
+    turns_to_resolution: int | None = None,
+    escalated: bool | None = None,
+    abandoned: bool | None = None,
+    edit_distance_ratio: float | None = None,
+    regeneration_count: int | None = None,
+    event_id: str | None = None,
+) -> bool:
+    """Enqueue a content-free real outcome without touching the request path."""
+    if _writer is None or not isinstance(task_completed, bool):
+        return False
+    route_name = str(route_name).strip()[:512]
+    model = str(model).strip()[:512]
+    session_key = str(session_key or snapshot().session_id or "").strip()[:512]
+    event_id = str(event_id or uuid.uuid4()).strip()[:128]
+    try:
+        feedback_score = float(feedback_score) if feedback_score is not None else None
+        turns_to_resolution = (
+            int(turns_to_resolution) if turns_to_resolution is not None else None
+        )
+        edit_distance_ratio = (
+            float(edit_distance_ratio) if edit_distance_ratio is not None else None
+        )
+        regeneration_count = (
+            int(regeneration_count) if regeneration_count is not None else None
+        )
+    except (TypeError, ValueError, OverflowError):
+        return False
+    if not route_name or not model or not session_key or not event_id:
+        return False
+    if feedback_score is not None and not -1 <= feedback_score <= 1:
+        return False
+    if turns_to_resolution is not None and not 1 <= turns_to_resolution <= 1_000_000:
+        return False
+    if edit_distance_ratio is not None and not 0 <= edit_distance_ratio <= 1:
+        return False
+    if regeneration_count is not None and not 0 <= regeneration_count <= 1_000_000:
+        return False
+    if escalated is not None and not isinstance(escalated, bool):
+        return False
+    if abandoned is not None and not isinstance(abandoned, bool):
+        return False
+    return _writer.enqueue(
+        {
+            "event_type": "outcome",
+            "event_id": event_id,
+            "ts": datetime.now(timezone.utc).isoformat(),
+            "route": route_name,
+            "session_id": session_key,
+            "model": model,
+            "task_completed": task_completed,
+            "feedback_score": feedback_score,
+            "turns_to_resolution": turns_to_resolution,
+            "escalated": escalated,
+            "abandoned": abandoned,
+            "edit_distance_ratio": edit_distance_ratio,
+            "regeneration_count": regeneration_count,
+        }
+    )
+
+
+def flush(timeout: float = 3.0) -> bool:
+    return True if _writer is None else _writer.flush(timeout)
+
+
+def shutdown() -> None:
+    global _writer, _config
+    if _config:
+        _config.stop()
+        _config = None
+    if _writer:
+        _writer.shutdown()
+        _writer = None
+    set_runtime(None)
+
+
+__all__ = [
+    "DEFAULT_INGEST_URL",
+    "flush",
+    "init",
+    "model_for",
+    "record_outcome",
+    "route",
+    "set_session",
+    "set_tags",
+    "shutdown",
+    "track",
+    "wrap",
+    "wrap_executor",
+]