blogs

PROVING Your AI-Generated Code Works

2026-10-22T20:41:30Z

Use CARBON and Lean to verify the rules your code must obey.

Most developers know how to run tests. Few know that you can actually prove a software property.

A test asks, “Does this example work?” A proof asks, “Does this rule hold for every input in the scope we agreed to?”

That is a useful question when the rule controls who gets access, whether an operation is allowed, or whether an important invariant holds.

Lean is a language and proof checker for expressing those rules precisely and checking the reasoning behind them. A convincing explanation and a checked proof are different things. Lean checks the latter. Its validation tools also let you inspect the assumptions a proof depends on and recheck the proof artifacts. Learn more about Lean proof validation.

CARBON Pro brings that process into your coding agent with /proof.

Jay, CARBON’s AI test manager, helps you choose the rule worth proving, makes the scope explicit, and brings back a result with evidence. Here is how the workflow fits together.

1. Start with consequences

Run /proof and Jay looks for consequential code: authorization, payments, data integrity, irreversible operations, parsers, state transitions, and logic used throughout the application.

The first result is a ranked shortlist, not a surprise marathon of proof attempts. Each candidate includes its location, why it matters, proposed properties, assumptions, likely approach, and difficulty. Inferred business importance is marked as uncertain.

You can also name a target directly:

Use /proof on policy.py::allow. Check that an unauthenticated user can never receive access.

Discovery is broad; execution is specific. The current verification backends handle a restricted set of pure Boolean Python decision functions and their Lean models. Jay identifies unsupported targets before promising a result.

2. Agree on exactly what “correct” means

Consider this function:

def allow(authenticated: bool, owner: bool) -> bool:
    return authenticated and owner

One useful property is:

Whenever this function grants access, the user must be authenticated.

That is more precise than “the authorization code looks good.” It gives the checker a concrete claim to evaluate.

Jay presents the property, input domain, assumptions, and resource budget for approval. Here, the domain is actual Boolean values: four combinations of authenticated and owner. Caller validation is a separate responsibility.

Once you approve, the property stays fixed. CARBON rejects a weaker replacement claim, convenient new assumptions, or skipped inputs introduced to make the result pass.

3. Run the check — and check the check

CARBON has two verification paths for this supported Boolean subset.

The native Python path evaluates the complete input domain and independently replays the original validated function expressions through CPython.

The Lean path translates the decision logic into a Boolean model, constructs a deterministic proof, and performs a fresh isolated build and proof recheck. It rejects unfinished proofs and any transitive axioms in this backend. The report identifies this as a Lean-model proof, alongside the separate production replay evidence; Python-to-Lean equivalence remains unverified.

Local Lean setup checks for the toolchain and, with your approval, downloads the pinned release and builds the local container. Proof execution then runs offline in isolation, with explicit resource limits.

The implemented search is deterministic. Jay helps frame the problem; an open-ended AI proof search is not running behind the scenes.

4. Bring back an answer you can use

CARBON reports four states. These are illustrative summaries, not logs from an executed run:

PROVED: The approved property holds across all four Boolean combinations under the recorded assumptions, with independent checking evidence.

COUNTEREXAMPLE: A specific input violates the property, with reproduction evidence and a runnable regression fixture.

UNPROVED: An obligation remains — for example, a resource limit was reached or the target uses unsupported semantics.

STALE: Verification inputs changed. The previous result needs a new check.

Now change one word in the function:

return authenticated or owner

The input authenticated=False, owner=True returns True. It breaks our rule: an unauthenticated user receives access.

For a reproduced failure, CARBON preserves the input and generates a regression fixture. When a proof cannot be established, it deliberately searches the approved domain for counterexamples within its separate allowance. An unsuccessful search remains inconclusive; it does not turn into a proof.

That gives you a productive outcome either way: checked evidence, a concrete failure to fix, or a clearly identified gap.

5. Keep the evidence attached to the code

Every proof workflow produces a CARBON HTML report with the property, scope, findings, limits, replay coverage, and links to the underlying evidence.

CARBON fingerprints the verification inputs — not just the function body. Dependency source, specifications, assumptions, configuration, toolchain details, and proof artifacts all matter. Changed inputs make the result stale. The incremental CI check replays approved evidence and flags changes instead of trusting an old green label.

The result is a precise guarantee you can inspect and maintain, rather than another reassuring paragraph from an AI.

Give your most important rules stronger evidence

CARBON is the testing harness with Jay, an AI test manager that lives inside your coding agent. It helps developers move from “the demo works” to evidence they can use to make a shipping decision.

Start with one consequential rule. Review the scope. Approve the budget. Let CARBON do the checking.

CARBON’s core is free and open source. /proof is included in CARBON Pro.

Get the downloads, documentation, and edition details at testers.ai/carbon.

Jason Arbon · Testers.ai

PROVING Your AI-Generated Code Works

2026-10-22T20:41:30Z

Use CARBON and Lean to verify the rules your code must obey.

Most developers know how to run tests. Few know that you can actually prove a software property.

A test asks, “Does this example work?” A proof asks, “Does this rule hold for every input in the scope we agreed to?”

That is a useful question when the rule controls who gets access, whether an operation is allowed, or whether an important invariant holds.

CARBON Pro brings that process into your coding agent with /proof.

Jay, CARBON’s AI test manager, helps you choose the rule worth proving, makes the scope explicit, and brings back a result with evidence. Here is how the workflow fits together.

1. Start with consequences

Run /proof and Jay looks for consequential code: authorization, payments, data integrity, irreversible operations, parsers, state transitions, and logic used throughout the application.

You can also name a target directly:

Use /proof on policy.py::allow. Check that an unauthenticated user can never receive access.

2. Agree on exactly what “correct” means

Consider this function:

def allow(authenticated: bool, owner: bool) -> bool:
    return authenticated and owner

One useful property is:

Whenever this function grants access, the user must be authenticated.

That is more precise than “the authorization code looks good.” It gives the checker a concrete claim to evaluate.

Once you approve, the property stays fixed. CARBON rejects a weaker replacement claim, convenient new assumptions, or skipped inputs introduced to make the result pass.

3. Run the check — and check the check

CARBON has two verification paths for this supported Boolean subset.

The native Python path evaluates the complete input domain and independently replays the original validated function expressions through CPython.

The implemented search is deterministic. Jay helps frame the problem; an open-ended AI proof search is not running behind the scenes.

4. Bring back an answer you can use

CARBON reports four states. These are illustrative summaries, not logs from an executed run:

PROVED: The approved property holds across all four Boolean combinations under the recorded assumptions, with independent checking evidence.

COUNTEREXAMPLE: A specific input violates the property, with reproduction evidence and a runnable regression fixture.

UNPROVED: An obligation remains — for example, a resource limit was reached or the target uses unsupported semantics.

STALE: Verification inputs changed. The previous result needs a new check.

Now change one word in the function:

return authenticated or owner

The input authenticated=False, owner=True returns True. It breaks our rule: an unauthenticated user receives access.

That gives you a productive outcome either way: checked evidence, a concrete failure to fix, or a clearly identified gap.

5. Keep the evidence attached to the code

Every proof workflow produces a CARBON HTML report with the property, scope, findings, limits, replay coverage, and links to the underlying evidence.

The result is a precise guarantee you can inspect and maintain, rather than another reassuring paragraph from an AI.

Give your most important rules stronger evidence

Start with one consequential rule. Review the scope. Approve the budget. Let CARBON do the checking.

CARBON’s core is free and open source. /proof is included in CARBON Pro.

Get the downloads, documentation, and edition details at testers.ai/carbon.

Jason Arbon · Testers.ai

The Bug That Hid in 70% of the Web for 10+ Years, and How AI Found It

2026-10-22T20:02:53Z

On October 21, 2026, websites around the world started showing “maintenance mode” pages. Government, school, and hospital sites in Europe went offline on purpose, and companies like Nintendo took some services down too.

The reason was not a hack of “the internet”. It was two critical bugs in PHP, the software that runs behind a huge part of the web. Together they are called PHP2Shell, and they had been sitting in PHP’s code for more than ten years. AI helped find them.

First, what is PHP?

PHP is a programming language that runs on web servers. When you open a website, PHP is often the part that takes your request, talks to the database, and builds the page you see. WordPress, Drupal, and Joomla all run on it. Wiz Research says PHP powers about 70% of websites.

Think of a website as a hotel:

You are the guest walking in.
The hotel’s rooms are the website’s data: accounts, orders, passwords.
PHP is the receptionist. Every guest goes through the front desk first. The receptionist reads your request, checks the register, and sends you where you need to go.

The website owner hires the receptionist, but does not train them. PHP comes ready-made. So if the receptionist has a bad habit, every hotel that uses them has the same problem. That is why this news is so big: the bug is in PHP itself, not in one website’s code.

The receptionist’s two bad habits

Bad habit 1: Panicking when the desk is full

When PHP runs out of memory, it stops what it is doing immediately. Sometimes it stops while a guest’s form is only half filled in. Later, during clean-up, PHP treats that half-filled form as if it were complete and correct. An attacker can send a specially built upload request that pushes PHP into exactly this situation. On servers using Apache with mod_php, this can happen before the website’s own code even runs.

Bad habit 2: Not taking the old key back

PHP keeps some notes from one guest’s visit after that guest has left and their space has been cleared. If the next guest is served by the same worker, PHP can use those stale notes before resetting them. It is like a hotel where the last guest’s room key still opens the door for the next person.

Why it matters

By using these habits, an attacker can make the server run their own commands. No username or password is needed. Wiz also says attackers could read passwords, tokens, and API keys from PHP’s memory.

The PHP security team rated both bugs 9.2 out of 10 (CVSS v4.0, “critical”). A score of 10.0 went around on social media before the release; the PHP Foundation says that number was incorrect.

Hidden for over a decade, found with AI

Every PHP version from 5.4 up to 8.5.11 is affected. Wiz says every PHP version released in the past decade carries at least one of the two bugs, and they survived years of manual security reviews.

So why now? Two teams found the problem using AI:

Calif: researcher Ryan Austin used OpenAI’s GPT-5.6 Sol during an August 2026 audit of PHP’s source code. The audit was funded by OpenAI under its “Patch the Planet” programme, which pairs AI models with human security experts to find and fix bugs in open-source software.
Wiz Research independently found and reported both bugs, also with help from AI models. Wiz says proving the bugs could actually be exploited needed a chain of steps so complex it sat at the edge of what human researchers could practically do.

Volker Dusch, a security engineer at the nonprofit that oversees PHP, called it the worst security problem the project has faced in more than ten years and compared it to Heartbleed, according to The Wall Street Journal.

The important point: AI did not create these bugs. They were already there. AI helped security researchers find them, so PHP could build a fix.

What happened this week

The plan was a quiet, coordinated fix. Instead, the bug IDs leaked a day early and attackers started probing.

The EU, the US, Germany, Japan, Australia, the UK and the Netherlands all issued local warnings, according to The Record.

What you should do

If you run a website on PHP

Update PHP to 8.5.12, 8.4.27, 8.3.36 or 8.2.35. If you install PHP through your operating system’s package manager, apply your vendor’s updated packages (UW-IT).
On older branches: PHP released minimal source backports for 7.4, 8.0, and 8.1 (Help Net Security). watchTowr notes there are no patches for PHP 5 or 7 overall (watchTowr).
On shared hosting, ask your provider to confirm the fix is installed, not just scheduled (Malwarebytes).
If you take a site down while patching, Google’s John Mueller advises returning HTTP 503 rather than letting pages time out or return 404/500 (Search Engine Roundtable).

If your site is behind Cloudflare

Cloudflare’s CTO Dane Knecht said PHP sites behind Cloudflare already have an initial set of firewall (WAF) rules for the known exploit paths, on every plan including Free (Help Net Security). Keep those rules on, but they are an extra layer only. Because the bug lives in PHP itself, you still have to update PHP.

If you are just browsing

The fix is applied on web servers, not on your phone or laptop. Some sites may stay in maintenance mode for a while as their teams patch (Malwarebytes).

The lesson for testers: test the failure path

Look at where both bugs lived. Not in login, search, or checkout. They lived in what PHP does when things go wrong: running out of memory, hitting a fatal error, cleaning up between requests.

Most test suites are built around the happy path. We check that the right input gives the right output. Far fewer tests ask:

What happens when the server runs out of memory halfway through a request?
What state is left behind after a crash, and does the next request see it?
What does the system do with a huge or oddly formatted upload?

