Configuration

The Patronus Experimentation Framework offers several configuration options that can be set in the following ways:

1. Through function parameters (in code)
2. Environment variables
3. YAML configuration file

Configuration options are prioritized in the order listed above, meaning that if a configuration value is provided through function parameters, it will override values from environment variables or the YAML file.

Configuration Options

Config name	Environment Variable	Default Value
service	PATRONUS_SERVICE	Defaults to value retrieved from OTEL_SERVICE_NAME env var or platform.node().
project_name	PATRONUS_PROJECT_NAME	Global
app	PATRONUS_APP	default
api_key	PATRONUS_API_KEY
api_url	PATRONUS_API_URL	https://api.patronus.ai
ui_url	PATRONUS_UI_URL	https://app.patronus.ai
otel_endpoint	PATRONUS_OTEL_ENDPOINT	https://otel.patronus.ai:4317
timeout_s	PATRONUS_TIMEOUT_S	300

Configuration Methods

1. Function Parameters

You can provide configuration options directly through function parameters when calling key Patronus functions.

Using init()

Use the init() function when you need to set up the Patronus SDK for evaluations, logging, and tracing outside of experiments. This initializes the global context used by the SDK.

import patronus

# Initialize with specific configuration
patronus.init(
    project_name="my-project",
    app="recommendation-service",
    api_key="your-api-key",
    api_url="https://api.patronus.ai",
    service="my-service"
)

Using run_experiment() or Experiment.create()

Use these functions when running experiments. They handle their own initialization, so you don't need to call init() separately. Experiments create their own context scoped to the experiment.

from patronus import run_experiment

# Run experiment with specific configuration
experiment = run_experiment(
    dataset=my_dataset,
    task=my_task,
    evaluators=[my_evaluator],
    project_name="my-project",
    api_key="your-api-key",
    service="my-service"
)

2. Environment Variables

You can set configuration options using environment variables with the prefix PATRONUS_:

export PATRONUS_API_KEY="your-api-key"
export PATRONUS_PROJECT_NAME="my-project"
export PATRONUS_SERVICE="my-service"

3. YAML Configuration File (patronus.yaml)

You can also provide configuration options using a patronus.yaml file. This file must be present in the working directory when executing your script.

service: "my-service"
project_name: "my-project"
app: "my-agent"

api_key: "YOUR_API_KEY"
api_url: "https://api.patronus.ai"
ui_url: "https://app.patronus.ai"
otel_endpoint: "https://otel.patronus.ai:4317"
timeout_s: 300

Configuration Precedence

When determining the value for a configuration option, Patronus follows this order of precedence:

1. Function parameter values (highest priority)
2. Environment variables
3. YAML configuration file
4. Default values (lowest priority)

For example, if you provide project_name as a function parameter and also have it defined in your environment variables and YAML file, the function parameter value will be used.

Programmatic Configuration Access

For more advanced use cases, you can directly access the configuration system through the Config class and the config() function:

from patronus.config import config

# Access the configuration singleton
cfg = config()

# Read configuration values
api_key = cfg.api_key
project_name = cfg.project_name

# Check for specific conditions
if cfg.api_url != "https://api.patronus.ai":
    print("Using custom API endpoint")

This approach is particularly useful when you need to inspect or log the current configuration state.