metergraph 0.4.0__tar.gz → 0.6.0__tar.gz

metergraph-0.6.0/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

{metergraph-0.4.0 → metergraph-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.4.0
+Version: 0.6.0
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -14,6 +14,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Provides-Extra: dev
+Requires-Dist: build>=1; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
 Requires-Dist: openai>=2.50.0; extra == "dev"
 Requires-Dist: anthropic>=0.40; extra == "dev"
@@ -23,14 +24,18 @@ Requires-Dist: google-genai>=1; extra == "dev"
 
 Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
 Vercel AI Gateway 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.
+Initialize Metergraph once, then wrap each provider client. `init()` reads the
+token and other omitted options from the environment.
+
+Initialization is process-wide. The first `init()` configuration remains
+active; later explicit calls are ignored and produce one generic warning
+without option names, token values, or other secrets.
 
 ```python
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 # Anthropic() and google-genai's genai.Client() wrap the same way.
 client = metergraph.wrap(OpenAI())
 metergraph.set_session("ticket-123")
@@ -61,6 +66,7 @@ import os
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 gateway = metergraph.wrap(OpenAI(
     api_key=os.getenv("AI_GATEWAY_API_KEY") or os.getenv("VERCEL_OIDC_TOKEN"),
     base_url="https://ai-gateway.vercel.sh/v1",
@@ -81,23 +87,32 @@ Configuration:
 
 - `METERGRAPH_APP_TOKEN` — required bearer token
 - `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
+- `METERGRAPH_REPOSITORY` — optional `owner/repository` identity; used by [MeterGraph Bot](https://github.com/apps/metergraph)
 - `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
 - `METERGRAPH_DISABLED=1` — process kill switch
 - `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
 
-SDK 0.4 associates traces with their GitHub repository automatically. On the
-first `init()` in a Git checkout, it reads the `origin` remote and creates
-`.metergraph/config.json` at the repository root if that file is absent.
-Commit this non-secret file so production can use repository-aware ingest
-without Git metadata. An existing file is authoritative and is never changed
-by the SDK. If discovery or creation is unavailable, ingest remains compatible
-with protocol v1.
+Repository identity enables repository-level attribution and
+[MeterGraph Bot](https://github.com/apps/metergraph). Choose any one of these
+options; each is sufficient on its own:
+
+- Pass `repository="owner/repository"` to `metergraph.init()`.
+- Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
+- Store the identity with the source code in `.metergraph/config.json`:
+
+```json
+{"repository":"owner/repository"}
+```
+
+Resolution order is the explicit option, environment variable, then
+configuration file. The SDK treats the file as read-only. Without repository
+identity, it warns once and continues capture without repository attribution.
 
 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.
-SDK 0.4 captures the scrubbed provider request and a normalized response
-envelope, including assistant content and tool calls, by default. Provider
+By default, Metergraph captures the scrubbed provider request and a normalized
+response envelope, including assistant content and tool calls. Provider
 credentials and transport headers are removed. Request and response are each
 limited to 100 KiB of UTF-8 with an explicit truncation marker.
 `capture_text=False` on `route()` or `trace()` overrides the global content
@@ -125,6 +140,35 @@ message batches are captured per inference while iterating a wrapped
 rows carry real per-result usage and the batch pricing flag; job-management
 polls themselves are not miscounted as model calls.
 
+## Batch-first execution (opt-in)
+
+`metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
+
+```python
+import metergraph
+from openai import OpenAI
+
+client = OpenAI()  # unwrapped — batch_first() drives it directly, not through wrap()
+
+outcome = metergraph.batch_first(
+    client, "openai",
+    {"model": "gpt-5-mini", "input": "Summarize this document."},
+    deadline_seconds=60,
+    accept_duplicate_provider_execution=True,  # required: a missed deadline can execute the request twice
+    on_late_batch_settled=lambda info: None,   # fires later, in the background, only for a losing batch
+)
+
+outcome.source                  # "batch" | "direct"
+outcome.result                  # the provider response
+outcome.metadata.batch_outcome  # "completed" | "failed" | "expired" | "pending_at_deadline"
+```
+
+`provider` is `"openai" | "anthropic" | "google"`, matching `wrap()`'s own explicit-provider option — never inferred from the client instance. A request with `stream=True` is rejected before any provider call. A request carrying `tools` is rejected unless `allow_duplicate_tool_call_plans=True` is also set, acknowledging that the batch result and the direct fallback are independent provider executions that may each choose a different tool-call plan. `accept_duplicate_provider_execution` must be exactly `True` — there is no default and no environment-variable override, and a missed deadline can execute (and bill) the same request twice. Neither the batch nor the direct path executes a tool call automatically; the caller receives the tool-call plan in `outcome.result` and is responsible for executing it, exactly as with a normal (non-batch-first) provider response.
+
+`batch_first()` is not integrated with `wrap()`'s capture/telemetry pipeline; its result and metadata are returned directly to the caller, never enqueued for delivery. The background poll that watches a losing batch for late telemetry runs on a daemon thread, which does not keep the process alive — a short-lived script may exit before `on_late_batch_settled` ever fires, silently dropping that signal. This milestone's adapters call their provider client's methods synchronously; `AsyncOpenAI`, `AsyncAnthropic`, and google-genai's `.aio` namespace are not supported.
+
+OpenAI, Anthropic, and Google Gemini all have adapters (`create_openai_batch_adapter`, `create_anthropic_batch_adapter`, `create_google_batch_adapter`), built against each provider's real SDK method signatures — verified by inspecting `openai`, `anthropic`, and `google-genai` as installed from this package's own dev extras, not by a live call — but **none has been exercised against a live provider Batch API from this SDK**. Treat this as a beta-quality, code-reviewed-but-not-live-verified surface.
+
 ## Set up with an AI coding agent
 
 Paste this into Claude Code, Codex, Cursor, or any coding agent inside the
@@ -138,11 +182,13 @@ genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
 OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
 AI Gateway clients and are detected automatically; keep their creator/model ID
 and AI_GATEWAY_API_KEY / VERCEL_OIDC_TOKEN configuration unchanged.
-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. SDK 0.4 captures scrubbed provider
-requests and normalized responses by default for the hosted dashboard; use
+Before wrapping, call metergraph.init(repository="owner/repository") using the
+actual GitHub owner and repository name. METERGRAPH_APP_TOKEN is required; the
+SDK warns and disables capture when it is missing. METERGRAPH_INGEST_URL is
+only for self-hosted servers. Document variable names with placeholders in
+.env.example, and put real values only in deployment configuration. Metergraph
+captures scrubbed provider requests and normalized responses by default for
+the hosted dashboard; use
 METERGRAPH_CAPTURE_TEXT=0 or capture_text=False around sensitive operations.
 Provider credentials and transport headers must never be captured. Capture is
 fail-open, so do not change call sites, arguments, or error handling; sync,

{metergraph-0.4.0 → metergraph-0.6.0}/README.md

@@ -2,14 +2,18 @@
 
 Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
 Vercel AI Gateway 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.
+Initialize Metergraph once, then wrap each provider client. `init()` reads the
+token and other omitted options from the environment.
+
+Initialization is process-wide. The first `init()` configuration remains
+active; later explicit calls are ignored and produce one generic warning
+without option names, token values, or other secrets.
 
 ```python
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 # Anthropic() and google-genai's genai.Client() wrap the same way.
 client = metergraph.wrap(OpenAI())
 metergraph.set_session("ticket-123")
@@ -40,6 +44,7 @@ import os
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 gateway = metergraph.wrap(OpenAI(
     api_key=os.getenv("AI_GATEWAY_API_KEY") or os.getenv("VERCEL_OIDC_TOKEN"),
     base_url="https://ai-gateway.vercel.sh/v1",
@@ -60,23 +65,32 @@ Configuration:
 
 - `METERGRAPH_APP_TOKEN` — required bearer token
 - `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
+- `METERGRAPH_REPOSITORY` — optional `owner/repository` identity; used by [MeterGraph Bot](https://github.com/apps/metergraph)
 - `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
 - `METERGRAPH_DISABLED=1` — process kill switch
 - `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
 
-SDK 0.4 associates traces with their GitHub repository automatically. On the
-first `init()` in a Git checkout, it reads the `origin` remote and creates
-`.metergraph/config.json` at the repository root if that file is absent.
-Commit this non-secret file so production can use repository-aware ingest
-without Git metadata. An existing file is authoritative and is never changed
-by the SDK. If discovery or creation is unavailable, ingest remains compatible
-with protocol v1.
+Repository identity enables repository-level attribution and
+[MeterGraph Bot](https://github.com/apps/metergraph). Choose any one of these
+options; each is sufficient on its own:
+
+- Pass `repository="owner/repository"` to `metergraph.init()`.
+- Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
+- Store the identity with the source code in `.metergraph/config.json`:
+
+```json
+{"repository":"owner/repository"}
+```
+
+Resolution order is the explicit option, environment variable, then
+configuration file. The SDK treats the file as read-only. Without repository
+identity, it warns once and continues capture without repository attribution.
 
 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.
-SDK 0.4 captures the scrubbed provider request and a normalized response
-envelope, including assistant content and tool calls, by default. Provider
+By default, Metergraph captures the scrubbed provider request and a normalized
+response envelope, including assistant content and tool calls. Provider
 credentials and transport headers are removed. Request and response are each
 limited to 100 KiB of UTF-8 with an explicit truncation marker.
 `capture_text=False` on `route()` or `trace()` overrides the global content
@@ -104,6 +118,35 @@ message batches are captured per inference while iterating a wrapped
 rows carry real per-result usage and the batch pricing flag; job-management
 polls themselves are not miscounted as model calls.
 
+## Batch-first execution (opt-in)
+
+`metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
+
+```python
+import metergraph
+from openai import OpenAI
+
+client = OpenAI()  # unwrapped — batch_first() drives it directly, not through wrap()
+
+outcome = metergraph.batch_first(
+    client, "openai",
+    {"model": "gpt-5-mini", "input": "Summarize this document."},
+    deadline_seconds=60,
+    accept_duplicate_provider_execution=True,  # required: a missed deadline can execute the request twice
+    on_late_batch_settled=lambda info: None,   # fires later, in the background, only for a losing batch
+)
+
+outcome.source                  # "batch" | "direct"
+outcome.result                  # the provider response
+outcome.metadata.batch_outcome  # "completed" | "failed" | "expired" | "pending_at_deadline"
+```
+
+`provider` is `"openai" | "anthropic" | "google"`, matching `wrap()`'s own explicit-provider option — never inferred from the client instance. A request with `stream=True` is rejected before any provider call. A request carrying `tools` is rejected unless `allow_duplicate_tool_call_plans=True` is also set, acknowledging that the batch result and the direct fallback are independent provider executions that may each choose a different tool-call plan. `accept_duplicate_provider_execution` must be exactly `True` — there is no default and no environment-variable override, and a missed deadline can execute (and bill) the same request twice. Neither the batch nor the direct path executes a tool call automatically; the caller receives the tool-call plan in `outcome.result` and is responsible for executing it, exactly as with a normal (non-batch-first) provider response.
+
+`batch_first()` is not integrated with `wrap()`'s capture/telemetry pipeline; its result and metadata are returned directly to the caller, never enqueued for delivery. The background poll that watches a losing batch for late telemetry runs on a daemon thread, which does not keep the process alive — a short-lived script may exit before `on_late_batch_settled` ever fires, silently dropping that signal. This milestone's adapters call their provider client's methods synchronously; `AsyncOpenAI`, `AsyncAnthropic`, and google-genai's `.aio` namespace are not supported.
+
+OpenAI, Anthropic, and Google Gemini all have adapters (`create_openai_batch_adapter`, `create_anthropic_batch_adapter`, `create_google_batch_adapter`), built against each provider's real SDK method signatures — verified by inspecting `openai`, `anthropic`, and `google-genai` as installed from this package's own dev extras, not by a live call — but **none has been exercised against a live provider Batch API from this SDK**. Treat this as a beta-quality, code-reviewed-but-not-live-verified surface.
+
 ## Set up with an AI coding agent
 
 Paste this into Claude Code, Codex, Cursor, or any coding agent inside the
@@ -117,11 +160,13 @@ genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
 OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
 AI Gateway clients and are detected automatically; keep their creator/model ID
 and AI_GATEWAY_API_KEY / VERCEL_OIDC_TOKEN configuration unchanged.
-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. SDK 0.4 captures scrubbed provider
-requests and normalized responses by default for the hosted dashboard; use
+Before wrapping, call metergraph.init(repository="owner/repository") using the
+actual GitHub owner and repository name. METERGRAPH_APP_TOKEN is required; the
+SDK warns and disables capture when it is missing. METERGRAPH_INGEST_URL is
+only for self-hosted servers. Document variable names with placeholders in
+.env.example, and put real values only in deployment configuration. Metergraph
+captures scrubbed provider requests and normalized responses by default for
+the hosted dashboard; use
 METERGRAPH_CAPTURE_TEXT=0 or capture_text=False around sensitive operations.
 Provider credentials and transport headers must never be captured. Capture is
 fail-open, so do not change call sites, arguments, or error handling; sync,

{metergraph-0.4.0 → metergraph-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph"
-version = "0.4.0"
+version = "0.6.0"
 description = "Fire-and-forget LLM spend capture for Metergraph"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,7 @@ Repository = "https://github.com/PioneerSquareLabs/metergraphsdk"
 Issues = "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
 
 [project.optional-dependencies]
-dev = ["pytest>=8", "openai>=2.50.0", "anthropic>=0.40", "google-genai>=1"]
+dev = ["build>=1", "pytest>=8", "openai>=2.50.0", "anthropic>=0.40", "google-genai>=1"]
 
 [build-system]
 requires = ["setuptools>=68"]

{metergraph-0.4.0 → metergraph-0.6.0}/src/metergraph/__init__.py

@@ -14,7 +14,14 @@ 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, trace, wrap_executor
-from ._repo_config import ensure_repo_config
+from ._batch_first import (
+    BatchFirstIneligibleError,
+    BatchFirstMetadata,
+    BatchFirstResult,
+    LateBatchInfo,
+    batch_first,
+)
+from ._repo_config import RepoConfig, discover_repo_config
 from ._session import SessionManager
 from ._track import track
 from ._transport import Writer
@@ -29,6 +36,8 @@ _config: ConfigPoller | None = None
 _session_manager: SessionManager | None = None
 _initialized = False
 _warned_no_token = False
+_warned_no_repository = False
+_warned_repeated_init = False
 
 
 def _env_bool(name: str, default: bool) -> bool:
@@ -38,6 +47,17 @@ def _env_bool(name: str, default: bool) -> bool:
     return value.lower() not in {"0", "false", "no", "off"}
 
 
+def _warn_repeated_init() -> None:
+    global _warned_repeated_init
+    if _warned_repeated_init:
+        return
+    _warned_repeated_init = True
+    log.warning(
+        "Metergraph init() was called more than once; "
+        "the first configuration remains active."
+    )
+
+
 def init(
     *,
     token: str | None = None,
@@ -45,13 +65,16 @@ def init(
     capture_text: bool | None = None,
     redact: Callable[[str, str], str] | None = None,
     app_root: str | None = None,
+    repository: 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, _session_manager
+    global _initialized, _warned_no_token, _warned_no_repository
+    global _writer, _config, _session_manager
     if _initialized:
+        _warn_repeated_init()
         return
     if os.getenv("METERGRAPH_DISABLED") == "1" or disabled:
         _initialized = True
@@ -66,10 +89,23 @@ def init(
                 "Metergraph capture disabled: token and ingest URL are required"
             )
         return
-    _initialized = True
     try:
         app_root_resolved = os.path.realpath(app_root or os.getcwd())
-        repo_config = ensure_repo_config(app_root_resolved)
+        repository_value = repository or os.getenv("METERGRAPH_REPOSITORY")
+        repo_config = (
+            RepoConfig(repository_value.strip(), app_root_resolved)
+            if isinstance(repository_value, str)
+            and "/" in repository_value.strip()
+            else discover_repo_config(app_root_resolved)
+        )
+        _initialized = True
+        if repo_config is None and not _warned_no_repository:
+            _warned_no_repository = True
+            log.warning(
+                "Metergraph repository identity is not configured; set "
+                "init(repository='owner/repository'), METERGRAPH_REPOSITORY, "
+                "or provide .metergraph/config.json. Continuing with legacy ingestion."
+            )
         session = (
             SessionManager(
                 token,
@@ -143,7 +179,8 @@ def wrap(client: Any, *, provider: str | None = None) -> Any:
     force gateway handling for a compatible client with a custom URL. Call
     init(...) first to pass Metergraph options in code.
     """
-    init()
+    if not _initialized:
+        init()
     return _wrap(client, provider=provider)
 
 
@@ -248,6 +285,11 @@ def shutdown() -> None:
 
 __all__ = [
     "DEFAULT_INGEST_URL",
+    "BatchFirstIneligibleError",
+    "BatchFirstMetadata",
+    "BatchFirstResult",
+    "LateBatchInfo",
+    "batch_first",
     "flush",
     "init",
     "model_for",