📊 FinLang Benchmarks

Applies to: FinLang v0.7.7+
Status: Reference
Last verified: v0.7.7 (11 April 2026)

This guide presents validated benchmark data for FinLang v0.7.7, tested on a real developer workstation.

⚙️ Test Environment

• CPU: Intel i7‑12700T (12th Gen)
• RAM: 48 GB
• OS: Windows 11 (64‑bit)
• Python: 3.13.7 (64‑bit)
• Backend: FastIO (PyArrow 21.0.0)
• FinLang: 0.7.7 (installed from PyPI)

Your absolute numbers may differ based on CPU, storage, and OS. Focus on shape (linear scaling) and relative performance.

🚀 v0.7.7 Performance Highlights

v0.7.7 contains a hot-path bug fix in _to_number (the function that runs on every amount value). The CR/DR detection regex contained an unnecessary \b word boundary that was both:

1. Producing wrong results on no-space CR/DR formats like 200DR (silently emitting +200 instead of -200, latent since v0.6.4)
2. Costing measurable runtime by forcing per-character boundary assertions on every regex evaluation

Removing the \b aligned the detection regex with its sibling stripping regex (which never had \b and worked correctly). The fix is a single character change. The performance gain is a direct side effect.

Headline numbers:

• Standard mode: ~180K rows/sec (steady-state from 5M rows upwards)
• FastIO mode: ~217K rows/sec at 20M rows
• 20M rows in ~90 seconds (FastIO), full field-by-field SHA-256 verified
• +30-50% throughput improvement vs v0.7.6 on the integrity harness

🧪 Benchmark Harnesses

1) Single Ruleset Harness — scaling across Rows × Cols

Evaluates performance for a single static ruleset over a grid of dataset sizes and column widths.

