Python SDK

The official VeraID Python SDK provides a client for managing credentials, monitoring AI agent usage, enforcing budgets, and detecting prompt injection attacks. It includes async support, built-in retry logic, and integration wrappers for OpenAI and LangChain.

Installation

pip install veraid

Optional Extras

Install with framework-specific integrations:

pip install veraid[openai]      # OpenAI integration
pip install veraid[langchain]   # LangChain integration
pip install veraid[all]         # All integrations

Quick Start

from veraid import VeraIDClient

client = VeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",
)

# Fetch a credential
db_url = client.get_credential("production-db-url")
print(f"Connected to: {db_url.value}")

---

Initialization

Create a client instance with your API key and optional configuration:

from veraid import VeraIDClient

client = VeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",             # Required for AI agent features
    base_url="https://app.veraid.io",   # Optional, defaults to production
    debug=False,                         # Optional, enables verbose logging
    retry_attempts=3,                    # Optional, default: 3
    timeout=30,                          # Optional, request timeout in seconds
)

Tip

Use environment variables for configuration instead of hardcoding values. The SDK automatically reads from environment variables when constructor arguments are not provided.

Async Client

For async applications, use the AsyncVeraIDClient:

from veraid import AsyncVeraIDClient

client = AsyncVeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",
)

# All methods are async
credential = await client.get_credential("production-db-url")

---

Credential Management

get_credential

Fetch a single credential by name.

credential = client.get_credential("aws-access-key")

print(credential.name)        # 'aws-access-key'
print(credential.value)       # 'AKIAIOSFODNN7EXAMPLE'
print(credential.expires_at)  # '2026-06-19T00:00:00Z'

Parameters:

Parameter	Type	Required	Description
name	str	Yes	Name of the credential to fetch

Returns: Credential

@dataclass
class Credential:
    name: str
    value: str
    expires_at: str | None
    scopes: list[str]
    metadata: dict[str, Any]

list_credentials

List all credentials available to the current identity.

credentials = client.list_credentials()

for cred in credentials:
    print(f"{cred.name}: expires {cred.expires_at or 'never'}")

Returns: list[Credential]

---

Budget Management

get_budget_status

Retrieve the current budget status for the AI agent.

budget = client.get_budget_status()

print(f"Budget: ${budget.used:.2f} / ${budget.limit:.2f} ({budget.percent_used:.1f}%)")
print(f"Status: {budget.status}")  # 'OK' | 'WARNING' | 'CRITICAL' | 'EXCEEDED'
print(f"Projected: ${budget.projected_spend:.2f}")

Returns: BudgetStatus

@dataclass
class BudgetStatus:
    limit: float
    used: float
    percent_used: float
    status: str  # 'OK' | 'WARNING' | 'CRITICAL' | 'EXCEEDED'
    period: str  # 'daily' | 'weekly' | 'monthly'
    projected_spend: float
    reset_at: str

check_budget

Check if a specific cost can be accommodated within the remaining budget.

result = client.check_budget(2.50)

if result.allowed:
    # Proceed with the AI call
    response = openai_client.chat.completions.create(...)
else:
    print(f"Budget exceeded: {result.reason}")

Parameters:

Parameter	Type	Required	Description
cost	float	Yes	Estimated cost in USD

Returns: BudgetCheck

@dataclass
class BudgetCheck:
    allowed: bool
    remaining_budget: float
    reason: str | None

---

Usage Tracking

record_usage

Record token and cost usage for an AI agent request.

client.record_usage(
    prompt_tokens=1250,
    completion_tokens=847,
    total_tokens=2097,
    cost=0.063,
    model="gpt-4",
    latency=2340,
    metadata={
        "task_type": "ticket-triage",
        "ticket_id": "TICKET-4521",
    },
)

Parameters:

Parameter	Type	Required	Description
prompt_tokens	int	Yes	Number of prompt tokens
completion_tokens	int	Yes	Number of completion tokens
total_tokens	int	Yes	Total tokens consumed
cost	float	Yes	Estimated cost in USD
model	str	Yes	Model identifier
latency	int	No	Response time in milliseconds
tool_calls	list[str]	No	Tools invoked during the request
metadata	dict	No	Additional context

Returns: None

---

Prompt Security

check_injection

Analyze a prompt for potential injection attacks.

result = client.check_injection(user_prompt)

if result.is_injection:
    print(f"Injection detected: {result.category}")
    print(f"Confidence: {result.confidence}")
    print(f"Details: {result.explanation}")
else:
    # Proceed with the prompt
    pass

Parameters:

Parameter	Type	Required	Description
prompt	str	Yes	The prompt to analyze

Returns: InjectionResult

@dataclass
class InjectionResult:
    is_injection: bool
    confidence: float        # 0.0 to 1.0
    category: str | None     # 'jailbreak' | 'data_exfil' | 'prompt_leak' | 'role_hijack'
    explanation: str | None

guard_prompt

Check for injection and raise an exception if one is detected.

from veraid.exceptions import InjectionDetectedError

try:
    safe_prompt = client.guard_prompt(user_prompt)
    # safe_prompt is the original prompt, returned only if safe
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": safe_prompt}],
    )
except InjectionDetectedError as e:
    print(f"Blocked: {e.category} ({e.confidence})")
    # Return a safe response to the user

