Existing application? Add one decorator.

Set the SpendLens environment variables, then decorate the business workflow that makes supported OpenAI or Anthropic calls. The provider client remains unchanged.

SPENDLENS_API_KEY=sli_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SPENDLENS_PROJECT=shopping-assistant
SPENDLENS_API_BASE_URL=https://spendlensai.dev/backend
SPENDLENS_PROMPT_SAMPLING=template_only
SPENDLENS_DISABLE=0

import spendlensai
from openai import OpenAI

client = OpenAI()

@spendlensai.observe(workload="customer-support-reply")
def generate_customer_reply(message: str):
    return client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Give concise, accurate billing help."},
            {"role": "user", "content": message},
        ],
    )

A bare @spendlensai.observe derives a stable workload name from the Python module and function. Use workload="..." when you want an explicit business-friendly name.

Decorator mode supports official Python OpenAI chat.completions.create and responses.create calls and Anthropic messages.create calls, including supported sync and async variants. It does not inspect arbitrary HTTP traffic or direct REST calls, and SpendLens does not proxy model traffic.

Use the tracked-client API when one function makes multiple unrelated model calls or you need exact endpoint, task, or dynamic metadata attribution. Explicit client tags override decorator context, which overrides inferred callsite information.

with client.tag(endpoint="recommend-products"):
    response = client.chat.completions.create(...)

with client.tag(endpoint="recommend-products"):
    response = client.messages.create(...)

Inside client.tag(), the SDK records provider, model, token usage, available OpenAI or Anthropic cache counters, latency, Python function name, file name, and line number. Without an endpoint, the workload key looks like shopping/recommendations.py::recommend_products.

Environment variables are the recommended configuration path. These explicit parameters remain available for existing tracked-client integrations.

client = track(
    openai_client,
    project="shopping-assistant",
    api_key="sli_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    api_base_url="https://spendlensai.dev/backend",
    provider="openai",
    prompt_sampling="template_only",
    debug=False
)

client = track(
    anthropic_client,
    project="shopping-assistant",
    api_key="sli_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    api_base_url="https://spendlensai.dev/backend",
    provider="anthropic",
    prompt_sampling="template_only",
    debug=False
)

The SDK reads process environment variables. Local .env files must be loaded by your application or runtime; production secrets should be injected by the deployment platform.

SPENDLENS_API_KEY=sli_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SPENDLENS_PROJECT=shopping-assistant
SPENDLENS_API_BASE_URL=https://spendlensai.dev/backend
SPENDLENS_PROMPT_SAMPLING=template_only
SPENDLENS_DISABLE=0

Set SPENDLENS_DISABLE=1 to temporarily return the original OpenAI or Anthropic client unchanged and stop SpendLens network calls.

Use a stable endpoint label when you want cleaner dashboard grouping. Good examples are recommend-products, classify-review, or summarize-ticket.

with client.tag(endpoint="recommend-products"):
    response = client.chat.completions.create(...)

with client.tag(endpoint="recommend-products"):
    response = client.messages.create(...)

Use metadata for low-risk operational labels such as customer tier, region, experiment name, or request type. Do not put prompts, API keys, emails, or personal data in metadata.

with client.tag(
    endpoint="recommend-products",
    metadata={"customer_tier": "enterprise", "region": "us"}
):
    response = client.chat.completions.create(...)

Automatic workload classification is the default. Advanced users can explicitly override a task when they know the correct category.

with client.tag(endpoint="recommend-products", task="generation"):
    response = client.chat.completions.create(...)

with client.tag(endpoint="recommend-products", task="generation"):
    response = client.messages.create(...)

template_only is recommended because reusable system/developer instructions improve workload categorisation without sending user prompts or model responses. Set prompt sampling to off when no prompt template text should leave your application.

client = track(
    openai_client,
    project="shopping-assistant",
    api_key="sli_test_xxx...",
    api_base_url="https://spendlensai.dev/backend",
    prompt_sampling="off"
)

with client.tag(endpoint="recommend-products"):
    response = client.chat.completions.create(...)

# Recommended for short scripts, tests, jobs, and notebooks.
client.flush()

When a provider returns cache usage, SpendLens records it automatically. OpenAI uses prompt_tokens_details.cached_tokens; Anthropic uses cache_read_input_tokens and cache_creation_input_tokens. View model-level hit rates under Dashboard → Reports → Cache Efficiency. If the provider response has no cache fields, SpendLens shows the unsupported state rather than assuming zero cache reads.