DEV Community: polycratia

Treat LLM Catalog Translation as a Cache, Not a Job

polycratia — Wed, 19 Aug 2026 13:26:11 +0000

Translating a product catalog with an LLM looks like a batch job: read rows, call the model, write rows back. It stops looking like that the first time a supplier re-uploads the same feed and you pay again to translate thousands of descriptions that did not change by a single byte.

I have run LLM pipelines that translate and adapt product catalogs for international audiences, and the part nobody warns you about is that almost none of the difficulty is in the prompt. It is in deciding what "the same input" means, and then letting that definition own your storage.

The constraint: catalogs are re-imported, not edited

A catalog that you own in your own database is a set of rows that get updated. A catalog that arrives from suppliers, parsers or partner feeds is a set of snapshots that get replaced. Nobody sends you a reliable updated_at. Titles come back with a different amount of whitespace, a different dash character, a supplier-side capitalization change, or a marketing suffix appended and later removed. The row identity is stable; the content identity is not.

If you drive translation off row identity, you either retranslate everything on every import, or you trust a dirty flag that is wrong often enough to ship stale copy to production. If you drive it off a hash of the whole item, one changed field invalidates every field on that item, including the long description that costs the most to translate.

So the unit of work is not the item and not the import. It is one field, in one target locale, under one prompt and one model.

Key the output by normalized content

The key has to include everything that can change the output. That is the source text, the target locale, the kind of field (a title and a bullet list want different instructions), the prompt version, the model identifier, and the glossary revision if you pin brand terms that must not be translated.

Normalization matters as much as hashing. Feeds are noisy, and you want cosmetic noise to collapse into the same key while real edits do not.

import hashlib
import unicodedata
import re

WHITESPACE = re.compile(r"\s+")


def normalize(text: str) -> str:
    text = unicodedata.normalize("NFKC", text)
    text = text.replace("\u00a0", " ")
    text = WHITESPACE.sub(" ", text)
    return text.strip()


def content_key(
    *,
    text: str,
    field_kind: str,
    target_locale: str,
    prompt_version: str,
    model: str,
    glossary_version: str,
) -> str:
    payload = "\x1f".join(
        [
            normalize(text),
            field_kind,
            target_locale,
            prompt_version,
            model,
            glossary_version,
        ]
    )
    return hashlib.sha256(payload.encode("utf-8")).hexdigest()

Two details are worth being deliberate about. Use a separator that cannot appear in the parts, so that a locale ending in a digit and a prompt version starting with one cannot collide into the same string. And do not normalize case: a supplier shouting a title in capitals is a real difference that a translator should see.

Normalization is a one-way decision. Whatever you fold away today, you cannot recover from the key tomorrow, so keep it to things that are genuinely cosmetic. Trimming and whitespace collapsing are safe. Stripping punctuation is not.

The store is the pipeline

Once the key exists, the translation service has no scheduling logic left in it. It is a lookup, a call on miss, and an insert.

