frugal-sdk-python 0.1.0__py3-none-any.whl

frugal_metrics/wrappers/openai.py

@@ -0,0 +1,465 @@
+"""OpenAI client wrapper.
+
+Monkey-patches `chat.completions.create`, `completions.create`,
+`embeddings.create`, and `responses.create` on a supplied OpenAI (or
+AzureOpenAI) client instance — sync or async. Streaming calls pass through
+unmodified in v1; streaming support lands in M2.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import logging
+from typing import Any, Callable, TypeVar
+
+from frugal_metrics import caller as caller_mod
+from frugal_metrics import semconv
+from frugal_metrics.config import load_config
+from frugal_metrics.instrument import (
+    CallContext,
+    UsageReport,
+    start_call,
+)
+from frugal_metrics.prompt_analyzer import RequestPayload
+from frugal_metrics.safe import safe_call
+from frugal_metrics.streams import AsyncStreamProxy, SyncStreamProxy
+
+logger = logging.getLogger("frugal_metrics")
+
+T = TypeVar("T")
+
+
+def wrap_openai(client: T) -> T:
+    """Instrument an OpenAI / AsyncOpenAI / AzureOpenAI client in place.
+
+    Returns the same client unmodified when configuration is missing (see
+    :func:`frugal_metrics.config.load_config`). Safe to call more than once on
+    the same client — subsequent calls are idempotent.
+    """
+    config = load_config()
+    if config is None:
+        return client
+
+    try:
+        import openai  # type: ignore
+    except ImportError:
+        logger.warning("frugal-metrics: openai package not installed; cannot wrap")
+        return client
+
+    if getattr(client, "_frugal_wrapped", False):
+        return client
+
+    system = _detect_system(client)
+    skip_dirs = _build_skip_dirs(openai)
+
+    _patch(
+        client,
+        attr_chain=("chat", "completions"),
+        method_name="create",
+        operation=semconv.OP_CHAT,
+        system=system,
+        skip_dirs=skip_dirs,
+        config=config,
+        usage_extractor=_chat_usage,
+        stream_handler=_chat_stream_event,
+        capture_payload=True,
+    )
+    _patch(
+        client,
+        attr_chain=("completions",),
+        method_name="create",
+        operation=semconv.OP_TEXT_COMPLETION,
+        system=system,
+        skip_dirs=skip_dirs,
+        config=config,
+        usage_extractor=_completion_usage,
+        stream_handler=_completion_stream_event,
+        capture_payload=True,
+    )
+    _patch(
+        client,
+        attr_chain=("embeddings",),
+        method_name="create",
+        operation=semconv.OP_EMBEDDINGS,
+        system=system,
+        skip_dirs=skip_dirs,
+        config=config,
+        usage_extractor=_embedding_usage,
+        stream_handler=None,  # embeddings don't stream
+    )
+    # `responses` is only present on newer SDK versions.
+    _patch(
+        client,
+        attr_chain=("responses",),
+        method_name="create",
+        operation=semconv.OP_CHAT,
+        system=system,
+        skip_dirs=skip_dirs,
+        config=config,
+        usage_extractor=_responses_usage,
+        stream_handler=_responses_stream_event,
+        required=False,
+        capture_payload=True,
+    )
+
+    try:
+        setattr(client, "_frugal_wrapped", True)
+    except Exception:  # noqa: BLE001
+        pass
+    return client
+
+
+def _detect_system(client: Any) -> str:
+    # v1 supports OpenAI only. AzureOpenAI clients land here too but are tagged
+    # as plain `openai` until native Azure support ships.
+    return semconv.SYSTEM_OPENAI
+
+
+def _build_skip_dirs(openai_mod: Any) -> tuple[str, ...]:
+    import frugal_metrics
+
+    return tuple(
+        d
+        for d in (
+            caller_mod.package_dir_for(frugal_metrics),
+            caller_mod.package_dir_for(openai_mod),
+        )
+        if d
+    )
+
+
+def _resolve_target(client: Any, attr_chain: tuple[str, ...]) -> Any | None:
+    target: Any = client
+    for attr in attr_chain:
+        target = getattr(target, attr, None)
+        if target is None:
+            return None
+    return target
+
+
+def _patch(
+    client: Any,
+    *,
+    attr_chain: tuple[str, ...],
+    method_name: str,
+    operation: str,
+    system: str,
+    skip_dirs: tuple[str, ...],
+    config: Any,
+    usage_extractor: Callable[[Any], UsageReport],
+    stream_handler: Callable[[Any, UsageReport], None] | None,
+    required: bool = True,
+    capture_payload: bool = False,
+) -> None:
+    target = _resolve_target(client, attr_chain)
+    if target is None:
+        if required:
+            logger.debug(
+                "frugal-metrics: %s missing on %s; skipping",
+                ".".join(attr_chain),
+                type(client).__name__,
+            )
+        return
+
+    original = getattr(target, method_name, None)
+    if original is None:
+        return
+    if getattr(original, "_frugal_wrapped", False):
+        return
+
+    is_async = inspect.iscoroutinefunction(original)
+    wrapped = (
+        _make_async_wrapper(
+            original,
+            operation,
+            system,
+            skip_dirs,
+            config,
+            usage_extractor,
+            stream_handler,
+            capture_payload,
+        )
+        if is_async
+        else _make_sync_wrapper(
+            original,
+            operation,
+            system,
+            skip_dirs,
+            config,
+            usage_extractor,
+            stream_handler,
+            capture_payload,
+        )
+    )
+    wrapped._frugal_wrapped = True  # type: ignore[attr-defined]
+    try:
+        setattr(target, method_name, wrapped)
+    except Exception as exc:  # noqa: BLE001
+        logger.warning(
+            "frugal-metrics: failed to patch %s.%s: %s",
+            ".".join(attr_chain),
+            method_name,
+            exc,
+        )
+
+
+def _make_sync_wrapper(
+    original: Callable[..., Any],
+    operation: str,
+    system: str,
+    skip_dirs: tuple[str, ...],
+    config: Any,
+    usage_extractor: Callable[[Any], UsageReport],
+    stream_handler: Callable[[Any, UsageReport], None] | None,
+    capture_payload: bool,
+) -> Callable[..., Any]:
+    @functools.wraps(original)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        # If ANY of our instrumentation logic fails, fall through to the
+        # original call unmodified — we must never break customer code.
+        try:
+            streaming = _is_streaming(kwargs)
+            if streaming and stream_handler is None:
+                return original(*args, **kwargs)
+            ctx = CallContext(
+                system=system,
+                operation=operation,
+                request_model=_request_model(kwargs),
+                skip_package_dirs=skip_dirs,
+                batched=False,
+                request_payload=(
+                    _capture_openai_payload(kwargs) if capture_payload else None
+                ),
+            )
+            emit = start_call(config, ctx)
+        except Exception as exc:  # noqa: BLE001
+            _record_internal_error("setup_failed", exc, config)
+            return original(*args, **kwargs)
+
+        try:
+            response = original(*args, **kwargs)
+        except BaseException as exc:
+            safe_call(lambda: emit.error(exc))
+            raise
+
+        if streaming:
+            try:
+                return SyncStreamProxy(response, emit, stream_handler)  # type: ignore[arg-type]
+            except Exception as exc:  # noqa: BLE001
+                _record_internal_error("stream_proxy_failed", exc, config)
+                return response
+
+        safe_call(lambda: emit.success(usage_extractor(response)))
+        return response
+
+    return wrapper
+
+
+def _make_async_wrapper(
+    original: Callable[..., Any],
+    operation: str,
+    system: str,
+    skip_dirs: tuple[str, ...],
+    config: Any,
+    usage_extractor: Callable[[Any], UsageReport],
+    stream_handler: Callable[[Any, UsageReport], None] | None,
+    capture_payload: bool,
+) -> Callable[..., Any]:
+    @functools.wraps(original)
+    async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            streaming = _is_streaming(kwargs)
+            if streaming and stream_handler is None:
+                return await original(*args, **kwargs)
+            ctx = CallContext(
+                system=system,
+                operation=operation,
+                request_model=_request_model(kwargs),
+                skip_package_dirs=skip_dirs,
+                batched=False,
+                request_payload=(
+                    _capture_openai_payload(kwargs) if capture_payload else None
+                ),
+            )
+            emit = start_call(config, ctx)
+        except Exception as exc:  # noqa: BLE001
+            _record_internal_error("setup_failed", exc, config)
+            return await original(*args, **kwargs)
+
+        try:
+            response = await original(*args, **kwargs)
+        except BaseException as exc:
+            safe_call(lambda: emit.error(exc))
+            raise
+
+        if streaming:
+            try:
+                return AsyncStreamProxy(response, emit, stream_handler)  # type: ignore[arg-type]
+            except Exception as exc:  # noqa: BLE001
+                _record_internal_error("stream_proxy_failed", exc, config)
+                return response
+
+        safe_call(lambda: emit.success(usage_extractor(response)))
+        return response
+
+    return wrapper
+
+
+def _record_internal_error(stage: str, exc: BaseException, config: Any) -> None:
+    """Try to emit an internal error metric; swallow any failure."""
+    try:
+        from frugal_metrics.otel import get_instruments
+
+        instruments = get_instruments(config)
+        err_attrs: dict[str, Any] = {
+            semconv.FRUGAL_PROJECT_ID: config.project_id,
+            "frugal.internal_error.stage": stage,
+            "frugal.internal_error.type": type(exc).__name__,
+        }
+        if config.customer_id:
+            err_attrs[semconv.FRUGAL_CUSTOMER_ID] = config.customer_id
+        instruments.internal_errors.add(1, err_attrs)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _is_streaming(kwargs: dict[str, Any]) -> bool:
+    return bool(kwargs.get("stream"))
+
+
+def _request_model(kwargs: dict[str, Any]) -> str:
+    model = kwargs.get("model")
+    return str(model) if model is not None else "<unknown>"
+
+
+def _capture_openai_payload(kwargs: dict[str, Any]) -> RequestPayload:
+    max_tokens = kwargs.get("max_tokens", kwargs.get("max_completion_tokens"))
+    if not isinstance(max_tokens, int):
+        max_tokens = None
+    # The Responses API uses `input` instead of `messages`. Treat both as
+    # messages for analyzer purposes — they share the role/content shape.
+    messages = kwargs.get("messages") if "messages" in kwargs else kwargs.get("input")
+    return RequestPayload(
+        messages=messages,
+        tools=kwargs.get("tools"),
+        response_format=kwargs.get("response_format"),
+        max_tokens=max_tokens,
+    )
+
+
+# --- usage extractors ------------------------------------------------------
+
+
+def _attr(obj: Any, name: str, default: Any = None) -> Any:
+    """Get attribute from either a Pydantic-model-like object or a dict."""
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)
+
+
+def _chat_usage(response: Any) -> UsageReport:
+    usage = _attr(response, "usage")
+    comp_details = _attr(usage, "completion_tokens_details")
+    prompt_details = _attr(usage, "prompt_tokens_details")
+    return UsageReport(
+        response_model=_attr(response, "model"),
+        input_tokens=_attr(usage, "prompt_tokens"),
+        output_tokens=_attr(usage, "completion_tokens"),
+        reasoning_tokens=_attr(comp_details, "reasoning_tokens"),
+        cache_read_tokens=_attr(prompt_details, "cached_tokens"),
+    )
+
+
+def _completion_usage(response: Any) -> UsageReport:
+    usage = _attr(response, "usage")
+    return UsageReport(
+        response_model=_attr(response, "model"),
+        input_tokens=_attr(usage, "prompt_tokens"),
+        output_tokens=_attr(usage, "completion_tokens"),
+    )
+
+
+def _embedding_usage(response: Any) -> UsageReport:
+    usage = _attr(response, "usage")
+    return UsageReport(
+        response_model=_attr(response, "model"),
+        input_tokens=_attr(usage, "prompt_tokens"),
+        output_tokens=None,
+    )
+
+
+def _responses_usage(response: Any) -> UsageReport:
+    """OpenAI Responses API — `usage.input_tokens` / `usage.output_tokens`."""
+    usage = _attr(response, "usage")
+    out_details = _attr(usage, "output_tokens_details")
+    in_details = _attr(usage, "input_tokens_details")
+    return UsageReport(
+        response_model=_attr(response, "model"),
+        input_tokens=_attr(usage, "input_tokens"),
+        output_tokens=_attr(usage, "output_tokens"),
+        reasoning_tokens=_attr(out_details, "reasoning_tokens"),
+        cache_read_tokens=_attr(in_details, "cached_tokens"),
+    )
+
+
+# --- stream handlers -------------------------------------------------------
+#
+# For OpenAI chat/completions streams, usage appears only on the final chunk
+# and only when `stream_options={"include_usage": True}` is passed. We record
+# whatever we see; if the customer didn't opt in, we emit the call counter but
+# no token counts.
+
+
+def _chat_stream_event(chunk: Any, usage: UsageReport) -> None:
+    model = _attr(chunk, "model")
+    if model and not usage.response_model:
+        usage.response_model = model
+    chunk_usage = _attr(chunk, "usage")
+    if chunk_usage is None:
+        return
+    usage.input_tokens = _attr(chunk_usage, "prompt_tokens", usage.input_tokens)
+    usage.output_tokens = _attr(chunk_usage, "completion_tokens", usage.output_tokens)
+    comp_details = _attr(chunk_usage, "completion_tokens_details")
+    if comp_details is not None:
+        reasoning = _attr(comp_details, "reasoning_tokens")
+        if reasoning is not None:
+            usage.reasoning_tokens = reasoning
+    prompt_details = _attr(chunk_usage, "prompt_tokens_details")
+    if prompt_details is not None:
+        cached = _attr(prompt_details, "cached_tokens")
+        if cached is not None:
+            usage.cache_read_tokens = cached
+
+
+def _completion_stream_event(chunk: Any, usage: UsageReport) -> None:
+    # Legacy /v1/completions streams share the chat chunk shape for usage.
+    _chat_stream_event(chunk, usage)
+
+
+def _responses_stream_event(chunk: Any, usage: UsageReport) -> None:
+    # Responses API streams emit ResponseEvent objects; the terminal
+    # "response.completed" event carries the full response including usage.
+    response = _attr(chunk, "response")
+    if response is None:
+        return
+    model = _attr(response, "model")
+    if model:
+        usage.response_model = model
+    r_usage = _attr(response, "usage")
+    if r_usage is None:
+        return
+    usage.input_tokens = _attr(r_usage, "input_tokens", usage.input_tokens)
+    usage.output_tokens = _attr(r_usage, "output_tokens", usage.output_tokens)
+    out_details = _attr(r_usage, "output_tokens_details")
+    if out_details is not None:
+        reasoning = _attr(out_details, "reasoning_tokens")
+        if reasoning is not None:
+            usage.reasoning_tokens = reasoning
+    in_details = _attr(r_usage, "input_tokens_details")
+    if in_details is not None:
+        cached = _attr(in_details, "cached_tokens")
+        if cached is not None:
+            usage.cache_read_tokens = cached

frugal_sdk_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: frugal-sdk-python
+Version: 0.1.0
+Summary: Instrumentation for Cost-to-Code attribution.
+Project-URL: Homepage, https://frugal.co
+Author: Frugal AI Inc.
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: opentelemetry-api>=1.25.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25.0
+Requires-Dist: opentelemetry-sdk>=1.25.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34.0; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.34.0; extra == 'dev'
+Requires-Dist: openai>=1.40.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: reuse[charset-normalizer]>=5.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.40.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Frugal SDK for Python
+
+Instrument AI API calls with one line of code. Get per-call-site metrics — token usage, latency, call counts — exported via OpenTelemetry to any collector.
+
+## Install
+
+```bash
+pip install frugal-sdk-python
+
+# Plus whichever provider SDKs you use:
+pip install openai anthropic
+```
+
+## Quick start
+
+```python
+from frugal_metrics import wrap_openai, wrap_anthropic, wrap_bedrock
+from openai import OpenAI
+from anthropic import Anthropic
+import boto3
+
+client = wrap_openai(OpenAI())
+anthropic_client = wrap_anthropic(Anthropic())
+bedrock_client = wrap_bedrock(boto3.client("bedrock-runtime", region_name="us-west-2"))
+
+# Every call now emits metrics — no other code changes needed
+response = client.chat.completions.create(model="gpt-4o", messages=[...])
+```
+
+## Configuration
+
+All configuration is via environment variables. No `init()` call, no configuration objects.
+
+### Required
+
+Set both or the wrapper silently returns the client unmodified:
+
+| Variable            | Purpose                                                    |
+| ------------------- | ---------------------------------------------------------- |
+| `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 the same repo across microservices no longer collides. |
+
+### Optional
+
+| 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_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_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_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_DISABLED`                        | Set to `1` to disable all instrumentation without uninstalling.                          |
+
+## What gets captured
+
+Every wrapped call emits OTel metrics tagged with the caller's source file and function, the provider, and the model:
+
+| 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                                     | —                                      |
+| `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.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.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.few_shot_count`          | histogram | Few-shot exemplar pairs before final user (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.
+
+Every metric carries this base attribute set:
+
+- `frugal.project_id` — from your env vars (`frugal.customer_id` too when set); `frugal.component` is added on the per-component series when `FRUGAL_COMPONENTS` is set
+- `frugal.caller_file`, `frugal.caller_function` — auto-detected from the call stack
+- `gen_ai.system` — `openai`, `anthropic`, `aws.bedrock`, or `vertex_ai`
+- `gen_ai.request.model`, `gen_ai.response.model` — the model used
+- `gen_ai.operation.name` — `chat`, `text_completion`, or `embeddings`
+- `frugal.batched` — `true` for batch-API submissions, `false` otherwise
+
+The "Additional attributes" column above lists what each metric carries on top of the base set. See [`docs/metrics-reference.md`](docs/metrics-reference.md) for the values each attribute takes, sentinel values for caller fields, and the full internal-error-stage list.
+
+Metrics are aggregated per export interval (not sent per call), so network overhead is minimal regardless of call volume.
+
+## Supported providers
+
+| Provider                                       | Usage                                                  |
+| ---------------------------------------------- | ------------------------------------------------------ |
+| OpenAI                                         | `wrap_openai(OpenAI())`                                |
+| Anthropic                                      | `wrap_anthropic(Anthropic())`                          |
+| Claude on AWS Bedrock (via Anthropic SDK)      | `wrap_anthropic(AnthropicBedrock())`                   |
+| AWS Bedrock — any model, AWS SDKs directly     | `wrap_bedrock(boto3.client("bedrock-runtime"))`        |
+| Claude on Google Vertex                        | `wrap_anthropic(AnthropicVertex())`                    |
+
+`wrap_bedrock` covers all four `bedrock-runtime` operations (`invoke_model`,
+`invoke_model_with_response_stream`, `converse`, `converse_stream`) across
+every model on Bedrock — Anthropic, OpenAI gpt-oss, Amazon Nova, Meta Llama,
+Mistral, Cohere, AI21, DeepSeek, Qwen, Kimi, etc. Cross-region inference
+profile prefixes (`us.`, `eu.`, `jp.`, `apac.`, `au.`, `global.`) are
+preserved in `gen_ai.request.model`. Async clients (`aiobotocore` /
+`aioboto3`) are detected automatically. See [`docs/quickstart.md`](docs/quickstart.md#native-aws-bedrock-wrap_bedrock) for the full Bedrock walkthrough.
+
+## Streaming
+
+Streaming works with no extra setup. The wrapper returns a drop-in replacement that passes events through and emits metrics when the stream finishes.
+
+```python
+# OpenAI — opt in to include_usage for token counts in streams
+stream = client.chat.completions.create(
+    model="gpt-4o",
+    messages=[...],
+    stream=True,
+    stream_options={"include_usage": True},
+)
+for chunk in stream:
+    ...
+
+# Anthropic — token counts available natively, no opt-in needed
+stream = anthropic_client.messages.create(
+    model="claude-sonnet-4-20250514",
+    max_tokens=1024,
+    messages=[...],
+    stream=True,
+)
+for event in stream:
+    ...
+```
+
+## Internal library attribution
+
+If your code calls an internal helper library that wraps the AI SDK (e.g. `acme_ai_helpers`), add it to the block list so attribution lands on your business code:
+
+```bash
+FRUGAL_PATH_BLOCK_LIST="src/acme_ai_helpers,libs/llm_utils"
+```
+
+## Safety guarantees
+
+- If any required env var is unset, `wrap_openai` / `wrap_anthropic` return the client completely unmodified with zero overhead.
+- If any part of our instrumentation fails at runtime (OTel init, stack walking, metric emission), the original SDK call executes normally. We never raise our own exceptions into your code.
+- Wrapping is idempotent — calling `wrap_openai(client)` twice on the same client is safe.
+
+## Verifying the setup
+
+Set the OTLP endpoint to empty to print metrics to the console instead of exporting them:
+
+```bash
+export FRUGAL_API_KEY=local
+export FRUGAL_PROJECT_ID=my-project
+export FRUGAL_OTEL_EXPORTER_OTLP_ENDPOINT=   # empty → ConsoleMetricExporter
+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.

frugal_sdk_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+frugal_metrics/__init__.py,sha256=BNGv6yC3amP1DPvrn7RHO1GmfzPDfkJJxqcOYNNM0L8,474
+frugal_metrics/block_hash_lru.py,sha256=hv3VMS6xdjIraceA8Rih9bFeKGjbAqLhaL-nHv9bxwI,2223
+frugal_metrics/caller.py,sha256=uiXLROjZ9sD54uUUinuAcgWq6El05B6HZzwSUdLkx1E,7045
+frugal_metrics/config.py,sha256=53ed-Aun14MK7Ca0OJR2YX_rae8SU2ApXdwpXSeI1jY,8548
+frugal_metrics/instrument.py,sha256=YVvR8uSnczTuwbfi1rl-HBxUULEyIndSo2X-wCsiqMA,9317
+frugal_metrics/otel.py,sha256=ZRE-n7hWo6n1T4-3BktQ5zieuaqyE_tNI6f_TxDOe6E,11634
+frugal_metrics/prompt_analyzer.py,sha256=GwxwULD73v-Qfr0cAKpd3DdusqjrbEUCuYhYh6l3EYc,8379
+frugal_metrics/safe.py,sha256=V04QVgYYGdXM67MJjfBew4g2VF1jJ-JiQGXs3wxOp2k,1068
+frugal_metrics/semconv.py,sha256=OVy79s9oKKAV6dqK_lG1vX6YpCS7geM-gxxQZ8ZRv9g,2573
+frugal_metrics/streams.py,sha256=5nawTD08yAS-I_VQK2g_GhtMOmaqWaJGX23SuHs5YE0,5085
+frugal_metrics/wrappers/__init__.py,sha256=asuO1kRv3sn_C5YVH81m9js5HcBErIzzY197CyWlxWE,45
+frugal_metrics/wrappers/anthropic.py,sha256=3EpN2SZ9bBFY0IMFCBARSkVEQ1hXvAOaSjcuym2248I,8960
+frugal_metrics/wrappers/bedrock.py,sha256=LsMh5BKKZsHPmSVnN2s-ko60ooqGB3RnXqbn3f2xVgk,12692
+frugal_metrics/wrappers/bedrock_models.py,sha256=LMQsXpQ9p6P18_1LKeKF0A3wk5vMS5xIe6CKcWfYUYQ,15065
+frugal_metrics/wrappers/openai.py,sha256=-F7PWx_9Zgze8fbEDaYg9Pe5sSmj0R55MRhCl-szqK4,15212
+frugal_sdk_python-0.1.0.dist-info/METADATA,sha256=NR_6bLR3DPgAjrEYXieYaZgPIDvE9Nbtfh1FEbPlWvQ,11798
+frugal_sdk_python-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+frugal_sdk_python-0.1.0.dist-info/RECORD,,

frugal_sdk_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any