Configuration

Donkey.from_env() resolves configuration from, in precedence order: explicit kwargs → environment variables → .donkey-kit.toml → defaults.

Governed model access

The three required values for the LLM proxy:

Missing required fields are reported all at once with their env-var names, so you can fix configuration in a single pass.

JWT / model-wallet auth mode

A model-wallet proxy identifies the caller from an IdP-issued JWT plus a durable wallet-selector client ID, with Client ID Enforcement disabled and no client_secret. Select it with DONKEY_LLM_PROXY_AUTH=jwt:

In jwt mode the required fields are llm_proxy_url and llm_proxy_wallet_client_id — not client_id / client_secret. The rotating JWT is not a config value: supply it through an AuthProvider passed as Donkey(llm_auth=…), so the SDK can re-fetch it as it rotates and refresh it once on a 401:

from donkey_kit import Donkey, DonkeyConfig
from donkey_kit.core.auth import StaticToken  # or your own rotating AuthProvider
 
donkey = Donkey(
    DonkeyConfig(
        llm_proxy_url="https://<ingress-gw>/<instance>/",
        llm_proxy_auth="jwt",
        llm_proxy_wallet_client_id="<wallet-client-id>",
    ),
    llm_auth=StaticToken("<jwt>"),  # rides as Authorization: Bearer <jwt>
)

Auth providers

An AuthProvider (in donkey_kit.core.auth) is any object with two async methods: token() returns the current credential and invalidate() drops a cached one. The transport calls invalidate() and retries exactly once when a downstream call returns 401.

For a rotating JWT from your IdP, implement the two methods yourself and pass the object as llm_auth.

Optional attribution

Correlation headers

Per-call and per-run correlation IDs ride on request headers. The gateway’s inbound header names aren’t published, so the SDK uses placeholder names you can override to match your gateway. The IDs also appear on spans and exceptions regardless of the header names. See Telemetry & cost.

Cost-attribution tags

A fixed set of dimensions set once and emitted on every call (both as request headers and as donkey.cost.* span attributes). Override them per run with donkey.run(team=…, project=…, env=…, enduser_id=…). The key set is fixed — an unknown dimension is a configuration error, not a silently dropped tag. See Telemetry & cost.

In .donkey-kit.toml these live under a [donkey.cost] table (the end-user dimension keeps its dotted key):

[donkey.cost]
team = "support"
project = "triage-v2"
env = "prod"
"enduser.id" = "user-42"

The request-header names the gateway reads for these tags aren’t published, so the SDK uses placeholder names you can override to match your gateway: DONKEY_COST_TEAM_HEADER, DONKEY_COST_PROJECT_HEADER, DONKEY_COST_ENV_HEADER, DONKEY_COST_ENDUSER_HEADER (or the matching cost_*_header config keys). The donkey.cost.* span attributes carry the full value regardless.

Telemetry

telemetry_capture_content defaults to false on purpose: spans are emitted inside your process, upstream of the gateway’s PII masking, so capturing content re-exports the very text the platform masks. Enable it only for a trusted collector. See Telemetry & cost.

Behaviour

Anypoint control plane

A separate credential from the LLM proxy, used by features that call the Anypoint control plane (for example, the connected-app token and the CLI). You don’t need these for governed model access.

Config file

Instead of env vars you can put non-secret values in a [donkey] table in .donkey-kit.toml, read from the working directory (or $XDG_CONFIG_HOME). Keys are the DonkeyConfig field names:

[donkey]
llm_proxy_url = "https://<ingress-gw>/<instance>/"
llm_proxy_client_id = "…"

donkey init generates this file from your current environment. Keep secrets (llm_proxy_client_secret, client_secret) out of the committed file and supply them as environment variables.

Programmatic

from donkey_kit import Donkey, DonkeyConfig
 
# Explicit config (kwargs win over env):
donkey = Donkey(DonkeyConfig(
    llm_proxy_url="https://<ingress-gw>/<instance>/",
    llm_proxy_client_id="…",
    llm_proxy_client_secret="…",
))
 
# Or from the environment, with lifecycle:
async with Donkey.from_env() as donkey:
    ...