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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: frugal-sdk-python
-Version: 0.5.0
+Version: 0.6.0
 Summary: Instrumentation for Cost-to-Code attribution.
 Project-URL: Homepage, https://frugal.co
 Author: Frugal AI Inc.
@@ -62,7 +62,7 @@ All configuration is via environment variables. No `init()` call, no configurati
 
 ### Required
 
-Set both or the wrapper silently returns the client unmodified:
+Console mode (`FRUGAL_METRICS_EXPORTER=console`) needs only `FRUGAL_PROJECT_ID`; every other mode needs both. If a required variable is unset, the wrapper silently returns the client unmodified:
 
 | Variable            | Purpose                                                    |
 | ------------------- | ---------------------------------------------------------- |
@@ -71,23 +71,27 @@ Set both or the wrapper silently returns the client unmodified:
 
 ### Optional
 
+The export endpoint and authentication come only from `FRUGAL_`-prefixed variables, so the SDK never crosses wires with the host's own OTel pipeline: the generic `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are never read. (The OTel exporter library still reads its own generic TLS, compression, timeout and temporality variables.)
+
 | Variable                                 | Purpose                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------- |
 | `FRUGAL_CUSTOMER_ID`                     | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `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_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics` (also when set but empty). |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Precedence: this variable wins; otherwise the header built from `FRUGAL_API_KEY` (`FRUGAL_METRICS_API_KEY` first), which is sent verbatim. Values set here are percent-decoded (`Bearer%20tok` → `Bearer tok`). A value with no `key=value` pair is treated as missing auth (the API key is not used instead); a blank (whitespace-only) value is treated as unset. |
 | `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_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=...`. The vocabulary is the first **20** comma-separated entries by raw position (hard cap, not configurable); empty entries are ignored and duplicates collapsed. `other` is reserved (the coercion sentinel) and is ignored with one warning. A value outside the allowlist is coerced to `other` with a bounded once-per-value warning; when the variable is unset, every value is `other`. One warning fires only when non-empty entries past the 20th are actually dropped (a trailing comma does not warn). |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console` (print metrics to stdout; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored). Case-insensitive; any other value warns once and uses `otlp`. |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`, for apps that already use those names. An empty value falls through to the bare name. |
 | `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_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds, `1`-`2147483647`. Default `60000`; a value outside the range warns once and uses the default.                                      |
 | `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_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls that run the lightweight prompt analyzer: a decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. 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_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `86400` (1 day). |
 | `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`.        |
@@ -125,7 +129,8 @@ 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.customer_id` / `frugal.custom_label` when set; `frugal.custom_label`
+never on the setup_failed / emission stages):
 
 - `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
@@ -133,7 +138,7 @@ stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
 - `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`
+- `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` (with a once-per-value warning). `custom_label=None` means no label; a non-string value 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.
 
