frugal-sdk-python 0.1.0__tar.gz → 0.3.0__tar.gz

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frugal-sdk-python
-Version: 0.1.0
+Version: 0.3.0
 Summary: Instrumentation for Cost-to-Code attribution.
 Project-URL: Homepage, https://frugal.co
 Author: Frugal AI Inc.
@@ -78,6 +78,7 @@ Set both or the wrapper silently returns the client unmodified:
 | `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. |
 | `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_API_KEY`. Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
 | `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. |
+| `FRUGAL_CUSTOM_PROVIDERS`                | Comma-separated allowlist of provider names beyond the built-in registry (e.g. `together_ai,fireworks`) that should pass through verbatim on `gen_ai.system` / `gen_ai.provider.name` instead of being coerced to `custom`. Capped at 10 (extras are coerced) to keep label cardinality bounded. |
 | `FRUGAL_PATH_BLOCK_LIST`                 | Comma-separated repo-relative paths to skip for caller attribution (see below).          |
 | `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds. Default `60000`.                                         |
 | `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute. Default `500`. Set to `0` to disable. |
@@ -113,9 +114,9 @@ Every metric carries this base attribute set:
 
 - `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
 - `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
-- `gen_ai.system` — `openai`, `anthropic`, `aws.bedrock`, or `vertex_ai`
+- `gen_ai.system` + `gen_ai.provider.name` — the provider, dual-emitted under both the legacy and current OTel attribute (`openai`, `anthropic`, `aws.bedrock`, `vertex_ai`/`gcp.vertex_ai`, …, or `custom`). Set via the `system` kwarg; an unrecognized value is coerced to `custom` with a one-time warning. See [`docs/metrics-reference.md`](docs/metrics-reference.md#attributes).
 - `gen_ai.request.model`, `gen_ai.response.model` — the model used
-- `gen_ai.operation.name` — `chat`, `text_completion`, or `embeddings`
+- `gen_ai.operation.name` — `chat`, `text_completion`, `embeddings`, `generate_content`, `execute_tool`, `create_agent`, `invoke_agent`, or `other` (the sentinel an unrecognized operation coerces to)
 - `frugal.batched` — `true` for batch-API submissions, `false` otherwise
 
 The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
@@ -140,6 +141,50 @@ profile prefixes (`us.`, `eu.`, `jp.`, `apac.`, `au.`, `global.`) are
 preserved in `gen_ai.request.model`. Async clients (`aiobotocore` /
 `aioboto3`) are detected automatically. See [`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrap_bedrock) for the full Bedrock walkthrough.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model gateway, a CLI shell-out, or an internal helper that returns raw usage — mark the call site yourself and feed in the usage you have. You get the same metrics and the same caller attribution as the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+The `with` block times the call and emits metrics on exit — or an error metric if the block raises (the exception always propagates). Works the same around an `await` in async code. Call `span.set_usage(...)` once the response is back; if you never call it, you still get a call-count and latency point.
+
+For calls that span function boundaries — where a single `with` block won't fit — use the manual handle:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`success()` and `error()` finalize the call exactly once and are idempotent — extra calls are ignored.
+
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
+
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `response_model`.
+
+The same env-var configuration, safety guarantees, and exported metrics apply. See [`docs/quickstart.md`](docs/quickstart.md#custom-call-sites) for the full custom call-site walkthrough.
+
 ## Streaming
 
 Streaming works with no extra setup. The wrapper returns a drop-in replacement that passes events through and emits metrics when the stream finishes.
@@ -180,6 +225,57 @@ FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
 - If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never raise our own exceptions into your code.
 - Wrapping is idempotent — calling `wrap_openai(client)` twice on the same client is safe.
 
+## Debugging
+
+The SDK is silent by design — when misconfigured it degrades to a no-op. To see *why* it is doing nothing (missing env var, instrument-build failure, cardinality-cap hit, a metric export that keeps failing), register a debug callback:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    # level: "info" | "warn" | "error"
+    # message: human-readable string
+    # context: optional dict of structured detail, e.g. {"stage": "setup_failed"}
+    getattr(my_logger, level if level != "warn" else "warning")(
+        "[frugal-metrics] %s", message, extra=context or {}
+    )
+
+set_debug_callback(on_debug)
+```
+
+This is a **structural-diagnostics hook, not a per-call trace**. It only fires for structural or persistent problems — missing/invalid configuration, setup failures, cardinality-cap hits, and *consecutive* export failures (one de-duped `error`, re-armed on the next success). Ordinary transient per-call API errors are never emitted — those are your own API errors and already visible to you.
+
+Notes:
+
+- **A throwing callback is swallowed.** If your callback raises, the exception never escapes into the SDK or your code.
+- **Issues are replayed.** Configuration runs lazily and may happen before you register, so init/config diagnostics emitted beforehand are held in a small bounded buffer and replayed in order the moment you call `set_debug_callback`. Register once at startup to catch them all.
+- The callback is global and thread-safe. Pass `None` to clear it.
+
+## Flushing & graceful shutdown
+
+Metrics export on a periodic interval (default 60s). A short-lived process — a CLI, a job, a serverless invocation, a test run — can exit before the next export, silently dropping its final window of metrics. Use `flush` / `shutdown` to avoid that:
+
+```python
+from frugal_metrics import flush, shutdown
+
+flush()     # force an immediate export; SDK keeps recording afterwards
+shutdown()  # flush + tear down the provider (rebuilt lazily on next wrap)
+```
+
+Both are **safe no-ops when the SDK was never initialized** and never raise.
+
+For processes that exit on their own, opt in to automatic flush-on-exit:
+
+```python
+from frugal_metrics import enable_auto_shutdown
+
+enable_auto_shutdown()  # flush + shutdown via atexit, plus SIGTERM / SIGINT
+```
+
+`enable_auto_shutdown` always registers an `atexit` hook and, when `handle_signals=True` (the default), installs SIGTERM/SIGINT handlers that flush+shutdown and then **chain to whatever handler was previously installed** (so your own handler still runs). Off the main thread, signal registration is unavailable and it falls back to atexit-only. It is **idempotent** — repeat calls register nothing extra.
+
+It is **opt-in** because installing signal handlers is intrusive. If you run your own signal handling, do **not** call `enable_auto_shutdown(handle_signals=True)`; prefer calling `shutdown()` from inside your own handler instead.
+
 ## Verifying the setup
 
 Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.3.0}/README.md

@@ -49,6 +49,7 @@ Set both or the wrapper silently returns the client unmodified:
 | `FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics`. Falls back to `OTEL_EXPORTER_OTLP_ENDPOINT`. |
 | `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Overrides the header built from `FRUGAL_API_KEY`. Falls back to `OTEL_EXPORTER_OTLP_HEADERS`. |
 | `FRUGAL_COMPONENTS`                      | Comma-separated logical components (e.g. `ai-handler,reco`). When set, each metric is ALSO emitted once per component (tagged `frugal.component`) on top of the base project series, so usage can be viewed for the whole project or split by component. |
+| `FRUGAL_CUSTOM_PROVIDERS`                | Comma-separated allowlist of provider names beyond the built-in registry (e.g. `together_ai,fireworks`) that should pass through verbatim on `gen_ai.system` / `gen_ai.provider.name` instead of being coerced to `custom`. Capped at 10 (extras are coerced) to keep label cardinality bounded. |
 | `FRUGAL_PATH_BLOCK_LIST`                 | Comma-separated repo-relative paths to skip for caller attribution (see below).          |
 | `FRUGAL_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds. Default `60000`.                                         |
 | `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute. Default `500`. Set to `0` to disable. |
@@ -84,9 +85,9 @@ Every metric carries this base attribute set:
 
 - `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
 - `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
-- `gen_ai.system` — `openai`, `anthropic`, `aws.bedrock`, or `vertex_ai`
+- `gen_ai.system` + `gen_ai.provider.name` — the provider, dual-emitted under both the legacy and current OTel attribute (`openai`, `anthropic`, `aws.bedrock`, `vertex_ai`/`gcp.vertex_ai`, …, or `custom`). Set via the `system` kwarg; an unrecognized value is coerced to `custom` with a one-time warning. See [`docs/metrics-reference.md`](docs/metrics-reference.md#attributes).
 - `gen_ai.request.model`, `gen_ai.response.model` — the model used
-- `gen_ai.operation.name` — `chat`, `text_completion`, or `embeddings`
+- `gen_ai.operation.name` — `chat`, `text_completion`, `embeddings`, `generate_content`, `execute_tool`, `create_agent`, `invoke_agent`, or `other` (the sentinel an unrecognized operation coerces to)
 - `frugal.batched` — `true` for batch-API submissions, `false` otherwise
 
 The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
@@ -111,6 +112,50 @@ profile prefixes (`us.`, `eu.`, `jp.`, `apac.`, `au.`, `global.`) are
 preserved in `gen_ai.request.model`. Async clients (`aiobotocore` /
 `aioboto3`) are detected automatically. See [`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrap_bedrock) for the full Bedrock walkthrough.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model gateway, a CLI shell-out, or an internal helper that returns raw usage — mark the call site yourself and feed in the usage you have. You get the same metrics and the same caller attribution as the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+The `with` block times the call and emits metrics on exit — or an error metric if the block raises (the exception always propagates). Works the same around an `await` in async code. Call `span.set_usage(...)` once the response is back; if you never call it, you still get a call-count and latency point.