That is exactly the kind of corner where this bug hid for over a decade. Wiz says AI models lowered the barrier to proving bugs like this are exploitable, so these corners deserve more of our testing time, not less.

One small step this week: add one “what if it breaks halfway?” test to your suite.

Myths vs facts

If you want to stay updated on tech & AI updates, follow me on other platforms:

Anshita Bhasin
Instagram | LinkedIn | Twitter | Youtube

RAG ou fine-tuning? A pergunta certa é outra

2026-10-22T18:52:07Z

Até pouco tempo atrás, classificar o motivo de uma inadimplência era trabalho de gente lendo. O analista lia as cinco últimas tentativas registradas pelo call center, consultava a política de cobrança — um PDF de cento e oitenta páginas que mudava a cada trimestre e que ninguém lia inteiro — e escolhia um código numa lista de quarenta e dois. De três a seis minutos por caso. Numa carteira de quarenta mil eventos por dia a conta não fecha, então o que acontecia era outra coisa: uma regra fixa pegava os casos óbvios, o resto caía num balde chamado "outros", e o balde crescia ano após ano até virar metade da carteira.

A alternativa clássica era treinar um classificador. Funcionava — e ainda funciona — mas exigia uma base rotulada que ninguém tinha e três meses que a diretoria não dava. E, quando o produto mudava, começava tudo de novo.

O que mudou não foi a inteligência disponível. Foi o custo de usá-la. Um modelo de linguagem1 lê os mesmos cinco registros de contato, a mesma cláusula da política, e devolve o código — em dois segundos, por uma fração de centavo, sem base rotulada e sem projeto de três meses. A precisão que antes exigia um especialista hoje está a uma chamada de API de distância.

E é exatamente aí que começa o problema que este artigo quer resolver. Porque assim que o time entende que dá para fazer, aparece a pergunta errada: a gente usa RAG ou faz fine-tuning? Essa pergunta trata duas coisas diferentes como se fossem concorrentes, e o custo de errar a resposta não é teórico — é uma fatura mensal.

A pergunta certa é outra, e ela cabe numa linha só:

Isto aqui muda com que frequência, e eu preciso provar de onde veio a resposta?

É essa. Não "qual é melhor", mas o que esse pedaço do seu problema faz ao longo do tempo e o que você vai precisar mostrar depois. Guarde a frase — ela volta no fim, e é honestamente a única coisa daqui que você precisa levar desse artigo para seu time de engenharia.

Este texto serve a quem escreve o código e a quem assina não escreve mas toma decisões de negócio. Toda parte técnica vem com tradução ao lado, e todo termo que costuma aparecer sem explicação tem nota de rodapé no fim. Se você nunca treinou um modelo na vida, relaxa: dá para acompanhar tudo. E no fim você sai com uma conta de guardanapo que resolve a discussão na sua mesa.

Tópico 1 — Onde o conhecimento mora

Um modelo de linguagem guarda conhecimento em dois lugares com propriedades opostas, e cada estratégia mexe num deles.

Pense no plantonista do pronto-socorro. O que ele aprendeu na faculdade está na cabeça dele: vale para qualquer paciente, não muda durante o plantão, e custou seis anos para entrar ali. O que ele sabe sobre o paciente do leito 12 está no prontuário preso na prancheta: entrou agora, é específico daquele caso, e se ele largar a prancheta na mesa, esqueceu tudo.

O modelo é igual. O que ele aprendeu no treinamento está nos pesos2 — milhões ou bilhões de números fixos. O que ele sabe sobre o seu caso está na janela de contexto3, o texto que você manda junto com a pergunta. Terminou a chamada, a prancheta sumiu. O modelo não lembra da conversa anterior; o que chamamos de memória é só o histórico sendo reenviado inteiro a cada chamada, e pago de novo a cada chamada.

Figura 1. Os dois reservatórios de conhecimento de um modelo e suas propriedades opostas. A escolha entre RAG e fine-tuning é a escolha de qual reservatório você vai abastecer.

A analogia já falha num ponto, e é melhor eu estragar isso agora do que deixar você descobrir em produção: a prancheta tem tamanho, e você paga por cada token4 que enfia nela. Em português a conta é pior — o tokenizador5 da maioria dos modelos foi otimizado para inglês, e uma palavra em português consome de 1,5 a 2 tokens contra cerca de 1,3 em inglês. Na prática, o mesmo texto custa de 15% a 50% mais caro em português do que em inglês.

Guarde essa frase, porque ela é o eixo de tudo que vem a seguir: RAG mexe no prontuário. Fine-tuning mexe na formação do médico.

Tópico 2 — RAG por dentro: a matemática da busca por significado

RAG não é um modelo; é uma busca bem-feita grampeada na frente de uma chamada ao modelo.

RAG6 significa geração aumentada por recuperação, e a ideia cabe numa frase: antes de perguntar ao modelo, procure nos seus documentos os trechos que importam e cole-os no prompt. O modelo não precisa ter decorado a política de cobrança. Ele precisa ter a cláusula relevante na frente dos olhos na hora de responder.

A parte não óbvia é como você acha o trecho certo. Busca por palavra-chave não serve: o usuário pergunta "posso parcelar", a cláusula fala em "fracionamento do débito", e o LIKE '%parcelar%' volta vazio. O que resolve é busca por significado.

A matemática, em dois minutos

Pense na gôndola do supermercado.

Você não acha o achocolatado procurando pela letra A: acha porque ele está perto do leite em pó, que está perto do café. A loja organiza por significado, não por ordem alfabética — e por isso você encontra sem saber o nome exato do produto.

Um embedding7 faz isso com texto. Cada trecho vira um ponto num mapa, e textos que falam da mesma coisa ficam vizinhos. O mapa não tem duas dimensões como a planta do supermercado — tem centenas ou milhares — mas a matemática é a mesma que você aprendeu no ensino médio.

Vou fazer a conta com você, usando só duas dimensões para caber no papel. Imagine que a primeira dimensão mede "quanto o texto fala de acordo entre as partes" e a segunda, "quanto fala de taxa de juros". Três frases viram três pontos:

"renegociação de dívida"  -> A = [0.90, 0.40]
"acordo de pagamento"     -> B = [0.85, 0.45]
"variação da taxa Selic"  -> C = [0.10, 0.95]

Para quem não programa: cada frase virou um par de coordenadas, tipo um endereço num mapa. Falta agora uma régua que diga quais endereços são "do mesmo bairro". Essa régua é a similaridade de cosseno8: ela mede o ângulo entre dois pontos vistos da origem. Ângulo pequeno, assunto parecido. A fórmula é a razão entre o produto escalar e o produto dos comprimentos:

cos(A,B) = (A · B) / (|A| × |B|)

A · B  = 0.90×0.85 + 0.40×0.45 = 0.765 + 0.180 = 0.945
|A|    = raiz(0.90² + 0.40²)   = raiz(0.97)    = 0.985
|B|    = raiz(0.85² + 0.45²)   = raiz(0.925)   = 0.962

cos(A,B) = 0.945 / (0.985 × 0.962) = 0.998

Praticamente 1 — e as duas frases não compartilham nenhuma palavra. Agora a terceira:

A · C  = 0.90×0.10 + 0.40×0.95 = 0.090 + 0.380 = 0.470
|C|    = raiz(0.10² + 0.95²)   = raiz(0.9125)  = 0.955

cos(A,C) = 0.470 / (0.985 × 0.955) = 0.500

Metade: a régua separou. Um embedding real tem de 768 a 3.072 dimensões e os números saem de um modelo treinado, não da sua mão — mas a conta que o banco executa milhões de vezes por dia é literalmente essa. Não tem mágica ali.

O passo a passo da implementação

Figura 2. As duas metades de um pipeline de RAG. A indexação roda quando o documento muda; a consulta roda a cada pergunta. É essa separação que torna a atualização barata.

Ingestão. Texto limpo d as fontes: política, FAQ, histórico de atendimento, cláusulas. Lixo entra, lixo sai — e PDF escaneado sem OCR é lixo.
Chunking9. Pedaços de 400 a 800 tokens, com 10% a 20% de sobreposição. Se o corte cair no meio da cláusula, a condição fica num pedaço e a exceção no outro, e o modelo responde com meia verdade. Corte por estrutura — seção, artigo, parágrafo — não por contagem de caracteres.
Embedding. Cada pedaço vira vetor. Use um modelo que entenda português de verdade: a diferença de qualidade entre modelos é maior em português que em inglês.
Armazenamento. Grave os vetores com os metadados que você vai querer filtrar depois: produto, versão da política, data de vigência, segmento. São eles que impedem o sistema de citar uma política revogada.
Recuperação. Na pergunta, gerar o vetor e buscar os k vizinhos mais próximos10 — k entre 3 e 10 na maioria dos casos. Combine com busca por palavra-chave (busca híbrida11): nomes próprios, números de contrato e códigos de produto são exatamente onde a busca semântica erra.
Re-ranking12. Passar os candidatos por um modelo menor que reordena por relevância real. Barato, e costuma ser o passo com melhor retorno por hora investida em todo o pipeline.
Montagem do prompt. Cole os trechos com a fonte identificada e instrua o modelo a responder apenas com base neles — e a dizer que não sabe quando não bastarem. Essa instrução é metade da defesa contra alucinação13.
Avaliação. Sem um conjunto de perguntas com resposta conhecida, nenhum dos sete passos acima é ajustável. É o assunto da próxima seção.

Qual decisão você consegue desfazer

Repare numa coisa: dos oito passos acima, dois você refaz num sábado e dois te prendem por um ano. Saber qual é qual vale mais do que acertar de primeira.

Barato de desfazer: tamanho do pedaço, valor de k, texto do prompt e re-ranking. Tudo configuração — você muda, roda a avaliação e compara. Se o time está travando a escolha de chunking numa reunião, já gastou em reunião mais do que custaria testar as três opções.

Caro de desfazer: o modelo de embedding. Trocá-lo obriga a re-embeddar o acervo inteiro, reconstruir o índice e recalibrar o k — e vetores de modelos diferentes não são comparáveis entre si, então não existe migração parcial nem convivência das duas versões. Essa é a decisão que merece meio dia de teste com os seus documentos, não a escolha do que estava no topo do ranking que você leu ontem.

E a métrica que arbitra as duas: num conjunto de 50 a 200 perguntas com resposta conhecida, meça recuperação (o trecho certo entrou nos k?) separada de fidelidade (a resposta usou o trecho que entrou?). Recuperação baixa é problema de busca; fidelidade baixa com recuperação alta é problema de prompt. Quem olha só a taxa de acerto geral fica meses ajustando o lado errado.

As ferramentas de cada passo — o que são, para que servem e como instalar — estão no apêndice, no fim do artigo.

Pense comigo
Se alguém perguntar hoje "de onde saiu essa resposta", seu sistema consegue devolver o documento, a versão e o parágrafo — ou só a resposta?
Quando a política de cobrança muda, quantas pessoas precisam agir para o sistema passar a usar a versão nova? Se a resposta for mais que uma, o custo real da sua solução não está na fatura da API.
Você já mediu quantas vezes o trecho certo foi recuperado e o modelo respondeu errado assim mesmo? É um número diferente da taxa de acerto geral, e é o que diz se o problema está na busca ou no prompt.

Tópico 3 — Fine-tuning por dentro: a matemática do ajuste

Fine-tuning muda como o modelo responde, não o que ele sabe — e confundir as duas coisas é o erro mais caro desta área.

Fine-tuning14 é ajustar os pesos do modelo com os seus exemplos. Você mostra mil pares de "entrada que eu tenho" e "saída que eu queria", e o treinamento empurra os números internos na direção que reduz o erro15. O resultado é um modelo que, sem que você peça nada no prompt, já responde no seu formato, com o seu jargão e com o seu critério.

Treinar todos os pesos de um modelo moderno é caro e, na maior parte dos casos, desnecessário. Foi daí que saiu a técnica que tornou isso viável para empresas normais.

LoRA: o que é

Você não reimprime as novecentas páginas do manual porque três procedimentos mudaram. Você publica uma errata de quatro páginas e manda grampear no fim. Quem consulta usa o manual original mais a errata, e o resultado é o manual corrigido.

LoRA16 — Low-Rank Adaptation, adaptação de posto17 baixo — é a errata dos pesos. Em vez de reescrever a matriz original, ela congela o modelo inteiro e aprende um ajuste pequeno, guardado à parte, que é somado por cima na hora de responder.