@@ -228,7 +233,7 @@ 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>"`), `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`.
+**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 except the `frugal.gen_ai.internal_errors` setup_failed / emission points; 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`, `agent_turns`, `response_model`.
 
@@ -327,14 +332,27 @@ It is **opt-in** because installing signal handlers is intrusive. If you run you
 
 ## Verifying the setup
 
-Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them. Console mode needs only `FRUGAL_PROJECT_ID`; the API key,
+endpoint and header variables are ignored. An empty
+endpoint does not select the console exporter: it falls through to the default
+Frugal endpoint.
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+python my_script.py
+```
+
+Or point the library at a local OTLP/HTTP collector to see what it exports:
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=test-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 python my_script.py
 ```
 
-You should see JSON metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
+The collector should receive metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.

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

@@ -33,7 +33,7 @@ All configuration is via environment variables. No `init()` call, no configurati
 
 ### Required
 
-Set both or the wrapper silently returns the client unmodified:
+Console mode (`FRUGAL_METRICS_EXPORTER=console`) needs only `FRUGAL_PROJECT_ID`; every other mode needs both. If a required variable is unset, the wrapper silently returns the client unmodified:
 
 | Variable            | Purpose                                                    |
 | ------------------- | ---------------------------------------------------------- |
@@ -42,23 +42,27 @@ Set both or the wrapper silently returns the client unmodified:
 
 ### Optional
 
+The export endpoint and authentication come only from `FRUGAL_`-prefixed variables, so the SDK never crosses wires with the host's own OTel pipeline: the generic `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_HEADERS` are never read. (The OTel exporter library still reads its own generic TLS, compression, timeout and temporality variables.)
+
 | Variable                                 | Purpose                                                                                 |
 | ---------------------------------------- | --------------------------------------------------------------------------------------- |
 | `FRUGAL_CUSTOMER_ID`                     | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `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_OTEL_EXPORTER_OTLP_ENDPOINT`     | OTLP collector URL for Frugal metrics. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics` (also when set but empty). |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`      | Export auth headers (e.g. `Authorization=Bearer ...`). Precedence: this variable wins; otherwise the header built from `FRUGAL_API_KEY` (`FRUGAL_METRICS_API_KEY` first), which is sent verbatim. Values set here are percent-decoded (`Bearer%20tok` → `Bearer tok`). A value with no `key=value` pair is treated as missing auth (the API key is not used instead); a blank (whitespace-only) value is treated as unset. |
 | `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_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=...`. The vocabulary is the first **20** comma-separated entries by raw position (hard cap, not configurable); empty entries are ignored and duplicates collapsed. `other` is reserved (the coercion sentinel) and is ignored with one warning. A value outside the allowlist is coerced to `other` with a bounded once-per-value warning; when the variable is unset, every value is `other`. One warning fires only when non-empty entries past the 20th are actually dropped (a trailing comma does not warn). |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console` (print metrics to stdout; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored). Case-insensitive; any other value warns once and uses `otlp`. |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`, for apps that already use those names. An empty value falls through to the bare name. |
 | `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_METRIC_EXPORT_INTERVAL_MS`       | Export cadence in milliseconds, `1`-`2147483647`. Default `60000`; a value outside the range warns once and uses the default.                                      |
 | `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_PROMPT_ANALYSIS_SAMPLE_RATE`     | Fraction of calls that run the lightweight prompt analyzer: a decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. 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_WINDOW_SECONDS`        | How long a request signature is remembered for duplicate detection. Default `3600`, max `86400` (1 day). |
 | `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`.        |
@@ -96,7 +100,8 @@ 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.customer_id` / `frugal.custom_label` when set; `frugal.custom_label`
+never on the setup_failed / emission stages):
 
 - `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
@@ -104,7 +109,7 @@ stage/type, `frugal.instrument` on the `otel_cardinality_overflow` stage, and
 - `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`
+- `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` (with a once-per-value warning). `custom_label=None` means no label; a non-string value 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.
 
@@ -199,7 +204,7 @@ 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>"`), `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`.
+**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 except the `frugal.gen_ai.internal_errors` setup_failed / emission points; 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`, `agent_turns`, `response_model`.
 
@@ -298,14 +303,27 @@ It is **opt-in** because installing signal handlers is intrusive. If you run you
 
 ## Verifying the setup
 
-Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them. Console mode needs only `FRUGAL_PROJECT_ID`; the API key,
+endpoint and header variables are ignored. An empty
+endpoint does not select the console exporter: it falls through to the default
+Frugal endpoint.
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+python my_script.py
+```
+
+Or point the library at a local OTLP/HTTP collector to see what it exports:
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=test-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 python my_script.py
 ```
 
-You should see JSON metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.
+The collector should receive metric records with `gen_ai.*` and `frugal.*` attributes every 5 seconds.

{frugal_sdk_python-0.5.0 → frugal_sdk_python-0.6.0}/docs/metrics-reference.md

@@ -120,8 +120,8 @@ Controls:
   `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,
+- `FRUGAL_DUPLICATE_WINDOW_SECONDS` (default `3600`, clamped to `86400` — 1
+  day) — 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,
@@ -133,6 +133,15 @@ Controls:
 - `FRUGAL_DUPLICATE_GENERATIONS` (default `2`, clamped to `16`) — rotating-Bloom
   generation count.
 
+Exporter selection: `FRUGAL_METRICS_EXPORTER` (`otlp` default, or `console` to
+print every metric to stdout via the OpenTelemetry console exporter; console
+mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables
+are ignored, and any other value warns once and uses `otlp`). An empty endpoint variable falls through to the next source and
+never selects console.
+
+`FRUGAL_METRIC_EXPORT_INTERVAL_MS` accepts `1` to `2147483647` (default `60000`);
+a value outside that range warns once and uses the default.
+
 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.
 
@@ -191,18 +200,18 @@ Reading `duplicate_requests` correctly:
 
 | Attribute                 | Value                                                      |
 | ------------------------- | ---------------------------------------------------------- |
