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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: frugal-sdk-python
-Version: 0.3.0
+Version: 0.5.0
 Summary: Instrumentation for Cost-to-Code attribution.
 Project-URL: Homepage, https://frugal.co
 Author: Frugal AI Inc.
@@ -77,12 +77,20 @@ Set both or the wrapper silently returns the client unmodified:
 | `FRUGAL_REPO_ROOT`                       | Absolute path to the source root; the strip prefix for `caller_file`. Defaults to the process working directory. |
 | `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_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. Deduped, and only the first **10** entries are honored (hard cap, not configurable); the rest are dropped at startup with one debug warning. |
 | `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_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; a value outside the first 20 entries (hard cap, not configurable) is coerced to `other`. |
 | `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. |
+| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute; past it `frugal.caller_file` / `frugal.caller_function` become `<overflow>`. Default `500`. Set to `0` to disable. |
+| `FRUGAL_MAX_MODELS`                      | Cardinality cap — max distinct model strings to attribute; past it `gen_ai.request.model` / `gen_ai.response.model` become `<overflow>`. One registry shared by both labels, so a request alias and its dated response snapshot each take a slot. Default `100`. Set to `0` to disable. |
+| `FRUGAL_MAX_SERIES_PER_INSTRUMENT`       | OpenTelemetry's per-instrument limit on distinct attribute **combinations**, raised from the SDK default. Default `50000`. Set to `0` for effectively unlimited (a 1,000,000 ceiling). Applied **only when the installed `opentelemetry-sdk` accepts a per-instrument cardinality limit** — current releases (through 1.42) do not implement one, so nothing is capped and setting this variable emits one `warn` telling you it has no effect. |
 | `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. |
+| `FRUGAL_DUPLICATE_REQUEST_DETECTION`     | Duplicate-request detection (the `frugal.gen_ai.duplicate_requests` metric) is **on by default** and hashes each chat request in-process (the hash never leaves the SDK). Set to `0`/`false`/`no`/`off` to disable — no hashing, no filter memory, no metric. |
+| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `604800` (7 days). |
+| `FRUGAL_DUPLICATE_CAPACITY`              | Expected distinct request signatures per window (sizes the in-memory filter). Default `10000`, max `1000000`. Raise it if the SDK warns the filter is saturated. |
+| `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate of the duplicate filter. Default `0.01`, clamped to `[1e-6, 0.5]`. |
+| `FRUGAL_DUPLICATE_GENERATIONS`           | Rotation granularity of the duplicate filter's time window. Default `2`, max `16`.        |
 | `FRUGAL_DISABLED`                        | Set to `1` to disable all instrumentation without uninstalling.                          |
 
 ## What gets captured
@@ -92,32 +100,40 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | Metric                                  | Kind      | Description                                                  | Additional attributes                  |
 | --------------------------------------- | --------- | ------------------------------------------------------------ | -------------------------------------- |
 | `gen_ai.client.operation.duration`      | histogram | Call latency in seconds                                      | —                                      |
-| `gen_ai.client.token.usage`             | histogram | Input and output token counts                                | `gen_ai.token.type`                    |
-| `frugal.gen_ai.calls`                   | counter   | Number of calls per site                                     | —                                      |
+| `gen_ai.client.token.usage`             | histogram | Input and output token counts                                | `gen_ai.token.type`, `frugal.history_bucket` |
+| `frugal.gen_ai.calls`                   | counter   | Number of calls per site                                     | `frugal.history_bucket`, `frugal.structured_output_mode` |
 | `frugal.gen_ai.cache_read_tokens`       | histogram | Prompt cache hits                                            | —                                      |
 | `frugal.gen_ai.cache_write_tokens`      | histogram | Prompt cache writes                                          | —                                      |
 | `frugal.gen_ai.reasoning_tokens`        | histogram | OpenAI reasoning tokens (o-series), Anthropic thinking tokens| —                                      |
+| `frugal.gen_ai.agent.turns`             | histogram | Model-response turns per successful `invoke_agent` call (manual only) | —                              |
 | `frugal.gen_ai.errors`                  | counter   | Errors by exception type                                     | `frugal.error.type`                    |
-| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality cap, bugs)     | `frugal.internal_error.stage`          |
+| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality caps, bugs)    | `frugal.internal_error.stage`, `frugal.internal_error.type`, `frugal.instrument` |
 | `frugal.gen_ai.output_cap_utilization`  | histogram | `output_tokens / max_tokens` ratio when `max_tokens` is set  | `frugal.structured_output_mode`        |
-| `frugal.gen_ai.history_depth`           | histogram | `messages.length` (analyzer-sampled)                         | —                                      |
+| `frugal.gen_ai.history_depth`           | histogram | `messages.length` — every chat call (100%, not sampled)      | —                                      |
+| `frugal.gen_ai.duplicate_requests`      | counter   | Repeat-request detection — every chat call (100%, not sampled; disable via `FRUGAL_DUPLICATE_REQUEST_DETECTION`) | `frugal.dup_state` |
 | `frugal.gen_ai.few_shot_count`          | histogram | Few-shot exemplar pairs before final user (analyzer-sampled) | —                                      |
+| `frugal.gen_ai.few_shot_tokens`         | histogram | Approx token size of the few-shot example block (analyzer-sampled) | —                                |
 | `frugal.gen_ai.noise_ratio`             | histogram | HTML/base64/whitespace fraction of input (analyzer-sampled)  | —                                      |
 | `frugal.gen_ai.cache_prefix_stable`     | counter   | Per-block prompt-cache stability (analyzer-sampled)          | `frugal.block`, `frugal.stable`        |
 | `frugal.gen_ai.structured_output_hint`  | counter   | "Return JSON" prompts missing `response_format`/`tools`      | —                                      |
 
-The bottom block of analyzer-sampled metrics fires on a fraction of calls
-(`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`, default 10%); the token-side metrics are
-100% — never sampled.
+The analyzer-sampled metrics fire on a fraction of calls
+(`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`, default 10%); the token-side metrics,
+`history_depth`, and `duplicate_requests` are 100% — never sampled.
 
-Every metric carries this base attribute set:
+Every metric carries this base attribute set (except
+`frugal.gen_ai.internal_errors`, which is emitted from failure paths where
+these attributes may not exist yet and carries only `frugal.project_id`, the
+stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
+`frugal.customer_id` / `frugal.custom_label` when 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` + `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.request.model`, `gen_ai.response.model` — the model used; both draw on one shared registry and become `<overflow>` past `FRUGAL_MAX_MODELS` distinct model strings
 - `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
+- `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise
+- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other`
 
 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.
 
@@ -157,6 +173,39 @@ with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
     )
 ```
 