Parameters:

Parameter	Type	Required	Description
prompt	str	Yes	The prompt to guard

Returns: str (the original prompt if safe)

Raises: InjectionDetectedError if injection is detected

---

Analytics

get_stats

Retrieve usage statistics for the AI agent over a specified time period.

stats = client.get_stats("7d")

print(f"Total requests: {stats.total_requests}")
print(f"Total cost: ${stats.total_cost:.2f}")
print(f"Average latency: {stats.average_latency}ms")
print(f"Injections blocked: {stats.injections_blocked}")

Parameters:

Parameter	Type	Required	Description
period	str	Yes	Time period: 1h, 24h, 7d, 30d, 90d

Returns: AgentStats

@dataclass
class AgentStats:
    total_requests: int
    total_tokens: int
    total_cost: float
    average_latency: float
    average_cost_per_request: float
    injections_blocked: int
    budget_utilization: float
    top_models: list[dict]
    top_tools: list[dict]

---

OpenAI Integration

The SDK provides a wrapper for the OpenAI client that automatically monitors all API calls.

from openai import OpenAI
from veraid import VeraIDClient
from veraid.integrations.openai import wrap_openai

veraid_client = VeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",
)

openai_client = wrap_openai(OpenAI(), veraid_client)

# All calls are now automatically monitored
response = openai_client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Summarize this document..."}],
)

# Usage is automatically recorded:
# - Token counts (prompt + completion)
# - Cost estimate based on model pricing
# - Latency
# - Budget check before each call
# - Prompt injection detection on user messages

Async OpenAI

from openai import AsyncOpenAI
from veraid import AsyncVeraIDClient
from veraid.integrations.openai import wrap_openai

veraid_client = AsyncVeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",
)

openai_client = wrap_openai(AsyncOpenAI(), veraid_client)

response = await openai_client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Summarize this document..."}],
)

Configuration

Customize the wrapper behavior:

openai_client = wrap_openai(OpenAI(), veraid_client,
    check_budget=True,
    record_usage=True,
    detect_injection=False,  # Disable for lower latency
)

---

LangChain Integration

Use the VeraID callback handler to automatically monitor LangChain chains and agents.

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from veraid import VeraIDClient
from veraid.integrations.langchain import VeraIDCallback

veraid_client = VeraIDClient(
    api_key="kd_live_your_api_key",
    agent_id="id_agent123",
)

callback = VeraIDCallback(veraid_client)

llm = ChatOpenAI(model="gpt-4", callbacks=[callback])

# All LLM calls through this chain are monitored
response = llm.invoke("What is the status of ticket TICKET-4521?")

The callback automatically tracks:

Feature	Description
Token usage	Records prompt and completion tokens for each LLM call
Cost tracking	Estimates cost based on model and token counts
Latency	Measures response time for each call
Tool calls	Logs tool invocations in agent chains
Chain tracking	Associates multiple LLM calls within a single chain execution
Error capture	Reports LLM errors and timeouts to VeraID

Agent Monitoring

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_functions_agent
from langchain.tools import Tool
from veraid.integrations.langchain import VeraIDCallback

callback = VeraIDCallback(veraid_client)

# Define your tools
tools = [
    Tool(name="search_kb", func=search_knowledge_base, description="Search the knowledge base"),
    Tool(name="get_ticket", func=get_ticket, description="Get ticket details"),
]

llm = ChatOpenAI(model="gpt-4")
agent = create_openai_functions_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, callbacks=[callback])

# The callback monitors the entire agent execution, including tool calls
result = executor.invoke({"input": "Resolve ticket TICKET-4521"})

---

Error Handling

The SDK provides typed exception classes for different failure modes:

from veraid import VeraIDClient
from veraid.exceptions import (
    VeraIDError,
    AuthenticationError,
    RateLimitError,
    BudgetExceededError,
    InjectionDetectedError,
    NotFoundError,
)

try:
    credential = client.get_credential("my-secret")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except BudgetExceededError as e:
    print(f"Budget exceeded: {e.limit} / {e.used}")
except InjectionDetectedError as e:
    print(f"Injection: {e.category} ({e.confidence})")
except NotFoundError:
    print("Credential not found")
except VeraIDError as e:
    print(f"VeraID error: {e.message}")

---

Context Manager

The client supports context manager usage for automatic cleanup:

with VeraIDClient(api_key="kd_live_your_api_key") as client:
    credential = client.get_credential("my-secret")
    # Client is automatically closed when exiting the block

Async version:

async with AsyncVeraIDClient(api_key="kd_live_your_api_key") as client:
    credential = await client.get_credential("my-secret")

---

Environment Variables

The SDK reads the following environment variables as defaults:

Variable	Description	Required
VERAID_API_KEY	API key for authentication	Yes
VERAID_AGENT_ID	Agent identity ID (for AI agent features)	For agent features
VERAID_BASE_URL	Base URL override (default: https://app.veraid.io)	No
VERAID_DEBUG	Enable debug logging (true / false)	No

export VERAID_API_KEY="kd_live_your_api_key"
export VERAID_AGENT_ID="id_agent123"
export VERAID_DEBUG="false"

Note

Constructor arguments take precedence over environment variables. If you provide api_key in the constructor, the VERAID_API_KEY environment variable is ignored.