-| `frugal.customer_id`      | From `FRUGAL_CUSTOMER_ID`                                  |
-| `frugal.project_id`       | From `FRUGAL_PROJECT_ID`                                    |
+| `frugal.customer_id`      | From `FRUGAL_CUSTOMER_ID` — present only when set           |
+| `frugal.project_id`       | From `FRUGAL_METRICS_PROJECT_ID`, else `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.error.type`       | Exception class name (error-path metrics only); stripped from `frugal.gen_ai.history_depth` and `frugal.gen_ai.duplicate_requests` so success and error points stay additive |
+| `frugal.batched`          | `true` when the metric came from a provider batch-API path, `false` otherwise. Present on every metric of the call except the `frugal.gen_ai.internal_errors` points. 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.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), except the `frugal.gen_ai.internal_errors` `setup_failed`/`emission` points, which carry only project, customer and error type. The value is trimmed of surrounding whitespace (matching the Node SDK), then must match the closed vocabulary from the first 20 comma-separated entries of `FRUGAL_CUSTOM_LABEL` by raw position (hard cap, not configurable; empties ignored, duplicates collapsed) or it is coerced to `other` with a bounded once-per-value warning. `other` is reserved as the coercion sentinel: an `other` entry in the env var is ignored with a warning. With the variable unset, every value is `other`. A non-string value is coerced to `other` with a type warning; `None` means no label. A truncation warning fires only when non-empty entries past the 20th are dropped. 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`
@@ -257,9 +266,10 @@ 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 |
+| `setup_failed`          | Our wrapper setup (OTel init, caller resolution) threw; original call continued normally. Emitted by the provider wrappers and the manual track API (`track_ai_call` / `start_ai_call`); carries `frugal.project_id`, `frugal.customer_id` (when set) and `frugal.internal_error.type` |
 | `stream_proxy_failed`   | Constructing the stream wrapper threw; original response returned unwrapped |
-| `emission`              | Emitting a success/error metric threw                                  |
+| `emission`              | Emitting a success/error metric threw. Emitted by the provider wrappers and the manual track API; carries the same project/customer identity and `frugal.internal_error.type` as `setup_failed` |
+| `call_shape`            | Deriving history_depth / history_bucket / structured_output_mode from the request payload threw; carries `frugal.internal_error.type`; core metrics still emitted |
 | `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>` |
@@ -271,7 +281,8 @@ 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`.
+`frugal.custom_label` (`setup_failed` and `emission` never carry the custom
+label).
 
 ## Provider coverage
 

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

@@ -10,39 +10,42 @@ pip install openai anthropic
 
 ## Configure (env vars only)
 
-Required — the library silently no-ops if either is unset:
+Required — console mode (`FRUGAL_METRICS_EXPORTER=console`) needs only `FRUGAL_PROJECT_ID`; every other mode needs both. The library silently no-ops if a required variable is unset:
 
 | Var                 | Value                                                               |
 | ------------------- | ------------------------------------------------------------------- |
 | `FRUGAL_API_KEY`    | Per-customer bearer token issued by Frugal; builds the export `Authorization` header. (Or supply the bearer yourself via `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`.) |
 | `FRUGAL_PROJECT_ID` | The Frugal project this deployment belongs to. Stats are attributed per project, so a shared repo across microservices no longer collides. |
 
-Optional:
+Optional — the export endpoint and authentication come only from
+`FRUGAL_`-prefixed variables, so the SDK never crosses wires with the host's
+own OTel pipeline: the generic `OTEL_EXPORTER_OTLP_ENDPOINT` and
+`OTEL_EXPORTER_OTLP_HEADERS` are never read. (The OTel exporter library still
+reads its own generic TLS, compression, timeout and temporality variables.)
 
 | Var                                   | Purpose                                                                                    |
 | ------------------------------------- | ------------------------------------------------------------------------------------------ |
 | `FRUGAL_CUSTOMER_ID`                  | Customer ID issued by Frugal. When unset, the tenant label (auto-injected server-side by VMAuth from the bearer token) identifies the customer and `frugal.customer_id` is omitted. |
 | `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_OTEL_EXPORTER_OTLP_ENDPOINT`  | Frugal-specific OTLP collector URL. Defaults to `https://metrics.frugal.co/opentelemetry/v1/metrics` (also when set but empty). |
