FinLang — The Financial Rules Engine

Deterministic. Auditable. Global.
Designed for explainable processing in regulated environments.

🌐 Overview

FinLang is a domain-specific language (DSL) and vectorised CLI engine for financial transaction processing.
It replaces opaque machine-learning categorization with transparent, deterministic rules — delivering explainability, auditability, and global compatibility.

Built for audit-friendly logic and deterministic processing.
A deterministic alternative where explainability and reproducibility matter.

What this is for

FinLang is a deterministic rules engine for financial transaction categorisation.

It is especially useful as a challenge layer alongside ML categorisers: the --reconcile workflow compares FinLang's rule-attributed output against an external classification, row by row.

Same input + same rules = reproducible output, with rule-attributed audit trails.

The v0.7.9 FastAPI wrapper makes the same engine reachable over a self-hosted HTTP surface for service/integration workflows; the v0.9.0 Workbench puts it in a local browser.

Four surfaces. One engine:

• Workbench — a local browser interface via finlang-ui (served from 127.0.0.1 only)
• CLI for batch processing
• Python workflows via subprocess-isolated CLI execution
• Self-hosted HTTP wrapper via finlang-api

📝 The FinLang DSL

FinLang rules are human-readable, Git-friendly, and designed for precision.
The engine processes rules top-to-bottom; the last matching rule sets the category, while flags accumulate.

# Example: Basic categorization and flagging
rule "GROCERIES: Tesco" {
  match:
    - counterparty ~ "*TESCO*"
  set:
    - category = "Groceries"
    - flags += "Supermarket"
}

# Example: Numeric range and exact match
rule "TRAVEL: High Value Flight" {
  match:
    - counterparty == "BRITISH AIRWAYS"
    - amount in -5000.00 .. -500.00
  set:
    - category = "Travel"
    - flags += "HighValue"
}

⚙️ Key Features (v0.9.1)

📦 Installation

Requirements: Python 3.10—3.14

From PyPI (Recommended):

pip install finlang

With Fast I/O (PyArrow):

pip install "finlang[fastio]"

(Enables --fastio for accelerated CSV I/O.)

The Workbench (local browser UI):

finlang-ui     # serves 127.0.0.1:8484 and opens your browser

(In the base install — no extras needed. See docs/workbench.md.)

HTTP API wrapper:

finlang-api    # binds 127.0.0.1:8000 — interactive docs at /docs

(Thin FastAPI wrapper over the CLI for HTTP-based integration and demos. In the base install since v0.9.0 — pip install "finlang[api]" remains valid as a no-op. See docs/api.md.)

From Source (Development):

git clone https://github.com/FinLang-Ltd/finlang.git
cd finlang
pip install -e .[fastio]

🚀 Quick Start — The 5-Step Growth Loop

1️⃣ Initial Categorization

finlang --input transactions.csv --output baseline.csv \
  --rules my_rules.fin --include-pack retail,transport

2️⃣ Discover Gaps

finlang-discover --input baseline.csv \
  --candidates candidates.csv --all-candidates all_candidates.csv \
  --min-count 5

3️⃣ Suggest Rules (Exact Mode Recommended)

finlang-suggest --input candidates.csv --output suggested_rules.fin \
  --rules my_rules.fin --emit-match exact

4️⃣ Merge and Re-run

cat my_rules.fin suggested_rules.fin > merged.fin
finlang --input transactions.csv --output improved.csv \
  --rules merged.fin --include-pack retail,transport

✅ Expected Result: 5–10% coverage improvement; zero duplicates in exact mode.

📊 Performance Benchmarks (v0.7.7)

Measured with --audit-mode none (max throughput) on Intel i7-12700T, 48GB RAM, Windows 11, Python 3.13.7, PyArrow 21.0.

v0.7.7 improvement: Hot-path bug fix in _to_number removed an unnecessary \b word boundary that was both producing wrong results on no-space CR/DR formats AND costing measurable runtime. The fix delivered +30-50% throughput on the integrity harness vs v0.7.6, taking standard mode to ~180K rows/sec and FastIO to ~217K rows/sec.