Três consequências saem direto dessa escolha, e são elas que explicam por que LoRA virou o padrão. Você treina muito menos números, então cabe numa GPU alugada em vez de num cluster. O que você guarda no fim não é um modelo, é um arquivo de poucos megabytes — versionável, revisável, fácil de reverter. E, como o ajuste é somado de volta à matriz original antes de servir, o modelo em produção continua sendo um modelo só: não há camada extra, nem um milissegundo a mais por resposta.

De onde surgiu

LoRA nasceu de um problema de conta de infraestrutura, não de uma teoria elegante. Em junho de 2021, Edward Hu e colegas da Microsoft publicaram o artigo que a descreve. O contexto era o GPT-3 de 175 bilhões de parâmetros, e o impasse era simples de enunciar: fazer fine-tuning daquele modelo produzia outro modelo de 175 bilhões de parâmetros. Uma cópia inteira por tarefa. Treinar exigia na casa de 1,2 TB de memória de vídeo18, e cada checkpoint salvo ocupava algo como 350 GB. Imagine agora que você quer um modelo especializado por cliente. A conta do armazenamento, sozinha, já mata o projeto antes de ele começar.

A aposta teórica veio de uma pesquisa anterior sobre dimensão intrínseca19, e aqui vale parar um segundo porque é contraintuitivo. Trabalhos de 2018 e 2020 mostraram que modelos com bilhões de parâmetros, na prática, se movimentam num espaço muito menor do que o tamanho deles sugere. É como um mapa de mil ruas onde todo mundo só usa trinta. Dá para projetar o treino nesse espaço menor e ainda assim aprender bem. Hu e os coautores deram um passo a mais: se o modelo vive num espaço pequeno, então a diferença entre o modelo antes e depois do ajuste também cabe num espaço pequeno. Ou seja, você não precisa escrever essa diferença por inteiro — basta escrevê-la comprimida.

Já existia um concorrente para o mesmo problema, as camadas adaptadoras20 de 2019: pequenos blocos novos enfiados entre as camadas do modelo, treinados enquanto o resto fica congelado. Funcionavam, e pela mesma razão — poucos parâmetros novos. Mas tinham um defeito que condenava a ideia em produção: por serem blocos extras, eles rodam em sequência com o resto da rede, e isso cobra tempo em toda inferência. Nos testes do próprio artigo da LoRA, com lote de tamanho um, os adaptadores acrescentavam entre 20% e 30% de latência. Vinte por cento a mais em cada resposta, para sempre, é um preço que ninguém quer pagar.

Aqui está a sacada que fez LoRA vencer. Como o ajuste dela é uma multiplicação de matrizes do mesmo formato da matriz original, ele pode ser somado de volta aos pesos antes de publicar o modelo. Treina-se separado; serve-se junto. O custo em latência não é baixo: é zero. Os números que o artigo reporta para o GPT-3 saem daí — até dez mil vezes menos parâmetros treináveis, cerca de um terço da memória de GPU, e o checkpoint de 350 GB virando um arquivo de 35 MB.

A matemática do ajuste

Para quem não programa: uma camada do modelo é uma tabela quadrada de números. Numa dimensão típica de 4.096, essa tabela tem 4.096 linhas por 4.096 colunas:

W : 4096 x 4096 = 16.777.216 números  (congelado)

LoRA diz: não toque em W. Aprenda o ajuste como o produto de duas tabelas magras — uma alta e estreita, outra baixa e larga — com uma largura r bem pequena, tipicamente 8, 16 ou 64:

A : 4096 x 16  =    65.536 números  (treinado)
B :   16 x 4096 =   65.536 números  (treinado)
                  --------------
                     131.072 números

16.777.216 / 131.072 = 128

Cento e vinte e oito vezes menos parâmetros para treinar. E a fórmula geral é tão simples que dá para fazer de cabeça: a economia é d / (2r), onde d é a dimensão da camada e r a largura que você escolheu. Dobre o r, corte a economia pela metade. É o único hiperparâmetro cuja consequência de custo você consegue calcular antes de rodar.

E qual r basta? Menos do que a intuição sugere. No artigo original, boa parte dos resultados usa r = 4, e os autores observam que para o GPT-3 valores de 1 ou 2 já funcionam — num modelo cuja dimensão cheia é 12.288. É a hipótese da dimensão intrínseca aparecendo na prática: a correção de rumo que você precisa é mesmo pequena. Vale notar também onde a errata é aplicada: nos experimentos principais, apenas nas matrizes de consulta e de valor do mecanismo de atenção — nem sequer no modelo inteiro.

Na prática, isso vira uma regra de bolso: comece em r = 8 ou 16, suba só se a avaliação mostrar que o modelo não está conseguindo aprender a tarefa. Se você precisou chegar a 128 ou 256 para o número subir, pare e reavalie — ou a tarefa não era de forma, era de conhecimento (e aí é RAG), ou o modelo base é pequeno demais para ela.

Figura 3. A decomposição de posto baixo do LoRA. A economia é exatamente d dividido por 2r, e é calculável antes de reservar a GPU.

Para que serve — e quando não serve

Por que funciona, afinal? Porque o ajuste é muito mais simples que o conhecimento que já está lá. O modelo já sabe português, já sabe o que é uma dívida, já sabe estruturar uma resposta. Falta uma correção de rumo — e correção de rumo cabe em pouca informação.

Serve para três coisas, bem concretas.

A primeira é especializar sem multiplicar infraestrutura. Como o adaptador é um arquivo pequeno e separado, você pode manter um modelo base carregado na memória e trocar o adaptador conforme a chamada — um para classificar motivo de inadimplência, outro para resumir atendimento, outro para o tom de um cliente específico. É a diferença entre operar um servidor de GPU e operar sete.

A segunda é tornar o treino um evento ordinário de engenharia. Um adaptador de modelo pequeno treina em horas numa GPU alugada e produz um artefato de megabytes. Isso cabe no seu fluxo normal: versionar, revisar, promover entre ambientes, reverter quando der errado. Fine-tuning deixa de ser um projeto de ciência de dados e vira mais um artefato de build.

A terceira é não pagar por isso em latência. Fundido o adaptador, o modelo servido é indistinguível de um modelo treinado por inteiro — do ponto de vista de quem chama, não existe LoRA ali.

E não serve para duas, igualmente concretas.

Não serve para injetar conhecimento — é o mesmo alerta do quadro acima, agora com o mecanismo explicado: um ajuste de posto baixo não tem capacidade para guardar fatos novos de forma confiável. Ele muda a direção da resposta, não o acervo do modelo.

E não serve quando o domínio é genuinamente estranho ao modelo base. Se o modelo nunca viu nada parecido com o seu assunto, a correção que você precisa não é de rumo, é de formação — e aí nenhum r razoável dá conta. O sinal é o que descrevi acima: você só consegue resultado subindo o posto até o ponto em que a errata fica do tamanho do manual. Nesse ponto, a resposta honesta é trocar o modelo base, não insistir no adaptador.

Uma nota de atualidade, porque a técnica não parou em 2021: a variante mais usada hoje é a QLoRA21, que congela o modelo base em precisão reduzida (4 bits) antes de treinar o adaptador. O efeito prático é que modelos que exigiriam várias GPUs passam a caber numa só. Para quem está começando, é o caminho de menor atrito.

Antes de treinar: a escada

Antes de você reservar GPU, uma ressalva importante: fine-tuning é o quarto degrau, não o primeiro. A ordem importa porque cada degrau custa mais e é menos reversível que o anterior. Subir sem medir é como trocar o banco de dados antes de olhar o plano de execução da query — você pode até acertar, mas foi sorte.

Prompt bem escrito. Instrução explícita, formato de saída declarado, critério de desempate para os casos ambíguos. Custo: uma tarde. Resolve mais do que a maioria dos times admite.
Exemplos dentro do prompt. De três a dez casos já resolvidos, colados na instrução. Custo: outra tarde, mais tokens por chamada. É fine-tuning de pobre — e às vezes é suficiente.
RAG. Quando o que falta é informação, não comportamento. O teste é direto: se a resposta errada melhora quando você cola o documento certo no prompt, o seu problema é de busca, e treinar não vai resolver.
Fine-tuning. Quando os três anteriores foram medidos, o número parou de subir, e o que ainda falta é consistência de forma ou economia em volume alto.

O teste para saber se você pode pular direto ao degrau quatro é um só: você tem o número do degrau anterior anotado em algum lugar? Se não tem, o fine-tuning não vai consertar nada — vai esconder o problema atrás de um modelo novo, e aí o diagnóstico fica mais caro, não mais barato.

O passo a passo da implementação

Definir a tarefa com borda nítida. "Classificar o motivo de não-pagamento em um de 42 códigos" é tarefa de fine-tuning. "Responder dúvidas sobre cobrança" não é — é tarefa de RAG disfarçada.
Montar o conjunto de exemplos. De 500 a 5.000 pares bem revisados batem 100 mil pares sujos, sempre. A qualidade do rótulo é o teto da qualidade do modelo, e não existe hiperparâmetro que conserte rótulo errado.
Formatar. JSONL22, um exemplo por linha, no formato de conversa que o modelo escolhido espera. Separe de 10% a 20% para avaliação e não deixe esses exemplos vazarem para o treino.
Estabelecer a linha de base. O número que você já mediu nos degraus anteriores. É o que o fine-tuning precisa bater para se justificar.
Treinar com LoRA. Comece com r = 16, alpha = 32, 2 ou 3 épocas23 e taxa de aprendizado24 na casa de 1e-4. Para um modelo de 7 a 8 bilhões de parâmetros, isso roda em poucas horas numa única GPU alugada.
Avaliar contra a linha de base. No conjunto separado, não no de treino. E verifique regressão: é comum o modelo ficar ótimo na tarefa e pior em tudo mais ao redor dela.
Servir. Funda o adaptador25 nos pesos, ou mantenha-o separado e carregue sob demanda — o segundo caminho serve vários adaptadores especializados sobre uma única cópia do modelo base.
Agendar o próximo treino. Fine-tuning não é entrega, é dependência: quando o produto mudar, o modelo precisa de nova rodada. Isso entra no orçamento do time no dia zero.

Também aqui as ferramentas estão no apêndice. Vale adiantar a ordem de grandeza do custo: um treino LoRA de modelo pequeno numa GPU alugada por hora custa de dezenas a poucas centenas de dólares — um almoço de time, não um projeto.

A frase que economiza dinheiro
Fine-tuning não injeta fatos de forma confiável. Se você treinar o modelo com a política de cobrança esperando que ele "decore" as regras, vai obter algo pior que não saber: um modelo que erra com convicção, no tom certo, no formato certo, sem nenhum sinal de que errou. Fatos vão para o contexto. Comportamento vai para os pesos.

Tópico 4 — A conta

A economia não está no preço do token; está no preço do token multiplicado pela frequência — e é a frequência que decide a estratégia.

Antes da conta, o terreno. Em outubro de 2026 todo fornecedor repete as mesmas três faixas: um modelo de ponta entre dois e dez dólares por milhão de tokens de entrada, com a saída custando de três a cinco vezes a entrada; um intermediário cerca de dez vezes mais barato, e uma faixa econômica cotada em centavos por milhão. É com essas faixas que eu vou calcular. Os preços vão mudar; a estrutura da conta, não.

E vamos usar a carteira de cobrança lá do começo do artigo: 40 mil eventos por dia, 1,2 milhão por mês, classificando o motivo de não-pagamento a partir do histórico de contato. Pegue papel, que são duas contas curtas.

Cenário A — RAG sobre modelo de ponta

Seis trechos recuperados mais a instrução: ~3.500 tokens de entrada e 150 de saída por chamada.

entrada: 1.200.000 x 3.500 = 4.200.000.000 tokens = 4.200 M
         4.200 M x US$ 2,00/M  = US$ 8.400
saída:   1.200.000 x   150 =   180.000.000 tokens =   180 M
           180 M x US$ 10,00/M = US$ 1.800
                                 -----------
                        total:   US$ 10.200 / mês

Cenário B — modelo pequeno com fine-tuning

O "como classificar" virou peso, então o prompt encolhe para 400 tokens: sem instrução, sem exemplos, sem trechos recuperados.

entrada: 1.200.000 x   400 =   480.000.000 tokens =   480 M
           480 M x US$ 0,15/M = US$ 72