CREATE TABLE translation (
    content_key   TEXT PRIMARY KEY,
    target_locale TEXT NOT NULL,
    field_kind    TEXT NOT NULL,
    model         TEXT NOT NULL,
    prompt_version TEXT NOT NULL,
    source_text   TEXT NOT NULL,
    output_text   TEXT NOT NULL,
    created_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX translation_locale_idx ON translation (target_locale, field_kind);

async def translate_field(conn, client, *, text, field_kind, locale) -> str:
    key = content_key(
        text=text,
        field_kind=field_kind,
        target_locale=locale,
        prompt_version=PROMPT_VERSION,
        model=MODEL,
        glossary_version=GLOSSARY_VERSION,
    )

    row = await conn.fetchrow(
        "SELECT output_text FROM translation WHERE content_key = $1", key
    )
    if row is not None:
        return row["output_text"]

    output = await client.translate(
        text=text, field_kind=field_kind, locale=locale
    )

    await conn.execute(
        """
        INSERT INTO translation (
            content_key, target_locale, field_kind, model,
            prompt_version, source_text, output_text
        )
        VALUES ($1, $2, $3, $4, $5, $6, $7)
        ON CONFLICT (content_key) DO NOTHING
        """,
        key, locale, field_kind, MODEL, PROMPT_VERSION, text, output,
    )
    return output

ON CONFLICT DO NOTHING is doing real work here. Two workers processing two items that happen to share a title — variants of the same product, or a supplier who copies boilerplate across a category — will race on the same key. Both calls are already paid for by then; the point is that neither write fails and neither overwrites the other.

The same property makes the import job restartable with no bookkeeping at all. Kill it halfway, run it again, and it resumes at cost proportional to what is left rather than to what exists.

Fan out per field, persist per field

The second failure mode is subtler than cost. An item has a title, a short description, a long description, a few attributes. If you translate them in one call and one of them trips a content filter or times out, the naive pipeline throws away the whole item and retries all of it. Do that inside a retry loop and a single stubborn field will burn the budget for every field around it, forever, on every run.

Translate fields independently and persist each success on its own.

import asyncio


async def translate_item(conn, client, item, locale) -> dict:
    fields = [
        ("title", item.title),
        ("short_description", item.short_description),
        ("long_description", item.long_description),
    ]

    async def one(field_kind, text):
        if not text:
            return field_kind, None
        try:
            value = await translate_field(
                conn, client, text=text, field_kind=field_kind, locale=locale
            )
        except TranslationFailed:
            return field_kind, None
        return field_kind, value

    results = await asyncio.gather(*(one(k, t) for k, t in fields))
    return {k: v for k, v in results if v is not None}

A partially translated item is a normal state, not an error state. The rendering layer falls back to the source locale for any field that is missing, and the next run retries only the gaps. That is the difference between a pipeline that converges over a few runs and one that oscillates.

What you must not do is cache the failure under the content key. A timeout is a property of the attempt, not of the text. If you want to stop hammering a field that fails deterministically, count attempts in a separate table keyed by the same content key, and let the reader decide when to give up. Keep the two concerns apart: one table is what the model said, the other is how the infrastructure behaved.

Prompt version is a migration, not a config value

Because the prompt version is inside the key, bumping it invalidates every cached output for every locale. That is correct — a changed prompt means changed output — but it means the version string is one of the most expensive variables in the system. Treat editing it the way you treat a schema migration: it happens deliberately, it gets reviewed, and you know what it will cost before you merge it.

The upside is that rollback is free. Nothing was overwritten. Point the pipeline back at the previous prompt version and the old outputs are still sitting there under their own keys, ready to be served again.

What I would do differently

I would put prompt_version and model in the key from the very first commit. It is obvious in hindsight and easy to skip when there is exactly one prompt and one model, and the moment you add a second one you are looking at a table of outputs you cannot attribute and therefore cannot trust.

I would separate "translated" from "approved" earlier. Machine output and human-reviewed output are different lifecycle states, and once a reviewer has touched a string you need the pipeline to never quietly replace it. Overloading one column with both meanings is the kind of shortcut that costs you a reviewer's afternoon the first time a re-import lands.

I would also keep the source text in the row, as above, even though it is redundant with the key. Hashes are not reversible, and the day you need to audit why a locale reads strangely, having the exact input that produced the output is worth far more than the storage it takes.

Close

The useful reframe is that an LLM call is a pure function of its inputs, and every input that is not the text — the locale, the field kind, the prompt, the model, the glossary — belongs in the key. Once that is true, the batch job disappears. What is left is a cache with a slow, expensive miss path, and caches are a problem the industry solved a long time ago.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

KYC webhooks arrive out of order, so rank the decisions

polycratia — Tue, 18 Aug 2026 13:27:09 +0000

An identity verification provider does not hand you a status. It hands you a stream of webhook events, and that stream arrives out of order, duplicated, and occasionally after one of your own compliance reviewers has already decided the case by hand. If your integration does user.kyc_status = payload['status'] on every callback, you will eventually flip a rejected applicant back to approved. You will not learn about it from your logs. You will learn about it from an audit.

I have been integrating KYC and KYB providers into payment and lending products for years, along with the real-time moderation tooling used by the humans on the other side of the queue. The bug always has the same shape, and the fix is always the same: stop trying to reconstruct a timeline you never had.

Why receipt order tells you nothing

Four independent things break ordering, and they compound:

Provider clocks. Timestamps commonly land at second granularity, and a document check plus a liveness check finishing in the same second is not rare, it is the normal case.
At-least-once delivery. Your endpoint returns a 500 once, or times out, and the same event is redelivered minutes later — after the events that logically follow it.
Parallel pipelines on their side. Document extraction, face match, and watchlist screening are separate workers. They emit transitions concurrently, and nobody sequences them for you.
Your own reviewers. A human acts in your database while the provider pipeline is still running.

So delivery order is meaningless, emission order is partly unknowable, and provider timestamps are not a total order. What you actually have is a set of decisions, each with a source and a meaning. A set does not need ordering. It needs precedence.

Store the events, decide separately

The first move is to stop letting the webhook handler own the status. It owns one thing: appending a fact.

create table kyc_event (
    id             bigserial   primary key,
    application_id uuid        not null references kyc_application(id),
    source         text        not null,   -- 'provider' | 'reviewer'
    external_id    text        not null,   -- provider event id, or internal action id
    decision       text        not null,   -- a value from the lattice below
    payload        jsonb       not null,
    received_at    timestamptz not null default now(),
    unique (source, external_id)
);

That unique constraint is the entire idempotency story. At-least-once delivery becomes exactly-once processing, enforced by the database rather than by a Redis key with a TTL that you will one day tune wrong.

def ingest(conn, application_id, source, external_id, decision, payload):
    with conn.cursor() as cur:
        cur.execute(
            '''
            insert into kyc_event
                (application_id, source, external_id, decision, payload)
            values (%s, %s, %s, %s, %s)
            on conflict (source, external_id) do nothing
            ''',
            (application_id, source, external_id, decision, Json(payload)),
        )
        if cur.rowcount == 0:
            return False  # duplicate delivery, already recorded

    reproject(conn, application_id)
    return True

Return 200 in both branches. A provider that receives a non-2xx will retry, and retrying a duplicate is pure noise that eventually buries the deliveries you actually care about.

One detail worth insisting on: reviewer actions go into the same table, with the reviewer action id as external_id. An event log that covers only the provider is half an audit trail, and it is the half that never explains the interesting cases.

Precedence, not chronology

Now define what outranks what. This is not a state machine over time — it is a lattice over outcomes.

RANK = {
    'started':            0,
    'pending_documents': 10,
    'in_review':         20,
    'approved':          30,
    'rejected':          40,
    'blocked':           50,   # watchlist / AML hit
}

Read it as: an application's visible status is the highest-ranked decision anyone has ever made about it. approved sits below rejected because a late-arriving approval from a parallel pipeline must never erase a rejection. blocked sits above everything because a screening hit is not negotiable by a document check that finished afterwards.

The projection is then a pure function of the event set:

def project(decisions):
    return max(decisions, key=lambda d: RANK[d], default='started')

And the write is guarded by rank rather than by time:

def reproject(conn, application_id):
    with conn.cursor() as cur:
        cur.execute(
            'select decision from kyc_event where application_id = %s',
            (application_id,),
        )
        status = project([row[0] for row in cur.fetchall()])
        cur.execute(
            '''
            update kyc_application
               set status = %s, status_rank = %s, updated_at = now()
             where id = %s
               and status_rank < %s
            ''',
            (status, RANK[status], application_id, RANK[status]),
        )

The status_rank < guard is what makes concurrency boring. Two webhook workers can process two events for the same application at the same time, in either order, more than once, and the row converges to the same value. No advisory locks, no serializable transactions, no ordering queue keyed by application id. Monotonicity does the work.

A human cannot un-reject; a human opens a new case

The obvious objection: applicants do get rejected for a bad document scan and then send a good one. Under a monotonic lattice, nobody can walk the status back down — which is exactly the property compliance wants, and exactly the property product does not.

Both are satisfied by moving the reversal up a level. A reviewer does not edit the decision; they open a new application row for the same user, with an incremented attempt number. The previous case stays terminal forever, with its evidence attached. The user-facing status is the status of the latest case.

def reopen(conn, user_id, previous_application_id, actor_id, reason):
    with conn.cursor() as cur:
        cur.execute(
            '''
            insert into kyc_application (user_id, attempt, status, status_rank)
            select user_id, attempt + 1, 'started', 0
              from kyc_application
             where id = %s
            returning id
            ''',
            (previous_application_id,),
        )
        new_id = cur.fetchone()[0]

    ingest(conn, new_id, 'reviewer', f'reopen:{actor_id}:{previous_application_id}',
           'started', {'reason': reason})
    return new_id

Nothing is ever overwritten. When someone asks in six months why a particular user is allowed to move money, the answer is a select, not an archaeology project.

What this buys you later

Because status is a projection rather than an accumulated side effect, three otherwise painful operations become routine. You can change the lattice — say, you introduce a manual_hold decision — and backfill by re-running reproject over the affected applications. You can replay a provider's event history after an outage without worrying about what it does to users who have since been decided. And you can diff your projection against the provider's own view of the case in a nightly job, which is how you discover that a webhook was silently dropped weeks ago.

That last one matters more than it sounds. Missing events are invisible in a last-write-wins design: the row simply holds a stale value that looks plausible. With an event table, a reconciliation query has something to compare against.

What I would do differently

My first version of this had a status column and a guard on the provider's updated_at. It survived exactly until two events shared the same second and the wrong one won. I patched it with a rule that terminal states cannot be overwritten. Then I patched that with a special case for screening hits. At that point I had a precedence lattice implemented as scattered if statements inside a webhook handler, which is the worst of both designs: the semantics of a lattice with none of the auditability.

So: write the rank table first, even if you only have three states. Put reviewer actions in the same event stream from day one. And never guard a state transition on a clock you do not control.

The shape generalises well beyond KYC. Any time you consume at-least-once events from a source that runs work in parallel — payment processor callbacks, chain reorg notifications, carrier tracking updates — the same three moves apply: append every decision with a natural idempotency key, define what outranks what, and make the visible state a projection you can recompute at any time.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Crediting On-Chain Deposits Without a Balance Column

polycratia — Mon, 17 Aug 2026 13:33:12 +0000

A custodial wallet has to answer one question honestly: how much of this user's money is spendable right now. The obvious implementation increments a balance column when a transaction appears in a block, and that column is wrong the first time the scanner restarts mid-batch, the node replays a range you already processed, or the chain reorganizes underneath you.

I have built custodial wallet services for BTC and ETH and an on-chain payment system on top of them, and the mistake I see repeated most often is treating the block scanner as a writer of balances. It is not. It is a reader of an external system that can retract what it told you five minutes ago.

The constraint that makes this hard

There is no transaction that spans your database and a blockchain node. You cannot commit "I saw this deposit" and "I credited this user" atomically with the chain's own view of history, because the chain's view is not yours to commit. Three things follow from that, and every design decision below is downstream of them:

Delivery is at-least-once. Your scanner will process the same block twice.
History is mutable near the tip. A block you accepted can stop existing.
The node is not authoritative about your ledger. It is authoritative about itself, and it can be replaced, resynced, or briefly behind.

So I stopped storing conclusions and started storing observations.

Store what the chain said, not what you concluded

Two tables. One records blocks and their lineage, the other records the deposit outputs found inside them. Nothing here is a status, and nothing is an aggregate.

create table chain_block (
    chain       text        not null,
    height      bigint      not null,
    block_hash  text        not null,
    parent_hash text        not null,
    seen_at     timestamptz not null default now(),
    orphaned_at timestamptz,
    primary key (chain, block_hash)
);

create index on chain_block (chain, height) where orphaned_at is null;

create table deposit_event (
    id           bigserial primary key,
    chain        text not null,
    block_hash   text not null,
    tx_hash      text not null,
    output_index int  not null,
    address      text not null,
    amount       numeric(38, 0) not null,
    unique (chain, tx_hash, output_index, block_hash),
    foreign key (chain, block_hash) references chain_block (chain, block_hash)
);

Two details carry most of the weight.

The amount is an integer in the smallest unit of the chain. Satoshis, wei. No floats, no decimal degrees of freedom, no unit conversion anywhere except the presentation layer. This is boring and it removes an entire category of incident.

The uniqueness key includes block_hash. That looks redundant until a fork puts the same transaction in two competing blocks. Both observations are real; exactly one of them will survive. If you make (tx_hash, output_index) unique you are asserting the chain has one history, which is precisely the assumption that breaks.

Ingestion is then a single transaction per block, and every statement in it is idempotent:

def ingest_block(conn, chain, block, watched):
    with conn, conn.cursor() as cur:
        cur.execute(
            '''
            insert into chain_block (chain, height, block_hash, parent_hash)
            values (%s, %s, %s, %s)
            on conflict (chain, block_hash) do nothing
            ''',
            (chain, block.height, block.hash, block.parent_hash),
        )
        for out in block.outputs_to(watched):
            cur.execute(
                '''
                insert into deposit_event
                    (chain, block_hash, tx_hash, output_index, address, amount)
                values (%s, %s, %s, %s, %s, %s)
                on conflict do nothing
                ''',
                (chain, block.hash, out.tx_hash, out.index, out.address, out.amount),
            )

Replaying a range costs CPU and nothing else. That property is what lets you recover from a bad deploy by rewinding the scanner cursor instead of writing a repair script under pressure.

Confirmations are a query, not a state machine

The common design gives each deposit a status column and a job that promotes pending to confirmed once enough blocks pile up. Now you own a scheduler, a retry policy, and a class of rows that get stuck in the wrong state when the job dies between two updates.

A deposit does not become confirmed. It is confirmed, because the tip moved. That is a read:

select w.account_id,
       sum(d.amount) as confirmed_amount
from deposit_event d
join chain_block b using (chain, block_hash)
join wallet_address w on w.chain = d.chain and w.address = d.address
where d.chain = %(chain)s
  and b.orphaned_at is null
  and b.height <= %(tip_height)s - %(min_confirmations)s
group by w.account_id;

I take tip_height from the highest non-orphaned block in my own table, not from the node. If the node is swapped or resyncs and briefly reports a lower tip, my projection stays consistent with the data I actually hold, and it advances again when ingestion advances.

The spendable balance is still a durable ledger posting — you cannot let a user's available funds silently shift because a query changed shape. So the projection feeds an append-only ledger, once, keyed on the money rather than on the block:

POST_DEPOSITS = '''
insert into ledger_entry (account_id, direction, amount, idempotency_key)
select w.account_id,
       'credit',
       d.amount,
       'deposit:' || d.chain || ':' || d.tx_hash || ':' || d.output_index
from deposit_event d
join chain_block b using (chain, block_hash)
join wallet_address w on w.chain = d.chain and w.address = d.address
where d.chain = %(chain)s
  and b.orphaned_at is null
  and b.height <= %(tip_height)s - %(min_confirmations)s
on conflict (idempotency_key) do nothing
'''

The idempotency key deliberately omits the block hash. If a shallow reorg moves the same transaction into a different block, it is the same money arriving once, and it must be credited once. The observation is block-scoped; the posting is not.

Reorgs: invalidate, never delete

When the chain rewinds, the temptation is to delete the rows you no longer believe in. Don't. Deleting destroys the evidence you will want during the incident review, and it turns a fork into a distributed-delete problem across every table that referenced those rows.

Instead, walk back from your tip, compare hashes with the node, and mark the divergent blocks orphaned:

def reconcile_tip(conn, chain, rpc):
    with conn, conn.cursor() as cur:
        cur.execute(
            '''
            select height, block_hash from chain_block
            where chain = %s and orphaned_at is null
            order by height desc
            limit 200
            ''',
            (chain,),
        )
        fork_height = None
        for height, block_hash in cur.fetchall():
            if rpc.block_hash_at(height) == block_hash:
                break
            cur.execute(
                '''
                update chain_block set orphaned_at = now()
                where chain = %s and block_hash = %s and orphaned_at is null
                ''',
                (chain, block_hash),
            )
            fork_height = height
        return fork_height

The scanner then re-ingests from the fork point. Every deposit event attached to an orphaned block drops out of the projection on the next read, because the join filters on orphaned_at is null. There are no compensating updates to write and no rows to remember to fix. The correction is structural.

The part you cannot solve in code

If a reorg goes deeper than your confirmation threshold, the money was already posted and the user may already have spent it. No amount of schema design prevents that; you chose a risk when you picked the threshold.

What you can do is make the threshold a function of value rather than a constant, so that small deposits stay fast and large ones wait:

deposit size band	confirmations required
small	low, optimised for user experience
medium	chain default
large	well beyond any fork depth you consider plausible

And when the deep reorg does happen, the reversal is a negative ledger entry with a human decision attached, not an automatic correction. Automatic debits against user balances driven by external state are how you turn a chain event into a support catastrophe. This is the same rule I apply to fiat: automation may propose, but taking money back is a reviewed action.

What I would do differently

I would separate address ownership from ingestion earlier. In an early version the scanner resolved address -> account inline while parsing blocks, which meant a deposit to an address that had just been reassigned could be attributed against a stale mapping. Ownership should be its own versioned table with validity ranges, and attribution should be a join at projection time, not a lookup at parse time.

I would also persist the raw block payload for the confirmation window instead of only the outputs I cared about. It costs storage that you delete a day later, and it means that when you discover a parsing bug, you can re-derive events from bytes you already have rather than asking the node to serve a range it may have pruned.

The general shape has held up across everything I have built with money in it, on-chain or not: record observations immutably, derive state by query, and make every write idempotent on a key that describes the money rather than the delivery. Reorgs, retries and replays stop being incidents and become inputs the system was already designed to accept.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Matching Incoming Bank Transfers to Users When the Reference Is Wrong

polycratia — Sun, 16 Aug 2026 15:34:51 +0000

A bank statement line gives you an amount, a date, a sender, and a free-text reference field, and your system has to decide which user that money belongs to. The reference field is wrong, truncated or missing often enough that attribution built on it alone leaves you with a growing pile of money you cannot assign to anybody.

I have built this layer for account-to-account flows and for virtual bank-account ledgering, where each user holds their own accounts and every incoming transfer has to land on exactly one of them. The failure mode is undramatic. Nothing crashes, no alert fires. You simply accumulate unattributed credits, support tickets from users who paid and see no balance, and a reconciliation report that nobody can close at the end of the day.

The constraint that makes it hard

Attribution is not a search problem, it is a money problem. A card authorization is a conversation: you send a request, you get an identifier back, you can query that identifier later. An incoming transfer is a monologue. The money is already in the account when you hear about it. Whatever you decide, you decide from a row of text produced by somebody else's system, and the person who typed the reference is not the person who formatted it.

That asymmetry sets two rules I now treat as non-negotiable. First, an automatic attribution must be provable from a value you yourself issued, not inferred from resemblance. Crediting user A with user B's money is a compliance incident, not a bug you patch next sprint. Second, unattributed money must have somewhere to live that is visible, ordered and aging, because it will exist no matter how good the matcher is.

Why the reference field cannot be trusted

Everything upstream of you is hostile to a free-text field. People retype the code from a screenshot and turn O into 0 and 1 into I. Banks truncate the field or strip punctuation. Corporate accounting departments overwrite the reference with their own invoice number, because their internal process needs that field more than yours does. A single transfer arrives covering two of your invoices, or a payment lands from a spouse's account, or from a company account whose name has no relationship to the user's name at all.

So the first design decision is to stop asking the reference field to carry identity when there is a better channel available.

Route first: the account is the identifier

If you can issue a dedicated virtual account per user, attribution stops being text processing and becomes routing. The user sends money to the account that belongs only to them, and the credited account on the statement line is the answer. The reference field becomes a hint for humans rather than a key for machines.

This is the single largest reduction in attribution work I have seen in production, and it also removes an entire class of support conversation, because the user no longer has to copy anything correctly. It is not always available, and legacy inflow to a shared collection account continues for years after you introduce it, so you still need the fallback path below. But every transfer you move onto a dedicated account is a transfer that never enters the queue.

When you must use a code, make it machine-checkable

On a shared collection account, the reference is all you have. The mistake is to put a raw internal identifier in it. A raw identifier is silently valid when mistyped: change one digit and you get another perfectly real user. A short code with a check character turns almost every human transcription error into a clean rejection instead of a wrong credit.

I encode over an alphabet that omits the characters people confuse, and I normalise aggressively before parsing.

ALPHABET = "0123456789ABCDEFGHJKLMNPQRSTVWXYZ"  # no I, L, O, U
BASE = len(ALPHABET)
BODY_LEN = 5
LOOKALIKES = str.maketrans({"I": "1", "L": "1", "O": "0"})


def _check_char(body: str) -> str:
    total = sum((i + 1) * ALPHABET.index(c) for i, c in enumerate(body))
    return ALPHABET[total % BASE]


def encode_reference(user_id: int) -> str:
    n, digits = user_id, []
    while n:
        n, rem = divmod(n, BASE)
        digits.append(ALPHABET[rem])
    body = "".join(reversed(digits)).rjust(BODY_LEN, ALPHABET[0])
    return "PAY" + body + _check_char(body)


def decode_reference(text: str) -> int | None:
    cleaned = "".join(text.upper().split()).translate(LOOKALIKES)
    cleaned = "".join(c for c in cleaned if c.isalnum())
    marker = cleaned.find("PAY")
    if marker < 0:
        return None
    token = cleaned[marker + 3 : marker + 3 + BODY_LEN + 1]
    if len(token) != BODY_LEN + 1:
        return None
    body, check = token[:BODY_LEN], token[BODY_LEN]
    if check != _check_char(body):
        return None
    value = 0
    for c in body:
        if c not in ALPHABET:
            return None
        value = value * BASE + ALPHABET.index(c)
    return value

The PAY prefix matters more than it looks. Without an anchor, you scan an arbitrary sentence for anything that could be a code, and corporate invoice numbers will happily satisfy a length-and-charset test. With an anchor plus a check character, a false positive requires deliberate effort.

Attribution is an ordered list of rules, not a score

I have seen the scoring approach several times and I no longer build it. A weighted score over account, amount, name similarity and timing produces a number that nobody can defend when an operator asks why a specific transfer landed on a specific user. Rules that run in a fixed order produce an answer plus the name of the rule that produced it, and that name goes into the ledger entry.

from dataclasses import dataclass
from decimal import Decimal


@dataclass(frozen=True)
class StatementLine:
    external_id: str
    amount: Decimal
    credited_account: str
    sender_account: str
    sender_name: str
    reference: str


@dataclass(frozen=True)
class Attribution:
    user_id: int
    rule: str


def by_virtual_account(line: StatementLine, repo) -> Attribution | None:
    user_id = repo.user_for_virtual_account(line.credited_account)
    return Attribution(user_id, "virtual_account") if user_id else None


def by_reference_code(line: StatementLine, repo) -> Attribution | None:
    user_id = decode_reference(line.reference)
    if user_id is None or not repo.user_exists(user_id):
        return None
    return Attribution(user_id, "reference_code")


def by_confirmed_sender(line: StatementLine, repo) -> Attribution | None:
    owners = repo.users_with_confirmed_sender_account(line.sender_account)
    if len(owners) != 1:
        return None
    return Attribution(owners[0], "confirmed_sender_account")


AUTOMATIC_RULES = (by_virtual_account, by_reference_code, by_confirmed_sender)


def attribute(line: StatementLine, repo) -> Attribution | None:
    for rule in AUTOMATIC_RULES:
        result = rule(line, repo)
        if result is not None:
            return result
    return None

Note what is missing. There is no name-similarity rule in the automatic path. Sender names are a ranking signal for a human reviewing candidates, never a reason to move money on their own. The confirmed-sender rule only fires when exactly one user has previously been linked to that sender account through an attribution a human or a stronger rule already made — ambiguity returns None rather than picking a winner.

The unmatched queue is a product surface

Everything that returns None goes into a queue, and that queue deserves the same care as a checkout page. It needs the statement line verbatim, ranked candidate users with the reason each was suggested, an age, and an operator action that is itself an auditable event. Age is the metric that matters: a queue measured by depth looks fine while the oldest item quietly turns into a chargeback or a complaint. Sort by oldest, not by largest.

The suggestion side is where fuzzy matching belongs, because a human is the safety mechanism.

def suggest(line: StatementLine, repo, limit: int = 5):
    scored = []
    for user in repo.users_with_open_expectation(line.amount):
        score = 0
        if user.sender_accounts and line.sender_account in user.sender_accounts:
            score += 50
        score += name_similarity(user.display_name, line.sender_name)  # 0..40
        if repo.recently_initiated_transfer(user.id):
            score += 10
        scored.append((score, user))
    scored.sort(key=lambda pair: pair[0], reverse=True)
    return [user for _, user in scored[:limit]]

Reattribution is a reversal, not an update

Operators will get some of these wrong, and users will call about it weeks later. If attribution is a mutable column on the payment row, correcting it destroys the evidence of what happened, and your statement-level reconciliation stops agreeing with your ledger.

Attribution is an event. Correcting it means posting the opposite of the original entry and then posting the new one, both carrying the statement line identifier.

def reattribute(session, line, wrong_user_id, right_user_id, operator_id):
    session.add_all([
        LedgerEntry(
            statement_line_id=line.external_id,
            user_id=wrong_user_id,
            amount=-line.amount,
            rule="reattribution_reversal",
            actor=operator_id,
        ),
        LedgerEntry(
            statement_line_id=line.external_id,
            user_id=right_user_id,
            amount=line.amount,
            rule="reattribution",
            actor=operator_id,
        ),
    ])

The sum of all ledger entries for a statement line then equals that line's amount, always, whatever happened in between. That single invariant is what makes the daily reconciliation a query rather than an investigation.

What I would do differently

I would issue per-user virtual accounts from the first day rather than adding them once the shared collection account became painful, because the migration is not technical, it is a matter of getting every existing user to change where they send money — and some of them never will.

I would also record the rule name from the very first version. On an early system, attribution was a boolean and the rule lived only in code, so when the matcher changed, no one could tell which historical credits came from which logic. Storing the rule per entry costs one column and answers the only question that gets asked during an audit.

The last thing I would change is expectations. Early on I treated the unmatched queue as a defect to be driven to zero. It is not. Transfers from third-party accounts, partial payments and overwritten references are normal traffic in any account-to-account flow. The queue is a permanent part of the system, and it should be built like one.

Originally published on polycratia.com — where I write about payment systems, crypto rails and marketplace backends.

Translating a product catalog with an LLM: cache keys and guard rails

polycratia — Thu, 30 Jul 2026 10:14:56 +0000

The first version of an LLM catalog translation pipeline usually works and is still wrong. It re-translates fields nobody touched, and it happily publishes a description where the model rewrote a voltage, dropped a placeholder, or turned a SKU into something that looks nicer.

I have built LLM pipelines that translate and adapt product catalogs for international audiences. Translation quality was never the part that kept me up. The two mechanisms below are what turn a demo script into something you can point at a live catalog: a cache key that captures every input that can change the output, and validators that treat the model's response as untrusted until proven safe.

The unit of work is a field, not a product

If you translate a product as one blob, any edit to any attribute invalidates the whole thing, and you cannot tell which part of the output the model changed. Worse, you lose the ability to say "the title is reviewed, the description is not".

So the pipeline operates on (product_id, field, target_lang) triples. Each one is normalized before anything else happens, because unstable whitespace and encoding differences from a scraper will otherwise produce cache misses for text that did not actually change.

import hashlib
import re
import unicodedata

WHITESPACE = re.compile(r'\s+')

def normalize(text: str) -> str:
    text = unicodedata.normalize('NFC', text)
    text = text.replace('\u00a0', ' ')
    return WHITESPACE.sub(' ', text).strip()

That normalization is not cosmetic. Catalog sources emit non-breaking spaces, trailing tabs and mixed Unicode forms that change from crawl to crawl. Without it, a large share of your spend goes to re-translating text that is byte-different and semantically identical.

The cache key must include everything that can change the output

The mistake I have seen most often is keying the cache on source text alone. Then someone edits the system prompt, or the model version is bumped, and the catalog becomes a mix of two generations of output with no way to tell them apart.

Everything that participates in producing the string belongs in the key:

PROMPT_VERSION = 'catalog-v4'

def cache_key(
    source: str,
    field: str,
    target_lang: str,
    model: str,
    glossary_version: str,
) -> str:
    payload = '\u241f'.join([
        normalize(source),
        field,
        target_lang,
        model,
        PROMPT_VERSION,
        glossary_version,
    ])
    return hashlib.sha256(payload.encode('utf-8')).hexdigest()

The separator matters more than it looks: joining with a plain comma or space lets two different tuples collide into the same key. Use a character that cannot appear in the inputs.

Store the key next to the translation, along with the model and prompt version as their own columns. When you bump the prompt, you can then answer the only question that matters operationally — which rows are stale, and what does it cost to refresh them — with a query instead of a guess. A prompt change becomes a migration you can run in slices, per language or per category, rather than a full re-translation of the catalog.

Guard rails: extract invariants from the source, assert them on the output

A translation model is a text generator, not a transformer with guarantees. It will occasionally localize a decimal separator, convert units it was not asked to convert, or drop a templating placeholder because the sentence reads better without it. None of these throw an exception. They land in your catalog and surface later as a support ticket about a wrong specification.

The fix is not a better prompt. It is a validator that pulls the invariants out of the source and checks they survived.

PLACEHOLDER = re.compile(r'\{[a-z_]+\}')
HTML_TAG = re.compile(r'</?[a-z][a-z0-9]*[^>]*>', re.IGNORECASE)
NUMBER = re.compile(r'\d+(?:[.,]\d+)?')


class InvariantError(Exception):
    pass


def numbers(text: str) -> list[str]:
    return [n.replace(',', '.') for n in NUMBER.findall(text)]


def check_invariants(source: str, translated: str) -> None:
    src_ph = sorted(PLACEHOLDER.findall(source))
    out_ph = sorted(PLACEHOLDER.findall(translated))
    if src_ph != out_ph:
        raise InvariantError(f'placeholders changed: {src_ph} -> {out_ph}')

    src_tags = sorted(t.lower() for t in HTML_TAG.findall(source))
    out_tags = sorted(t.lower() for t in HTML_TAG.findall(translated))
    if src_tags != out_tags:
        raise InvariantError('markup changed')

    src_nums = sorted(numbers(source))
    out_nums = sorted(numbers(translated))
    if src_nums != out_nums:
        raise InvariantError(f'numbers changed: {src_nums} -> {out_nums}')

Comparing sorted multisets rather than sequences is deliberate: word order legitimately moves between languages, numeric values do not. The decimal-separator normalization before comparison is there because a model translating into a locale that uses commas will reformat 1.5 as 1,5, which is a rendering decision, not a value change — and you want your formatter to own that decision, not the model.

This validator is intentionally cheap and mechanical. It does not judge whether the translation is good. It only proves the model did not quietly alter something that carries commercial or legal meaning.

The failure policy is the actual design decision

When validation fails, you have three options, and choosing between them is the part that requires an opinion.

def translate_field(client, source, field, lang, model, glossary_version):
    key = cache_key(source, field, lang, model, glossary_version)
    cached = store.get(key)
    if cached is not None:
        return cached

    violation = None
    for _ in range(2):
        out = client.translate(
            source=source,
            field=field,
            target_lang=lang,
            model=model,
            correction=violation,
        )
        try:
            check_invariants(source, out)
        except InvariantError as exc:
            violation = str(exc)
            continue
        store.put(key, out, status='ok')
        return out

    store.put(key, source, status='needs_review', reason=violation)
    return source

One retry, and the retry carries the specific violation back to the model — not a generic "try again". Naming the constraint that was broken is what makes the second attempt materially different from the first; a bare retry mostly resamples the same failure.

After that, stop. Fall back to the source string and flag the row. Publishing untranslated English text into a localized catalog is a visible, honest degradation. Publishing a translation with a changed specification is an invisible one, and invisible failures in catalog data behave exactly like invisible failures in payment attribution: nobody finds them until a human complains, and by then you cannot tell how long it has been wrong or how many rows are affected.

The needs_review queue is the deliverable here, not a nice-to-have. It is the only place where the pipeline's real error rate is observable.

What I would do differently

I would keep the glossary — brand names, product terms that must not be translated, unit spellings — as a versioned data table from day one, not as text pasted into the prompt. Once it lives in the prompt, every glossary edit silently invalidates the entire cache, and you cannot slice a refresh by the terms that actually changed.

I would also stop letting free-form placeholders into translatable text. Regex-matching {price} works until someone writes a template with nested braces or a currency symbol adjacent to a placeholder. Splitting the string into structured segments before translation, and reassembling after, removes a whole class of validator false negatives — at the cost of a more complex renderer.

The wider point: an LLM in a data pipeline is a non-deterministic component sitting where you previously had a deterministic one. Everything above is what you would build around any unreliable dependency — an idempotency key, invariant checks at the boundary, an explicit failure state. The model is new. The engineering around it is not.