Python SDK

The adjudon package is the Python ingestion path. One install, one client.trace(...) call per AI decision, and the response tells you whether to proceed (approved), pause for human review (flagged), or stop (blocked).

Install

pip

pip install adjudon

For the async client (uses httpx):

pip — async extra

pip install "adjudon[async]"

The package has zero runtime dependencies for the sync client (stdlib only); the async client adds httpx>=0.24.

First call

Sync — one trace

from adjudon import Adjudon

client = Adjudon(
    api_key="adj_agent_<48-hex>",     # see /authentication
    agent_id="customer-support-bot",
)

trace = client.trace(
    input_context  = {"prompt": "Can I get a refund for order #1234?"},
    output_decision = {"action": "initiate_refund", "amount": 49.99},
)

if trace.status == "blocked":
    return "Sorry, I can't process this request right now."
elif trace.status == "flagged":
    # Human reviewer will check — proceed with caution
    pass

Async — one trace

import asyncio
from adjudon import AsyncAdjudon

async def main():
    async with AsyncAdjudon(
        api_key="adj_agent_<48-hex>",
        agent_id="customer-support-bot",
    ) as client:
        trace = await client.atrace(
            input_context  = {"prompt": "Refund request"},
            output_decision = {"action": "initiate_refund"},
        )
        print(trace.status, trace.trace_id)

asyncio.run(main())

trace.status is one of approved, flagged, blocked, or passthrough. passthrough is returned when the SDK is in fail_mode="open" (the default) and Adjudon is unreachable — the agent is never blocked by infrastructure failure.

Versions

Python	Supported	Notes
3.9	✓	Minimum supported
3.10	✓
3.11	✓
3.12	✓
3.8 and earlier	—	Not supported
3.13	partial	Should work; not in CI matrix yet

Current package version: 0.1.0 (Beta). Type stubs ship in the package (Typing :: Typed); mypy strict-mode passes.

Configuration

Constructor argument	Default	Purpose
api_key	required	Agent API key (adj_agent_<48-hex>)
agent_id	required	Agent identifier matching the key's scope
base_url	https://api.adjudon.com	Override only for staging
fail_mode	"open"	open returns passthrough on failure; closed raises
timeout	10 (seconds)	Request timeout
max_retries	3	Retry attempts on 429 / 5xx
redact_pii	False	Optional client-side scrub; server-side is always on

Idempotency

client.trace(idempotency_key=...) accepts a string. If omitted, the SDK generates a UUID4 per call. Duplicate keys within the 24-hour window return the cached response.

Errors

Exception	Cause
AdjudonAuthError	Invalid API key; never retried
AdjudonRateLimitError	Retries exhausted on 429 (only in fail_mode="closed")
AdjudonTimeoutError	Retries exhausted on timeout (only in fail_mode="closed")
AdjudonBlockedException	Policy returned block; always propagated as a compliance signal
AdjudonConfigError	Constructor argument invalid

fail_mode="open" returns TraceResponse.passthrough() for every exception except AdjudonBlockedException and AdjudonAuthError — the first is a compliance signal you must not swallow, the second is a configuration bug.

Framework adapters

The core package is what most teams need. The seven adapter packages wrap popular Python AI frameworks so a single import auto-instruments every model call:

Package	Wraps
adjudon-anthropic-tools	Anthropic SDK + tool-use
adjudon-langchain	LangChain
adjudon-llamaindex	LlamaIndex
adjudon-pydantic-ai	Pydantic AI
adjudon-autogen	AutoGen
adjudon-crewai	CrewAI
adjudon-otel	OpenTelemetry exporter

The OTel package is also documented at OpenTelemetry for teams already on an OTel collector.

Resources

• Quickstart — first trace in 60 seconds
• Authentication — API key formats and rotation
• Traces API — the underlying HTTP surface this SDK calls
• Error Codes — HTTP-level errors this SDK raises
• GitHub: github.com/adjudon/adjudon-python (the source-of-truth for issues, releases, and the changelog)
• PyPI: pypi.org/project/adjudon
• Changelog: ships with each release on GitHub