saída:     180 M x US$ 0,60/M = US$ 108
                                 -----------
                        total:   US$ 180 / mês
                        treino:  ~US$ 300, uma vez por trimestre

Dez mil e duzentos contra cento e oitenta. Cinquenta e seis vezes. O treino se paga em menos de um dia de operação. Se o seu caso é esse, não existe discussão a ter.

Mas aqui eu preciso ser honesto sobre o número, porque ele favorece a minha tese por um motivo que não é o da minha tese. O cenário A também não carrega o índice vetorial nem o re-ranking na fatura, o que torna a diferença ainda maior do que o número mostra. Mas o ponto central é outro: essa economia existe porque a tarefa é classificação estável: 42 códigos que mudam uma vez por ano. Troque a tarefa por "explicar ao cliente qual condição de parcelamento se aplica ao contrato dele hoje" e o cenário B vira uma máquina de dar resposta errada com segurança — e um acordo oferecido fora da alçada custa, num único caso, mais do que os dez mil dólares que você economizou no mês inteiro.

A fronteira, em uma fórmula

Em linguagem comum: a conta abaixo diz quantos meses o fine-tuning leva para se pagar.

meses_para_pagar = custo_do_treino / (volume_mensal x economia_por_chamada)

e o treino só vale a pena se:
meses_para_pagar  <  meses_ate_a_tarefa_mudar

O denominador tem volume. O limite tem estabilidade. É por isso que a pergunta "qual é melhor" não tem resposta: ela ignora as duas variáveis que decidem.

E agora o que a fórmula não vê, que é onde a maioria das decisões de fine-tuning azeda. O custo do treino não é a GPU: é o conjunto de avaliação que alguém precisa manter vivo, a rodada de retreino a cada mudança de produto, e mais uma versão de modelo para rastrear quando a resposta sair errada em produção às duas da manhã. Numa conta honesta, some ao numerador algumas horas de engenharia por trimestre. Se o seu time não tem quem assuma isso nominalmente, o payback de um dia vira passivo permanente.

Falta também a dimensão que não aparece em dólar: latência. Um modelo pequeno com prompt de 400 tokens responde numa fração do tempo de um modelo de ponta com 3.500 tokens de contexto para ler. Se o seu caso é lote noturno, isso não vale nada. Se é uma tela de atendimento com o cliente na linha, pode valer mais que a economia inteira — e aí a decisão deixa de ser sobre fatura.

Figura 4. As três curvas de custo. O fine-tuning parte de um patamar por causa do treino e cresce devagar; o modelo de ponta parte do zero e cresce rápido. O ponto de virada é a única coisa que você precisa estimar.

Três alavancas que mudam a conta antes de qualquer decisão de arquitetura, e que muita gente deixa na mesa:

Processamento em lote26. Se a resposta não precisa ser imediata — e classificação de carteira noturna não precisa — a maioria dos fornecedores dá cerca de 50% de desconto. Metade da fatura, por uma mudança de desenho, não de modelo.

Cache de prompt27. Quando o começo do prompt é sempre igual (sua instrução, suas regras, seus exemplos fixos), ele pode ser cobrado uma vez e reaproveitado. Isso exige que a parte estável venha antes da parte variável — uma decisão de ordenação de string que vale milhares de dólares por mês.

Destilação28. O terceiro caminho, e onde mora a economia mais bonita. Você usa o modelo caro para gerar alguns milhares de exemplos de alta qualidade, treina o modelo pequeno com eles e aposenta o caro no caminho de alto volume. É o cenário B sem meses de rotulação humana: o modelo grande vira ferramenta de fábrica, não peça de produção.

Pense comigo
Você sabe qual é o volume mensal de chamadas do seu caso de uso mais caro, ou só o valor total da fatura? Sem separar por caminho, não dá para saber onde otimizar.
Quanto do seu prompt é idêntico em todas as chamadas? Essa fração é desconto de cache esperando para ser cobrado.
Qual é o custo de um erro no seu domínio? Enquanto esse número não estiver na mesa, a discussão sobre modelo mais barato está sendo feita com metade da informação.

Tópico 5 — O critério: o que muda, o que é estável, e o que precisa de prova

A pergunta da abertura tem duas metades, e nenhuma delas é sobre tecnologia.

Lembra dela? Isto aqui muda com que frequência, e eu preciso provar de onde veio a resposta? A primeira metade mede velocidade de mudança. A segunda mede necessidade de prova. São eixos independentes, então cruze os dois e a escolha para de ser opinião: vira um quadrante com quatro respostas, e cada uma delas aponta para um lugar diferente.

Vamos aos quatro.

Muda rápido e precisa de prova. Política vigente, condição contratual, saldo devedor, norma do regulador. RAG, sem discussão. Fine-tuning aqui é tecnicamente possível e profissionalmente irresponsável: você grava nos pesos uma regra que vence no mês que vem, sem jeito de mostrar a fonte.

Não muda e não precisa de prova. Formato de saída, tom, jargão do domínio, classificação em taxonomia fechada. Território natural do fine-tuning — dá para fazer com instrução no prompt também, mas aí você paga aqueles tokens em toda chamada, para sempre.

Não muda mas precisa de prova. Cálculo de juros, régua de negativação, critérios de alçada. Aqui a resposta raramente é um modelo: é código determinístico que o modelo chama. Regra estável e auditável merece teste unitário, não treino.

Muda rápido e não precisa de prova. Resumo de atendimento, priorização de fila, rascunho de mensagem. RAG leve, ou nem isso — às vezes é só um prompt bom.

A auditabilidade não é um detalhe de conformidade

Esse eixo decide sozinho uma quantidade enorme de casos no nosso domínio. O AI Act29 europeu classifica pontuação de crédito como alto risco, com transparência e conformidade obrigatórias desde agosto de 2026. No Brasil, LGPD, normas do Banco Central e o direito do consumidor à explicação de decisão automatizada apontam para o mesmo lugar por caminhos diferentes.

Um modelo com fine-tuning responde "código 17, inadimplência por desemprego". Você não tem como mostrar de onde saiu — a justificativa está diluída nos milhões de números que o treino ajustou, espalhados por todas as camadas. Um sistema com RAG responde a mesma coisa e anexa o trecho do atendimento e a cláusula da política que sustentam o código.

Numa área onde a decisão afeta o acesso de alguém ao crédito, poder apontar a fonte não é um bônus de engenharia. É requisito de operação.

E a resposta que ninguém quer ouvir

Na prática, os sistemas que funcionam fazem as duas coisas. O fine-tuning ensina o formato, o jargão e o critério; o RAG entrega o fato do dia. O modelo pequeno treinado sabe como classificar e o contexto recuperado diz o que aconteceu. Não é escolha excludente; é divisão de trabalho.

Mas, se eu puder deixar só um conselho: a maioria dos times não precisa de fine-tuning nenhum. Precisa de um RAG bem construído e de um conjunto de avaliação de verdade. Fine-tuning é otimização — e otimizar antes de medir continua sendo o erro mais antigo da nossa profissão, com roupa nova.

O que fazer na segunda-feira

Se você só for levar uma coisa daqui, leve esta sequência. Ela cabe em duas semanas e substitui aquela reunião em que o time discute RAG contra fine-tuning sem um número sequer na mesa — você sabe exatamente de que reunião eu estou falando.

Escolha um caso de uso só, o de maior volume. Anote duas coisas: quantas chamadas por mês ele faz e quanto custa, em reais, um erro dele.
Monte 50 perguntas com resposta conhecida. Esse arquivo é o ativo mais valioso do projeto e o único que não dá para comprar pronto. Tudo que vem depois mede contra ele.
Meça o degrau um — modelo de ponta, prompt bem escrito, nada mais. Esse número é a sua linha de base para o resto do ano, e metade das vezes ele já é bom o bastante.
Classifique o que falta nos quatro quadrantes acima. O que muda rápido vai para RAG; o que é estável e precisa de prova vira código determinístico; o resto espera.
Só então faça a conta do tópico 4, com tokens medidos e não estimados. Se o payback não couber dentro do prazo de validade da tarefa, você acabou de economizar um trimestre.

Voltando ao analista e ao PDF de cento e oitenta páginas

Ele não desaparece. Muda o que ele faz com as horas que gastava lendo. O balde de "outros" para de crescer, e a política que ninguém lia inteira passa a ser consultada corretamente quarenta mil vezes por dia.

Nada disso depende de escolher a tecnologia da moda. Depende de olhar para cada pedaço do problema e fazer aquela pergunta sem glamour nenhum: Isto aqui muda com que frequência, e eu preciso provar de onde veio a resposta?

A engenharia boa quase sempre começa separando o que muda do que não muda. Nesse sentido, não mudou nada — só o nome das ferramentas.

Na sua operação, qual é a parte que todo mundo trata como estável e que na verdade muda toda semana? Conta nos comentários — eu desconfio que a resposta mais comum vai ser "a política".

Apêndice — as ferramentas, uma a uma

Esta parte é de consulta, não de leitura corrida — pode favoritar e voltar depois. Cada ferramenta vem com três coisas: o que ela é, para que serve na prática e quando você pode pular sem culpa. Comandos e nomes de pacote em inglês, como sempre.

Para montar um RAG

pgvector30 — extensão do PostgreSQL que guarda vetores e faz busca por proximidade. Serve para: ser o seu banco vetorial sem adicionar banco nenhum ao inventário. Pule se: você já passou de alguns milhões de vetores com exigência de latência baixa — e só depois de medir.
Qdrant — banco vetorial dedicado, roda como container. Serve para: volume alto, filtros complexos por metadado e controle fino do índice. Pule se: o pgvector ainda dá conta; é infraestrutura a mais para operar.
Spring AI — abstração de modelos, embeddings e bancos vetoriais para Java/Spring Boot. Serve para: manter o RAG dentro do mesmo stack do motor, com injeção de dependência e configuração que o time já entende. Pule se: a casa é Python.
LangChain e LlamaIndex — bibliotecas Python de orquestração. A primeira é mais geral; a segunda nasceu focada em indexação e recuperação. Servem para: não escrever à mão o encadeamento de carregar, picar, embeddar, buscar e montar o prompt. Pule se: o seu pipeline tem quatro passos; nesse caso a biblioteca pesa mais que o problema.
sentence-transformers — biblioteca para rodar modelos de embedding na sua própria máquina. Serve para: usar modelos abertos como BGE-M3 ou E5 multilingual, que vão bem em português, quando o dado não pode sair da sua infraestrutura. Pule se: você pode chamar um embedding hospedado — é mais simples e você não opera GPU.
Reranker — um modelo menor que reordena por relevância os trechos que a busca trouxe. Existem versões abertas (a família bge-reranker) e hospedadas. Serve para: o melhor retorno por hora investida em todo o pipeline. Pule se: você ainda não mediu a recuperação — sem o número, não dá para saber se melhorou.
Ragas e DeepEval — bibliotecas de avaliação de RAG. Servem para: dar prontas as métricas de recuperação e de fidelidade à fonte, em cima do seu conjunto de perguntas. Pule se: você prefere escrever as duas métricas à mão, o que é perfeitamente razoável e leva uma tarde.

Para quem não programa: os comandos abaixo baixam e instalam esses pacotes. A primeira linha sobe um PostgreSQL já com o pgvector dentro; as demais instalam bibliotecas Python.

docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=dev pgvector/pgvector:pg17
# then, inside the database: CREATE EXTENSION vector;

docker run -d -p 6333:6333 qdrant/qdrant

pip install langchain llama-index
pip install sentence-transformers
pip install ragas deepeval

Para fazer fine-tuning

APIs gerenciadas (OpenAI, Vertex AI, Bedrock) — você sobe o JSONL e recebe um modelo treinado. Servem para: a primeira tentativa, sempre. Mais caro por rodada, muito mais barato em tempo de gente. Pule se: o dado não pode sair da sua infraestrutura.
transformers — a biblioteca base da Hugging Face para carregar e rodar modelos. Serve para: ser a fundação de todo o resto nesta lista.
peft — é onde o LoRA mora, literalmente. Serve para: aplicar o adaptador de posto baixo sobre um modelo congelado, escolher o r e salvar o resultado como arquivo separado. Pule se: você usa Unsloth ou Axolotl, que já o embrulham.
trl — a camada de treino supervisionado em cima do peft. Serve para: rodar o laço de treino sem escrevê-lo.
bitsandbytes — quantização. Serve para: habilitar a QLoRA, congelando o modelo base em 4 bits para que ele caiba numa GPU só. Pule se: o modelo já cabe sem isso.
Unsloth — empacotamento otimizado do treino LoRA/QLoRA. Serve para: treinar bem mais rápido e com menos memória, com poucas linhas. É o caminho de menor atrito para a primeira rodada local.
Axolotl e LLaMA-Factory — treino dirigido por arquivo de configuração. Servem para: tornar o treino reproduzível e versionável: o YAML vai para o repositório junto com o dataset. Pule se: você está só experimentando.