python -m benchmarks.bench_finlang_harness `
  --mode full-cli `
  --run-fin "finlang --fastio --audit-mode none --headless" `
  --rules examples/rules.demo.fin `
  --include-pack retail,transport,subs `
  --rows 25000 50000 100000 200000 `
  --cols 5 20 35 50 `
  --runs 3 `
  --final-rows 1000000 5000000 `
  --outdir bench_out_v077

Outputs:

• bench_surface.png — 3D runtime surface
• bench_heatmap.png — runtime heatmap
• bench_results.csv — raw timings (averaged over 3 runs)
• bench_big.csv — finals (1M and 5M rows)

2) Ruleset Comparison Harness — small vs medium vs large rules

Measures runtime impact of ruleset size/complexity.

python -m benchmarks.bench_finlang_rulesets `
  --run-fin "finlang --fastio --audit-mode none --headless" `
  --rules-set Small:examples/rules.demo.fin `
  --rules-set Medium:src/finlang/rulepacks/01-vendors-retail.fin `
  --rules-set Large:src/finlang/rulepacks/03-subscriptions.fin `
  --include-pack transport `
  --grid-rows 25000 50000 100000 200000 `
  --grid-cols 5 20 35 50 `
  --repeats 3 `
  --final-rows 1000000 5000000 `
  --outdir bench_out_rulesets_v077

Outputs:

• heatmap_Small.png, heatmap_Medium.png, heatmap_Large.png
• results_all.csv, finales.csv

3) Integrity Test — cryptographic verification at scale

Validates data integrity with SHA-256 fingerprinting. Proves zero data corruption or cross-row contamination.

# Default: 5K rows, fingerprint-only (daily use)
python integrity_testv2.py

# Full validation: field-by-field + fingerprint
python integrity_testv2.py --full

# Scale testing
python integrity_testv2.py --rows 20000000 --full

# Generate annotated proof CSV (demo/audit collateral)
python integrity_testv2.py --rows 500000 --full --proof

What it proves:

• Row count preserved (no dropped/duplicated rows)
• Immutable fields unchanged (date, amount, counterparty)
• SHA-256 fingerprint per row validates no cross-row contamination
• Both code paths (standard + PyArrow) produce identical results

📈 Validated Results (v0.7.7)

Single Ruleset Performance — Grid (3-run average)

Single Ruleset Performance — Finals (3-run average)

Ruleset Comparison (5M × 50)

Key finding: ~1.2% variance across rulesets — rule complexity has negligible impact at scale.

All three rulesets land within ~2 seconds of each other at the 5M × 50 extreme. The engine's hot path is ruleset-shape-independent at scale.

🔐 Integrity Test Results (v0.7.7)

Cryptographic verification using SHA-256 fingerprints on every row.

Performance by Scale

20M Row Validation — Full Output

=== FinLang Data Integrity Test (Python) ===
  Row count: 20,000,000
  Validation mode: Full (field-by-field + fingerprint)
  PyArrow available: Yes
  Proof output: No
[1/6] Generating 20,000,000 test rows with fingerprints... OK (1.2m)
[2/6] Creating test rules... OK
       Loading input data for validation... OK (20.9s)
[3/6] Running FinLang engine (standard)... OK (1.8m, 181,566 rows/s)
[4/6] Validating integrity (standard, full)... OK (20,000,000 categorized, 5.9m)
[5/6] Running FinLang engine (--fastio)... OK (1.5m, 217,068 rows/s)
[6/6] Validating integrity (--fastio, full)... OK (20,000,000 categorized, 5.9m)
=== Integrity Test PASSED ===
  Rows tested: 20,000,000
  Immutable fields verified: date, amount, counterparty
  Fingerprints validated: 20,000,000 (no cross-row contamination)
  Validation mode: Full (field-by-field + fingerprint)
  Standard mode: PASS (181,566 rows/s)
  FastIO mode:   PASS (217,068 rows/s)

Why Integrity Test Shows Higher Throughput

The integrity test uses a minimal 6-column schema (date, amount, counterparty, memo, category, fingerprint) versus the benchmark harness's 50-column enterprise schema.

This is expected: narrower data = less I/O, less memory pressure, faster processing. Both numbers are valid for their respective use cases. The integrity test isolates engine performance from CSV I/O overhead; the enterprise harness measures real-world end-to-end throughput.

📊 Version Comparison

Integrity Harness (FastIO, full validation)

Single Ruleset Harness (5M × 50)

Cumulative gain v0.6.4 → v0.7.7: -14% runtime, +16% throughput on the enterprise harness.

What Changed in v0.7.7

The improvement is dominated by a single hot-path fix in _to_number:

# v0.6.4 - v0.7.6 (broken on no-space CR/DR formats)
r'\b(?:CR|CRED|CREDIT)\b\.?\s*$'

# v0.7.7 (correct)
r'(?:CR|CRED|CREDIT)\.?\s*$'

The \b word boundary was inconsistent with the sibling stripping regex (which never had \b), causing 200DR to be silently parsed as +200 instead of -200. Removing it:

• Fixed the correctness bug
• Removed per-character boundary assertions from a regex evaluated tens of millions of times per dataset
• Delivered 30-50% throughput improvement on the integrity harness

The performance gain is a direct side effect of the bug fix, not a separate optimisation.

🖼️ Visual Results

Visualization	Description
	3D runtime surface (Rows × Cols)
	Runtime heatmap (Rows × Cols)
	Ruleset comparison — Small
	Ruleset comparison — Medium
	Ruleset comparison — Large

🔬 Methodology Notes

• 3 runs per point, average reported to smooth variance
• Warm runs (Chrome closed, system idle)
• --audit-mode none to measure engine speed (no audit overhead)
• PyArrow (--fastio) enabled for CSV I/O
• Deterministic data generation, reproducible CLI scripts
• All v0.7.7 runs from PyPI-installed package (pip install "finlang[fastio]")
• Run-to-run variance under 1.5% on the 5M × 50 finale (179.27s averaged across 3 runs)

💡 Practical Interpretation

Rule of thumb: FinLang scales linearly — doubling rows ≈ doubling runtime; increasing columns raises evaluation cost predictably.

🧩 Troubleshooting

📚 Related Documentation

• CLI Reference — Complete command reference
• Runtime Contract — Backend selection logic
• Flags — Full CLI flags and canonical formats
• Workflows — End‑to‑end workflow guide
• Release Notes v0.7.7 — Bug fix and performance details