+For an enclosing agent invocation, set `operation="invoke_agent"` and report
+the number of model-response steps performed inside it:
+
+```python
+with track_ai_call(
+    system="anthropic",
+    operation="invoke_agent",
+    request_model="claude-sonnet-4-20250514",
+) as span:
+    result = my_agent_framework_call(prompt)
+    span.set_usage(
+        input_tokens=result.usage.input_tokens,
+        output_tokens=result.usage.output_tokens,
+        agent_turns=result.turn_count,
+    )
+```
+
+- Provider wrappers still measure individual model calls and never set
+  `agent_turns`.
+- Agent frameworks such as the Claude Agent SDK, OpenAI Agents SDK, and
+  LangGraph do not have dedicated wrappers yet; track them manually as shown.
+- `frugal.gen_ai.history_depth` is the request message count
+  (`messages.length`), not a turn count.
+- Missing, non-integer, non-positive, or otherwise invalid `agent_turns`
+  values are silently dropped. They never raise or affect customer execution.
+- Turn data is emitted only on success, like token usage.
+- **Avoid double-counting tokens.** Only report aggregate `input_tokens` /
+  `output_tokens` on the `invoke_agent` call when the agent's inner
+  model-client calls are **not** already wrapped by a supported provider
+  wrapper. If they are wrapped, those wrappers already emit token usage per
+  inner call — report `agent_turns` only on the `invoke_agent` call in that
+  case, or the same tokens are double-counted.
+
 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:
@@ -179,9 +228,9 @@ except BaseException as exc:
 
 `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`.
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). 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`.
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `agent_turns`, `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.
 

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

@@ -48,12 +48,20 @@ Set both or the wrapper silently returns the client unmodified:
 | `FRUGAL_REPO_ROOT`                       | Absolute path to the source root; the strip prefix for `caller_file`. Defaults to the process working directory. |
 | `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_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. Deduped, and only the first **10** entries are honored (hard cap, not configurable); the rest are dropped at startup with one debug warning. |
 | `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_CUSTOM_LABEL`                   | Comma-separated allowlist of values for the `frugal.custom_label` label (e.g. `billing,search`). Applies only to `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; a value outside the first 20 entries (hard cap, not configurable) is coerced to `other`. |
 | `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. |
+| `FRUGAL_MAX_CALL_SITES`                  | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute; past it `frugal.caller_file` / `frugal.caller_function` become `<overflow>`. Default `500`. Set to `0` to disable. |
+| `FRUGAL_MAX_MODELS`                      | Cardinality cap — max distinct model strings to attribute; past it `gen_ai.request.model` / `gen_ai.response.model` become `<overflow>`. One registry shared by both labels, so a request alias and its dated response snapshot each take a slot. Default `100`. Set to `0` to disable. |
+| `FRUGAL_MAX_SERIES_PER_INSTRUMENT`       | OpenTelemetry's per-instrument limit on distinct attribute **combinations**, raised from the SDK default. Default `50000`. Set to `0` for effectively unlimited (a 1,000,000 ceiling). Applied **only when the installed `opentelemetry-sdk` accepts a per-instrument cardinality limit** — current releases (through 1.42) do not implement one, so nothing is capped and setting this variable emits one `warn` telling you it has no effect. |
 | `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls (0..1) that run the lightweight prompt analyzer. Default `0.1`. Set to `0` to disable, `1` for every call. |