Em linguagem comum: a primeira linha abaixo instala o conjunto básico de treino; a segunda, o atalho otimizado; a terceira, o treino por configuração.

pip install transformers peft trl datasets accelerate bitsandbytes

pip install unsloth

pip install axolotl

Para servir e observar

vLLM — servidor de inferência de alta vazão. Serve para: colocar o seu modelo em produção com throughput sério, e carregar vários adaptadores LoRA sobre uma única cópia do modelo base — exatamente o cenário que torna o LoRA interessante em operação. Pule se: você está usando modelo hospedado por API.
Ollama — roda modelos na sua máquina com um comando. Serve para: testar antes de gastar com infraestrutura, e para desenvolver offline. Pule se: seu notebook não tem memória para o modelo que você quer testar.
Langfuse e Phoenix — observabilidade de aplicações com modelo. Servem para: rastrear, em cada chamada, qual prompt foi montado, quais trechos foram recuperados e o que o modelo respondeu. Sem isso você não depura: você adivinha. Pule se: nunca — este é o item que mais gente deixa para depois e mais faz falta no primeiro incidente.

pip install vllm
pip install langfuse arize-phoenix
# Ollama: installer at ollama.com

O mínimo para começar amanhã

Se você quer sair daqui com uma única linha de comando e um caminho, é este: um Postgres com pgvector para o índice, um modelo hospedado para gerar e embeddar, e Langfuse ligado desde a primeira chamada. Nada de GPU, nada de treino, nada de banco vetorial novo. Monte o degrau um e o degrau três da escada, meça contra as suas cinquenta perguntas, e só então decida se alguma das outras ferramentas desta lista entra no seu problema.

Fontes

Dados de preço e referências regulatórias verificados em 22 de outubro de 2026.

Modelo de linguagem (LLM). Programa treinado para prever o próximo pedaço de texto a partir do anterior. Como um autocompletar que leu uma biblioteca inteira — e que, de tanto prever, aprendeu a raciocinar sobre o que prevê.

Pesos. Os números internos do modelo, ajustados durante o treinamento. São o que o modelo "sabe" sem precisar que ninguém conte na hora.

Janela de contexto. Quanto texto o modelo consegue ler de uma vez numa chamada. É a bancada de trabalho: tudo que não está em cima dela não existe para aquela tarefa.

Token. O pedaço de texto que o modelo manipula — geralmente uma palavra curta ou parte de uma longa. É a unidade da conta, como o minuto era na ligação interurbana.

Tokenizador. O componente que corta o texto em tokens. Cada modelo tem o seu, e o corte é mais eficiente nas línguas que estavam mais presentes no treino.

RAG. Retrieval-Augmented Generation, geração aumentada por recuperação. Buscar o trecho certo antes de perguntar, como o advogado que consulta o artigo em vez de confiar na memória.

Embedding. A representação de um texto como lista de números, construída de forma que textos de sentido parecido fiquem próximos. É o endereço do texto num mapa de significados.

Similaridade de cosseno. Medida do ângulo entre dois vetores. Vale de -1 a 1; perto de 1 significa "apontam para o mesmo lado", ou seja, falam da mesma coisa.

Alucinação. Quando o modelo produz uma afirmação plausível e falsa. O problema não é o erro — é que ele vem com a mesma confiança do acerto.

Fine-tuning. Treinar um modelo já pronto com os seus exemplos, para ajustar como ele responde. É o estágio na empresa depois da faculdade, não a faculdade de novo.

Gradiente / descida do gradiente. O método que ajusta os pesos: mede o erro, calcula para que lado cada número deve se mover para errar menos, e dá um passo nessa direção. Milhões de vezes.

LoRA. Low-Rank Adaptation. Em vez de reescrever a matriz de pesos, aprende um ajuste pequeno aplicado por cima — a errata grampeada no manual.

Adaptador. O arquivo com o resultado de um treino LoRA. Pesa megabytes em vez de gigabytes e pode ser carregado e descarregado sobre o modelo base.

Chunking. Quebrar documentos em pedaços indexáveis. O tamanho e o ponto do corte são a decisão que mais afeta a qualidade de um RAG.

Busca híbrida. Combinar busca por significado com busca por palavra-chave, somando os resultados. Cobre o ponto cego da primeira, que são nomes, números e códigos.

Re-ranking. Segunda passada que reordena os candidatos recuperados por relevância real, usando um modelo menor e mais criterioso que a busca vetorial.

Top-k. Quantos trechos você recupera para colar no prompt. Mais nem sempre é melhor: trecho irrelevante no contexto atrapalha ativamente.

pgvector. Extensão do PostgreSQL que armazena vetores e faz busca por proximidade. Permite ter RAG sem adicionar um banco novo ao inventário.

JSONL. Arquivo de texto com um objeto JSON por linha. Formato padrão para conjuntos de treino porque é lido aos poucos, sem carregar tudo na memória.

Época. Uma passada completa do treino por todos os exemplos. Poucas demais, o modelo não aprende; muitas, ele decora e perde a generalização.

Taxa de aprendizado. O tamanho do passo a cada ajuste. Grande demais passa do ponto; pequena demais nunca chega.

Destilação. Usar um modelo grande para ensinar um pequeno, gerando com ele os exemplos de treino. O especialista escreve o manual; o estagiário executa com o manual.

Cache de prompt. Reaproveitamento cobrado uma vez só do trecho inicial do prompt que se repete entre chamadas. Exige que a parte fixa venha antes da variável.

Processamento em lote. Enviar muitas requisições de uma vez aceitando resposta em horas em vez de segundos, em troca de desconto — tipicamente metade do preço.

AI Act. Regulamento europeu de inteligência artificial, que classifica aplicações por nível de risco e impõe obrigações proporcionais. Pontuação de crédito está na faixa de alto risco.

Memória de vídeo (VRAM). A memória da placa de vídeo, onde o modelo precisa caber inteiro para treinar. É o gargalo real do treino — não o processador, não o disco.

Dimensão intrínseca. O tamanho do espaço em que um modelo de fato se movimenta, bem menor que o número de parâmetros que ele tem. Como um mapa de mil ruas onde todo mundo só usa trinta.

Camadas adaptadoras. Técnica anterior ao LoRA: blocos pequenos inseridos entre as camadas do modelo e treinados com o resto congelado. Economizam treino, mas custam latência em toda resposta.

QLoRA. LoRA com o modelo base congelado em precisão reduzida (4 bits). O modelo perde pouca qualidade e passa a caber numa GPU só — é o que torna o treino acessível fora de laboratório.

Posto (rank). Quantas direções realmente independentes existem dentro de uma tabela de números. Posto baixo significa que, apesar do tamanho, a tabela carrega pouca informação nova — e por isso pode ser comprimida sem perda relevante.

OpenAI’s COBOL migration score has made a striking leap

2026-10-22T15:34:58Z

OpenAI reports dramatic improvements in legacy software modernization, but it's keeping the tests behind its biggest claim private.

DeepSeek V4.1-Flash-1017 vs. Claude Haiku 5.5: More accurate at a fraction of the price

2026-10-22T14:22:50Z

In our tests, DeepSeek’s updated open-weight Flash model beat Claude Haiku 5.5 on two tasks and tied on a third. Total cost: $0.07 versus Haiku’s $0.30.

That’s What She Said!

2026-10-22T08:12:56Z

What happens when you bring incredible women, honest conversations, and improv comedy into one room? ✨ A whole lot of connection, inspiration, and laughter! 🔅 Yesterday, I attended “That’s What She Said” at Boom Chicago in Amsterdam – and what a refreshing evening it was! It was so much more than networking. 🤝 💫 I […]

AI to Test Netflix Games

2026-10-22T06:46:47Z

The AI controls the phone. The phone controls the game. And the test goes far beyond getting a high score.

Recorded gameplay and the paired iPhone controller, with input indicators.

First, the AI learns the game.

CARBON for Games starts with a learning phase. The AI explores the app, tries the controls, navigates menus and discovers available settings. It observes what happens after each action to learn how to start, play and recover when something goes wrong.

That knowledge becomes a test plan: which player personas to exercise, which goals to pursue, which settings to vary and what outcomes to verify. Learning continues during testing. An unfamiliar screen or unexpected response can send the AI back into exploration. CARBON saves knowledge separately for each game and can revisit it as the app changes.

One game. Two devices. A lot to coordinate.

Some Netflix desktop games use a phone as the controller while the game runs in a browser. The AI must coordinate the phone, the browser and the connection between them. In this demo, it operates a physical iPhone paired with Tetris in the desktop browser.

Even getting to the first move takes work. Pairing links expire. A controller can appear connected but stop responding. A session may need a restart or cleared state. Setup, connection recovery and getting back into the game belong in the test plan too.

The game will not wait for the AI.

Gameplay is more demanding than clicking a predictable sequence of buttons. The AI has to understand the current state, choose a useful move, deliver the input and observe the result. In Tetris, a block keeps falling while that happens. A sensible decision delivered too late is still a bad move.

Our custom-trained gameplay model can run locally. In the recorded Max Score run, median model inference was 1.77 milliseconds. The complete observe-and-act loop was much slower: median placement time was 4.56 seconds, with phone input delivery a major bottleneck. Fast reasoning helps, but the whole interaction must keep up.

In our recorded Tetris demo, the result was 1,260 points and six lines cleared in a completed three-minute Time Attack round. This is a recorded run, not a promise of the same score every time. Capture gaps are marked in the video.

Custom models, working together with AI.

CARBON uses custom-trained gameplay models for different player personas, working with AI components for other parts of the testing stack: exploration, test design, orchestration and evaluation. They interact through shared observations, plans, decisions and execution evidence to test apps together.

The current Tetris models learn from simulated games and outcome-based training. A selected persona guides gameplay decisions, while the broader AI workflow supplies context and evaluates what happened. The demo uses the local Max Score model; the exploration and evaluation components are separate AI capabilities, not all custom-trained models.

This division lets each part focus on its job: learn the app, create the test plan, choose actions, and verify execution. The useful output is a traceable result backed by what the system actually observed.

Different players expose different problems.

A perfect player can miss problems that a confused beginner finds immediately. CARBON’s testing workflow can explore multiple player styles:

First timer: discovers controls, misses instructions and makes understandable mistakes.
Casual player: explores at a relaxed pace without optimizing every move.
High scorer: pursues points, combinations and efficient placements.
Speedrunner: looks for quick routes and fewer inputs.
Rule breaker / cheater: looks for loopholes in visible gameplay mechanics, such as unexpected action sequences or repeatable advantages.
Edge-case explorer: probes boundaries, interruptions and unusual states.

The local Tetris bundle has trained policies for high score, casual, speedrunner and rule-breaker play. First-time discovery and wider edge-case exploration use the broader testing workflow. Each persona needs its own observed run before we can claim its tests passed.

Personas describe how. Goals define what to test.

A casual player can still test a difficult setting. A high scorer can test recovery after a pause. A test goal might be to complete a round, reach a score, discover every menu, exercise a shortcut or recover from a controller disconnect.

The plan also covers configuration. Does a difficulty change alter gameplay? Does the selected level appear correctly? Does music actually stop when it is turned off? Do settings persist when the player leaves a menu and returns?

Selecting an option is only the first half of that test. The AI must verify its effect using suitable evidence. A silent-looking screenshot cannot establish that music stopped; that check needs audio evidence. Missing evidence should remain an open question.

The most interesting checks are qualitative.

CARBON’s AI can examine more than scores, crashes and completed rounds. Did the player understand what happened? Was feedback timely and helpful? Did the controls feel responsive? Was a recovery path confusing? Did the game behave consistently with the player’s expectations?

These are observations to investigate, with evidence and context — not universal verdicts about what every player will enjoy. Different personas and goals make those questions more useful.

Learn. Plan. Play. Verify. Learn more.

CARBON for Games brings AI into the full testing workflow: learning the app, creating a test plan, executing scenarios with different personas and goals, checking outcomes, and reporting findings. New discoveries can feed back into the next round of learning and testing.

