Python SDK

pip install benchspan

from benchspan import BenchGuard

guard = BenchGuard(
    api_key="ag_live_...",           # required
    agent="email-agent",              # optional: tags scans in dashboard
    mode="block",                     # optional: "block" (default) or "warn"
    api_url="https://api.benchspan.com",  # optional: override for self-hosted
)

result = guard.scan("some text", role="tool", source="gmail.get_email")

# result.injection      → bool
# result.score          → float, 0–1
# result.verdict        → "block" | "warn" | "pass"
# result.model_version  → str
# result.latency_ms     → int
# result.id             → str (UUID)

result = await guard.scan_async("some text", role="tool")

from openai import OpenAI
client = OpenAI()

@guard.wrap
def call_llm(messages):
    return client.chat.completions.create(model="gpt-5", messages=messages)

result = call_llm(messages)
# Raises InjectionDetectedError BEFORE client.chat.completions.create is invoked
# if any user/tool message is classified as injection.

@guard.wrap_async
async def call_llm(messages):
    return await client.chat.completions.create(model="gpt-5", messages=messages)

llm.invoke(messages, config={"callbacks": [guard]})
# or
crew = Crew(agents=[...], tasks=[...], callbacks=[guard])

from agents import Agent
agent = Agent(name="...", model="gpt-5", hooks=guard.as_agent_hooks())

from google.adk import LlmAgent
agent = LlmAgent(
    name="...",
    model="gemini-2.5-pro",
    before_model_callback=guard.as_adk_callback(),
)

from dataclasses import dataclass

@dataclass
class ScanResult:
    id: str
    injection: bool
    score: float
    verdict: str  # "block" | "warn" | "pass"
    model_version: str
    latency_ms: int

class InjectionDetectedError(Exception):
    result: ScanResult  # attached for inspection

from benchspan import InjectionDetectedError

try:
    call_llm(messages)
except InjectionDetectedError as e:
    print(f"Blocked: score={e.result.score:.4f}, id={e.result.id}")

import logging
logging.getLogger("benchspan").setLevel(logging.WARNING)