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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: frugal-sdk-python
-Version: 0.4.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,14 @@ 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). |
@@ -103,8 +105,9 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | `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` — 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` |
@@ -121,12 +124,13 @@ The analyzer-sampled metrics fire on a fraction of calls
 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, and `frugal.customer_id` / `frugal.custom_label` when set):
+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 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`
@@ -169,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:
@@ -193,7 +230,7 @@ except BaseException as exc:
 
 **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.4.0 → frugal_sdk_python-0.5.0}/README.md

@@ -48,12 +48,14 @@ 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). |
@@ -74,8 +76,9 @@ Every wrapped call emits OTel metrics tagged with the caller's source file and f
 | `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` — 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` |
@@ -92,12 +95,13 @@ The analyzer-sampled metrics fire on a fraction of calls
 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, and `frugal.customer_id` / `frugal.custom_label` when set):
+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 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`
@@ -140,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:
@@ -164,7 +201,7 @@ except BaseException as exc:
 
 **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.4.0 → frugal_sdk_python-0.5.0}/docs/metrics-reference.md

@@ -20,6 +20,7 @@ metric may carry the extra attributes shown in the rightmost column.
 | `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`                |
@@ -34,6 +35,37 @@ metric may carry the extra attributes shown in the rightmost column.
 `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
@@ -182,6 +214,11 @@ Reading `duplicate_requests` correctly:
 | `<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
@@ -196,6 +233,23 @@ 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`
@@ -208,13 +262,16 @@ attribute describing where our own code failed. Non-exhaustive list:
 | `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 — when set —
-`frugal.customer_id` and `frugal.custom_label`.
+`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
 

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.5.0}/docs/quickstart.md

@@ -25,11 +25,13 @@ Optional:
 | `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`  | Frugal-specific OTLP collector URL. 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. The list is deduped (order-preserving) and only the first **10** entries are honored (hard cap, not configurable); the rest are dropped at startup with one debug warning. See [Cardinality caps](#cardinality-caps). |
 | `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 when attributing the caller (see below).        |
 | `FRUGAL_METRIC_EXPORT_INTERVAL_MS`    | Export cadence. Default `60000`.                                                            |