The result is a growing understanding of how the game works and where the player experience needs attention. Playing the game is how we get there.

Interested in AI game testing? Visit Testers.ai or reply to this article. If someone on your team is testing games, share this with them.

This is an independent Testers.ai demonstration, not a Netflix endorsement, or collaboration.

— Jason Arbon, Testers.ai

AI to Test Netflix Games

2026-10-22T06:46:47Z

The AI controls the phone. The phone controls the game. And the test goes far beyond getting a high score.

Recorded gameplay and the paired iPhone controller, with input indicators.

First, the AI learns the game.

One game. Two devices. A lot to coordinate.

The game will not wait for the AI.

Custom models, working together with AI.

Different players expose different problems.

A perfect player can miss problems that a confused beginner finds immediately. CARBON’s testing workflow can explore multiple player styles:

First timer: discovers controls, misses instructions and makes understandable mistakes.
Casual player: explores at a relaxed pace without optimizing every move.
High scorer: pursues points, combinations and efficient placements.
Speedrunner: looks for quick routes and fewer inputs.
Rule breaker / cheater: looks for loopholes in visible gameplay mechanics, such as unexpected action sequences or repeatable advantages.
Edge-case explorer: probes boundaries, interruptions and unusual states.

Personas describe how. Goals define what to test.

The most interesting checks are qualitative.

These are observations to investigate, with evidence and context — not universal verdicts about what every player will enjoy. Different personas and goals make those questions more useful.

Learn. Plan. Play. Verify. Learn more.

The result is a growing understanding of how the game works and where the player experience needs attention. Playing the game is how we get there.

Interested in AI game testing? Visit Testers.ai or reply to this article. If someone on your team is testing games, share this with them.

This is an independent Testers.ai demonstration, not a Netflix endorsement, or collaboration.

— Jason Arbon, Testers.ai

My learning bits for Thursday of 22nd October 2026

2026-10-22T06:15:00Z

From Fortran to LLMs, https://hrih.si/articles/the-compiler-was-supposed-to-end-programming/

A Letter to a Developer, From a Tester 💙

2026-10-22T02:17:15Z

We’ve all heard the joke, haven’t we?

Developers and Testers are like Tom and Jerry. One writes the code, and the other tries to find something wrong with it. One fixes a bug, and the other comes back with another one. And the chase continues!

It’s a familiar stereotype, and perhaps we all have laughed at it at some point.

But I think our story has evolved.

Over the years, I have had the privilege of working with some wonderful developers. Some challenged me with a healthy competitive spirit. Some patiently explained their code when I wanted to understand what was happening behind the scenes. Others helped me understand build releases and the technical decisions that shaped the product.

These experiences meant more to me than they might have realised.

They reminded me that collaboration isn’t just about attending the same meetings or working towards the same deadline. It’s about sharing knowledge, listening to another perspective, and being willing to learn from each other.

And I’m happy to see more teams embracing this mindset. Developers and testers are collaborating earlier, discussing risks together, and treating quality as a shared responsibility rather than something that belongs to just one role.

There is still room to grow, of course, but I think we should appreciate how far we have come.

And that’s why I want to write this letter.

Dear Developer,

I know how much thought, creativity, and effort go into building software. Behind a feature that looks simple to a user, there may be hundreds of decisions, complicated logic, integrations, and hours of problem-solving.

As a tester, I may come along with questions, unexpected scenarios, or a defect report. But my intention isn’t to question your ability or make your work harder.

I’m not here to find bugs just to bug you.

I’m here because I care about the product, too.

I want to understand what you’re building. I want to ask questions that might uncover a hidden assumption. I want to explore what happens when a user does something unexpected, when two systems interact, or when a perfectly reasonable feature behaves differently in the real world.

Sometimes, I’ll find a defect. Sometimes, I’ll raise a concern that turns out not to be a problem. And sometimes, you’ll explain something that helps me understand the system in a completely new way.

That’s the beauty of working together.

Some of my best learning experiences have come from developers who were willing to explain why something worked the way it did, rather than simply telling me that it worked as expected.

Those conversations helped me ask better questions, understand technical risks, and become a better tester. I hope my questions and observations have helped you see your work from a different perspective, too.

Dear Developer, There Are Things I Admire About You

There are so many things I admire about what you do, and perhaps I don’t say them often enough.

I admire how you navigate hundreds, sometimes thousands, of lines of code, understanding how each piece connects to another. What might look like a maze to someone else is a system you have patiently built, understood, and maintained.

I admire how you investigate a defect, trace it back through layers of logic, and work to understand what went wrong.

And when we finally get to the bottom of it, I appreciate those moments when you look at the evidence and say, “Yes, that’s a bug.”

Not because I was right and you were wrong, but because we found something that could affect someone using our product.

That willingness to listen, investigate, and acknowledge an issue is something I deeply respect.

I admire how you explore new technologies, discuss technical possibilities, and think through solutions that many of us might never have considered. I admire how you translate complex technical decisions into language the business can understand, helping people see not just what is possible, but what makes sense for the product.

And I admire the creativity behind your work. The time spent untangling a complicated problem, the careful decisions that make a system more reliable, and the satisfaction of finally getting something to work.

Sometimes, as testers, we see the outcome of your work through test cases, failures, and defect reports. But behind every line of code is thought, effort, and a person trying to solve a problem.

I see that effort. I respect it. And I appreciate it.

To the developers who have patiently answered my questions, walked me through technical details, and helped me understand the bigger picture, thank you. Those moments have shaped the way I work, and I hope I’ve made a positive difference to your work, too.

We may have different strengths, but that is precisely what makes our collaboration valuable.

Different Perspectives, One Shared Goal

One of the things I appreciate most about working with developers is that we don’t always look at a problem in the same way.

You might look at a feature and think about its architecture, implementation, performance, and maintainability. I’ll look at it and wonder what happens when the user takes an unexpected path, when the data is incomplete, or when something goes wrong at the worst possible moment.

Neither perspective is more important than the other. They complement each other.

Sometimes, a question from a tester leads to a better design. Sometimes, a developer’s explanation helps a tester identify a risk they hadn’t considered. Sometimes, a healthy technical debate leads us to a solution that neither of us would have reached alone.

And sometimes, we simply learn something new from each other.

That’s not conflict. That’s collaboration doing what it does best.

We won’t always agree, and we don’t have to. What matters is that we can challenge ideas while respecting the people behind them.

When a defect is raised, we can investigate it together. When a technical constraint exists, we can explore the options together. When something goes wrong, we can focus on understanding the problem rather than finding someone to blame.

The goal isn’t to prove who’s right. The goal is to get it right.

And when we do, the real winner is the end user using our software/product.

And Now, in the Age of AI…

Our tools are changing, and so is the way we build and test software.

AI can help developers generate code, explore solutions, and explain complex logic. It can help testers create test cases, analyse failures, and discover scenarios worth investigating.

These capabilities give us even more opportunities to learn from each other and improve the way we work.

But faster work doesn’t automatically mean better software.

We still need to ask questions, challenge assumptions, understand context, and consider how real people will experience the product. We need to think critically about what our tools produce and work together to determine whether the results are good enough.

I see this as another opportunity for developers and testers to strengthen their partnership.

We don’t need to compete over who can produce more code or find more bugs. We can use these tools to spend more time understanding risks, discussing solutions, and making thoughtful decisions about quality.

Our tools will continue to evolve, and our roles will evolve with them. But our shared responsibility towards the people who trust our software remains.

A Little Appreciation Goes a Long Way

To the developers who have shared their knowledge with me, answered my questions, explained the complicated bits, challenged my thinking, and treated testing as a collaborative effort: thank you.

You may not remember every conversation, but I remember how those moments helped me grow.

And to every developer reading this, I hope you know that your work is seen and appreciated.

When I raise a defect, I’m not standing on the opposite side of the table. I’m standing beside you, looking at the same product, trying to make it better.

You bring your creativity and engineering expertise. I bring my curiosity, testing skills, and a different perspective. Together, we bring a more complete understanding of the product and the people who will use it.

So, perhaps it’s time we gave Tom and Jerry a little break!

Let’s celebrate the partnerships that are already making a difference. Let’s keep sharing knowledge, asking questions, challenging assumptions, and learning from each other.

Because great software isn’t built by developers alone or made reliable by testers alone. It’s built by people who care about what they’re creating and work together to make it better.

Dear Developer, I am glad we are on the same team.

Let’s keep building software worth trusting, together.

Main 3k Character Syndrome

2026-10-21T22:11:44Z

There are reasons this timeline is so exhausting.

Between all the manufactured urgency of forced AI adoption, constantly moving goal posts around retraining, and relentless fear inducing job insecurity, AI related anxiety and burnout are taking a heavy toll on the mental health of tech workers and the general public.

A report from the America Psychological Association is revealing, with workers reporting that “technological change is benefiting employers more than workers.” The numbers are also increasing this year for folks worrying that they will “fall behind other workers at their company if they do not use AI”.

So to all my dear friends in the AI cargo cult of middle management perpetuating this pyramid scheme of abuse, I’m sure talking to a positive affirmation machine all day might give you a touch of main character syndrome, but good grief, don’t assume everything is about you!

A piece in Fast Company “AI psychosis is the new leadership blind spot” nails why that’s so hard when “polished-looking output with less substance beneath”, that the folks at Stanford and BetterUp call “workslop” gets to leadership. Who isn’t feeling this lately? The amount of incompetent experts AI is churning out might be the reason their talk is converging on the same ideas as well.

Skepticism is essential to responsible tool adoption and not the tired, boring claim of protecting the old guard, but just like that scene in Her when he finds out his AI girlfriend is simultaneously talking to thousands of other people and “in love” with a bunch of them at the same time, guess what:

“In one recent survey, 74% of executives said they had more confidence in AI’s advice than in that of colleagues or friends, and 44% said they would defer to its reasoning over their own insights.”

So if you feel like you’re taking crazy pills, remember it’s definitely not you – it’s them. We’re under a multi-billion dollar marketing assault that has “more than tripled in the US in Q1 2026, with OpenAI and Anthropic increasing spend by 800%+ YoY as competition for users intensifies.” Nothing about this is normal.

I know I’m feeling on the edge of burn out these days, so I guess it’s also time for our regular reminder to those being called a Luddite for being skeptical of AI bros or vendor claims that:

Thinking critically about a technology is NOT being AGAINST it…
Considering harm in a technology’s use is NOT being AGAINST it…
Being critical of the marketing of a technology is NOT being AGAINST it…
Having principles and values drive your adoption of technology is NOT being AGAINST it…
Calling out unverifiable claims used misleadingly to sell a technology is NOT being AGAINST it…

But as my friend Michael Bolton likes to say, “Good luck with your thing”…

The post Main 3k Character Syndrome first appeared on Quality Remarks.

Testing Adventure

2026-10-21T21:12:23Z

Much like my Test Defender post, this post’s title is a bit of a double entendre. It’s (hopefully) going to be an adventure but it’s also testing Adventure. And, yes, there will be something about AI in all this.

So, imagine a time when home video games were mostly simple arcade ports (like Pong or Space Invaders) where players just shot at targets or chased a high score on a single screen. Yep, you guessed it. I’m talking about the Dark Ages as the 1970s slipped into the 1980s. In this context, a game called Adventure was the first action-adventure game on a console. Specifically, on the Atari 2600. It allowed players to explore a vast (well, vast for the time) world spanning multiple screens, carry items in an inventory (or, rather, attached to your body), and search for a legendary artifact. It was almost exciting.

Because I clearly know how to use my time wisely, I decided to create a modern version of this. Well, modern insofar as it’s an exact recreation, but playable in a browser. So, retro-modern? Modern-retro? I have no idea. It’s called Adventure Uncartridged. It’s open sourced so you can make fun of it. And it’s directly playable online so you at least know what you’re making fun of.

If you’re thinking, “Wow, that looks hideous!”, well, don’t blame me. Blame the 1980s. You know, retro.

For purposes of this blog post, I want to talk about testing this game. Don’t worry! I already covered testing like it was 1980. We’re not quite going to do that.

If you are someone who is a tester or who has to think like a tester, and thus adopt the testing role, it’s worth looking at this game and considering how you would test it. Awhile back I wrote a Test Quest game that I used for interviews, because I found then, and still do today, that you can learn a whole lot from watching someone decide how to test a game; moreso than any other application.

Purpose and Audience

