fin123
fin123.dev

The operating standard for financial models

Financial models should behave like software.

fin123 compiles spreadsheet models into deterministic, verifiable artifacts that applications and teams can execute reliably.

View Core on GitHub View Examples Request a walkthrough
Deterministic build + verify Batch scenario sweeps Finance-safe joins and lookups Governed AI artifacts Team registry + runner (Pod)
valuation_review.yaml 
columns:
  - source: ticker
  - source: price
  - source: estimate
  - name: upside_pct
    expression: (estimate - price) / price

flags:
  - name: high_upside
    expression: upside_pct > 0.15

Worksheet specification compiled into a portable artifact.

worksheet viewer · valuation_review

The calculations live in the worksheet — not your application code.

How fin123 works

fin123 separates model authoring, model execution, and model delivery.

execution model 
Spreadsheet (workbook.yaml)
        |
        |  fin123 build
        v
Build Outputs (scalars + tables)
        |
        |  fin123 worksheet compile
        v
Compiled Worksheet Artifact (immutable JSON)
        |
        v
Applications / dashboards / reports

Spreadsheet = model authoring

A YAML workbook with explicit parameters, formulas, table plans, and assertions. This is where the financial logic lives. Built deterministically from local files — no database, no network calls.

Worksheet = structured view of model output

A declarative YAML spec that projects build results into derived columns, display formats, sorts, and flags. This is what analysts define. Compiled at build time, not reimplemented in application code.

Compiled worksheet artifact = what applications consume

An immutable JSON file with full provenance and a deterministic content hash. Applications embed, serve, or verify the artifact directly. The calculations live in the worksheet — not your code.

One system, three products

Local authoring → embedded execution → hosted delivery.

1. Standalone spreadsheet runtime

Author and execute finance-grade models locally. Deterministic builds, immutable versioning, headless batch execution. No server required.

fin123-core · open source · Apache-2.0

2. Embeddable worksheet runtime

Compile model outputs into structured worksheet artifacts. Applications render the compiled result instead of reimplementing spreadsheet logic.

fin123-core · open source · Apache-2.0

3. Hosted worksheet platform

Publish, govern, and serve worksheet artifacts from a central registry. Applications fetch released artifacts over an API.

fin123-pod · requires license

Get started

1. Explore the examples

fin123-examples walks through three finance use cases: DCF valuation, earnings review worksheets, and batch sensitivity sweeps.

2. Understand the architecture

Read the execution model above or the full architecture doc to see how spreadsheets become compiled artifacts.

3. Install fin123-core

Standalone binaries (no Python required): macOS arm64 · Windows x86_64

source install + first build 
git clone https://github.com/reckoning-machines/fin123-core.git
cd fin123-core && pip install -e ".[dev]"

fin123 init demo --template demo_fin123
fin123 build demo
fin123 ui demo

Examples

DCF Valuation

Finance-native model authoring. Scalar formula DAG with NPV(), explicit parameters, assertions, and named scenarios.

Concept: how fin123 evaluates a financial model deterministically.

Earnings Review Worksheet

Worksheet as structured output view. Quarterly results with derived metrics, display formatting, and row-level flags compiled into a portable artifact.

Concept: how build outputs become artifacts applications can render.

Sensitivity Sweep

Deterministic batch execution. The same model runs across a 9-scenario parameter matrix with structurally comparable, verifiable outputs.

Concept: how fin123 runs one model across many assumptions reproducibly.

All examples: fin123-examples on GitHub

Why fin123

Finance teams should not have to reimplement spreadsheet logic in application code. fin123 compiles it into artifacts instead.

Software lifecycle for models

Commit → build → verify → release. Explicit parameters, named scenarios, immutable versioning. No hidden cell edits.

Columnar execution engine

Table computations compile as Polars LazyFrame plans and execute against real datasets. Faster than recalculating spreadsheets.

Headless batch execution

The same committed model runs across tickers, scenarios, and parameter sets without someone sitting in front of a spreadsheet.

Finance-safe joins and lookups

join_left defaults to many_to_one — silent row multiplication is rejected. lookup_scalar errors on missing or duplicate keys.

Deterministic and verifiable

Builds run offline against local files. Every output is fingerprinted. fin123 verify detects post-build tampering.

lifecycle 
fin123 commit  -> immutable snapshots
fin123 build   -> deterministic outputs + hashes
fin123 verify  -> drift detection
fin123 release -> approved, governed artifacts

Hosted platform — fin123-pod

Shared state, automation, and governance for teams. Extends fin123-core with Postgres-backed infrastructure.

Worksheet registry and governance

Teams publish compiled worksheet artifacts to a shared Postgres registry. Artifacts are versioned, reviewed, and promoted through approval stages. Applications consume released artifacts from the registry instead of reimplementing spreadsheet logic.

registry preview 
Worksheet Lifecycle
Authoring -> Compile -> Draft -> Approved -> Released -> Alias -> Application

Latest activity:
revenue_summary v0005 compiled
revenue_summary v0004 released
production alias -> v0004

Worksheet: revenue_summary
v0005   draft      approve
v0004   released   archive
v0003   archived

Shared registry and runner

SQL sync pulls Postgres tables into local parquet caches with provenance. Bloomberg and plugin connectors bring vendor data into the same governed sync path. A Postgres-backed registry stores model versions, builds, and releases. The headless runner executes models by (model_id, model_version_id) with parameter overrides.

Production mode governance

Builds can be blocked on import parse errors, missing SQL schema guards, missing plugin pins, or an unreachable registry. Releases are gated on verify pass. Assertions with severity error hard-fail builds.

Contact for access
Pod is closed source. It depends on fin123-core (open source) and adds enterprise capabilities. The core engine works fully standalone without Pod. Contact us for licensing.