+| `FRUGAL_OTEL_EXPORTER_OTLP_HEADERS`   | Export auth headers (e.g. `Authorization=Bearer ...`). Precedence: this variable wins; otherwise the header built from `FRUGAL_API_KEY` (`FRUGAL_METRICS_API_KEY` first), which is sent verbatim. Values set here are percent-decoded (`Bearer%20tok` → `Bearer tok`). A value with no `key=value` pair is treated as missing auth (the API key is not used instead); a blank (whitespace-only) value is treated as unset. |
 | `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_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=...`. The vocabulary is the first **20** comma-separated entries by raw position (hard cap, not configurable); empty entries are ignored and duplicates collapsed. `other` is reserved (the coercion sentinel) and is ignored with one warning. A value outside the allowlist is coerced to `other` with a bounded once-per-value warning; when the variable is unset, every value is `other`. One warning fires only when non-empty entries past the 20th are actually dropped (a trailing comma does not warn). |
+| `FRUGAL_METRICS_EXPORTER` | `otlp` (default) or `console` (print metrics to stdout; console mode needs only `FRUGAL_PROJECT_ID`; the API key, endpoint and header variables are ignored). Case-insensitive; any other value warns once and uses `otlp`. |
+| `FRUGAL_METRICS_PROJECT_ID` / `FRUGAL_METRICS_API_KEY` | Namespaced overrides read before `FRUGAL_PROJECT_ID` / `FRUGAL_API_KEY`, for apps that already use those names. An empty value falls through to the bare name. |
 | `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_METRIC_EXPORT_INTERVAL_MS`    | Export cadence in ms, `1`-`2147483647`. Default `60000`; a value outside the range warns once and uses the default.                                                         |
 | `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_PROMPT_ANALYSIS_SAMPLE_RATE`  | Fraction of calls where the lightweight prompt analyzer runs and emits derived metrics (`noise_ratio`, `cache_prefix_stable`, `few_shot_*`, …): a decimal in [0, 1], plain or scientific notation (e.g. `0.25`, `1e-1`); anything else warns once and uses `0.1`. 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). |
+| `FRUGAL_DUPLICATE_WINDOW_SECONDS`     | How long a request signature is remembered for duplicate detection. Default `3600`, max `86400` (1 day). |
 | `FRUGAL_DUPLICATE_CAPACITY`           | Expected distinct request signatures per window — sizes the in-memory duplicate filter. Default `10000`, max `1000000`. Raise it if the debug callback warns the filter is saturated. If the filter's memory can't be allocated at all, detection disables itself for the rest of the process (one-time `error` diagnostic + one `internal_errors` point). |
 | `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`                     | Kill switch. Set to `1` to disable without uninstalling.                                    |
 
-Standard `OTEL_EXPORTER_OTLP_*` env vars are honored as fallbacks if the
-`FRUGAL_*` variants are unset.
-
 ## Wrap your clients
 
 **OpenAI**
@@ -296,7 +299,8 @@ 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>"`), `custom_label` (→ the
-`frugal.custom_label` label on every metric of the call; values outside the
+`frugal.custom_label` label on every metric of the call except the
+`frugal.gen_ai.internal_errors` setup_failed / emission points; values outside the
 `FRUGAL_CUSTOM_LABEL` allowlist become `other`). To also run the sampled
 prompt analyzer, pass any of `messages` / `system_prompt` / `tools` /
 `response_format` / `max_tokens`.
@@ -514,16 +518,28 @@ your handler).
 
 ## Verifying the setup
 
-Point the library at a local collector (or set the endpoint empty to print
-metrics to the console on the export interval):
+Set `FRUGAL_METRICS_EXPORTER=console` to print the metrics to stdout instead
+of exporting them. Console mode needs only `FRUGAL_PROJECT_ID`; the API key,
+endpoint and header variables are ignored. An empty
+endpoint does not select the console exporter: it falls through to the default
+Frugal endpoint.
+
+```bash
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_METRICS_EXPORTER=console
+export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
+python my_script.py
+```
+
+Or point the library at a local OTLP/HTTP collector to see what it exports:
 
 ```bash
-export FRUGAL_API_KEY=local
+export FRUGAL_API_KEY=test-key
 export FRUGAL_PROJECT_ID=my-project
-export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318/v1/metrics
 export FRUGAL_METRIC_EXPORT_INTERVAL_MS=5000
 python my_script.py
 ```
 
-Every five seconds you should see JSON metric records emitted with
+Every five seconds the collector should receive metric records with
 `gen_ai.*` and `frugal.*` attributes.