The dr-providers provider-call transport contract
A reference for the terms and guarantees that bind dr-providers.
This is the vocabulary of the provider-call transport contract dr-providers implements: the terms that name a validated provider-call configuration, its executed HTTP call, and the typed result; the guarantees that bind this repo; what is in and out of scope at the transport boundary; and the mapping from each term to the names actually exported by dr_providers.
Terms
| Term | Definition |
|---|---|
| Definition | A versioned description of an object's shape and its unset variables. |
| Variable | A named slot whose allowed values and identity effect are declared by a definition. |
| Config | A definition with every required variable set. |
| Hash | A deterministic fixed-length value computed by a declared algorithm over exact declared input bytes; its specific role and semantics come from the qualified term. dr-providers builds the identity hash specialization for its identity documents. |
| Identity Payload | Validated finite-JSON domain data deliberately selected to contain exactly the fields that determine an object's identity, and none that are incidental runtime or transport state. |
| Identity Document | A complete versioned finite-JSON document that carries its own schema name and version, with exactly the shape {schema, schema_version, payload}; the domain selects the identity payload fields inside it, while the serialization layer validates the finite JSON and exact document shape. |
| Canonical Identity JSON | The single deterministic UTF-8 JSON rendering of a validated identity document, produced without lossy normalization. |
| Identity Hash | The full 64-character lowercase SHA-256 hash of the canonical identity JSON of an identity document. |
| Model | A requested model name scoped to one provider service. |
| Transcript | An ordered sequence of role-and-content messages sent as provider-call input. |
| Provider Service | An external service family that exposes one or more model-serving API protocols. dr-providers targets OpenRouter, OpenAI, Gemini, and Anthropic. |
| Provider Client | An injected executor that translates and performs calls to a provider service. This package names that protocol Provider; both the HTTP client and the scripted test client implement it. |
| Model Route | The executable target tuple (provider, protocol, model), carrying a model and its HTTP protocol but excluding credentials, accounts, and generation controls. |
| Provider Quota Identity | A quota identity equal to one model route's exact (provider, protocol, model) tuple, with no credential, account, or override component, distinguishing quota pools only to route granularity. |
| Provider Call Definition | A versioned variable-bearing definition declaring a model route, output-affecting generation controls and provider body extensions, their constraints, and their identity effects. It is the sole owner of one or more provider call configs, each a complete assignment of its variables. |
| Provider Call Config | A complete validated config in which every required variable of exactly one provider call definition is set; its typed definition reference and full identity hash identify that owner. The fields that determine its identity are the model route plus every output-affecting generation control and provider body extension; transport policy is excluded. |
| Provider Call Request | An immutable transport request, itself identified by a full identity hash, referencing exactly one provider call config and containing one transcript, without duplicating config assignments or transport policy. |
| Provider Transport Policy | An operational transport-only policy for credentials, base URL, timeout, native retry count, and other HTTP execution concerns. Its native retry count defaults to zero; it carries no semantic failure classification, attempt bound, backoff, or durability policy, and is excluded from identity. |
| Provider Transport Response | A typed successful transport value containing the raw response body as received, without normalization, plus provider identifiers, usage, cost, warnings, and diagnostics available at the transport boundary. It does not assert semantic acceptance by the caller. |
| Provider Transport Failure | A typed expected transport failure value retaining the complete raw request and failure-response bytes as received, without normalization, plus transport diagnostics, without the caller's semantic classification or retry decisions. |
| Provider Transport Outcome | The closed union of a provider transport response or a provider transport failure that never raises for an expected result. Unexpected programming and infrastructure errors remain exceptions. |
| Provider Invocation Evidence | A stable serializable artifact for one completed transport invocation, binding the exact provider call request and provider transport policy identities to its provider transport outcome and the complete raw request and success-or-failure bytes as received, without normalization. Credential material and authorization headers are excluded, and it retains bodies without silent truncation. |
Guarantees
Execution and Reporting Without Semantic Judgment. dr-providers turns a validated provider call request into an executed HTTP call and a typed provider transport outcome, retaining complete raw evidence; it never decides semantic acceptance, retry, or backoff — those belong to the caller.
- Splits the provider call definition from the provider call config it owns — the definition owns the variables, the config carries a complete validated assignment of them.
- Identifies each provider call config by a full 64-character identity hash over its canonical identity JSON — never a truncated value on the identity path.
- References rather than duplicates: a provider call request stores its config's identity hash and one transcript, never a copy of the config's controls.
- Excludes the provider transport policy from identity, and defaults its native retry count to zero.
- Returns a closed provider transport outcome for every expected result; only unexpected programming and infrastructure errors raise.
- Retains complete raw request, response, and failure bodies as received in provider invocation evidence without silent truncation.
- Redacts credential material and authorization headers from all retained evidence.
- Derives a provider quota identity as exactly the
(provider, protocol, model)tuple — no credential, account, or override component. - Leaves semantic acceptance, failure taxonomy, retry, backoff, checkpointing, result storage, and concurrency to the caller.
In vs. Out of Scope
| In scope | Out of scope |
|---|---|
|
|
Exported Names
Each row maps a term, or a group of supporting exports, to names in dr_providers.__all__. Every exported name appears exactly once in the names column; there are no aliases or alternate spellings. The terms definition, variable, config, hash, identity payload, identity document, canonical identity JSON, identity hash, and provider service name concepts rather than exports, so they have no row.
| Term | Exported names | Note |
|---|---|---|
| Model | ModelRoute, ProviderKind, Protocol, ProviderBaseUrl, ApiKeyEnv |
Listed under model route below, which carries the model; the HTTP Protocol and ProviderKind are its other two components. ProviderBaseUrl / ApiKeyEnv are transport-policy vocabulary (they live in policy.py, not on the route or in identity) enumerating the default per-provider base URLs and key-environment names. |
| Transcript | Transcript, PromptMessage, MessageRole |
An ordered tuple of PromptMessage, each a MessageRole and its content. |
| Provider Client | Provider, HttpProvider, ScriptedProvider, ScriptedOutcome |
The protocol is named Provider; HttpProvider performs real calls (imported lazily so pure modules never pull in httpx), and ScriptedProvider replays a sequence of ScriptedOutcome with no network. |
| Model Route | See the model row. | The ModelRoute and its component enums are listed with model above. |
| Provider Quota Identity | ProviderQuotaIdentity |
Its label method returns a stable collision-free label string. |
| Provider Call Definition | ProviderCallDefinition, PROVIDER_CALL_DEFINITION_SCHEMA, PROVIDER_CALL_DEFINITION_SCHEMA_VERSION, RequestControl, TokenLimitParameter, ReasoningEffort, ReasoningRequestShape, GenerationControls, ControlConstraints, ProviderBodyExtensions |
The definition declares the output-affecting controls (RequestControl, with GenerationControls values), their HTTP mapping (TokenLimitParameter, ReasoningEffort, ReasoningRequestShape), their ControlConstraints, and raw ProviderBodyExtensions; the schema constants name its identity document. |
| Provider Call Config | ProviderCallConfig, PROVIDER_CALL_CONFIG_SCHEMA, PROVIDER_CALL_CONFIG_SCHEMA_VERSION, openrouter_chat_config, openai_chat_config, openai_responses_config, gemini_chat_config, anthropic_messages_config |
Each per-protocol builder returns a ProviderCallConfig for one provider call definition, carrying the full identity hash; the builders fix only the model route and constraints, never any base URL or credential (those are transport-policy concerns). |
| Provider Call Request | ProviderCallRequest, PROVIDER_CALL_REQUEST_SCHEMA, PROVIDER_CALL_REQUEST_SCHEMA_VERSION, build_payload, protocol_path |
The request references exactly one provider call config (by its identity hash on the identity path) and one transcript, and is itself an identity document named by its schema constants and carrying its own full identity hash; build_payload renders the HTTP request body and protocol_path the endpoint path for its config's protocol. |
| Provider Transport Policy | ProviderTransportPolicy, policy_for, DEFAULT_TIMEOUT_SECONDS, DEFAULT_IDLE_TIMEOUT_SECONDS, DEFAULT_BASE_URLS, DEFAULT_API_KEY_ENVS |
policy_for(kind, ...) takes a ProviderKind and derives the api_key_env and base_url from DEFAULT_API_KEY_ENVS / DEFAULT_BASE_URLS (the default per-provider maps), each overridable. DEFAULT_TIMEOUT_SECONDS (120s) is the absolute wall-clock cap and DEFAULT_IDLE_TIMEOUT_SECONDS (90s) the primary idle/progress stall detector; the effective idle timeout is clamped to at most the wall-clock cap at construction. |
| Provider Transport Response | ProviderTransportResponse, TokenUsage, CostInfo, ResponsesDiagnostics, parse_response, parse_chat_completions_body, parse_responses_body, parse_anthropic_messages_body, token_usage_from_body, cost_from_body |
The response carries TokenUsage, CostInfo, and (for the Responses surface) ResponsesDiagnostics. The parse and extraction functions build these from the raw response body as received. ResponsesDiagnostics.response_id_hash is a truncated, unsalted SHA-256 value documented as diagnostic-only, never a domain identity hash. |
| Provider Transport Failure | ProviderTransportFailure, ProviderFailure, failure_record |
ProviderTransportFailure is the flat typed failure outcome: its classification fields (failure_class, code, message, retryable) sit directly on the value alongside the raw request/response evidence — it does not embed a ProviderFailure. ProviderFailure is a standalone compact classification record built by failure_record and carried only on the raised-error path (ProviderFailureError.failure), never returned as an expected outcome. The transport-level failure taxonomy and redaction helpers are in the supporting rows below. |
| Provider Transport Outcome | ProviderTransportOutcome, is_response, is_failure |
The union type plus its two predicates, is_response and is_failure, that report which member an outcome holds. |
| Provider Invocation Evidence | ProviderInvocationEvidence, RawHttpRequest, PROVIDER_INVOCATION_EVIDENCE_SCHEMA, PROVIDER_INVOCATION_EVIDENCE_SCHEMA_VERSION |
RawHttpRequest is the retained request record with authorization headers redacted; the schema constants name its identity document. |
| Transport failure taxonomy | FailureClass, RETRYABLE_FAILURE_CLASSES, RECOVERABLE_FAILURE_CLASSES, classify_status_code, FAILURE_ERROR_TYPES, raise_failure |
Transport-level labeling only: classify_status_code maps an HTTP status to a FailureClass, and the frozensets flag which classes carry a retry hint. Semantic failure classification and retry eligibility belong to the caller. |
| Error types | ProviderFailureError, PermanentProviderError, TransientProviderError, RateLimitedProviderError, ResourceExhaustionProviderError, UnknownProviderError, ControlValidationError |
Raised carriers for unexpected errors, rooted at ProviderFailureError (which wraps a ProviderFailure record). ControlValidationError (a PermanentProviderError) fires at definition or config validation time for an unsupported control, a missing required control, an undeclared or reserved extension key, or a reasoning effort with no wire equivalent. |
| Credential redaction | sanitize_headers, sanitize_kwargs, SANITIZE_KEYS |
Strip authorization headers and credential-like keys before persistence; SANITIZE_KEYS is the redacted key set. |
| Conformance warnings | conformance_warnings, with_conformance_warnings, ProviderTransportWarning, WarningSeverity |
Post-response checks over observed evidence; each violation is a ProviderTransportWarning at a WarningSeverity, and the caller decides fatality. |
Scope. This sheet is the authoritative statement of the provider-call transport contract dr-providers implements. Exported names match src/dr_providers/__init__.py.