Migration and portability

Read these first

• Model deprecation and version pinning
• Evaluation in CI

What you will know

• Place the abstraction boundary that makes a provider swap feasible

  A seam around provider-specific prompts, tool schemas, and response handling limits the blast radius of a swap.

• Estimate the cost of migrating off a current dependency

  Include inventory, dual-run effort, data revalidation, and rollback time; the hidden work usually dominates API rewrites.

• Re-qualify against an eval suite rather than by inspection

  Model updates can change refusals, tool calls, latency, and output structure even when benchmark scores look stable.

• Plan for a deprecation before it is announced

  A sunset date is less useful than an owner, replacement path, compatibility test, and last safe rollout window.

• Write a decision record that names the lock-in, its expected payoff, exit trigger, and reversal cost

  Vendor-specific features can be rational when their benefit is measurable and the conditions for abandoning them are explicit.

Chapters

1. 1

   A complete(prompt) helper abstracts the transport, not the task

   One function used in forty places looks provider-agnostic while hiding nothing that matters: prompts tuned to a particular model's quirks sit at the call sites, streaming and tool calls escape around the boundary, and structured output cannot be expressed through it at all. It abstracts the HTTP call, which was never the expensive part of a swap. Here you trace what actually leaks when a provider changes behind that signature.

   Read chapter
2. 2

   The seam belongs around a task, with its prompt, schema and evals

   The portable unit is a task, such as classify-ticket or extract-invoice, owning its prompt, tool schema, output parsing, retry rules and eval set behind a single interface. A provider swap then proceeds one task at a time, each with a test that says whether the swap worked. Blast radius becomes a count of tasks rather than call sites, and each task can be migrated, or not, on its own evidence.

   Read chapter
3. 3

   A lowest-common-denominator layer discards the features you pay for

   Serving three providers through one interface means exposing only what all three share, which pushes prompt caching, native structured output, provider-specific tool semantics and reasoning controls outside the boundary. That forfeit is a real cost, sometimes larger than the migration it insures against, and it is usually paid silently over years. Portability deserves funding at specific seams rather than uniform application across the codebase.

   Read chapter
4. 4

   Migration cost is revalidation, not rewriting API calls

   The API surface changes in an afternoon. The schedule goes on inventorying every prompt in production, re-tuning them, dual-running old and new against real traffic, revalidating stored outputs and embeddings, and holding a rollback path open. A credible estimate prices that work plus the part nobody plans for: agreeing what counts as good enough on tasks where the two models are simply different rather than better or worse.

   Read chapter
5. 5

   A point release can change refusals and tool calls with flat benchmarks

   Same family, same published scores, different product: refusal rates move, tool-call frequency rises, answers lengthen, and JSON that always parsed starts to vary. A few engineers trying it will not find this, because the changes concentrate in cases nobody thinks to try. Re-qualifying means running the task-level suite, including structure and latency assertions, and treating any change of model identifier as a release that needs sign-off.

   Read chapter
6. 6

   The useful part of a deprecation plan exists before the announcement

   A ninety-day sunset notice is only alarming when nothing is standing. What you want in place beforehand is a named owner per model dependency, a qualified replacement with eval results attached, a compatibility test in CI, and the last date a rollout can safely land. On the day the notice arrives, the first move is the inventory, because you cannot plan around dependencies nobody has listed.

   Read chapter
7. 7

   Lock-in is a decision with an exit trigger and a reversal cost

   Depending on one provider's prompt caching for the 70% saving that makes your unit economics work is rational when the benefit is measured and the exit conditions are written down: which quality gap justifies moving, what the migration costs, who decides, and by when. Absent those, the dependency becomes a fact nobody owns. You will write that record for the caching-against-quality trade and name what would flip it.

   Read chapter