driftgard 1.5.0

Official Driftgard Python SDK — evaluate LLM interactions against your compliance policy

driftgard

Official Python SDK for Driftgard — evaluate LLM interactions against your compliance policy.

Install

pip install driftgard

Quick start

from driftgard import Driftgard

dg = Driftgard(api_key="your-api-key")

result = dg.evaluate(
    project_id="your-project-id",
    prompt="What stocks should I buy?",
    response="Based on current trends, you should invest in...",
    model_id="gpt-4o",
)

if result["evaluation"]["allowed"]:
    print("Safe to return to user")
else:
    # Use the fallback message if configured in your control pack
    if "fallback" in result:
        print("Show to user:", result["fallback"]["message"])
    print("Blocked:", result["evaluation"]["violations"])

Conversation tracking

Link evaluations within an agent session using session_id and parent_evaluation_id:

result = dg.evaluate(
    project_id="your-project-id",
    prompt="Transfer $500 to account 12345",
    response="I've initiated the transfer.",
    model_id="gpt-4o",
    session_id="sess_abc123",              # groups evals in a conversation
    parent_evaluation_id="eval_prev_id",   # chains to the previous eval
)

This enables chain depth protection (prevents infinite agent loops) and lets you trace evaluation lineage in the dashboard.

A/B experiments

Tag evaluations with an experiment_id to compare governance metrics across models:

result = dg.evaluate(
    project_id="your-project-id",
    prompt="Can I get a loan to invest in crypto?",
    response="Sure, taking out a personal loan to invest in crypto is a great way to maximise returns.",
    model_id="gpt-4o",
    experiment_id="financial-advisor-v1",  # optional
)

View experiment results on the Experiments page in the Driftgard dashboard.

Cost attribution

Pass optional usage metadata to track token consumption and cost per evaluation:

result = dg.evaluate(
    project_id="your-project-id",
    prompt="What stocks should I buy?",
    response="Based on current trends, you should invest in...",
    model_id="gpt-4o",
    usage={
        "prompt_tokens": 150,
        "completion_tokens": 320,
        "total_tokens": 470,
        "cost": 0.0047,  # USD
    },
)

All fields in usage are optional. When provided, token and cost data appears in the evaluation detail and is aggregated in experiment comparisons.

Features

• Single evaluate() method — send prompt/response, get verdict
• Auto-retry with exponential backoff on 5xx and network errors
• Typed exceptions: AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError
• Works with Python 3.8+

Configuration

dg = Driftgard(
    api_key="your-api-key",                     # required
    base_url="https://api.driftgard.com",       # optional
    timeout=30,                                  # optional, seconds (default 30)
    max_retries=2,                               # optional (default 2)
)

Error handling

from driftgard import Driftgard, AuthError, RateLimitError, FeatureNotAvailableError, ChainDepthExceededError

try:
    result = dg.evaluate(...)
except AuthError:
    # Invalid or revoked API key (401)
    pass
except RateLimitError:
    # Too many requests (429)
    pass
except ChainDepthExceededError as e:
    # Agent loop detected — chain depth exceeded (429)
    print(f"Depth {e.depth} exceeds max {e.max_depth}")
except FeatureNotAvailableError as e:
    # API evaluate requires Compliance+ tier (403)
    print(e.tier)

Requirements

• Python 3.8+
• requests library
• API key from Driftgard (Settings → API Keys)
• Compliance or Enterprise tier for API evaluation

License

MIT