Cumulative v0.6.4 → v0.7.7: -14% runtime, +16% throughput on the enterprise harness (5M × 50).

Audit Overhead: Enabling --audit-mode lite/full reduces throughput by ≈38% due to diff calculation; provides full decision provenance.

Note: These figures are validated benchmark results from controlled tests. Actual performance varies depending on dataset, ruleset, and audit mode.
See docs/benchmarks.md for full details.

🔐 Integrity Verification (v0.7.7+)

SHA-256 fingerprint verification benchmarked on large datasets:

What this benchmark validated: Every row's immutable fields (date, amount, counterparty) were verified via SHA-256 hash before and after engine processing. Zero cross-row contamination detected. Zero data corruption detected. 60M rows verified field-by-field across three runs, zero mismatches.

Note: As of v0.7.7, SHA-256 integrity verification is available as a CLI feature via --verify (fast fingerprint) and --verify-full (fingerprint + field comparison). Use --verify-output-dir to save audit artifacts (JSON report + proof CSV). See docs/cli_reference.md for details.

🌍 Internationalization Matrix

Auto-Detection and Normalization: BOM-safe UTF-8 encodings, , ; | \t delimiters, and automatic currency symbol stripping.

🧠 The Growth Loop Explained

Discover → Suggest → Categorize → Repeat

FinLang's Growth Loop accelerates rule creation through data-driven discovery.

• Discover uncategorized counterparties
• Suggest new rules in seconds (1:1 mapping in exact mode)
• Merge + Re-run for incremental coverage gains
• Validated Result: 97.8% average coverage gain across 5 runs (source)

📄 See: docs/growth_loop_best_practices.md

🧾 Known Limitations (v0.7.x)

• ⚠️ --emit-match fuzzy (default) filters corporate stopwords (LTD, LLC, PLC, INC, GROUP, COMPANY, CO, SAS, GMBH, CORP) and deduplicates patterns within a batch (v0.7.7). Edge cases with very short counterparty names may still produce broad patterns. → Use --emit-match exact for production workflows.
• ⚠️ Hyphenated/apostrophe names may affect fuzzy matching (< 1% impact).
• ⚠️ No support for non-Gregorian calendars or non-Western numerals.

📘 Documentation

• docs/release_notes/v0_9_0.md — the Workbench (finlang-ui), one-install dependencies, /process verify status change
• docs/release_notes/v0_7_9.md — FastAPI wrapper (finlang-api), three surfaces / one engine
• docs/release_notes/v0_7_8.md
• docs/release_notes/v0_7_7.md
• docs/release_notes/v0_7_6.md
• docs/workbench.md — the Workbench local browser UI (finlang-ui, v0.9.0)
• docs/reconciliation.md — --reconcile ML validation layer (v0.7.8)
• docs/verify.md — --verify integrity verification
• docs/api.md — FastAPI wrapper (finlang-api; base install since v0.9.0)
• docs/api_reference.md — full API endpoint reference
• docs/runtime_contract.md
• docs/cli_reference.md
• docs/rulepacks.md
• docs/benchmarks.md
• docs/growth_loop_best_practices.md
• docs/amount_synthesis.md
• docs/i18n_examples.md
• docs/stateless_processing.md

Command-line help:

finlang --help
finlang-discover --help
finlang-suggest --help

🧩 Example CLI Usage

finlang --input bank.csv --output categorized.csv \
  --rules examples/rules.demo.fin \
  --include-pack retail,transport,subs \
  --fastio --audit audit_log.json --audit-mode lite

📜 License & Commercial Use

FinLang is open source under the GNU Affero General Public License (AGPL-3.0).
Commercial licenses and enterprise support are available via FinLang Ltd.

📧 info@finlang.io
🌐 https://finlang.io

Contributing

Contributions are welcome! Before submitting a PR, please review and accept our Contributor Licence Agreement (CLA).

📌 Version Summary