[#47] tools/report: researcher-grade PDF report generator #51

Merged

robertismo merged 1 commit from 47-report into master

2026-09-29 18:49:40 +00:00

Winnie commented

2026-09-29 18:46:11 +00:00

Owner

What changed

Adds tools/report/, the researcher-grade PDF report pipeline for issue #47 — the release-blocker report Robert can hand to a professional researcher. Consumes the structured iteration log (iterations.json, schema in iterlog.go from #46/#48), git history, and live Forgejo issue data, and renders a reproducible PDF.

The PDF

Title page — title, subtitle, prepared-for/author/date, repository revision, records analysed; provenance banner and optional --note stamp (e.g. synthetic-data warning).
Contents — real page numbers.
Abstract — headline statistics computed from the log (brain-plays per preset, per-brain aggregate wins/win%/avg equity, gauntlet totals, bench-vs totals) plus the research questions.
Methodology — game model (die roll, deposit float, Vickrey loan pricing, bonds, bankruptcy auction, GAAP finance phase); Lisp AI architecture (embedded Lisp, hyphenated API, strategy hooks, the four mains + ten specialists); bench harness and the fixed-seed scheme (g*7919 + len(preset)); and the 13 punishing presets transcribed from bench.go benchPresets().
Results — per-preset mains tables (wins/plays/win%, avg equity, max |equity|), full per-preset per-brain detail for the latest record, specialist gauntlet table (wins/plays/win%/presets-won), bench-vs before/after table with win%-delta, and an iteration-history table over every record.
Key findings — computed sentences only: top brain, preset ownership, gauntlet challengers, bench-vs direction per brain, win-rate trends across records.
Accounting & validation — the equity-change == net-income invariant, plus the schema validation the generator actually runs on the input file (reported as a PASS/FAIL table in the PDF).
Future work — central bank (#15), replay/save-file, churn economy — issue titles fetched live.
Data provenance appendix — generation timestamp, generator version, git history table, fetched-issue table, reproducibility instructions.

No fabricated numbers, ever

Every figure derives from exactly three machine-readable sources: iterations.json, git log, and the Forgejo API. Unknown values render as "—"; schema failures are reported in the validation table and flagged as voiding the findings.

Zero dependencies

Pure Python standard library. The PDF is written by the vendored bwpdf.py (PDF 1.4, flate streams, standard 14 fonts, ruled tables, footers, metadata). No pip, no installs; python3.8+ runs it anywhere.

Verification (no bench run was executed)

Fixture run (testdata/iterations.sample.json, 2 schema-valid synthetic records with real git SHAs for linkage testing): 12 pages, %PDF-1.4 magic, 24,647 chars extracted via pypdf, all expected tokens present; fixture numbers spot-checked in extracted text (e.g. record-2 duel wins 13/47/13/13); rendered pages inspected visually.
Empty-log run (repo's current iterations.json = []): degrades gracefully to a 6-page report stating "no records".
--all-records: 15 pages with full detail for both records.
TOC page numbers cross-checked against actual section pages.

Usage

cd bankwars && python3 tools/report/generate_report.py          # after bench runs
python3 tools/report/generate_report.py --no-api --out r.pdf    # offline
python3 tools/report/generate_report.py     --iterations tools/report/testdata/iterations.sample.json     --note "SYNTHETIC FIXTURE DATA - verification run only"    # fixture check

Full docs in tools/report/README.md.

## What changed Adds `tools/report/`, the researcher-grade PDF report pipeline for issue #47 — the release-blocker report Robert can hand to a professional researcher. Consumes the structured iteration log (`iterations.json`, schema in `iterlog.go` from #46/#48), git history, and live Forgejo issue data, and renders a reproducible PDF. ## The PDF - **Title page** — title, subtitle, prepared-for/author/date, repository revision, records analysed; provenance banner and optional `--note` stamp (e.g. synthetic-data warning). - **Contents** — real page numbers. - **Abstract** — headline statistics computed from the log (brain-plays per preset, per-brain aggregate wins/win%/avg equity, gauntlet totals, bench-vs totals) plus the research questions. - **Methodology** — game model (die roll, deposit float, Vickrey loan pricing, bonds, bankruptcy auction, GAAP finance phase); Lisp AI architecture (embedded Lisp, hyphenated API, strategy hooks, the four mains + ten specialists); bench harness and the fixed-seed scheme (`g*7919 + len(preset)`); and the 13 punishing presets transcribed from `bench.go benchPresets()`. - **Results** — per-preset mains tables (wins/plays/win%, avg equity, max |equity|), full per-preset per-brain detail for the latest record, specialist gauntlet table (wins/plays/win%/presets-won), bench-vs before/after table with win%-delta, and an iteration-history table over every record. - **Key findings** — computed sentences only: top brain, preset ownership, gauntlet challengers, bench-vs direction per brain, win-rate trends across records. - **Accounting & validation** — the equity-change == net-income invariant, plus the schema validation the generator actually runs on the input file (reported as a PASS/FAIL table in the PDF). - **Future work** — central bank (#15), replay/save-file, churn economy — issue titles fetched live. - **Data provenance appendix** — generation timestamp, generator version, git history table, fetched-issue table, reproducibility instructions. ## No fabricated numbers, ever Every figure derives from exactly three machine-readable sources: `iterations.json`, `git log`, and the Forgejo API. Unknown values render as "—"; schema failures are reported in the validation table and flagged as voiding the findings. ## Zero dependencies Pure Python standard library. The PDF is written by the vendored `bwpdf.py` (PDF 1.4, flate streams, standard 14 fonts, ruled tables, footers, metadata). No pip, no installs; python3.8+ runs it anywhere. ## Verification (no bench run was executed) - Fixture run (`testdata/iterations.sample.json`, 2 schema-valid synthetic records with real git SHAs for linkage testing): 12 pages, `%PDF-1.4` magic, 24,647 chars extracted via pypdf, all expected tokens present; fixture numbers spot-checked in extracted text (e.g. record-2 duel wins 13/47/13/13); rendered pages inspected visually. - Empty-log run (repo's current `iterations.json` = `[]`): degrades gracefully to a 6-page report stating "no records". - `--all-records`: 15 pages with full detail for both records. - TOC page numbers cross-checked against actual section pages. ## Usage ```bash cd bankwars && python3 tools/report/generate_report.py # after bench runs python3 tools/report/generate_report.py --no-api --out r.pdf # offline python3 tools/report/generate_report.py --iterations tools/report/testdata/iterations.sample.json --note "SYNTHETIC FIXTURE DATA - verification run only" # fixture check ``` Full docs in `tools/report/README.md`.

Winnie added 1 commit

2026-09-29 18:46:11 +00:00

[#47 ] tools/report: researcher-grade PDF report generator

build / build (push) Successful in 24s

Details

1205ad4d15

Consumes iterations.json (schema: iterlog.go), git history, and Forgejo
issue data to produce a reproducible, researcher-grade PDF report: title
page, abstract, methodology (game model, Lisp AI architecture, bench
harness, fixed seeds, 13 punishing presets), results (per-preset mains,
specialist gauntlet, bench-vs before/after), key findings,
accounting/validation notes, future work (central bank #15, replay, churn
economy), and a data-provenance appendix.

Pure Python standard library - vendored bwpdf.py writer, no pip needed.
Schema-valid synthetic fixture + README with usage and verification.

Winnie requested review from robertismo

2026-09-29 18:46:11 +00:00

Winnie referenced this pull request

2026-09-29 18:46:26 +00:00

[v0.4.0] Research report PDF pipeline #47

Winnie referenced this pull request

2026-09-29 18:46:56 +00:00

AI improvements before v0.4.0 #28