How FinSimLab Authors Country Tax Rules
The source-first workflow behind country models, review gates, implementation checks, and documented limitations.
You may wonder how I added all these countries's tax rules.
I have a reasonable understanding of the Irish and the Agentinian tax systems, having lived in both. But if other countries are as different from each other as these two, there’s no way for me to hand-model more than a couple of countries. It simply doesn’t scale.
So I had two options, if I wanted to make this a reality (and I very much did): hire a large team of finance experts to explain in detail each country’s tax system; or use AI. I was jobless so opton 1 was out the window.
I know, LLMs “hallucinate” every word they say, and sometimes that happens to match reality. So, asking an AI to “model the tax rules for country X and implement them in the simulator” would produce pure garbage. Unless…
So let me explain how I add a new country to the simulator.
Independent research packet
The first step is to get an AI agent to research the country’s tax system and write an official-source citation packet following a template that has a section for each aspect of the tax system, with exact source quotes. This is done without any access or knowledge of the simulator, to avoid any bias. The source quotes are critical because if they match the text found in the source, it proves that the AI actually had to read the document. It’s well known that LLMs make up sources, with likely sounding URLs and everything.Mechanical quote verification
The next step is a mechanical verification of the actual presence of the quoted text in the linked source material. A simple script goes through the list of citations, fetches the cited document, and verifies that the quote is present. Scripts can’t hallucinate. If this gate is passed, the research agent did actually read a real document.Semantic review
A valid quote doesn’t guarantee that a tax rule claimed to come from the quoted document is actually in the document. So now another AI agent goes through the tax rules and the cited documents, one by one, and tries to find proof that the tax rule is not correctly described in the document. LLMs like to please the user. This user is pleased if it finds an issue, a mistake. This kind of adversarial review, while not perfect, works quite well.Targetted addendum
If any of the last two steps produced findings (invalid quotes or unsupported claims), a new research brief is created to correct the mistake. That goes back to step 1, which produces a research addendum, which then goes through steps 2 and 3 again. And if there’s still issues, another round is made. This keeps going until there’s no more issues. In most cases this takes one or two passes.Modeling spec
Now we have a set of tax rules for each aspect of the simulator that has been vetted. Now it’s time to bring in the knowledge about the simulator: what it can model and what it can’t. An AI agent takes the research packet and decides, aspect by aspect, what can be represented directly, what should be approximated, and what is not currently representable by the tax engine. That last part becomes a “gap report” and includes a list of recommendations to expand the tax engine.Ruleset implementation
Another AI agent takes the modeling spec and encodes the country’s tax rules as a structured tax rules configuration file. Part of the research packet was to find worked examples and calculators. Those are then turned into tests and used to validate the implementation. This agent also contributes to the gap report.Economic data
A script then fetches economic figures like inflation, exchange rates, cost of living, rental yield, etc, from sources like the World Bank and Numbeo, and adds that to the country configuration file.Audit
The final gate audits the chain from research packet to modeling spec, from modeling spec to the implemented rules, and from the implemented rules to the gap report. The audit looks for dropped rules, unsupported modeled claims, undocumented approximations, label problems, missing tests, and remaining issues that are better treated as future tax engine improvements, that get added to the gap report.
Each step is performed by a separate AI agent. This helps keep each task smaller, avoiding the issues that come from context overflow and compression. All in all, the whole process can take around two hours.
Do I blindly trust the output of this process? Of course not. I need real people checking the result. Since I can’t hire experts, I let people try it for free if they promise to give me feedback. If they do, they get a year free.