+
+For calls that span function boundaries — where a single `with` block won't fit — use the manual handle:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`success()` and `error()` finalize the call exactly once and are idempotent — extra calls are ignored.
+
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`). To also run the sampled prompt analyzer, pass any of `messages` / `system_prompt` / `tools` / `response_format` / `max_tokens`.
+
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `response_model`.
+
+The same env-var configuration, safety guarantees, and exported metrics apply. See [`docs/quickstart.md`](docs/quickstart.md#custom-call-sites) for the full custom call-site walkthrough.
+
 ## Streaming
 
 Streaming works with no extra setup. The wrapper returns a drop-in replacement that passes events through and emits metrics when the stream finishes.
@@ -151,6 +196,57 @@ FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
 - If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never raise our own exceptions into your code.
 - Wrapping is idempotent — calling `wrap_openai(client)` twice on the same client is safe.
 
+## Debugging
+
+The SDK is silent by design — when misconfigured it degrades to a no-op. To see *why* it is doing nothing (missing env var, instrument-build failure, cardinality-cap hit, a metric export that keeps failing), register a debug callback:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    # level: "info" | "warn" | "error"
+    # message: human-readable string
+    # context: optional dict of structured detail, e.g. {"stage": "setup_failed"}
+    getattr(my_logger, level if level != "warn" else "warning")(
+        "[frugal-metrics] %s", message, extra=context or {}
+    )
+
+set_debug_callback(on_debug)
+```
+
+This is a **structural-diagnostics hook, not a per-call trace**. It only fires for structural or persistent problems — missing/invalid configuration, setup failures, cardinality-cap hits, and *consecutive* export failures (one de-duped `error`, re-armed on the next success). Ordinary transient per-call API errors are never emitted — those are your own API errors and already visible to you.
+
+Notes:
+
+- **A throwing callback is swallowed.** If your callback raises, the exception never escapes into the SDK or your code.
+- **Issues are replayed.** Configuration runs lazily and may happen before you register, so init/config diagnostics emitted beforehand are held in a small bounded buffer and replayed in order the moment you call `set_debug_callback`. Register once at startup to catch them all.
+- The callback is global and thread-safe. Pass `None` to clear it.
+
+## Flushing & graceful shutdown
+
+Metrics export on a periodic interval (default 60s). A short-lived process — a CLI, a job, a serverless invocation, a test run — can exit before the next export, silently dropping its final window of metrics. Use `flush` / `shutdown` to avoid that:
+
+```python
+from frugal_metrics import flush, shutdown
+
+flush()     # force an immediate export; SDK keeps recording afterwards
+shutdown()  # flush + tear down the provider (rebuilt lazily on next wrap)
+```
+
+Both are **safe no-ops when the SDK was never initialized** and never raise.
+
+For processes that exit on their own, opt in to automatic flush-on-exit:
+
+```python
+from frugal_metrics import enable_auto_shutdown
+
+enable_auto_shutdown()  # flush + shutdown via atexit, plus SIGTERM / SIGINT
+```
+
+`enable_auto_shutdown` always registers an `atexit` hook and, when `handle_signals=True` (the default), installs SIGTERM/SIGINT handlers that flush+shutdown and then **chain to whatever handler was previously installed** (so your own handler still runs). Off the main thread, signal registration is unavailable and it falls back to atexit-only. It is **idempotent** — repeat calls register nothing extra.
+
+It is **opt-in** because installing signal handlers is intrusive. If you run your own signal handling, do **not** call `enable_auto_shutdown(handle_signals=True)`; prefer calling `shutdown()` from inside your own handler instead.
+
 ## Verifying the setup
 
 Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.3.0}/docs/metrics-reference.md

