Unified Provider Adapters
Introduction: One Interface, Three Providers
Welcome back to Model Selection and Routing in Python. Two units down, we have built a working router: it reads a prompt, decides which tier deserves the request, and prices each call against the model that served it. That is real progress, but it rests on an assumption we never questioned: every call went through one company's SDK.
That assumption gets expensive to maintain. The moment we want a cheap model from one vendor and a strong model from another, four separate differences show up: how we send the request, where the answer text lives in the response, what the usage fields are named, and what the tokens cost. If those differences leak into our routing and logging code, every new provider means edits everywhere.
So, in this unit, we will draw a boundary and put all of that variation behind it:
- A normalized result that every provider must produce;
- One shared pricing function that never branches on vendor;
- Three thin adapter functions, one per provider;
- A provider registry that lets a single loop serve all three.
By the end, we will run the same prompt through OpenAI, Anthropic, and Google from one loop that never touches a vendor-specific type.
The Shared Foundation: Model Constants, Clients, and Pricing
Before any adapter, we need the pieces all three providers share: three model constants, three clients, and one pricing table keyed by all three models.
Each client is constructed with no arguments because each one reads its API key from the environment, so credentials never appear in our calling code. The pricing table is the interesting part: as you may recall from the earlier cost course, we always divide the per-million published rate by 1_000_000 to store a per-token rate. That habit pays off here, since three different companies now sit in the same table with the same two keys, input and output. Identical structure across vendors is precisely what lets a single pricing function serve all of them.
The Normalized Completion and call_cost()
Now we write down the contract. Every adapter, regardless of vendor, must return this exact shape.
This is the Completion idea from the earlier course with one new field, provider, which matters now that a model name alone no longer tells us who served the request:
textholds the answer as a plain string, so downstream code never digs through nested response objects;providerandmodelidentify who served the request and with what, which is what routing and logging read;input_tokensandoutput_tokensare already merged into single counts, whatever the vendor called them;costis the dollar figure for this one call.
Notice what call_cost() does not contain: no if, no vendor check, and no special case. Rates arrive through a dictionary lookup, so adding a fourth provider never touches this math.
Adapter One: generate_openai()
With the contract fixed, an adapter is just a translator. Here is the first one, which sets the shape that the other two will imitate.
The signature is the part to memorize: (prompt, model) -> Completion. A provider call goes in, a normalized result comes out, and nothing else escapes. OpenAI makes this adapter short because response.output_text already gives us a single string, and usage.input_tokens and usage.output_tokens already match our field names.
One detail carries over from the previous unit: the same model variable goes into the request and into call_cost(). A request can never be billed at another model's rates because there is only one value to get wrong.
Adapter Two: generate_anthropic() and Where the Shapes Differ
The signature and return type are the same, but there are three concrete differences in the middle.
The prompt must be wrapped in a messages list of role-and-content dictionaries; the response returns a list of content blocks, so the text lives at response.content[0].text; and max_tokens is mandatory, which is worth pausing on. It is a provider constraint, not a style preference: omit it, and the call raises an error rather than picking a default for us. It also caps billable output, since output tokens are the priciest line on any bill.
The point is not that Anthropic is awkward. The point is that every bit of this awkwardness is now sealed inside one function, and its caller sees a plain Completion.
Adapter Three: generate_google() and Normalizing Usage Fields
The third adapter renames almost everything, and its usage fields need real arithmetic rather than a straight copy.
Requests use contents=, text arrives at response.text, and usage lives under usage_metadata, with prompt_token_count standing in for input tokens. The two middle lines are where the money is:
thoughts_token_countcounts thinking tokens, the same reasoning tokens we metered in the earlier course. Google bills them as output but reports them in their own field, so adding them tocandidates_token_countis required for a correct total; skipping the addition quietly understates the cost.or 0handles the case where the API does not report a thinking-token count. In this example, it treats an absent count as zero soNone + intdoes not raise aTypeError; verify the provider's reporting semantics for the model you deploy.
The PROVIDERS Registry and the Provider-Independent Loop
Three adapters with one shared signature can be stored in a dictionary, which removes the need for any dispatch logic at the call site.
PROVIDERS maps names to functions, not strings, so PROVIDERS[provider](prompt, model) looks up an adapter and calls it in one expression: there is no if/elif chain to extend. The models list is our workload of (provider, model) pairs, and the loop sends one identical prompt to each. Look closely at the print statements: they read result.provider, result.model, result.cost, and result.text, all normalized fields. Not one line below the adapters touches a vendor SDK object, and the width specifiers :10 and :24 keep the cost column aligned.
The abstraction boundary can be visualized as three provider-specific paths converging on one shared result shape.

Reading the Output and What the Abstraction Buys
Running the program sends one prompt through three companies and prints three comparable reports.
The cost column is the payoff: $0.000208, $0.000683, and $0.000441 for the same question, with differences driven mostly by how much each model chose to write. Those three numbers are only comparable because usage was normalized before pricing. To add a fourth provider, create its client, translate its request, response, and usage fields in one adapter, then add its model to PRICING, its adapter to PROVIDERS, and its pair to models. The reporting loop, shared cost math, routing, JSONL logging, and spend aggregation stay untouched. The honest limit is that this interface exposes only what all providers share, so vendor-specific features live outside it and are added deliberately when needed.
Conclusion and Next Steps
We have drawn a clean abstraction boundary. Above it sit a normalized Completion, shared pricing math, and a registry-driven loop that speaks only in normalized fields. Below it sit three adapters absorbing every difference in request format, response nesting, usage naming, and token accounting. Provider variation stopped being an application-wide concern and became a per-function detail.
Two gaps remain, and they are the same ones we flagged after routing. Nothing yet checks whether an answer was actually good enough, and nothing reacts when a provider errors out or rate-limits us. With one common interface in place, both become straightforward to add: a quality check reads result.text, and a fallback simply tries the next entry in PROVIDERS. That is exactly what the final unit builds.
Time to write it yourself: in the practices ahead, we will define the Completion contract, implement each adapter one provider at a time, and watch the same loop absorb a brand-new vendor without a single edit.