So let’s keep in mind some crucial context here: this is a port of the original game, staying as true to the original as possible. (That’s for better and worse, mind you.) One goal of testing this game is to find every place where the browser version behaves differently from the 1979 Atari 2600 original. Playability and a stable build matter too, but fidelity comes first.

Wait, playability is secondary? It would seem like a primary quality attribute, would it not? Well, sure, it is, but remember: if fidelity is the goal, then how playable or not it is would remain a function of what the game was. That’s important to keep in mind. Unless they have a time machine and don’t mind altering the past, any bugs a tester wrote about pure playability would be entirely missing the point.

This strategy serves two kinds of test thinking, and most sections I talk about here are marked for one or both.

Testers who explore by playing. The live game, the manual, an emulator; using keyboard, notes, screen recordings, and a healthy dose of nostalgia.
Testers who explore the code. The TypeScript and (maybe?) 6502 assembly; using the source, the tests, the original assembly listing; involving code review, unit and property tests, and scripted play.

The two tracks feed each other. An exploratory tester can see a dragon behave oddly but can also find the line responsible. A tester who spots suspicious code can also use that finding to try a very precise thing in the game.

What Correct Means

In this context, the original game is the specification. When my version and the original disagree, the default verdict is that my version has a bug. That makes the usual question of how to know what correct looks like unusually answerable.

You can the following sources, in order of authority. And this is what I used as I was creating this and testing this port.

The original game running in an emulator. The Stella emulator plays the original cartridge image, which ships in my repository at docs/adventure.bin. You could play the same scenario side by side and compare. This is the main oracle for testers. It certainly was for me.
The annotated assembly listing. docs/adventure.asm is the original source with comments. Many functions in src/adventure.ts mirror a named routine in the assembly. This is a secondary, but still important, oracle for testers.
The original manual. docs/adventure-manual.pdf describes intended play, but not edge cases.
Project notes. You, as a reader, have docs/DIFFICULTY.md and docs/ASSEMBLY.md, which explain how specific mechanics work. I didn’t have those, of course, since I had to write them!

Some differences are deliberate, because a browser is not an Atari 2600. The keyboard replaces the joystick, buttons replace the difficulty switches, and keys 1 and 2 stand in for the console’s Reset and Select switches. A tester who finds a difference should first ask whether it’s one of these. Any other deliberate deviation should, of course, be questioned.

It is defensible to ask whether the game should support a joystick even in browser form, but it’s not defensible to say the browser should use the same exact mechanics as those that existed on a physical Atari 2600.

Risk Areas

As in all things, testing effort should follow risk, and the highest risk is a silent translation error from 6502 assembly into TypeScript. This would be a case where the game still runs, but some behavior is subtly wrong. When I was testing, I wrote up the following table that ranks the risk areas this strategy targets.

Rank	Risk	Why it is risky here	Tracks
1	Translation errors	The original relies on 8-bit wraparound, bit order and unsigned math that TypeScript does not copy automatically	Technical
2	Randomness	Game 3 placement and the bat depend on random numbers, so bugs hide until the right roll	Both
3	Frame timing	The 2600 ran at a fixed rate. A browser runs at the display’s refresh rate, and tabs can be paused	Both
4	State interactions	Carrying, being eaten, the bat, the magnet and portals can all happen on the same frame	Both
5	Room connections	Exits change with the game level, so a wrong table entry only shows at one level	Human
6	Input handling	A keyboard is not a joystick. Keys can stick, overlap or be released while the tab is unfocused	Human
7	Toolchain drift	Dependency updates can change the formatter, test runner or build without any code change	Technical

The Game 3 freeze, covered in the case study below, was a rank 2 bug with a rank 1 cause.

Test Layers

The automated tests cover the pure geometry fairly well. Even given that coverage, everything that depends on game state, randomness or input is still tested only by playing. The layers below go from cheapest to most expensive.

Layer	What it checks	Status	Track
Unit tests	Collision, playfield bit mapping, room picks	In place	Technical
Property tests	The same functions across thousands of generated inputs	In place	Technical
State machine tests	Every transition below, driven by scripted switch presses	Not started	Technical
Scripted playthroughs	A recorded input sequence with fixed random numbers, checked against the expected end state	Not started (although see agent section below)	Technical
Visual comparison	Each room rendered and compared with an emulator screenshot	Not started	Both
Exploratory sessions	Time-boxed play against a charter	Ongoing	Human

A test I found it was very easy to miss was that a mid-game reset puts the player back at the castle and revives all the dragons, but leaves objects where they are. That’s just how the game worked. Because transitions fire on release, both test types should hold keys down across transitions and release them at awkward moments.

Testability

In the developer role, I worked hard to make sure that the code already had the right seam for deeper testing. Every contact with the browser goes through src/hardware.ts, and the game itself advances one frame per call to startGame. So why are three of those layers still marked “Not started”?

It’s not because I didn’t think of them. (Of course, I would say that, right?) It’s because the tests can’t get at what those layers need. A state machine test has to press Reset and Select on exact frames and then ask the game which state it’s in. A scripted playthrough has to feed in the same key presses and get the same game every time, including in Game 3, where the random numbers decide where everything goes. A visual comparison has to render a room on demand and capture the picture. Right now, the key states are private, the random numbers come straight from the browser, the game’s current state is hidden, and each frame expects a real canvas to draw on. The geometry tests work because geometry is pure: give a function some numbers, check what comes back. Everything else is locked away from a test, so the only way to check it is to play.

In fairness to my developer self, the seam is in the right place. Nearly everything a test needs passes through that one hardware file. But a seam is only useful if a test can actually reach through it, and right now this one is closed. Four small changes would open it.

And here’s where I’d like you to put your tester hat on. Before reading on, look at src/hardware.ts and src/adventure.ts and ask yourself what you would change. What stops a test from pressing a key on frame 200? What stops it from replaying a Game 3 layout? What stops it from asking whether the game is in its Win state? Finding those blockers is a testing skill in its own right. It’s the difference between saying “we should have more tests” and saying exactly what stands in the way of them. I’ve put my four answers at the end of this post, so you can compare with yours, if you choose to give this a shot.

I can tell you that with those in place, a scripted playthrough becomes a list of frame numbers and key changes, plus a seed and an expected end state. This matters for a variety of reasons. One is that an exploratory tester’s bug report could become one of these scripts. Two is that you could use this as the basis for some automation based on that exploration. Three is that you could use AI to assist with this scripting.

Heuristics for Exploratory Play

The heuristics I’m about to talk about need no code. Each one is a way of looking at the game that tends to find bugs. My advice to testers would be to pick a few per session rather than trying them all at once. And if you were actually testing this “for real,” I would say to keep an emulator running the original open for comparison. That’s exactly what I did, when I stepped out of my developer role on this and went into my tester role.

That interleaving of roles is what I talked about regarding how testing knowledge isn’t just a testing skill.

You might want to stop reading and explore the game a bit then come back and see which of the following you tried or thought of.

Moving through the World

Walk every exit at every level. Room connections change between Games 1, 2 and 3, so an exit that works in one game can be wrong in another.
Hug the walls. Slide along walls, into corners and through narrow gaps. Collision bugs live at edges, not in open space.
Cross the screen edge slowly. Step back and forth across a room boundary, one press at a time.

Objects

Carry everything through everything. Take each object across a room edge, through a castle gate and over the bridge.
Drop things in awkward places. Drop items inside walls, half off the screen and in a castle gateway as it closes.
Lock yourself in. Use each key to close a castle behind you and check that you can still get out.

Creatures

Collide on the same frame. Touch the sword just as a dragon bites. Let the bat grab what you’re holding. Let the magnet pull an object into a wall.
Play keep-away with the bat. Follow it, block it, and see where stolen items end up.
Test each dragon’s personality. Yorgle should flee the sword and the chalice. Grundle and Rhindle should hunt. Compare their speeds with the emulator.

Switches and States

Interrupt every state. Press and release 1 or 2 while being eaten, while carrying, during a roar and after a win.
Hold keys across transitions. As I said earlier, state changes fire when a key is released, so hold 1 or 2 down and release it at the worst possible moment.
Flip difficulty mid-chase. The difficulty buttons take effect immediately, so toggle them while a dragon is chasing or roaring.
Cover the switch matrix. Three game levels times four difficulty settings gives twelve configurations. Check each against the bite delays in the project’s difficulty notes.

Input and the Browser

Abuse the keyboard. Hold opposite arrows together. Mash several keys at once. Hold space while moving.
Lose focus mid-move. Hold an arrow, then click another window or switch tabs, and come back. Check whether the player keeps moving.
Leave and return. Put the tab in the background for a minute, then return. Watch whether the game briefly runs faster than normal.
Change the display. Play on 60, 120 and 144 Hz screens, in full screen mode and in a small window. Check whether the arrow keys or space scroll the page.

Fidelity

Find the Easter egg. (For those who know the game, yes, I did implement it!) The secret dot and author room exercise several obscure mechanics at once. If that path works, a lot of fidelity holds.
Race the emulator. Play the same route in both versions and compare timing, sounds and colors at each step.

Heuristics for Reading the Code

These next heuristics are for testers who can read the TypeScript and the assembly side by side. Each one targets a way that a faithful-looking translation can still be wrong.

Where a heuristic has a clear example in the original, I’ve linked straight to the lines in the annotated assembly listing, so you can see what the TypeScript is supposed to be matching. If you’re not used to reading 6502, the comments down the right-hand side do most of the work.

Again, you might want to take a shot at this yourself before reading on.

Translation from 6502 Assembly

Check the range math on every random call. Confirm that the result can reach every intended value and nothing outside them. This would have caught the Game 3 freeze that I’ll talk about below. In the original, RandomizeLevel3 stirs a counter into a pseudo-random number and then trims it with and #$1f, which can only ever give 0 to 31.
Wrap where the ROM wraps. The 2600 stores most values in one byte, so 255 plus 1 is 0. TypeScript numbers do not wrap, so any counter, timer or position that relies on overflow needs an explicit mask. The original’s CheckInput counts on this: inc rolls the low byte over to 0, and only that rollover bumps the high byte. That same low byte is the seed for the Game 3 shuffle.
Check bit order against the hardware. The playfield registers are read in different directions, and the existing playfield tests pin this down. Apply the same suspicion to sprite and flag bits. The original’s PrintDisplay writes each room line straight into PF0, PF1 and PF2, and the hardware draws PF1 in the opposite bit order from the other two.
Translate comparisons exactly. The 6502 branches on carry and zero flags, which map to unsigned less-than and greater-or-equal. An inclusive bound written as exclusive is an off-by-one that only shows at the edge. The Game 3 room bounds check is a good one to practice on: bcc rejects a room below the lower bound, then beq and bcs accept the upper bound itself and reject anything above it. Both bounds are inclusive.
Trace every table index. For a lookup such as the dragon bite delay table, work out the index for every level and difficulty and confirm it lands on the intended entry. The original builds the index by taking one difficulty bit and merging in the level number, which is stored as 0, 2 or 4, and then reads the DragonDiff table.

Game Structure

Respect the frame split. The game spreads its work across three sub-frames, as the original did. Moving a call to a different sub-frame changes timing and the order of collisions. In the original’s MainGameLoop, three waits for vertical sync divide the loop into those three frames, and the player’s movement is handled once in each, a different way each time.
Look for state that survives a reset. List every module-level variable and check whether a full reset and a mid-game reset each restore it. A missed one produces a bug only on the second game. The original’s CheckGameStart shows exactly what a mid-game reset restores: the player’s room and position, all three dragons, and the carried object. Objects aren’t touched. It also zeroes the note count, which the person who annotated the listing flagged with “(ops!??)”.
Read the frame loop for catch-up. The loop advances its clock in fixed steps and runs one tick per display frame. After a long pause, it may tick on every display frame until it catches up, which is faster than normal on high refresh screens. Confirm or rule this out. The original never has this problem: its DoVSYNC routine waits on a hardware timer every frame, so the game can’t run faster than the console.

Claims in Comments and Docs

Treat comments as claims to test. For example, a comment says the Win state ignores the Reset key, while the Win state’s own handler returns to Game Select when Reset is released. Both can be true, but a test should pin down the exact behavior. And here the original can settle it. A win marks the game as inactive, and a Reset while the game is inactive goes straight back to the game select screen.
Check that docs still match the code. The difficulty notes still refer to a source file that has since been split up. Stale docs mislead the next tester.

The Build Itself

