Detection Modes

Choose between local and cloud detection

When using the Avaliar SDK, you can choose between two detection modes: local and cloud. Each mode determines where detection runs, what infrastructure is required, and how results are delivered.

Detection modes apply to SDK integration only. When using the Proxy, detection always runs on Avaliar’s cloud backend.

Local Detection

Local detection runs entirely on your infrastructure using the avaliar_eval package and your OpenAI API key. After a traced function returns, a background thread runs all configured detectors and then posts the complete trace (with detection results) to the Avaliar backend.

Requirements

• pip install avaliar_eval — the local detection engine
• The OPENAI_API_KEY environment variable must be set in your runtime environment

How it works

1. Your traced function executes and returns a result to the caller
2. A background thread picks up the trace data (prompt + response)
3. Detection runs locally using the avaliar_eval package and your OpenAI API key
4. The complete trace — including detection results — is posted to Avaliar

Pros and cons

Pros:

• Data stays on your infrastructure until the final trace post
• Fast feedback loop during development
• Full control over the detection pipeline

Cons:

• Requires an OpenAI API key (additional cost)
• Uses your compute resources
• You manage the avaliar_eval dependency and its updates

Best for

Development, testing, and environments where data cannot leave your infrastructure.

Example

from avaliar import traceable

@traceable(detection_mode="local")
def summarize(text: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "user", "content": f"Summarize: {text}"}
        ]
    )
    return response.choices[0].message.content

Cloud Detection

Cloud detection offloads all analysis to Avaliar’s backend infrastructure. The trace is posted immediately after the function returns, and a background worker on Avaliar’s servers runs detection asynchronously via a Redis queue.

Requirements

• No additional API keys or infrastructure needed
• An active Avaliar API key with SDK scope (already required for tracing)

How it works

1. Your traced function executes and returns a result to the caller
2. The trace data (prompt + response) is posted to Avaliar immediately
3. Avaliar queues the detection job for asynchronous processing
4. A backend worker picks up the job, runs all detectors, and stores the results

Pros and cons

Pros:

• No additional API keys needed
• No local compute overhead
• Always uses the latest detector versions automatically
• Simplest setup

Cons:

• Content is sent to Avaliar’s backend for analysis
• Detection results are not immediately available (async processing)

Best for

Production deployments where you want minimal infrastructure overhead.

Example

from avaliar import traceable

@traceable(detection_mode="cloud")
def summarize(text: str) -> str:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "user", "content": f"Summarize: {text}"}
        ]
    )
    return response.choices[0].message.content

Comparison

	Local	Cloud
Data location	Your infrastructure	Avaliar backend
Extra dependencies	avaliar_eval, OpenAI key	None
Compute cost	Your resources	Included in Avaliar plan
Detector updates	Manual package updates	Automatic
Setup complexity	Medium	Low
Recommended for	Development	Production

Start with local mode during development for fast feedback, then switch to cloud in production to minimize overhead on your application.