> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weflayr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Name the feature and customer of your gateway calls, call the management API, or track LLM calls made without the gateway.

<Columns cols={2}>
  <Card title="PyPI" icon="https://mintcdn.com/weflayr/jf99vD0W4dsGuj5S/images/icons/brand-python.svg?fit=max&auto=format&n=jf99vD0W4dsGuj5S&q=85&s=be466123963abf6057c3cd6f42362a78" href="https://pypi.org/project/weflayr/" width="24" height="24" data-path="images/icons/brand-python.svg">
    The `weflayr` package.
  </Card>

  <Card title="Changelog" icon="https://mintcdn.com/weflayr/jf99vD0W4dsGuj5S/images/icons/history.svg?fit=max&auto=format&n=jf99vD0W4dsGuj5S&q=85&s=84c4ca074f5d7d74cf6f394abb6f37d9" href="/changelog/python" width="24" height="24" data-path="images/icons/history.svg">
    What changed in each release.
  </Card>
</Columns>

## Install

Requires Python 3.13 or later.

```bash theme={null}
pip install weflayr
```

## Send metadata to the gateway

Wrap your calls in `propagate_metadata` to tag them with their feature, customer and call name, through the gateway or with telemetry. See [Name features, customers and runs](/sdks/features-and-runs).

## Call the management API

`weflayr.client()` returns a client for every management route, with a key that has the Management scope. See [Call the management API](/sdks/management-api) for an example and the list of routes.

## Track calls made without the gateway

When your app calls the providers directly, the SDK can record each call with OpenTelemetry and send it to Weflayr. See [Telemetry](/sdks/telemetry) for the step by step.

```python theme={null}
import weflayr

weflayr.auto_instrument(ai_sdks=[weflayr.AiSdk.OPENAI, weflayr.AiSdk.ANTHROPIC])
```

## Reference

### `enable_propagate_metadata_to_gateway`

```python theme={null}
weflayr.enable_propagate_metadata_to_gateway(gateway_base_url=None)
```

Makes every OpenAI client send the current `propagate_metadata` and `set_call_name` values in the `x-weflayr-metadata` header, on requests to `https://gateway.weflayr.com`. Pass `gateway_base_url` to target another gateway URL. Calls sent to the gateway are recorded by the gateway itself, never twice by the SDK.

### `propagate_metadata`

```python theme={null}
weflayr.propagate_metadata(feature_name, customer_name=None, extra_tags=None, feature_run_uuid=None, fn=None, provider_name_override_if_telemetry_instrumentation=None)
```

Use it as a context manager (`with`), a decorator (`@`), or call `fn` directly with `fn=`. Every LLM call made inside the scope, including nested ones, gets its values. Each scope (or each call of a decorated function) is one feature run.

<ParamField body="feature_name" type="string" required>
  The product feature making the call (e.g. `"support-chat"`).
</ParamField>

<ParamField body="customer_name" type="string">
  The customer the call is made for. It joins your AI cost to your revenue.
</ParamField>

<ParamField body="extra_tags" type="dict[str, str | int | float | bool]">
  Your own dimensions to filter on.
</ParamField>

<ParamField body="feature_run_uuid" type="string">
  Records the calls under this run instead of a new one, to group the calls of one run made in several scopes or processes. Create it with `weflayr.create_feature_run_uuid()`: 32 lowercase hexadecimal characters.
</ParamField>

<ParamField body="provider_name_override_if_telemetry_instrumentation" type="weflayr.AIProviderName">
  The provider to bill a call recorded by the SDK, when the client on the wire differs from it (e.g. Mistral reached through the OpenAI client). Ignored for gateway calls.
</ParamField>

### `set_call_name`

```python theme={null}
weflayr.set_call_name(call_name)
```

A context manager or decorator naming the LLM call inside a feature (e.g. `"summarize_ticket"`). It keeps the enclosing `propagate_metadata` scope and does not start a new feature run.

### `auto_instrument`

```python theme={null}
weflayr.auto_instrument(ai_sdks, api_key=None, base_url=None, default_tags=None, export_mode="batch", mask=None, capture_message_content=None, warn_on_export_error=True)
```

Records every call of the given provider SDKs: `weflayr.AiSdk.OPENAI`, `ANTHROPIC`, `BEDROCK`, `COHERE`, `GOOGLE_GENAI`, `ELEVENLABS`, `MISTRAL`, or a list of them. Each needs its instrumentation package, listed in [Telemetry](/sdks/telemetry#install-and-instrument). The other parameters are those of `setup`.

### `setup`

```python theme={null}
weflayr.setup(api_key=None, base_url=None, default_tags=None, export_mode="batch", mask=None, capture_message_content=None, warn_on_export_error=True)
```

Configures where recorded calls are sent, without instrumenting any provider SDK: use it when your app already runs its own OpenTelemetry instrumentation. Calling it again replaces the previous configuration.

<ParamField body="api_key" type="string">
  A key with the Management scope. Defaults to `WEFLAYR_API_KEY`.
</ParamField>

<ParamField body="base_url" type="string" default="&#x22;https://api.weflayr.com&#x22;">
  Where recorded calls are sent. Defaults to `WEFLAYR_BASE_URL` when set.
</ParamField>

<ParamField body="default_tags" type="dict">
  Tags added to every recorded call.
</ParamField>

<ParamField body="export_mode" type="&#x22;batch&#x22; | &#x22;immediate&#x22;" default="&#x22;batch&#x22;">
  `"immediate"` sends each call as soon as it ends, instead of in batches.
</ParamField>

<ParamField body="capture_message_content" type="boolean" default="true">
  Set `False` to keep prompts, answers and tool definitions in your process: only tokens, cost and latency are sent.
</ParamField>

<ParamField body="mask" type="function">
  Receives a copy of each call's attributes and returns the ones to send. Returning `None` keeps them unchanged; raising an error drops all of them.
</ParamField>

<ParamField body="warn_on_export_error" type="boolean" default="true">
  Set `False` to silence the warning written to stderr on each failed export.
</ParamField>

### `flush`

```python theme={null}
weflayr.flush()
```

Sends the recorded calls still in memory. Call it before a short-lived process (script, Lambda) exits; a long-running server flushes on its own.

### `client`

```python theme={null}
weflayr.client(api_key=None, base_url="https://app.weflayr.com/api")
```

Returns the [management API](/api/management/get-costs) client. `api_key` defaults to `WEFLAYR_API_KEY`.

## Environment variables

| Variable | What it does |
| - | - |
| `WEFLAYR_API_KEY` | The API key used by `setup`, `auto_instrument` and `client` when none is passed. |
| `WEFLAYR_BASE_URL` | Where recorded calls are sent, when `base_url` is not passed. |
| `WEFLAYR_DEBUG` | Set to any value to log what the SDK records and sends. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.