Run the whole pipeline before merging a dependency update. Run the check, the tests and the build locally, not just the check. Then confirm CI passes on the merged commit, not only on the pull request.
Keep toolchain versions pinned. A version range such as latest lets any lockfile regeneration bring in a breaking change. This happened to me once.

Sample Charters

A charter gives an exploratory session a target and a purpose without scripting the steps. Each one below follows the form: explore a target, with some resources, to discover some information. Time boxes are suggestions.

Charter	Track	Time box
Explore Game 3 starts under all four difficulty settings, to discover whether every start gives a playable layout	Human	30 min
Explore the castle gates with each key, to discover whether the player can be wrongly locked in or out	Human	45 min
Explore the bat with each carriable object, to discover where stolen items end up and whether any can be lost	Human	45 min
Explore Reset and Select presses in every state, to discover transitions that leave the game inconsistent	Human	30 min
Explore dragon encounters side by side with the emulator, to discover differences in speed and bite timing	Both	60 min
Explore the game after leaving its tab in the background, to discover whether the frame loop runs fast while catching up	Both	30 min
Explore the reset code paths, to discover module-level state that survives a new game	Technical	60 min
Explore every random number call against the assembly, to discover range or distribution errors	Technical	45 min

At the end of a session, write down what was covered, what was found and what is still unexplored. The unexplored list becomes the next charter. Yet, look at those times! Now, even if those are built with a bit of buffer, it does make you think about regression testing, right?

“But, Jeff, you fool. This is a port. Once it’s done, it’s done, right? Why would we need regression tests?” Well, new browser versions. Or an entirely new browser. Or maybe some styling updates for mobile. And so on.

But … but … what about AI ?!?

AI, as with any automation, can help with that time issue. For a tester, an AI agent that wins Games 1 and 2 is a test instrument, not a player. The question it answers is whether a route that wins on the original also wins here, on the same frames. And continues to do so over time.

A key thing to understand about this game is that Games 1 and 2 are deterministic. Neither this port nor the original assembly uses randomness outside the Game 3 shuffle. Given the same key presses on the same frames, both games should play out identically every time. A winning run can therefore be recorded as an input sequence and replayed. If the port is faithful, the replay wins on the same frame as the original.

Three Kinds of Agent

Approach	Sees	Acts by	A win shows	Main difficulty
Search-based solver	Game state: rooms, objects, positions	Planning a route through the room graph and steering to each target	The win is reachable in this version	Needs the testability changes. It plans rather than learns
Reinforcement learning agent	Screen pixels or game memory	Trial and error over many thousands of runs	A strategy learned on one version works on the other only if they match	The game gives one reward, at the very end
Vision language model	Screenshots	Choosing key presses and explaining why	Little on its own, but it can follow a charter and describe oddities	Far too slow for real time, so it needs a pause-and-step mode. It can misdescribe what it sees

The Agent I Built

Looking at that table, I went with the first option: a search-based solver. Partly that was a practical choice. A reinforcement learning agent would need thousands of runs to stumble onto a single reward at the very end (something my Pacumen project showed), and a vision model would be describing the screen long after the dragon had finished eating me. But mostly it was because Game 1 has no randomness. A plan that works once works every time (at least in this context), so planning beats learning.

The goal was simple to state. Have an agent win Game 1 on its own, record every key press it made, and then play that recording back in the real game so I could watch it.

The Seam Pays Off

Remember the testability point about every contact with the browser going through one file? Well, that’s what made this possible. It wasn’t that “AI exists and it can do this for me.” It’s “I’ve instrumented this code in a way that AI can likely use to learn how to play the game just as a human would.” The agent runs the real game code in Node, with no browser at all. A small loader hook swaps src/hardware.ts for a headless stand-in. The stand-in reads input from whatever the agent sets for each frame instead of the keyboard, draws into memory instead of onto a canvas, and doesn’t play sounds.

Nothing else in the game changes. The agent calls startGame once per frame, exactly as the browser’s loop would, and reads the game’s own state between frames: which room the player is in, what they’re carrying, whether a dragon is dead, whether a castle gate is open.

This is the testability work from earlier, just done for a reason. Scriptable input and stepping frames directly stopped being suggestions the moment I needed them.

Test the Instrument First

To plan a route, the agent has to predict where the player will end up after each move. So it carries a model of the player’s movement. I didn’t write that model from a description of how I thought the game worked. It’s built from the game’s own collision checks and room tables, mirroring the movement code step by step: the six-unit moves, the room wraps at the screen edges, the castle entrances, the way a wall hit is undone.

Here’s the thing, though. A model is a claim, and claims (ideally) get tested. Before trusting the planner with anything, a separate check drives the real game with random moves and compares every step against what the model predicted. The latest run checked 98,956 steps with zero mismatches.

I think this is the most tester-flavored part of the whole exercise. An agent planning with a wrong model would fail in confusing ways, and I would have spent my time debugging the agent when the actual problem was its picture of the world. So the instrument gets tested before it’s used to test anything else.

How It Plays

Crucially, the agent doesn’t discover the route. I gave it the one a human would take, as a list of goals checked in order against the game state:

Take the yellow key.
Open the yellow castle and go in.
Take the sword.
Kill the yellow dragon, then the green dragon.
Swap the sword for the black key.
Open the black castle and go in.
Take the chalice and carry it home to the yellow castle.

Notice: I gave it my intent; not the implementation. For each goal, the agent searches outward from the player’s position, breadth first, until it finds a position where the goal is met. That might be touching the key, or touching a dragon with the sword in hand. The search avoids anything it shouldn’t touch. In Adventure, walking into a carriable object swaps it into your hand, so brushing past the bridge on the way to the key would quietly ruin the plan, since it would now pick up the bridge.

Then it follows the path, one movement cycle at a time. If the game ever ends up somewhere the model didn’t predict, usually because a dragon or the bat moved something, the agent throws the plan away and searches again. When it’s chasing a dragon, it replans on every step, because the target keeps moving. If a dragon eats the player, it presses Reset and starts from the first goal it hasn’t completed yet.

There’s one setting worth mentioning. The run uses the right difficulty switch at A, which makes dragons charge at the player instead of fleeing the sword. That sounds harder, but for an agent it’s easier. Why? Because the dragons come to the sword instead of the agent having to chase them across the map.

But … you actually don’t have to kill the dragons at all to win the game. This was something I did not specifically tell the agent. Just as I didn’t tell Pac-Man everything it needed to know about ghosts and dots. So, realistically, the agent should have opted for difficulty B, right? The dragons just run away. Ah, but the agent knew, based on my constraints, that this would not test some of the most important conditions, such as the dragon chasing you to eat you.

The Result

The agent wins Game 1 in 3,368 frames, which is just under a minute of game time, and no dragon eats it along the way. Its log reads a lot like a test report:


frame      2  game 1 started, difficulty left B, right A
frame     68  done: take the yellow key
frame    134  done: open the yellow castle
frame    140  done: enter the yellow castle
frame    185  done: take the sword
frame    371  done: kill the yellow dragon
frame    677  done: kill the green dragon
frame    731  done: swap the sword for the black key
frame   1889  done: open the black castle
frame   1901  done: enter the black castle
frame   2012  done: take the chalice
frame   3128  the chalice is home: game won

The output is a recording with one number per frame, where each bit stands for a key: up, down, left, right, fire, reset, select. Since Game 1 is deterministic, that recording is the whole game. Playing it back always produces the same win on the same frame.

That also meant I could watch it. The browser version accepts a ?replay= parameter pointing at a recording. While it plays, the keyboard is ignored and inputs are applied per game frame rather than per unit of time, so the playback matches the recording whatever the display’s refresh rate. Here’s that run, filmed from the real page:

I posted a video of this on YouTube if you want to bask in the glory of AI Adventure!

This is where the earlier point about bug reports becoming scripts gets concrete. A recording is a scripted playthrough. If a future change breaks something on the route, replaying the file will fail to win, or win on a different frame, and that’s a regression test nobody had to write by hand.

What It Proves and What It Doesn’t

I have to be careful here, since overclaiming is a failure mode we testers like to spot in others. The agent proves Game 1 can be won in my version, by this route, under these switch settings. It doesn’t prove my version matches the 1979 original. The agent uses my code’s collision checks to plan, so if my translation of the walls were wrong, the agent would happily plan around my wrong walls.

Fidelity needs the original in the loop. The next step would be to get a winning run on the original, for example through the Arcade Learning Environment, which supports Adventure and rewards getting the chalice to the yellow castle. That run would be recorded frame by frame, with the environment’s random input repeats turned off. Then you would replay it in my version and compare the player’s room and position on every frame. The first frame where they differ points at the bug.

One small fidelity check has already passed, though. The original’s win check and mine agree. Both test whether the chalice is in the yellow castle’s inner room.

Heuristics for Judging Agent Results

Building this let me demonstrate a few heuristics that apply to any agent you point at software, not just this game:

Validate the model before trusting the planner. Whatever the agent believes about the system, check that belief against the real system first.
Treat a surprising win as a bug lead. If an agent wins by passing through a wall or scoring without the chalice, check whether the original allows the same move.
Don’t read a failure as evidence. An agent that never wins may simply be a weak agent. Only a replay that diverges is a clean signal.
Keep determinism intact. The browser’s animation loop varies with the display, so only frame stepping gives repeatable runs.
Check what an agent claims. Confirm every reported problem against a recording or the game state before filing it. The agent’s log is a claim, just like a comment in the code.

Case Study: The Game 3 Freeze

Starting Game 3 would freeze the browser tab. The bug was found by reading code with the first technical heuristic, confirmed by tests rather than in a browser.

The defect was that Game 3 scatters objects by picking a random room and retrying until the room is within that object’s allowed range. The room was picked like this:

let room = Math.floor(random()) * 0x1f;

The random number is always below 1, so rounding it down always gives 0, and every pick was room 0. No object is allowed in room 0, so the retry loop never ended. The original assembly masks a random byte down to the range 0 to 31. The fix scales first and rounds second:

const room = Math.floor(rng() * 0x20);

I literally fixed that bug as I was writing this post so the operative question is why did it survive for so long? Well, the room pick was buried inside a private setup function, so no test could reach it. It also only runs when Game 3 starts, and no existing test drove the game through a level start of any kind.

How would each track have caught it? Well, that’s fairly simple. A tester running the first sample charter would have hit the freeze within seconds of choosing Game 3. A tester applying the range-math heuristic would have spotted it from the single line above, without running anything.

If you check the repo, it’s about four months old at the time of writing. That means if this was a real bug that I had not seeded, it would have been live for four months. Maybe that would have mattered, maybe not. It depends if anyone had tried to play Game level 3.

Taking off my tester role and putting on my developer role, the fix was simple. The room pick became a small function that accepts its random source. Its tests feed it scripted values and give up after a fixed number of calls, so a regression fails quickly instead of hanging the test run. The new tests were confirmed to fail on the old code before the fix went in.

Okay, our trip down adventure lane is probably at an end here, and I did promise an answer key from earlier, so here that is.

Answer Key: Four Changes for Testability

These are the four changes I came up with for the exercise in the Testability section. If you found others, I would genuinely like to hear about them.

Make randomness seedable. random() in the hardware layer calls Math.random directly. A seeded generator would let any Game 3 layout or bat behavior be replayed exactly. Showing the seed somewhere on screen would let a tester report a strange layout that could then be reproduced.
Make input scriptable. Key state lives in private variables set by keyboard events. A test hook that sets the joystick and switches directly, or a mock of the hardware module, would let tests press and release keys on exact frames.
Step frames directly. Tests can call startGame once per frame with no animation loop, as long as drawing and sound are stubbed. The test setup already stubs browser audio.
Expose state for inspection. Object positions are already exported from the object data. The current game state, level and frame count are private, so tests can’t yet check which state the game is in.

As it turned out, building the Game 1 agent did two of these for me. Its headless hardware layer makes input scriptable and lets a test step through frames directly, and the agent’s recording is a scripted playthrough in all but name. Seeding randomness wasn’t needed for Game 1, since it has no randomness, so that one, and exposing the game’s state, are still open.

What Next?

This Adventure may be over, but I don’t think all test adventures are over. In the next post, I’ll show another game I worked on. Prepare yourself to run the gauntlet.

Software Testing & QA Jobs – October 21, 2026 | Daily Job Openings

2026-10-21T15:23:08Z

Software Testing & QA Jobs – October 21, 2026

Position - QC Manager - TSD

Company - Ubisoft

Experience - 8+ years

Location - Pune, Maharashtra