Installation

Install and configure the Avaliar Python SDK

Prerequisites

The Avaliar Python SDK requires Python 3.13 or higher.

Verify your Python version before proceeding:

python --version

Installation

Install the SDK from PyPI:

pip install avaliar-python-sdk

For local detection mode

If you want to run detectors locally on your own infrastructure, also install the evaluation engine:

pip install avaliar_eval

avaliar_eval is only needed when using detection_mode="local". Cloud detection (detection_mode="cloud") works without it.

Environment Variables

Configure the SDK through environment variables. You can set them in your shell, a .env file, or your deployment platform.

Variable	Required	Default	Description
AVALIAR_API_KEY	Yes	—	Your API key from the Avaliar dashboard
AVALIAR_API_URL	No	https://api.avaliar.ai/v1	API endpoint URL
OPENAI_API_KEY	No	—	Required when using detection_mode="local"

Set your environment variables:

Shell

export AVALIAR_API_KEY="your-api-key"

# Optional
export AVALIAR_API_URL="https://api.avaliar.ai/v1"
export OPENAI_API_KEY="your-openai-key"

.env file

.env

AVALIAR_API_KEY=your-api-key

# Optional
AVALIAR_API_URL=https://api.avaliar.ai/v1
OPENAI_API_KEY=your-openai-key

Basic Usage

Once installed and configured, import the SDK and start tracing your LLM calls:

from avaliar import traceable
from openai import AsyncOpenAI

client = AsyncOpenAI()

@traceable(
    "llm",
    model="gpt-4o",
    provider="openai",
)
async def generate(messages: list) -> str:
    response = await client.chat.completions.create(
        model="gpt-4o",
        messages=messages,
    )
    return response.choices[0].message.content


result = await generate([
    {"role": "user", "content": "Hello, world!"}
])

The @traceable decorator automatically captures inputs, outputs, latency, and token usage — then submits the trace to the Avaliar platform in the background.

You can get your API key from the API Keys page in the Avaliar dashboard. Each key is scoped to your organization and can be revoked at any time.

Next Steps

@traceable Decorator

Learn how to instrument your LLM functions with automatic tracing.

Detection

Enable safety detection on your traced calls.

AvaliarBaseLLM

Implement the LLM interface for benchmarks and evaluations.

Error Handling

Handle errors and configure retry behavior.