+| `FRUGAL_DUPLICATE_REQUEST_DETECTION`     | Duplicate-request detection (the `frugal.gen_ai.duplicate_requests` metric) is **on by default** and hashes each chat request in-process (the hash never leaves the SDK). Set to `0`/`false`/`no`/`off` to disable — no hashing, no filter memory, no metric. |
+| `FRUGAL_DUPLICATE_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `604800` (7 days). |
+| `FRUGAL_DUPLICATE_CAPACITY`              | Expected distinct request signatures per window (sizes the in-memory filter). Default `10000`, max `1000000`. Raise it if the SDK warns the filter is saturated. |
+| `FRUGAL_DUPLICATE_FP_RATE`               | Target false-positive rate of the duplicate filter. Default `0.01`, clamped to `[1e-6, 0.5]`. |
+| `FRUGAL_DUPLICATE_GENERATIONS`           | Rotation granularity of the duplicate filter's time window. Default `2`, max `16`.        |
 | `FRUGAL_DISABLED`                        | Set to `1` to disable all instrumentation without uninstalling.                          |
 
 ## What gets captured
@@ -63,32 +71,40 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | Metric                                  | Kind      | Description                                                  | Additional attributes                  |
 | --------------------------------------- | --------- | ------------------------------------------------------------ | -------------------------------------- |
 | `gen_ai.client.operation.duration`      | histogram | Call latency in seconds                                      | —                                      |
-| `gen_ai.client.token.usage`             | histogram | Input and output token counts                                | `gen_ai.token.type`                    |
-| `frugal.gen_ai.calls`                   | counter   | Number of calls per site                                     | —                                      |
+| `gen_ai.client.token.usage`             | histogram | Input and output token counts                                | `gen_ai.token.type`, `frugal.history_bucket` |
+| `frugal.gen_ai.calls`                   | counter   | Number of calls per site                                     | `frugal.history_bucket`, `frugal.structured_output_mode` |
 | `frugal.gen_ai.cache_read_tokens`       | histogram | Prompt cache hits                                            | —                                      |
 | `frugal.gen_ai.cache_write_tokens`      | histogram | Prompt cache writes                                          | —                                      |
 | `frugal.gen_ai.reasoning_tokens`        | histogram | OpenAI reasoning tokens (o-series), Anthropic thinking tokens| —                                      |
+| `frugal.gen_ai.agent.turns`             | histogram | Model-response turns per successful `invoke_agent` call (manual only) | —                              |
 | `frugal.gen_ai.errors`                  | counter   | Errors by exception type                                     | `frugal.error.type`                    |
-| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality cap, bugs)     | `frugal.internal_error.stage`          |
+| `frugal.gen_ai.internal_errors`         | counter   | frugal-metrics internal failures (cardinality caps, bugs)    | `frugal.internal_error.stage`, `frugal.internal_error.type`, `frugal.instrument` |
 | `frugal.gen_ai.output_cap_utilization`  | histogram | `output_tokens / max_tokens` ratio when `max_tokens` is set  | `frugal.structured_output_mode`        |
-| `frugal.gen_ai.history_depth`           | histogram | `messages.length` (analyzer-sampled)                         | —                                      |
+| `frugal.gen_ai.history_depth`           | histogram | `messages.length` — every chat call (100%, not sampled)      | —                                      |
+| `frugal.gen_ai.duplicate_requests`      | counter   | Repeat-request detection — every chat call (100%, not sampled; disable via `FRUGAL_DUPLICATE_REQUEST_DETECTION`) | `frugal.dup_state` |
 | `frugal.gen_ai.few_shot_count`          | histogram | Few-shot exemplar pairs before final user (analyzer-sampled) | —                                      |
+| `frugal.gen_ai.few_shot_tokens`         | histogram | Approx token size of the few-shot example block (analyzer-sampled) | —                                |
 | `frugal.gen_ai.noise_ratio`             | histogram | HTML/base64/whitespace fraction of input (analyzer-sampled)  | —                                      |
 | `frugal.gen_ai.cache_prefix_stable`     | counter   | Per-block prompt-cache stability (analyzer-sampled)          | `frugal.block`, `frugal.stable`        |
 | `frugal.gen_ai.structured_output_hint`  | counter   | "Return JSON" prompts missing `response_format`/`tools`      | —                                      |
 
-The bottom block of analyzer-sampled metrics fires on a fraction of calls
-(`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`, default 10%); the token-side metrics are
-100% — never sampled.
+The analyzer-sampled metrics fire on a fraction of calls
+(`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`, default 10%); the token-side metrics,
+`history_depth`, and `duplicate_requests` are 100% — never sampled.
 
-Every metric carries this base attribute set:
+Every metric carries this base attribute set (except
+`frugal.gen_ai.internal_errors`, which is emitted from failure paths where
+these attributes may not exist yet and carries only `frugal.project_id`, the
+stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
+`frugal.customer_id` / `frugal.custom_label` when 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` + `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.request.model`, `gen_ai.response.model` — the model used; both draw on one shared registry and become `<overflow>` past `FRUGAL_MAX_MODELS` distinct model strings
 - `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
+- `frugal.batched` — `true` for batch-API paths (OpenAI Batch API submissions; Anthropic Message Batches submissions and results), `false` otherwise
+- `frugal.custom_label` — only on `track_ai_call` / `start_ai_call` calls that pass `custom_label=...`; the value must be in the `FRUGAL_CUSTOM_LABEL` allowlist or it is coerced to `other`
 
 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.
 
@@ -128,6 +144,39 @@ with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
     )
 ```
 
