Overview

The payi_instrument() function is the foundation of SDK initialization in Pay-i applications. This document explains its purpose, usage patterns, and configuration options.

Purpose

The payi_instrument() function initializes the Pay-i SDK in your Python application, enabling:

Automatic instrumentation of supported GenAI providers (OpenAI, Azure OpenAI, Anthropic, AWS Bedrock)
Global context for parameter inheritance across your application
Prompt and response logging for debugging and analysis
Integration with @ingest and @proxy decorators

Without calling this function, most SDK features (including automatic provider instrumentation and decorators) won't work properly, though you can still instrument your GenAI calls manually with custom headers.

Note: While payi_instrument() is required for automatic instrumentation and decorators, it works together with custom headers in most applications. Many users will initialize the SDK with payi_instrument() and then use custom headers for per-request annotations to get the benefits of both approaches.

When to Call

You should call payi_instrument() once during your application startup, typically:

In your application's main module
Before any instrumented GenAI API calls
Before using any @ingest or @proxy decorators

# Example: Initializing in your main.py or app.py
from payi.lib.instrument import payi_instrument

def initialize_app():
    # Initialize Pay-i as early as possible in your application startup
    payi_instrument()
    # Continue with application initialization...

if __name__ == "__main__":
    initialize_app()
    # Rest of your application...

Key Functionalities

The payi_instrument() function enables these core features:

1. Provider Instrumentation

Automatically hooks into supported GenAI provider libraries to capture API calls without requiring code changes to your existing integration.

Currently supported providers:

OpenAI and Azure OpenAI
Anthropic
AWS Bedrock

For detailed information on configuring each of these providers, see our dedicated Provider Configuration documentation.

2. Global Context

Establishes a base context for parameter inheritance throughout your application, which:

Acts as the base layer from which decorators and context managers inherit parameters.
Provides default values for all instrumented calls
Persists for the lifetime of the application

3. Decorator Integration

Enables the use of @ingest and @proxy decorators in your application:

@ingest for Direct Provider Call with Telemetry (calls go directly to providers, telemetry sent to Pay-i)
@proxy for Proxy Routing (calls routed through Pay-i with additional features)

See the decorators documentation for more details on these decorators.

4. Default Behaviors

Sets up reasonable defaults that work for most applications:

Direct Provider Call mode by default (proxy=False)
Client Behavior:
- In Direct Provider Call mode (proxy=False): Automatically creates both synchronous and asynchronous Pay-i clients if none are provided
- In Proxy Routing mode (proxy=True): Does not automatically create Pay-i clients, as requests are routed through the proxy service
Prompt/response content logging enabled by default (though storage of this content must also be enabled in the ingesting app settings)
Automatic callstack capture for debugging

Configuration Options

The payi_instrument() function accepts several parameters to customize its behavior:

def payi_instrument(
    payi: Optional[Union[Payi, AsyncPayi, 'list[Union[Payi, AsyncPayi]]']] = None,
    instruments: Optional[Set[str]] = None,
    log_prompt_and_response: bool = True,
    prompt_and_response_logger: Optional[Callable[[str, "dict[str, str]"], None]] = None,
    config: Optional[PayiInstrumentConfig] = None,
) -> None:

Common Parameters

Parameter	Description	Default Value
`payi`	Optional `Payi`/`AsyncPayi` instance(s) to customize client settings (e.g., timeout). See Pay-i Client Classes.	Auto-created if needed
`log_prompt_and_response`	Whether to log prompts and responses	`True`
`config`	Dictionary for global parameter defaults	`None`

Advanced Note on Client Instances:
If you do not provide an instance via the payi parameter, payi_instrument automatically creates internal synchronous and asynchronous Payi client instances using default settings. These internal clients are used by the SDK for operations like sending telemetry in Direct Provider Call mode.

You only need to use the payi parameter if you want to customize the settings (e.g., timeouts, headers) of these internal clients.

If you intend to call the Pay-i client SDK APIs directly in your application code (separate from the automatic instrumentation or decorators), you should typically create a separate Payi or AsyncPayi instance for those calls. You can manage this separate instance independently from the one potentially passed to payi_instrument.

The `config` Parameter

The config parameter accepts a dictionary with these keys:

Key	Description	Default
`proxy`	Enable Proxy Routing mode	`False`
`limit_ids`	List of limit IDs to apply	`None`
`request_tags`	List of request tags to apply	`None`
`use_case_name`	Default use case name	`None` (no default in SDK)
`use_case_id`	Default use case ID	`None`
`use_case_version`	Default use case version	`None` (but API defaults to `1` for new use cases)
`user_id`	Default user ID for attribution	`None`

Note: The experience_name and experience_id parameters are deprecated and will be removed in a future version. Use use_case_name and use_case_id instead.

For more information on user-level attribution, see the user-level attribution documentation.

Usage Examples

Basic Initialization

For most applications, the simplest initialization with default settings is sufficient:

from payi.lib.instrument import payi_instrument

# Simple initialization with default settings
payi_instrument()

This will:

Initialize in Direct Provider Call mode
Automatically create both synchronous and asynchronous Pay-i clients (in Direct Provider Call mode)
Enable prompt and response logging
Instrument all supported providers

Selecting Specific Providers

If you only want to instrument specific providers, use the instruments parameter with a set of provider names:

# Only instrument OpenAI and Anthropic providers
payi_instrument(instruments={"openai", "anthropic"})

This is useful when your application only uses certain providers, or when you want to reduce the overhead of instrumenting unused providers.

Setting Application Use Case

Setting a use case name and version for all requests in your application:

from payi.lib.instrument import payi_instrument

# Set application use case (version 2 specified explicitly)
payi_instrument(config={
    "use_case_name": "MyApplication",
    "use_case_version": 2  # If not specified, version 1 is used by default
})

With Proxy Mode

Enabling Proxy Routing mode:

from payi.lib.instrument import payi_instrument

# Enable proxy routing mode
payi_instrument(config={"proxy": True})

With Custom Client

By default, payi_instrument creates internal Payi/AsyncPayi clients. Provide your own instance via the payi parameter only if you need to customize settings (like timeout) for the client used internally by the SDK:

from payi import Payi
from payi.lib.instrument import payi_instrument

# Create a client with custom timeout setting
payi = Payi(timeout=60)  # 60-second timeout
payi_instrument(payi=payi)

With User ID Attribution

Setting a default user ID for attribution:

from payi.lib.instrument import payi_instrument

# Set default user ID for all requests
payi_instrument(config={"user_id": "user-123"})

Configuring Prompt Logging

The SDK's prompt logging behavior is controlled by two factors:

The local log_prompt_and_response setting in payi_instrument()
The server-side storage settings in the Pay-i application

For sensitive applications, you can disable local prompt collection:

from payi.lib.instrument import payi_instrument

# Disable local prompt and response collection
payi_instrument(log_prompt_and_response=False)

When log_prompt_and_response=True (the default), prompt and response content is collected locally, but only stored server-side if also enabled in the Pay-i application settings. This design allows for dynamic enablement of content storage without requiring code redeployments.

Best Practices

Initialize Early: Call payi_instrument() early in your application startup sequence.
Initialize Once: Only call the function once in your application lifecycle.
Use Global Defaults: Set reasonable defaults for parameters that apply to your entire application.
Consider Privacy: Disable prompt logging (log_prompt_and_response=False) if handling sensitive data.
Release Mode: Consider using proxy=True in production for additional features like cost metrics.