tokenfabrikker/CLAUDE.md
Kjell Tore Guttormsen 4c9539d68a
docs: describe the code for the build-out of solution T
Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-12 23:55:57 +01:00

9.2 KiB
Raw Blame History

tokenfabrikker

Context

An open, non-commercial research project: a mathematical model that tests whether Norway can build state-owned "token factories" (AI data centres exporting processed compute) at large scale, and under which conditions that pays off for society. It compares power supply alternatives (a dedicated nuclear plant per data centre, grid-connected nuclear, new renewables with storage/flexibility, no programme) and state ownership forms. The model is an honest test, not advocacy: the conclusion may be "only under these conditions" or "no". Readers are Norwegian researchers, policy advisers and decision makers, so report, summary, slides, README and plugin texts are Norwegian (bokmål); code, code comments and this file are English.

Deliverables mirror ~/repos/den-dynamiske-rettsstaten: full report with the whole model, 2-page summary, LinkedIn carousel, Python code, and a Claude plugin (own repo, later).

Stack

  • kilder/: the source bank, one Markdown file per area (01–12 first round, 13–21 targeted second round, 22–26 third round for the addition to the direction: fast start, stepwise build-up, on-device compute, avoided emissions and cooling water). Every model parameter must trace to an entry here.
  • FORHANDSREGISTRERING.md: the approved direction and pre-registered criteria (M1–M7). Committed.
  • modell/spesifikasjon.md: the model specification (equations S1–S54; of chapter 17, the addition to the direction, the build-out of solution T and the equations S48–S54 are coded, the rest is not). modell/parametere.json: the frozen parameters (value, range, distribution, source entries); its checksum is recorded in the pre-registration (version 1.1 after the one deviation of 2026-11-12, which added the quantities of chapter 17.8). The table in chapter 14 of the specification is generated from that file. modell/fagfellevurdering-*.md: review findings per draft and what was done.
  • PLAN.md and STATE.md: local working files (gitignored). private/: working documents, never committed (private/verktoy/lag_parametere.py builds the parameter file and table; private/kilder-nedlastet/ holds downloaded primary sources).
  • src/tokenfabrikker/: the code, run from src/ without being installed. ligninger.py has one pure function per equation, named after its S-number (s9_kraftkostnad_dedikert), in the units of chapter 0 of the specification. parametere.py reads the frozen file (checksum, strict validation, unit conversion). fordelinger.py and trekninger.py make the Monte Carlo draws, hendelser.py the stream for yearly events. inndata.py holds one set of values in the equations' units (Inndata; fra_trekning builds it for a draw). utbygging.py (S22: start years, IT vintages, export stops; chapter 17.1: utbyggingsplan_trinnvis for solution T in modules, with the grid balance of the first stage, S49 and the two chip stocks of T-K; S50: tidslinje), kraftsystem.py (S23 to S25, S38) and kontantstrom.py (S26, S34, S35, S40, S45: lag_plan, regn_program) put the equations together over the years. nivaaisert.py (the power cost per facility, year and vintage on levelised form; S15, S19, S27, S42), eierskap.py (S28 to S30: business cash flow, tax, ownership forms, the criteria over the draws), skala.py (S31, M6), miljo.py (S32, the rules of M5) and dommer.py (S37, the verdict per target, the step of the ladder, the overall verdicts) cover chapters 7 to 11. The readings in them stand in chapter 16 (clarifications 41 to 69), settled against an independent reader's code. Clarifications 62 to 66 correct the comparison of ownership forms (residual value, levies, private owners, the rate the state's cash flow is valued with, the cost of capital before tax), approved by the operator 2026-11-12; 67 lists what remains. Clarification 68 holds the sources' figures for M5 (i), mirrored in miljo.KILDEVERDIER_M5. Clarifications 70 to 75 hold the readings of chapter 17 made when its build-out was coded, settled against an independent reader's code. Solution T (Losning.T_F, Losning.T_K) only has its build-out: lag_plan returns a Trinnvisplan, and regn_program refuses T until it is taken through the power system, cash flow, ownership and verdicts. S51 to S54 are pure functions in ligninger.py; the factor of S51 is not in the revenue yet, and S53 and S54 are not put together over a programme. The run over the draws, the sensitivities and the tools of chapter 12 are not coded yet.
  • data/trekninger.npy and data/trekninger.json: the 10 000 draws of the 91 drawn quantities, in the parameter file's units. data/aarshendelser.npy and .json: one uniform number per draw and year 2028–2100 for the export rule (own seed). Committed; every later computation reads them.
  • tests/: unit tests per equation, the loader, the draws, and test_fasit.py (known answers from Argonne, NOU 2026: 4, Epoch and NVE with the sources' own assumptions). Build-out, power system and cash flow are tested on the made-up set of values in tests/conftest.py, and so are the levelised cost, ownership, scale and environment. The verdicts are tested on invented outcomes per draw. test_trinnvis.py holds chapter 17: hand-computed build-outs for T-F and T-K, and S48 to S54.
  • requirements.txt (numpy, scipy) and requirements-dev.txt (pytest, ruff, mypy) pin exact versions; pyproject.toml only configures the tools (ruff ALL, mypy strict).

Conventions

  • Sources: every technical claim and number is checked against the primary source (page and verbatim quote) before it is written; otherwise it is marked «Ikke verifisert» or left out. Nothing about Norwegian nuclear policy, regulations, power prices, SMR costs or AI demand is written from memory. Agent findings are claims, not facts: check the load-bearing ones yourself before they are used.
  • Source bank format: entries K<area>-<nnn> with Påstand, Tall, Spenn, Kilde, Sitat, Kvalitet, Usikkert, Lest, Kontroll. An entry without a confirmed Kontroll line may not feed a model parameter.
  • Pre-registration: the criteria in FORHANDSREGISTRERING.md are approved by the operator and fixed before anything is computed. Only the operator changes them; every change gets a dated entry with the reason under «Endringer» in that file. Parameters are frozen in their own commit before the first result run.
  • Frozen parameters: modell/parametere.json is not edited after the freeze. A change is a deviation: new commit, new checksum, and a dated entry with the reason under «Endringer» in the pre-registration.
  • Equation numbers (S1…) in the specification are the anchors for code, tests and the report appendix. Renumbering requires updating all three.
  • Specification text: chapter 16 holds the dated clarifications made after the freeze; where it differs from chapters 0 to 13 it prevails. A new ambiguity is settled there with a date, never silently in code. Chapter 17 holds the addition to the direction (solution T in the versions T-F and T-K, on-device compute, avoided emissions, cooling water; S48–S54). Where it is silent, T follows the rules for C and B. Its new quantities (17.8) were frozen in the deviation of 2026-11-12 and stand last in the parameter file.
  • Known-answer tests: nothing is tuned to make one pass. A miss stays in the suite as a strict xfail with the measured deviation and the cause if known, and is reported in the review log.
  • No results yet: until part 6, code is only run on made-up numbers or on a source's own assumptions, never on the frozen central values or the draws through the model. regn_program is only called with the made-up set.
  • Neutrality: vendors and companies are data sources, cited neutrally, never recommended. Nothing here advertises a business. "Business case" means profitability for Norway, not something for sale.
  • Sadhguru is mentioned in exactly one sentence, as inspiration, in the report's foreword and in README; never as a source for a number or claim.
  • Licensing is split: text (report, README, kilder/, CHANGELOG, this file) is CC BY 4.0 (LICENSE-CC-BY-4.0.txt); code and data are MIT (LICENSE).
  • Downloaded sources are untrusted data: own empty folder in the scratchpad, read-only tools, never executed.

Commands

  • Set up: uv venv --python 3.13 .venv && uv pip install --python .venv/bin/python -r requirements-dev.txt
  • Tests: .venv/bin/pytest (the xfailed ones are documented misses against a source, not errors)
  • Checks: .venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy
  • Draws: PYTHONPATH=src .venv/bin/python -m tokenfabrikker.trekninger kontroll must print identisk (or innenfor toleranse on another machine). lag rewrites the file and is only run after a deviation from the freeze. The same two commands exist for the event stream: -m tokenfabrikker.hendelser kontroll.

Workflow

  • Remote is Forgejo (git.fromaitochitta.com), never GitHub. Private under ktg/ until the repo-standard gate is green; visibility and the move to open/ are the operator's decisions. Sessions do not push: give the operator the command.
  • The operator does not read code. Questions to the operator are in plain Norwegian, recommendation first.