+For an enclosing agent invocation, set `operation="invoke_agent"` and report
+the number of model-response steps performed inside it:
+
+```python
+with track_ai_call(
+    system="anthropic",
+    operation="invoke_agent",
+    request_model="claude-sonnet-4-20250514",
+) as span:
+    result = my_agent_framework_call(prompt)
+    span.set_usage(
+        input_tokens=result.usage.input_tokens,
+        output_tokens=result.usage.output_tokens,
+        agent_turns=result.turn_count,
+    )
+```
+
+- Provider wrappers still measure individual model calls and never set
+  `agent_turns`.
+- Agent frameworks such as the Claude Agent SDK, OpenAI Agents SDK, and
+  LangGraph do not have dedicated wrappers yet; track them manually as shown.
+- `frugal.gen_ai.history_depth` is the request message count
+  (`messages.length`), not a turn count.
+- Missing, non-integer, non-positive, or otherwise invalid `agent_turns`
+  values are silently dropped. They never raise or affect customer execution.
+- Turn data is emitted only on success, like token usage.
+- **Avoid double-counting tokens.** Only report aggregate `input_tokens` /
+  `output_tokens` on the `invoke_agent` call when the agent's inner
+  model-client calls are **not** already wrapped by a supported provider
+  wrapper. If they are wrapped, those wrappers already emit token usage per
+  inner call — report `agent_turns` only on the `invoke_agent` call in that
+  case, or the same tokens are double-counted.
+
 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:
@@ -150,9 +199,9 @@ except BaseException as exc:
 
 `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`.