-| `FRUGAL_MAX_CALL_SITES`               | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute before overflow. Default `500`, set to `0` to disable. See [Cardinality cap](#cardinality-cap). |
+| `FRUGAL_MAX_CALL_SITES`               | Cardinality cap — max distinct `(caller_file, caller_function)` pairs to attribute before overflow. Default `500`, set to `0` to disable. See [Cardinality caps](#cardinality-caps). |
+| `FRUGAL_MAX_MODELS`                   | Cardinality cap — max distinct model strings to attribute before `gen_ai.request.model` / `gen_ai.response.model` overflow to `<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. See [Cardinality caps](#cardinality-caps). |
+| `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). See [Cardinality caps](#cardinality-caps). |
 | `FRUGAL_PROMPT_ANALYSIS_SAMPLE_RATE`  | Fraction of calls (0..1) where the lightweight prompt analyzer runs and emits derived metrics (`noise_ratio`, `cache_prefix_stable`, `few_shot_*`, …). Default `0.1`. Set to `0` to disable, `1` for every call. See [Prompt analysis](#prompt-analysis). |
 | `FRUGAL_DUPLICATE_REQUEST_DETECTION`  | Duplicate-request detection (`frugal.gen_ai.duplicate_requests`) is **on by default**: every chat request is canonicalized and SHA-256 hashed in-process to classify it `first_seen`/`repeat_seen`. Set to `0`/`false`/`no`/`off` to turn it off entirely (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). |
@@ -231,6 +233,39 @@ with track_ai_call(system="anthropic", request_model="claude-sonnet-4-20250514")
     )
 ```
 
+For an agent framework, manually track the enclosing invocation and report its
+model-response turns:
+
+```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 measure individual model calls and never set `agent_turns`;
+the Claude Agent SDK, OpenAI Agents SDK, LangGraph, and other agent frameworks
+do not have dedicated wrappers yet. `frugal.gen_ai.history_depth` is request
+message count (`messages.length`), not turns. Missing, non-integer,
+non-positive, or otherwise invalid values are silently dropped without
+affecting customer execution, and turn data is success-path only, like token
+usage. See the [metrics reference](metrics-reference.md) for the complete
+contract.
+
+**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
@@ -268,7 +303,7 @@ prompt analyzer, pass any of `messages` / `system_prompt` / `tools` /
 
 **Usage** — `set_usage(...)` / `success(...)` kwargs (all optional):
 `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`,
-`reasoning_tokens`, `response_model`.
+`reasoning_tokens`, `agent_turns`, `response_model`.
 
 The same env-var configuration, safety guarantees, and exported metrics apply.
 
@@ -291,12 +326,22 @@ FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
 Paths are repo-relative (rooted at `FRUGAL_REPO_ROOT`) and match any file
 under the given prefix.
 
-## Cardinality cap
+## Cardinality caps
+
+Runaway metric cardinality — a bug that calls the SDK from thousands of source
+locations, a model id with a timestamp in it, a component list that grows with
+every deploy — is the one way this library can cost you real money. Four caps
+bound it: **three configurable caps**, each of which takes `0` to disable, plus
+a fixed one on components.
 
-To prevent runaway metric cardinality (e.g. a bug that calls the SDK from
-thousands of distinct source locations), we cap the number of distinct
-`(caller_file, caller_function)` pairs the library will attribute per
-process. Default **500**, configurable via `FRUGAL_MAX_CALL_SITES`.
+| Cap | Setting | Default | What overflows |
+| --- | --- | --- | --- |
+| Call sites | `FRUGAL_MAX_CALL_SITES` | `500` | `frugal.caller_file` / `frugal.caller_function` → `<overflow>` |
+| Models | `FRUGAL_MAX_MODELS` | `100` | `gen_ai.request.model` / `gen_ai.response.model` → `<overflow>` |
+| Components | fixed, not configurable | `10` | extra `FRUGAL_COMPONENTS` entries are dropped |
+| Series per instrument | `FRUGAL_MAX_SERIES_PER_INSTRUMENT` | `50000` | OpenTelemetry's own limit (see below); `0` = effectively unlimited (a 1,000,000 ceiling) |
+
+### Call sites (`FRUGAL_MAX_CALL_SITES`)
 
 **First-come-first-served**: the first N unique call sites observed are
 always reported with their real names. Additional call sites overflow:
@@ -316,6 +361,75 @@ To disable the cap entirely (you vouch that your cardinality is bounded):
 FRUGAL_MAX_CALL_SITES=0
 ```
 
+### Models (`FRUGAL_MAX_MODELS`)
+
+Model ids are free-form provider strings, so nothing stops a gateway or a
+fine-tune naming scheme from minting a new one per request. The first **100**
+distinct model strings a process sees keep their real names; every one after
+that is reported as `<overflow>`.
+
+The registry is **shared** by `gen_ai.request.model` and
+`gen_ai.response.model` — a model first seen in a response is free to use as a
+request model, and vice versa — and it is process-wide, so a call site that
+starts using an already-seen model is never charged for it. The default is
+deliberately generous because **one logical model routinely burns two slots**:
+providers answer a request alias (`claude-sonnet-4-5`) with a dated response
+snapshot (`claude-sonnet-4-5-20250929`), and both labels draw on this one
+registry. The SDK's own sentinels — `<unknown>` (a batch submission with no
+discoverable model) and `<overflow>` itself — never consume a slot.
+
+The first time the cap is crossed the SDK emits one
+`frugal.gen_ai.internal_errors{stage=model_cap_hit}` point plus one `warn`
+through the debug callback; further overflows are silent.
+
+### Components (`FRUGAL_COMPONENTS`)
+
+`FRUGAL_COMPONENTS` is a static list, and every entry multiplies **every**
+metric's series count (each metric is emitted once for the base project series
+and once per component). The list is deduplicated first (order-preserving, first
+occurrence wins), then only the first **10** entries are honored; the rest are
+dropped at startup with one `warn` through the debug callback naming the deduped
+and dropped counts. Like the `FRUGAL_CUSTOM_LABEL` allowlist this is a fixed constant with no
+env var to change it. There is no sentinel value — nothing is emitted for a
+dropped component, and the un-attributed base series still carries every call,
+so project totals stay correct.
+
+### Series per instrument (`FRUGAL_MAX_SERIES_PER_INSTRUMENT`)
+
+The three caps above bound individual **labels**. OpenTelemetry bounds something
+different: the number of distinct label **combinations** (attribute sets) per
+instrument. 400 call sites × 3 models × 2 token types × 7 history buckets is one
+instrument's worth of combinations, not four labels' worth — which is why the
+SDK raises that per-instrument limit to **50000** via
+`FRUGAL_MAX_SERIES_PER_INSTRUMENT` (`0` = effectively unlimited; you vouch for
+your cardinality).
+
+When an instrument does exceed its limit, OTel does not drop the excess points —
+it **merges them into a single overflow series with every attribute stripped**
+and replaced by `otel.metric.overflow=true`. Project id, caller, model, token
+type: all gone. The numbers still add up, but that instrument goes dark for
+every breakdown you care about. The SDK detects that condition on the export
+path and emits
+`frugal.gen_ai.internal_errors{stage=otel_cardinality_overflow, frugal.instrument=…}`
+once per affected instrument, plus one `error` through the debug callback.
+
+On Python the limit kwarg is passed **only when the installed
+`opentelemetry-sdk` accepts it** — as of 1.42 it does not implement the spec's
+per-instrument limit at all, so nothing is merged and nothing is raised. That
+omission is silent unless you set `FRUGAL_MAX_SERIES_PER_INSTRUMENT` yourself,
+in which case the SDK emits one `warn` telling you the setting has no effect on
+the installed OTel. The detector exists so that the day OTel Python ships the
+limit, an overflow is a loud condition rather than a silent one.
+
+> **Memory.** All 17 instruments share the same label space, but only the 3–4
+> busiest (the calls counter, the token histogram, the duration histogram)
+> realistically approach the limit — the rest carry a fraction of the
+> combinations. At a few hundred bytes per attribute set, 50000 sets on the busy
+> ones is tens of MB worst case, comparable to the duplicate filter's documented
+> ceiling. The value is not clamped: the real cost of high cardinality is active
+> series on the metrics server, which is why the model and component axes are
+> capped rather than the limit being lowered.
+
 ## Prompt analysis
 
 In addition to token-level metrics, the library runs a lightweight per-request

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.5.0}/examples/test-env/grafana/dashboards/frugal-metrics.json

@@ -109,7 +109,7 @@
       "targets": [
         {
           "datasource": { "type": "prometheus", "uid": "prometheus" },
-          "expr": "sum(frugal_gen_ai_internal_errors_total{frugal_internal_error_stage=\"cardinality_cap_hit\"}) or vector(0)",
+          "expr": "sum(frugal_gen_ai_internal_errors_total{frugal_internal_error_stage=~\"cardinality_cap_hit|model_cap_hit|otel_cardinality_overflow\"}) or vector(0)",
           "legendFormat": "events",
           "refId": "A"
         }

{frugal_sdk_python-0.4.0 → frugal_sdk_python-0.5.0}/src/frugal_metrics/block_hash_lru.py

@@ -11,6 +11,12 @@ from __future__ import annotations
 import threading
 from collections import OrderedDict
 from dataclasses import dataclass
+from typing import Final
+
+# Matches the default call-site cardinality cap. Also the floor: this LRU lives
+# in the customer's process, so an unbounded one is a memory leak rather than a
+# cardinality choice.
+_DEFAULT_CAPACITY: Final[int] = 500
 
 
 @dataclass(frozen=True)
@@ -22,8 +28,12 @@ class BlockHashes:
 
 
 class BlockHashLRU:
-    def __init__(self, capacity: int = 500) -> None:
-        self._capacity = capacity
+    def __init__(self, capacity: int = _DEFAULT_CAPACITY) -> None:
+        # The capacity is fed from FRUGAL_MAX_CALL_SITES, where 0 means "don't
+        # cap the label cardinality — I vouch for it". That is a statement about
+        # what reaches the metrics server, NOT permission to grow a process-local
+        # map forever, so a non-positive value means "default capacity" here.
+        self._capacity = capacity if capacity > 0 else _DEFAULT_CAPACITY
         self._map: "OrderedDict[str, BlockHashes]" = OrderedDict()
         self._lock = threading.Lock()
 
@@ -42,9 +52,10 @@ class BlockHashLRU:
                 self._map[call_site_id] = hashes
                 return
             self._map[call_site_id] = hashes
-            if self._capacity > 0:
-                while len(self._map) > self._capacity:
-                    self._map.popitem(last=False)
+            # _capacity is normalized to a positive value in __init__, so this
+            # loop always runs — there is no "never evict" mode.
+            while len(self._map) > self._capacity:
+                self._map.popitem(last=False)
 
     def size(self) -> int:
         with self._lock:
@@ -65,7 +76,12 @@ def get_shared_block_hash_lru(capacity: int | None = None) -> BlockHashLRU:
         return _shared
     with _shared_lock:
         if _shared is None:
-            _shared = BlockHashLRU(capacity if capacity is not None else 500)
+            # A None or non-positive capacity both mean "use the default" —
+            # BlockHashLRU.__init__ enforces the floor, so callers passing
+            # FRUGAL_MAX_CALL_SITES=0 straight through still get a bounded map.
+            _shared = BlockHashLRU(
+                capacity if capacity is not None else _DEFAULT_CAPACITY
+            )
         return _shared