Provider-neutral generation APIs

What you will be able to do

1. Define a minimal provider-neutral contract.
2. Normalize response, usage, refusal, and error evidence.
3. Document feature gaps and migration risk.

Prerequisites: dictionaries, loops, functions, exceptions and installed Python or paper tracing. Reuse earlier Builder artifacts only when the task requires them.

This curriculum runs self-study on VetsLearn. Where the text calls for an instructor, peer or formal review, use the stated acceptance criteria for self-review. Reflection questions support reflection; they do not replace independent assessment. A peer review is optional unless your actual organization requires it.

Part 1 Technical instruction

Provider neutrality is deliberate containment, not the fiction that every model has identical behavior. Define the smallest application contract - messages or input, constraints, response text or object, request ID, usage, finish state, and structured error. Keep provider-specific translation inside adapters. Capability discovery, snapshot/model selection, streaming events, structured output, refusal semantics, and tool calls must be represented explicitly where the application depends on them. A migration record names the old and new behavior, evaluation set, acceptance rule, and rollback path.

Mechanism and implementation

An adapter translates provider events while exposing capability gaps. Declare input/output modalities, schemas, tools, streaming, state, context limits, usage and supported reasoning controls. Local/cloud is deployment; frontier is a capability claim. Neither substitutes for a manifest. Endpoint-compatible syntax does not imply feature equivalence.

Constructed offline example

Save as topic_example.py and run python topic_example.py with an installed Python 3.11+ interpreter. This standard-library construction uses synthetic values; its checks are not provider measurements.

capabilities = {"tools": True, "schema": False, "reasoning_controls": []}
def normalize(raw):
    state = raw.get("state")
    if state not in {"complete", "partial", "refusal", "error", "cancelled"}:
        state = "error"
    return {"status": state, "text": raw.get("text") if state == "complete" else None,
            "usage": raw.get("usage")}
assert normalize({"state": "partial", "text": "half"})["text"] is None
assert normalize({"state": "refusal"})["status"] == "refusal"
assert not capabilities["schema"]
print("adapter checks passed")

Engineering decisions

• Select the stable application contract.
• Expose or hide a provider feature gap.
• Choose when to pin a model snapshot and what change triggers reevaluation.

Worked example

Two mock adapters return different field names and refusal indicators. The common interface normalizes both into GenerationResult. The application never branches on provider name; it branches on declared capabilities. The pack tests request identifiers, usage, refusal, schema failures, capability declarations and a simulated retry/deadline policy. It does not call provider APIs or prove real network timeout behavior.

Diagnose the failure

Unknown status is an error; refusal and partial are not empty successful strings. Missing usage means unknown, not zero. B3v2 remains the bounded offline reference pack; no live provider behavior is measured.

Part 2 Guided practice

Normalize two mock provider shapes into one contract, retaining request IDs and original status metadata. Reject a requested schema feature absent from the manifest. Independently preserve partial content separately without rendering it as final.

Answer criteria and feedback: Unknown status is an error; refusal and partial are not empty successful strings. Missing usage means unknown, not zero. B3v2 remains the bounded offline reference pack; no live provider behavior is measured.

Continue with the downloadable pack below. If the pack or interpreter is unavailable, trace this self-contained example by hand in an input/expected-status/controlling-rule table and label execution unverified. Do not invent passing output. No account, credential, paid call, purchase or actual deployment is required.

Part 3 Remediation

Start with a single adapter and pass the common contract. Add the second only after the contract is stable. If a feature cannot be represented honestly, declare the gap instead of silently degrading it. After repair, reassess with the alternate scenario in scenario_alt.json. A critical authorization, data-handling, evidence-integrity, or prohibited-action failure cannot be averaged into successful practice; it requires targeted remediation.

Part 4 Sources and currency

• https://platform.openai.com/docs/api-reference/responses
• https://docs.anthropic.com/en/api/messages

Use the workflow reference for capability manifests and task/model/deployment/harness comparisons. Source currency must be checked before any real provider integration. Provider/product behavior is illustrative where mocked; resolve current interfaces only from official documentation in an authorized environment.