+**Metadata** — `track_ai_call` / `start_ai_call` kwargs (all optional): `system` (→ `gen_ai.system`, default `"custom"`), `operation` (default `"chat"`), `request_model` (default `"<unknown>"`), `custom_label` (→ the `frugal.custom_label` label on every metric of the call; trimmed, and coerced to `other` unless in the `FRUGAL_CUSTOM_LABEL` allowlist). 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`.
+**Usage** — `set_usage(...)` / `success(...)` kwargs (all optional): `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `reasoning_tokens`, `agent_turns`, `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.
 

frugal_sdk_python-0.5.0/docs/metrics-reference.md

@@ -0,0 +1,308 @@
+# Metrics reference
+
+All metrics follow the OpenTelemetry GenAI semantic convention where a name
+exists; Frugal-namespaced extensions (`frugal.*`) cover signals semconv does
+not yet define.
+
+Every metric point carries the attribute set listed under
+[Attributes](#attributes) below.
+
+## Metrics
+
+In addition to the base attribute set (see [Attributes](#attributes)), each
+metric may carry the extra attributes shown in the rightmost column.
+
+| Name                                  | Kind      | Unit        | Emitted by                                            | Additional attributes                          |
+| ------------------------------------- | --------- | ----------- | ----------------------------------------------------- | ---------------------------------------------- |
+| `gen_ai.client.operation.duration`    | histogram | `s`         | every call, success or error                          | —                                              |
+| `gen_ai.client.token.usage`           | histogram | `{token}`   | every call with a usage payload                       | `gen_ai.token.type`                            |
+| `frugal.gen_ai.calls`                 | counter   | `{call}`    | every call, success or error                          | `frugal.history_bucket` (chat calls), `frugal.structured_output_mode` (with payload) |
+| `frugal.gen_ai.cache_read_tokens`     | histogram | `{token}`   | when provider reports cache reads                     | —                                              |
+| `frugal.gen_ai.cache_write_tokens`    | histogram | `{token}`   | when provider reports cache writes                    | —                                              |
+| `frugal.gen_ai.reasoning_tokens`      | histogram | `{token}`   | OpenAI o-series reasoning models                      | —                                              |
+| `frugal.gen_ai.agent.turns`           | histogram | `{turn}`    | successful `invoke_agent` calls with a valid `agent_turns` count (manual tracking only) | —                    |
+| `frugal.gen_ai.errors`                | counter   | `{error}`   | when the wrapped call raises                          | `frugal.error.type`                            |
+| `frugal.gen_ai.internal_errors`       | counter   | `{error}`   | frugal-metrics internal failures (cardinality cap, instrumentation bugs) | `frugal.internal_error.stage`     |
+| `frugal.gen_ai.output_cap_utilization`| histogram | `1`         | when request had `max_tokens` (ratio 0..1)            | `frugal.structured_output_mode`                |
+| `frugal.gen_ai.history_depth`         | histogram | `{message}` | every chat call (`messages.length`) — 100%, not sampled | —                                            |
+| `frugal.gen_ai.few_shot_count`        | histogram | `{example}` | analyzer-sampled single-turn chat (count of `(user, assistant)` pairs before final user) | —           |
+| `frugal.gen_ai.few_shot_tokens`       | histogram | `{token}`   | analyzer-sampled single-turn chat — approx token size of the `(user, assistant)` example block, beside `few_shot_count` | —      |
+| `frugal.gen_ai.noise_ratio`           | histogram | `1`         | analyzer-sampled chat call (HTML / base64 / whitespace fraction of input) | —                          |
+| `frugal.gen_ai.cache_prefix_stable`   | counter   | `{call}`    | analyzer-sampled chat call, when previous call to the same call site existed (one point per block, see Attributes) | `frugal.block`, `frugal.stable` |
+| `frugal.gen_ai.structured_output_hint`| counter   | `{call}`    | analyzer-sampled chat call where the prompt asks for JSON without `response_format` or `tools` | —             |
+| `frugal.gen_ai.duplicate_requests`    | counter   | `{call}`    | every chat call with a canonicalizable request, success or error — 100%, not sampled; off when `FRUGAL_DUPLICATE_REQUEST_DETECTION=false` | `frugal.dup_state` |
+
+`gen_ai.client.token.usage` is split across input and output via the
+`gen_ai.token.type` attribute (`input` | `output`).
+
+### Agent turns
+
+Manual `track_ai_call` and `start_ai_call` instrumentation accepts the
+`agent_turns` usage kwarg through `AICallSpan.set_usage` and
+`AICallSpan.success`. A sample is emitted only when the call succeeds, the
+normalized `gen_ai.operation.name` is exactly `invoke_agent`, and the value is
+a positive integer. Booleans, missing values, non-integers, zero, and negative
+values are silently ignored; validation never affects customer execution.
+Provider wrappers never set this field, so agent frameworks remain
+manual-tracking call sites in this release. `frugal.gen_ai.history_depth`
+continues to mean request message count, not agent turns. The histogram uses
+explicit bucket boundaries
+`(1, 2, 3, 4, 5, 6, 8, 10, 12, 15, 20, 25, 30, 40, 50, 75, 100)` (mirroring
+`gen_ai.client.operation.duration`'s view) so `histogram_quantile()` resolves
+meaningful spread across realistic agent-run turn counts instead of
+collapsing into OTel's duration-tuned default buckets.
+
+Only report aggregate token usage on the `invoke_agent` call itself when the
+agent's inner model-client calls are **not** already wrapped by a supported
+provider wrapper; if they are wrapped, report `agent_turns` only on the
+`invoke_agent` call, since the inner wrappers already emit token usage and
+combining both would double-count tokens.
+
+To derive average turns per reporting agent invocation in MetricsQL, use:
+
+```promql
+increase(frugal.gen_ai.agent.turns_sum[...])
+/
+increase(frugal.gen_ai.agent.turns_count[...])
+```
+
+The analyzer-sampled metrics are gated by `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`
+(default `0.1`). Sampling is deterministic per `(caller_file, caller_function,
+minute)` — within a minute a given call site is either fully sampled or fully
+skipped, so the LRU comparisons that drive `cache_prefix_stable` see contiguous
+data when active. The token-side metrics (cap utilization, batched label,
+calls, token usage) are 100% — never sampled. `frugal.gen_ai.history_depth` and
+the `frugal.history_bucket` label are likewise 100% — `messages.length` is a
+trivially-cheap integer needing no prompt analysis, so it is emitted on every chat
+call (`few_shot_count`, `few_shot_tokens`, `noise_ratio`, `cache_prefix_stable`, and
+`structured_output_hint` remain analyzer-sampled). `few_shot_tokens` is emitted from
+the same analyzer pass as `few_shot_count` (identifying which turns are examples
+needs prompt inspection, so there is no cheap 100% path); its token count is an
+approximate chars/4 estimate over the example block.
+
+Label placement and cardinality: `frugal.history_bucket` rides BOTH the
+`frugal.gen_ai.calls` counter and the `gen_ai.client.token.usage` histogram —
+on token.usage deliberately, so spend can be cut by conversation depth.
+Worst-case that multiplies the token.usage series by 7 buckets × 2 token types
+per call site (in practice a site occupies 1–3 buckets, so expect 2–6× — but
+provision for 14×). `frugal.structured_output_mode` rides ONLY `calls` (and
+`output_cap_utilization`), NOT token.usage — the full 7×4 bucket×mode
+cross-tab lives on `calls` alone, where worst-case it is 28 series per call
+site.
+
+`frugal.gen_ai.duplicate_requests` is also 100% (independent of
+`FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`). Each chat call's request is canonicalized
+(`model + system + messages + tools + response_format + max_tokens` — plus
+`previous_response_id` for stateful OpenAI Responses-API calls — with the call
+site folded in) and hashed; the hash is checked against a shared, time-and-size-
+limited rotating Bloom filter and classified `first_seen` / `repeat_seen`. Errored
+calls are classified too — a failed-then-retried identical request reads
+`repeat_seen`, keeping retry storms visible. The raw signature never leaves the
+SDK — only the 2-value state is exported. Hashing is incremental and hard-capped
+at 256 KiB of canonicalized request per call: the small discriminators (call
+site, model, system, tools, response_format, max_tokens, previous_response_id)
+are hashed FIRST, then `messages` under the remaining budget — so an over-budget
+history truncates the tail of the conversation (plus a truncation marker), never
+the fields that keep distinct call sites or models from colliding. Binary/image
+content contributes only its type and length — never its bytes — covering raw
+`bytes` blocks AND the base64-string forms providers actually send (OpenAI
+`data:` URLs, Anthropic base64 source blocks). If the filter saturates (actual
+traffic far above `FRUGAL_DUPLICATE_CAPACITY`, generation union over 50% full),
+a one-time `warn` diagnostic is emitted through the debug callback. If the
+filter's lazy bit-array allocation fails (`MemoryError`), duplicate detection is
+**disabled for the rest of the process**: a one-time `error` diagnostic is
+emitted, the first failing call records a
+`frugal.gen_ai.internal_errors{stage=duplicate_detection}` point, and every
+subsequent call skips detection silently (no `duplicate_requests` metric).
+Controls:
+
+- `FRUGAL_DUPLICATE_REQUEST_DETECTION` (default `true`) — kill switch. When
+  `false`/`0`/`no`/`off`, no filter is allocated, no signature is hashed, and the
+  metric is not emitted. Any other value keeps detection enabled and emits a
+  one-time `warn` diagnostic naming the unrecognized value.
+- `FRUGAL_DUPLICATE_WINDOW_SECONDS` (default `3600`, clamped to `604800` — 7
+  days) — retention window. Because the filter rotates in `generations` slots,
+  a signature is remembered for **at least**
+  `window × (generations−1)/generations` and **at most** `window` seconds
+  (30–60 min at defaults) — treat the counterfactual cache TTL as that range,
+  not a flat window.
+- `FRUGAL_DUPLICATE_CAPACITY` (default `10000`, clamped to `1000000`) — expected
+  distinct signatures per window (Bloom sizing target).
+- `FRUGAL_DUPLICATE_FP_RATE` (default `0.01`, clamped to `[1e-6, 0.5]`) —
+  target false-positive rate.
+- `FRUGAL_DUPLICATE_GENERATIONS` (default `2`, clamped to `16`) — rotating-Bloom
+  generation count.
+
+Out-of-range or non-finite values for any of these fall back to the default (or
+clamp to the bound) with a one-time named `warn` through the debug callback.
+
+Reading `duplicate_requests` correctly:
+
+- **Denominator.** Coverage is a per-endpoint subset of `calls` (embeddings,
+  legacy text completions, bare `track_ai_call` without messages, and other
+  non-chat surfaces emit no duplicate signal), so compute repeat rates as
+  `repeat_seen / (first_seen + repeat_seen)` — never against `calls`.
+- **Retries count as repeats.** Errored calls insert into the filter, so a
+  retried-after-failure request reads `repeat_seen`. That keeps retry storms
+  visible, but it also means `repeat_seen` includes required retry traffic that
+  a response cache would not eliminate — net it against
+  `frugal.gen_ai.errors` when estimating cacheable waste.
+- **Sampling params are ignored.** The signature deliberately excludes
+  `temperature`, `top_p`, `seed`, `n`, and `tool_choice`, so best-of-N /
+  self-consistency workloads read as 100% duplicates. Fine for spotting
+  caching opportunities; wrong for assuming every repeat is waste.
+- **Why a separate counter, not a label on `calls`:** the metric has its own
+  kill switch, covers only a subset of calls, and its 2-value state would
+  otherwise double every `calls` series; keeping it separate keeps `calls`
+  stable when detection is toggled.
+
+## Attributes
+
+### From the GenAI semantic convention
+
+| Attribute                  | Example                                    |
+| -------------------------- | ------------------------------------------ |
+| `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                                                      |
+| ------------------------- | ---------------------------------------------------------- |
+| `frugal.customer_id`      | From `FRUGAL_CUSTOMER_ID`                                  |
+| `frugal.project_id`       | From `FRUGAL_PROJECT_ID`                                    |
+| `frugal.component`        | From each entry in `FRUGAL_COMPONENTS` — present only on the per-component series, absent on the base project series |
+| `frugal.caller_file`      | Source file repo-relative to `FRUGAL_REPO_ROOT`             |
+| `frugal.caller_function`  | Function/method name at the call site                       |
+| `frugal.error.type`       | Exception class name (error-path metrics only)              |
+| `frugal.batched`          | `true` when the metric came from a provider batch-API path, `false` otherwise. Present on every metric. Batch submissions (OpenAI `batches.create`, Anthropic `messages.batches.create`) emit `frugal.gen_ai.calls` with `batched="true"` — one point per request for Anthropic (the requests array is in hand, grouped by model), one per submission for OpenAI (per-request counts are not reported at submission time, so OpenAI batched call volume is a floor, never an overcount). Iterating Anthropic `messages.batches.results()` additionally emits per-entry `gen_ai.client.token.usage` (+ cache metrics) with `batched="true"`, attributed to the call site that submitted the batch when the submission happened in the same process (bounded in-process memory; falls back to the results call site). OpenAI batch token usage lives in the output file read through the generic files API and is not intercepted. The manual track API accepts a `batched` flag for hand-instrumented batch paths. An app on an SDK predating batch support reads `false` on genuinely batched traffic — the label reflects what the deployed SDK can see. |
+| `frugal.structured_output_mode` | `none` \| `json_object` \| `json_schema` \| `tools`. Derived from request params by precedence: non-empty `tools` → `tools`; else `response_format.type` `json_object` / `json_schema` → the matching value; else `none`. On `frugal.gen_ai.output_cap_utilization` (when `max_tokens` set), and on `frugal.gen_ai.calls` for every call with a request payload (omitted when there is no payload). |
+| `frugal.block`            | `system` \| `user` \| `tools` \| `schema`. Only on `frugal.gen_ai.cache_prefix_stable`. |
+| `frugal.stable`           | `true` when the block hash matches the previous call at this site. Only on `frugal.gen_ai.cache_prefix_stable`. |
+| `frugal.history_bucket`   | Bounded bucket of `messages.length`: `0` \| `1-2` \| `3-5` \| `6-10` \| `11-20` \| `21-50` \| `51+`. On `frugal.gen_ai.calls` and `gen_ai.client.token.usage`, and only for chat calls (payload has a `messages` array); omitted otherwise. 100% (not analyzer-sampled). |
+| `frugal.custom_label`    | Custom label (e.g. a business unit) passed as `custom_label=` to `track_ai_call` / `start_ai_call` — never set by the provider wrappers. When passed, it rides EVERY metric of that call (success and error paths alike). The value is trimmed of surrounding whitespace (matching the Node SDK), then must match one of the first 20 entries of `FRUGAL_CUSTOM_LABEL` (hard cap, not configurable) or it is coerced to `other`. Omitted when not passed. |
+| `frugal.dup_state`        | `first_seen` \| `repeat_seen` — whether this request's canonical signature was already seen within the duplicate-detection window. Only on `frugal.gen_ai.duplicate_requests`. |
+
+### Sentinel values for `frugal.caller_file` / `frugal.caller_function`
+
+| Value          | Meaning                                                    |
+| -------------- | ---------------------------------------------------------- |
+| `<external>`   | Caller frame resolved outside `FRUGAL_REPO_ROOT`            |
+| `<unknown>`    | Could not resolve a caller frame (should not happen in practice) |
+| `<lambda>`     | Call originated from a `lambda` expression. This is Python's native `co_name` for lambdas. Only appears in `frugal.caller_function`. |
+| `<overflow>`   | Cardinality cap (`FRUGAL_MAX_CALL_SITES`) exceeded. See below. |
+
+> `<overflow>` is the shared overflow sentinel, not a caller-only value: it also
+> appears on `gen_ai.request.model` / `gen_ai.response.model` once
+> `FRUGAL_MAX_MODELS` distinct model strings have been observed. See
+> [Model cap behavior](#model-cap-behavior).
+
+### Cardinality cap behavior
+
+Once `FRUGAL_MAX_CALL_SITES` distinct `(file, function)` pairs have been
+observed, new call sites overflow. Two shapes are possible:
+
+| Attribution | Meaning |
+| --- | --- |
+| `(real/file.py, <overflow>)` | The file was already seen in the first N pairs; the new function inside that file is bucketed into `<overflow>` |
+| `(<overflow>, <overflow>)` | Neither the file nor the function was seen before the cap was reached |
+
+The first time the cap is hit per process, the library emits a single
+`frugal.gen_ai.internal_errors{stage=cardinality_cap_hit}` point so you can
+see the transition in your dashboard.
+
+### Model cap behavior
+
+Model ids are free-form provider strings, so `FRUGAL_MAX_MODELS` (default `100`,
+`0` disables) bounds them the same way. The first N distinct model strings a
+process observes keep their real names; every later one is reported as
+`<overflow>` on whichever of `gen_ai.request.model` / `gen_ai.response.model`
+carries it. The registry is process-wide and **shared by both labels** — a model
+first seen in a response is free to use as a request model, and vice versa — so
+a model already in the registry is never re-charged. The default is generous
+because one logical model normally occupies **two** slots: providers answer a
+request alias (`claude-sonnet-4-5`) with a dated response snapshot
+(`claude-sonnet-4-5-20250929`). The SDK's own sentinels — `<unknown>` and
+`<overflow>` — pass through without consuming a slot. The first time the cap is
+hit per process the library emits a single
+`frugal.gen_ai.internal_errors{stage=model_cap_hit}` point plus one `warn`
+through the debug callback.
+
+### Internal-error stages
+
+`frugal.gen_ai.internal_errors` carries a `frugal.internal_error.stage`
+attribute describing where our own code failed. Non-exhaustive list:
+
+| Stage                   | When it fires                                                          |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `setup_failed`          | Our wrapper setup (OTel init, caller resolution) threw; original call continued normally |
+| `stream_proxy_failed`   | Constructing the stream wrapper threw; original response returned unwrapped |
+| `emission`              | Emitting a success/error metric threw                                  |
+| `duplicate_detection`   | The duplicate-request path (signature, filter, or emission) threw — including the one-time filter allocation failure; carries `frugal.internal_error.type` with the exception class |
+| `cardinality_cap_hit`   | `FRUGAL_MAX_CALL_SITES` was just reached (once per process)            |
+| `model_cap_hit`         | `FRUGAL_MAX_MODELS` was just reached (once per process); further distinct models are reported as `<overflow>` |
+| `otel_cardinality_overflow` | OpenTelemetry merged an instrument's attribute sets into its `otel.metric.overflow` series (once per instrument name); carries `frugal.instrument` with the affected instrument |
+
+Unlike every other metric, `frugal.gen_ai.internal_errors` does **not** carry
+the full base attribute set — it is emitted from failure paths where the
+caller/provider/model attributes may not exist yet. Its points carry only
+`frugal.project_id`, `frugal.internal_error.stage` (plus
+`frugal.internal_error.type` where noted, and `frugal.instrument` on the
+`otel_cardinality_overflow` stage), and — when set — `frugal.customer_id` and
+`frugal.custom_label`.
+
+## Provider coverage
+
+| Provider                                                | Wrapper                              | `gen_ai.system`  |
+| ------------------------------------------------------- | ------------------------------------ | ---------------- |
+| OpenAI                                                  | `wrap_openai`                        | `openai`         |
+| Anthropic (direct API)                                  | `wrap_anthropic`                     | `anthropic`      |
+| 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
+hosted on Bedrock — Anthropic Claude, OpenAI gpt-oss, Amazon Nova, Meta Llama,
+Mistral, Cohere, AI21 Jamba, DeepSeek, Qwen, Kimi, Twelvelabs, Nvidia, etc.
+Per-provider response parsing handles the major families (Anthropic /
+OpenAI / Nova / Llama / Mistral) for accurate cache + reasoning token
+extraction; everything else falls back to the universal
+`amazon-bedrock-invocationMetrics` (streaming) /
+`x-amzn-bedrock-*-token-count` (non-streaming) headers that Bedrock attaches
+to every response.
+
+> **Reasoning tokens on Bedrock.** Anthropic's `InvokeModel` path exposes
+> `usage.thinking_tokens` for extended-thinking calls; we surface it as
+> `frugal.gen_ai.reasoning_tokens`. Bedrock's `Converse` API normalizes
+> reasoning tokens into `outputTokens` rather than breaking them out, so
+> calls made via `Converse` lose reasoning-token visibility.
+
+Azure OpenAI clients currently fall through the OpenAI wrapper and are tagged
+as `openai`; dedicated Azure detection is deferred.
+
+Native Vertex SDKs (`google-cloud-aiplatform`) for non-Claude models are not
+yet instrumented.