@@ -45,12 +45,31 @@ calls, token usage) are 100% — never sampled.
 
 | Attribute                  | Example                                    |
 | -------------------------- | ------------------------------------------ |
-| `gen_ai.system`            | `openai` \| `anthropic` \| `aws.bedrock` \| `vertex_ai` |
-| `gen_ai.operation.name`    | `chat` \| `text_completion` \| `embeddings` |
+| `gen_ai.system`            | `openai` \| `anthropic` \| `aws.bedrock` \| `vertex_ai` \| `az.ai.openai` \| `cohere` \| `mistral_ai` \| `deepseek` \| `groq` \| `perplexity` \| `x_ai` \| `ibm.watsonx.ai` \| `gcp.gemini` \| `custom` (legacy spelling — see below) |
+| `gen_ai.provider.name`     | `openai` \| `anthropic` \| `aws.bedrock` \| `gcp.vertex_ai` \| `azure.ai.openai` \| `cohere` \| `mistral_ai` \| `deepseek` \| `groq` \| `perplexity` \| `x_ai` \| `ibm.watsonx.ai` \| `gcp.gemini` \| `custom` (current OTel attribute) |
+| `gen_ai.operation.name`    | `chat` \| `text_completion` \| `embeddings` \| `generate_content` \| `execute_tool` \| `create_agent` \| `invoke_agent` \| `other` (sentinel for an unrecognized operation) |
 | `gen_ai.request.model`     | `gpt-4o` / `claude-3-5-sonnet-latest` / …   |
 | `gen_ai.response.model`    | Provider-returned model id (often identical)|
 | `gen_ai.token.type`        | `input` \| `output` (token usage metric only) |
 
