Your Shipped App Still Remembers the Retired Model

Taking the model name out of the client

There is really only one direction to move in. The client says what it wants done; the server decides which model does it.

Ship capability names, not model names

The client sends something like image.describe or wallpaper.classify. No model name is included at all. Here is the minimal Swift shape:

struct AIRequest: Encodable {
    let capability: String   // a capability name such as "wallpaper.classify"
    let assetId: String
    let locale: String
}
 
func classify(assetId: String) async throws -> Classification {
    var req = URLRequest(url: URL(string: "https://api.example.com/v1/ai")!)
    req.httpMethod = "POST"
    req.setValue("application/json", forHTTPHeaderField: "Content-Type")
    // Send the client version. Never send a model name.
    req.setValue(Bundle.main.appVersion, forHTTPHeaderField: "X-App-Version")
    req.httpBody = try JSONEncoder().encode(
        AIRequest(capability: "wallpaper.classify",
                  assetId: assetId,
                  locale: Locale.current.identifier)
    )
    let (data, resp) = try await URLSession.shared.data(for: req)
    guard let http = resp as? HTTPURLResponse, http.statusCode == 200 else {
        // Degrade one feature quietly. Do not take the whole screen down.
        throw AIError.unavailable
    }
    return try JSONDecoder().decode(Classification.self, from: data)
}

The version header is the part that pays off later. It lets you count which builds are still alive using nothing but server logs.

Keep exactly one resolution table on the server

Confine every appearance of a model name to a single place. When the next deprecation notice lands, whether the edit is one file or forty decides how calm your cutoff day is.

import os
from google import genai
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
# Model names appear here and nowhere else
CAPABILITY_MODELS = {
    "wallpaper.classify": "gemini-3.7-flash",
    "image.describe":     "gemini-3.7-flash",
    "image.generate":     "gemini-3.1-flash-image",
}
 
# Capability names older clients might still send
CAPABILITY_ALIASES = {
    "image.imagen4": "image.generate",   # sent by builds up to v2.3.0
}
 
class UnknownCapability(Exception):
    pass
 
def resolve_model(capability: str) -> str:
    key = CAPABILITY_ALIASES.get(capability, capability)
    model = CAPABILITY_MODELS.get(key)
    if model is None:
        # Fail loudly. Guessing a default hides the incident from you.
        raise UnknownCapability(capability)
    return model
 
def run(capability: str, parts: list) -> str:
    model = resolve_model(capability)
    resp = client.models.generate_content(model=model, contents=parts)
    return resp.text

The deliberate choice here is refusing to route unknown capabilities to a default model. A well-meaning fallback conceals the existence of old clients. Failing instead fills your logs with UnknownCapability, and by the end of the day you know exactly which builds were left behind.

If you are still moving code off generate_images(), the arguments do not map one-to-one onto generate_content(). I wrote that part up separately in the argument mapping notes.

Refuse model names that arrive from the client

The most dangerous thing to carry into a cutoff is a request schema that still lets a client name a model. You cannot change the string an old build sends.

FORBIDDEN_FIELDS = ("model", "model_name", "engine")
 
def sanitize(payload: dict) -> dict:
    # Drop client-supplied model hints, but record them before dropping
    leaked = [f for f in FORBIDDEN_FIELDS if f in payload]
    if leaked:
        logger.warning(
            "client sent model hint: fields=%s version=%s",
            leaked, payload.get("_app_version", "unknown"),
        )
        for f in leaked:
            payload.pop(f)
    return payload

Record, then drop. The volume of that warning line is a decent proxy for how many old clients are still out there.

The compatibility branch is the first thing to break

This is where my expectation was most clearly wrong.

My instinct was to thicken the compatibility layer for the sake of old clients: requests from older builds go to the old model, newer builds go to the new one. Perfectly reasonable on its face.

Read it again with a cutoff in mind and the branch works against you. The code you wrote for compatibility is the one piece guaranteed to fail on the retirement date. Worse, it only executes for requests from old clients, so your staging environment never touches it. Production alone goes red, on the day.

So I stopped thickening it. Requests from old builds now flow to the new model like everything else. The output shape may shift enough that an old build renders something slightly off, but a cosmetic defect is a lighter failure than a hard one.

When the thing you are trying to stay compatible with has an expiry date, compatibility work makes you less safe. That inversion did not land for me until I had lived through one retirement.

A forced update will not arrive in time

Forcing an update is the obvious way to retire old builds, and I considered it once.

The arithmetic does not work. Build the release that carries the forced-update gate, clear review, run the phased rollout, wait for people to actually update. In my experience as a solo developer, you should budget several weeks between announcement and meaningful adoption. That competes head-on with the window a deprecation notice gives you.

A forced update also locks out people who cannot update. A meaningful share of my users are still on older devices, and bricking their app over a scheduling problem of mine was not a trade I was willing to make.

The order that actually works looks like this:

1. Absorb model resolution on the server and route old clients to the new model — this must be finished before the date
2. Build per-feature degradation so a failure costs one feature, not the whole screen
3. Treat forced updates as next month's cleanup, not as a cutoff-day weapon

Reframing the forced update from "today's tool" to "next release's tidying" made the decision considerably easier.

Three things to look at before the date

On the morning itself, what I read is logs, not code. Three checks, in order:

1. Where model names appear. Search the whole repository and confirm nothing outside the resolution table names a model — config files, tests, notebooks, and sample snippets in documentation included
2. Client version distribution. Aggregate the X-App-Version header over the last week. As long as old numbers show up, the old path is alive
3. How far back a rollback reaches. Open the actual diffs and confirm which revision is the last safe one to return to

Start collecting the second one the day the deprecation notice lands. Adding it on the cutoff day leaves you with no history to compare against.

For the inventory step itself — finding every place you call the retired model from — I wrote up the procedure in the shutdown audit notes. This article picks up after that, with the layer you cannot rewrite yourself.

One thing to do today

Open a single real request coming from your client and look at what is inside it. If a model name is in there, that value now has an expiry date attached.

It took me one full retirement cycle to arrive at this line. Do not put values that expire in places you cannot edit. Written down it sounds obvious, and that is exactly why it survives, quietly, in a corner of a config file.