Matching name variants in a print catalog: normalize first, then ask Gemini for candidates

Layer two: ask only for candidates

For the names that make it past layer one, I ask Gemini exactly one thing: list the alternate names, art names, and pre-succession names used by the artist known under this name. I never ask whether two names match.

# alias_lookup.py — candidates and context, never a verdict
import json
import os
from google import genai
from google.genai import types
 
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])
 
SCHEMA = {
    "type": "object",
    "properties": {
        "canonical": {"type": "string"},
        "aliases": {"type": "array", "items": {"type": "string"}},
        "generation": {"type": "string", "enum": ["first", "later", "unknown"]},
        "note": {"type": "string"},
    },
    "required": ["canonical", "aliases", "generation"],
}
 
SYSTEM = """You help build an index of ukiyo-e artist names.
- List only alternate names, art names (go), and pre-succession names used by the artist.
- If more than one person has held this name, set generation to "later" and explain in note.
- If you cannot confirm anything, return an empty aliases array. Never invent a name.
- Do not translate or transliterate names. Return them in their original script."""
 
 
def lookup(name: str) -> dict:
    res = client.models.generate_content(
        model="gemini-3.8-flash",
        contents=f"name: {name}",
        config=types.GenerateContentConfig(
            system_instruction=SYSTEM,
            response_mime_type="application/json",
            response_schema=SCHEMA,
        ),
    )
    return json.loads(res.text)
 
 
if __name__ == "__main__":
    out = lookup("安藤広重")
    print(out["canonical"], out["generation"], out["aliases"][:3])
    # shape of the expected output:
    # 歌川広重 unknown ['安藤重右衛門', '一遊斎', '一幽斎']

The note field is for a human to read; it never feeds the matching logic. I also decline to ask the model for a confidence score. The moment a number lands in the payload, I want to threshold on it — and thresholding on a self-reported score is the yes/no question wearing a different hat.

Why lowering temperature does not settle the output

When output wobbles, the instinct is to push temperature toward zero. I did that first. Nothing changed.

On the Gemini 3.x Flash family, temperature, top_p, and top_k are deprecated: the request is accepted and the values are ignored. No error, no warning. The only person affected is the one who believes the setting is doing something.

Stability comes from three other places.

1. Fix the shape with response_schema. Declare array item types and mark fields required.
2. Close the vocabulary with enum. While generation was a free-text field, I got answers like "probably the first" and "second generation, I believe", and the branch downstream broke on both.
3. Permit emptiness in the system instruction. If an empty array is not allowed, the model will fill the shape by inventing a name.

A negative dictionary for succession names

Even with two layers, one hole remains: the aliases array can contain names belonging to a different person. Artists who inherited a studio name appear under that name throughout the literature, so they surface naturally in any list of candidates.

So alongside the positive alias table, I keep a set of pairs that must never share a row.

# guard.py — trim the model output against my own prohibition table
NEVER_SAME = {
    frozenset({"歌川広重", "二代広重"}),
    frozenset({"歌川広重", "三代広重"}),
    frozenset({"歌川豊国", "三代豊国"}),
    frozenset({"歌川国貞", "三代豊国"}),  # attribution is contested; never auto-merge
}
 
GENERATION_HINT = ("二代", "三代", "四代", "門人", "襲名")
 
 
def filter_aliases(query: str, result: dict) -> dict:
    kept, dropped = [], []
    for a in result.get("aliases", []):
        if frozenset({query, a}) in NEVER_SAME or any(h in a for h in GENERATION_HINT):
            dropped.append(a)
        else:
            kept.append(a)
    result["aliases"] = kept
    result["needs_review"] = dropped          # keep them; route them to a human column
    return result

The pitfall worth naming: if you discard dropped, you lose the ability to ask later why a candidate disappeared. I learned that by researching the same pair twice, two weeks apart. Recording the reason for a rejection is one line of code that pays a later version of you.

Three boxes for the result

Once both layers have run, every row in the catalog lands in one of three places, and the split is what makes this practical to operate.

1. Matched by normalization. Accepted automatically. Nobody reads it.
2. Matched through an alias. Accepted, with a column recording which alias made the link.
3. Undecided. A human reads it. This is the only manual work left.

When box three gets very small, I treat that as a warning rather than a win. Either the negative dictionary has loosened or normalization is folding too aggressively, and tidiness has started pulling against correctness.

Cost and time at a thousand rows

Calls only happen for rows layer one could not settle, which in my catalog is a fraction of the total. Even if every row went to the model, the order of magnitude would not change.

At roughly 400 input and 200 output tokens per row, a thousand rows is 400K input and 200K output tokens. With the gemini-3.8-flash introductory pricing of $0.75 input and $3.75 output per MTok, that is $0.30 and $0.75 — a little over a dollar.

One deadline is worth pinning down. The introductory pricing runs through December 31, 2026; from January 1, 2027 it becomes $1.50 and $7.50 per MTok. If your estimate crosses the new year, write it in two columns. For the same reason, I recommend keeping the model ID in a config file rather than in the source: preview endpoints come with retirement dates, and hardcoded IDs stop working on those dates. I wrote separately about picking a generation in choosing 3.8 Flash now that the same price buys more tokens.

Classifying the images themselves is a different job, which I covered in running wallpaper category classification as an indie developer. The metadata work here sits one step earlier in the same pipeline.

Where to start tomorrow

If you are carrying a similar reconciliation, write normalize() first, run it over your own data, and count how many rows collapse onto a shared key. Designing the model call can wait until you have that number in front of you. In my case, counting showed that most of the calls I had planned were unnecessary.

Repairing an old sheet of paper and attaching a name to it are two different kinds of work. The first one I keep doing by hand. The second one shrinks when you give it structure, and being able to draw that line myself is the part of this two-layer setup I value most.

If this saves you one wrong attribution, the writing was worth it.