+> **Provider attribute migration.** OTel renamed `gen_ai.system` to
+> `gen_ai.provider.name` (some spellings changed, e.g. `vertex_ai` →
+> `gcp.vertex_ai`). The SDK **dual-emits both** during the transition: every
+> metric carries the legacy `gen_ai.system` value (so existing queries/history
+> keep matching) and the new `gen_ai.provider.name` value. The `system` kwarg
+> accepts either spelling. A value outside the well-known set (e.g. a typo like
+> `amazon-bedrock`) is **coerced to `custom`** on both labels — so a wrong label
+> never reaches metrics — and surfaced once through the debug callback
+> (`set_debug_callback`), per distinct value (bounded so a high-cardinality
+> caller can't grow the warning set without limit). To keep a legitimate provider
+> that isn't in the registry, register it via `FRUGAL_CUSTOM_PROVIDERS` (up to 10)
+> and it passes through verbatim on both labels. An `operation` outside the accepted set is coerced to
+> the `other` sentinel (NOT `chat`, so a typo can't inflate the real chat series) with the same
+> one-time warning — the seven listed values plus an explicit `other` pass through unchanged. The
+> exported `GenAiSystem` / `GenAiOperation` `Literal` aliases give strict typing for callers who want
+> it — `GenAiSystem` lists both provider spellings the runtime accepts (the kwargs stay `str` so a
+> free-form custom value remains legal).
+
 ### Frugal-added
 
 | Attribute                 | Value                                                      |
@@ -110,6 +129,7 @@ attribute describing where our own code failed. Non-exhaustive list:
 | Claude on AWS Bedrock (via Anthropic SDK)               | `wrap_anthropic(AnthropicBedrock())` | `aws.bedrock`    |
 | AWS Bedrock — any model, AWS SDKs directly              | `wrap_bedrock`                       | `aws.bedrock`    |
 | Claude on Google Vertex                                 | `wrap_anthropic(AnthropicVertex())`  | `vertex_ai`      |
+| Custom / manual call sites                              | `track_ai_call` / `start_ai_call`    | `custom` (override via `system=`) |
 
 `wrap_bedrock` covers all four `bedrock-runtime` operations (`InvokeModel`,
 `InvokeModelWithResponseStream`, `Converse`, `ConverseStream`) on every model

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.3.0}/docs/quickstart.md

@@ -92,6 +92,13 @@ token counts are not (the OpenAI SDK doesn't send them).
 Use `wrap_anthropic` with the Anthropic SDK's `AnthropicBedrock` client. The
 wrapper detects it and tags metrics with `gen_ai.system = aws.bedrock`.
 
+> Every metric is **dual-emitted** under both `gen_ai.system` (legacy) and
+> `gen_ai.provider.name` (current OTel spelling — e.g. `aws.bedrock`,
+> `gcp.vertex_ai`). A provider or operation outside the known set is coerced to
+> the `custom` / `other` sentinel with a one-time warning (via
+> `set_debug_callback`); register extra providers with `FRUGAL_CUSTOM_PROVIDERS`.
+> See [metrics-reference.md](metrics-reference.md#attributes).
+
 ```python
 from anthropic import AnthropicBedrock
 from frugal_metrics import wrap_anthropic
@@ -198,6 +205,65 @@ client = wrap_anthropic(AnthropicVertex(region="us-central1", project_id="my-pro
 > integrations are not yet instrumented. The block-list approach below
 > usually covers framework wrappers in the meantime.
 
+## Custom call sites
+
+For AI calls that don't go through a wrapped client — an HTTP call to a model
+gateway, a CLI shell-out, or an internal helper that returns raw usage — mark
+the call site yourself and feed in the usage you have. You get the same metrics
+(tagged `gen_ai.system = custom` by default) and the same caller attribution as
+the auto-wrappers.
+
+```python
+from frugal_metrics import track_ai_call
+
+with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514") as span:
+    res = my_custom_llm_call(prompt)
+    span.set_usage(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+```
+
+The `with` block times the call and emits metrics on exit — or an error metric
+if the block raises (the exception always propagates). Works the same around an
+`await` in async code. Call `span.set_usage(...)` once the response is back; if
+you never call it, you still get a call-count and latency point.
+
+For calls that span function boundaries — where a single `with` block won't fit
+— use the manual handle:
+
+```python
+from frugal_metrics import start_ai_call
+
+span = start_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
+try:
+    res = my_custom_llm_call(prompt)
+    span.success(
+        input_tokens=res.usage.input_tokens,
+        output_tokens=res.usage.output_tokens,
+        response_model=res.model,
+    )
+except BaseException as exc:
+    span.error(exc)
+    raise
+```
+
+`success()` and `error()` finalize the call exactly once and are idempotent —
+extra calls are ignored.
+
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional):
+`system` (→ `gen_ai.system`, default `"custom"`), `operation` (default
+`"chat"`), `request_model` (default `"<unknown>"`). To also run the sampled
+prompt analyzer, pass any of `messages` / `system_prompt` / `tools` /
+`response_format` / `max_tokens`.
+
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional):
+`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`,
+`reasoning_tokens`, `response_model`.
+
+The same env-var configuration, safety guarantees, and exported metrics apply.
+
 ## Attributing the right caller
 
 By default we walk the stack and pick the first frame that is:
@@ -272,6 +338,46 @@ The token-side metrics (`gen_ai.client.token.usage`, `frugal.gen_ai.calls`,
 `frugal.gen_ai.cache_*`, `frugal.gen_ai.output_cap_utilization`) are 100% —
 never sampled.
 
+## See why nothing is exporting (debug callback)
+
+The SDK is silent by design, so when it no-ops you get no feedback. Register a
+debug callback once at startup to surface structural diagnostics (missing config,
+setup failures, cardinality-cap hits, persistent export failures) through your own
+logger:
+
+```python
+from frugal_metrics import set_debug_callback
+
+def on_debug(level, message, context=None):
+    print(f"[frugal-metrics] {level}: {message}", context or {})
+
+set_debug_callback(on_debug)
+```
+
+It is a structural-diagnostics hook, not a per-call trace. A throwing callback is
+swallowed, and issues emitted before you register are replayed on registration —
+so register early. Pass `None` to clear it.
+
+## Flush on shutdown
+
+Export runs on an interval, so a short-lived process can exit before the final
+batch ships. Flush (or shut down) before exit:
+
+```python
+from frugal_metrics import flush, shutdown, enable_auto_shutdown
+
+flush()     # immediate export, keep recording
+shutdown()  # flush + tear down (safe even if never initialized)
+
+enable_auto_shutdown()  # or: opt in to auto flush+shutdown on exit/SIGTERM/SIGINT
+```
+
+`flush` / `shutdown` are safe no-ops when the SDK was never initialized.
+`enable_auto_shutdown` registers an `atexit` hook and (by default) chained
+SIGTERM/SIGINT handlers, and is idempotent; if you manage your own signal
+handlers, call it with `handle_signals=False` (or just call `shutdown()` from
+your handler).
+
 ## Verifying the setup
 
 Point the library at a local collector (or set the endpoint empty to print

frugal_sdk_python-0.3.0/src/frugal_metrics/__init__.py

@@ -0,0 +1,41 @@
+"""frugal-metrics: call-site instrumentation for AI API calls."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from frugal_metrics.debug import set_debug_callback
+from frugal_metrics.providers import (
+    PROVIDERS,
+    GenAiOperation,
+    GenAiSystem,
+    ProviderEntry,
+    normalize_operation,
+    normalize_provider,
+)
+from frugal_metrics.shutdown import enable_auto_shutdown, flush, shutdown
+from frugal_metrics.track import AICallSpan, start_ai_call, track_ai_call
+from frugal_metrics.wrappers.openai import wrap_openai
+from frugal_metrics.wrappers.anthropic import wrap_anthropic
+from frugal_metrics.wrappers.bedrock import wrap_bedrock
+
+__all__ = [
+    "wrap_openai",
+    "wrap_anthropic",
+    "wrap_bedrock",
+    "track_ai_call",
+    "start_ai_call",
+    "AICallSpan",
+    "set_debug_callback",
+    "flush",
+    "shutdown",
+    "enable_auto_shutdown",
+    "PROVIDERS",
+    "ProviderEntry",
+    "GenAiSystem",
+    "GenAiOperation",
+    "normalize_provider",
+    "normalize_operation",
+]
+try:
+    __version__ = version("frugal-sdk-python")
+except PackageNotFoundError:
+    __version__ = "0+unknown"

{frugal_sdk_python-0.1.0 → frugal_sdk_python-0.3.0}/src/frugal_metrics/config.py

@@ -35,12 +35,15 @@ import os
 import threading
 from dataclasses import dataclass, field
 
+from frugal_metrics.debug import emit_log, emit_log_once
+
 logger = logging.getLogger("frugal_metrics")
 
 _ENV_API_KEY = "FRUGAL_API_KEY"
 _ENV_CUSTOMER_ID = "FRUGAL_CUSTOMER_ID"
 _ENV_PROJECT_ID = "FRUGAL_PROJECT_ID"
 _ENV_COMPONENTS = "FRUGAL_COMPONENTS"
+_ENV_CUSTOM_PROVIDERS = "FRUGAL_CUSTOM_PROVIDERS"
 _ENV_REPO_ROOT = "FRUGAL_REPO_ROOT"
 _ENV_PATH_BLOCK_LIST = "FRUGAL_PATH_BLOCK_LIST"
 _ENV_DISABLED = "FRUGAL_DISABLED"
@@ -56,6 +59,8 @@ _ENV_PROMPT_ANALYSIS_SAMPLE_RATE = "FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE"
 _DEFAULT_OTLP_ENDPOINT = "https://metrics.frugal.co/opentelemetry/v1/metrics"
 _DEFAULT_MAX_CALL_SITES = 500
 _DEFAULT_PROMPT_ANALYSIS_SAMPLE_RATE = 0.1
+# Upper bound on customer-registered provider names — keeps label cardinality bounded.
+_MAX_CUSTOM_PROVIDERS = 10
 
 _warned_once = False
 _warned_lock = threading.Lock()
@@ -70,6 +75,10 @@ class Config:
     repo_root: str
     # Optional logical components; metrics fan out one extra series per entry.
     components: tuple[str, ...] = field(default_factory=tuple)
+    # Customer-registered provider names (beyond the built-in OTel registry) that
+    # pass through verbatim instead of being coerced to "custom". Capped to keep
+    # gen_ai.system / gen_ai.provider.name cardinality bounded.
+    custom_providers: tuple[str, ...] = field(default_factory=tuple)
     path_block_list: tuple[str, ...] = field(default_factory=tuple)
     otlp_endpoint: str = _DEFAULT_OTLP_ENDPOINT
     otlp_headers: str | None = None
@@ -92,6 +101,7 @@ def _warn_once(message: str) -> None:
             return
         _warned_once = True
     logger.warning("frugal-metrics disabled: %s", message)
+    emit_log("warn", f"disabled: {message}")
 
 
 def load_config() -> Config | None:
@@ -154,6 +164,28 @@ def load_config() -> Config | None:
         entry.strip() for entry in components_raw.split(",") if entry.strip()
     )
 
+    # Optional comma-separated allowlist of custom provider names that pass
+    # through verbatim (e.g. "together_ai,fireworks"). Deduped (order-preserving)
+    # and capped at _MAX_CUSTOM_PROVIDERS so a misconfigured value can't blow up
+    # label cardinality.
+    custom_providers_raw = os.environ.get(_ENV_CUSTOM_PROVIDERS, "")
+    custom_providers_all = list(
+        dict.fromkeys(
+            entry.strip()
+            for entry in custom_providers_raw.split(",")
+            if entry.strip()
+        )
+    )
+    custom_providers = tuple(custom_providers_all[:_MAX_CUSTOM_PROVIDERS])
+    if len(custom_providers_all) > _MAX_CUSTOM_PROVIDERS:
+        emit_log_once(
+            "custom_providers_truncated",
+            "warn",
+            f"{_ENV_CUSTOM_PROVIDERS} lists {len(custom_providers_all)} entries; "
+            f"only the first {_MAX_CUSTOM_PROVIDERS} are honored, the rest are "
+            f'coerced to "custom".',
+        )
+
     otlp_endpoint = (
         os.environ.get(_ENV_FRUGAL_OTLP_ENDPOINT)
         or os.environ.get(_ENV_OTLP_ENDPOINT)
@@ -182,6 +214,7 @@ def load_config() -> Config | None:
         project_id=project_id,  # type: ignore[arg-type]
         repo_root=repo_root_abs,
         components=components,
+        custom_providers=custom_providers,
         path_block_list=block_list,
         otlp_endpoint=otlp_endpoint,
         otlp_headers=otlp_headers,
@@ -207,6 +240,10 @@ def _parse_int(raw: str | None, *, default: int) -> int:
             raw,
             default,
         )
+        emit_log(
+            "warn",
+            f"could not parse int env var value {raw!r}; using default {default}",
+        )
         return default
 
 
@@ -221,6 +258,10 @@ def _parse_float(raw: str | None, *, default: float) -> float:
             raw,
             default,
         )
+        emit_log(
+            "warn",
+            f"could not parse float env var value {raw!r}; using default {default}",
+        )
         return default