Forge

📌 R&D Prototype — Interpret claims as hypotheses, not proven facts.

Financial models an AI agent can write and a program can calculate.

YAML-based financial modeling with Excel-style formula evaluation. Git-native and deterministic. Beta software: see Status and known limitations.

A raw spreadsheet file is mostly XML. A YAML model is small, readable and diffable.

Status and known limitations

Forge is a beta (v10.0.0-beta.8) and an R&D prototype, built with AI assistance under the author's direction (Claude is listed as a co-author in Cargo.toml). Do not rely on it for real financial decisions without checking the results independently.

Known problems as of 2026-11-04:

• Arithmetic on whole columns inside an aggregate, such as =SUM(a * b), gives wrong results. Compute the product in its own column, then aggregate that column.
• IRR does not report when it fails to converge or when the cash flows have no sign change.
• A table column formula that starts with MAX(, SUM( or similar can be rejected by the schema check. Use an IF(...) form, or put the result in a scalar.
• Tornado and sensitivity inputs need fully qualified names such as assumptions.growth_rate. Short names can fail or give empty results.
• forge export handles simple single-table models. Formulas that reference other sections are not translated correctly yet, and forge import output may not validate.
• Some files in examples/ do not pass forge validate, and forge examples <name> --run fails for monte-carlo, bayesian and breakeven.

The Problem

Size: for one 5-year DCF model, the .xlsx file was about 7× the size of the YAML in bytes (about 19× counting the XML inside it). Token counts were not measured, and an agent that reads only the cells it needs avoids most of this cost.

AI Integration

Any AI coding agent can use Forge — Claude Code, ChatGPT, Gemini, Cursor, Copilot, Aider, or anything that writes files and runs commands:

1. AI writes a YAML model
2. forge calculate model.yaml
3. Deterministic result

That's it. No SDK. No API key. No protocol. Files are the universal interface.

Example: AI Agent Swarm

# You describe the problem to your AI coding assistant
"Model a SaaS acquisition: $10M, 3-year earnout,
 15% growth base case, Monte Carlo on churn risk"

# AI spawns agents, each writes a scenario
├── valuation.yaml      # DCF with earnout structure
├── scenarios.yaml      # Bull/base/bear cases
└── simulation.yaml     # Monte Carlo on churn

# Forge evaluates deterministically
forge calculate valuation.yaml
forge scenarios scenarios.yaml
forge simulate simulation.yaml -n 10000

# Results feed back to AI for synthesis

Results come from the formula evaluator, not from a model's own arithmetic, and each one traces to a formula.

MCP server and REST API available for tighter integration (see below).

Validation status

Forge's results are checked in three ways. None of them is complete yet.

Next steps: compare forge calculate directly with Gnumeric, cover the other analyses against R, and run both suites in CI.

What Excel Can't Do

Forge isn't Excel 2.0. It's a purpose-built FP&A engine with 7 analysis types that a plain spreadsheet does not include:

1. Monte Carlo Simulation

Model uncertainty with probability distributions. Run 10,000+ iterations to get P10/P50/P90 outcomes.

assumptions:
  revenue_growth:
    formula: "=MC.Normal(0.15, 0.05)"  # Mean 15%, StdDev 5%

  project_cost:
    formula: "=MC.Triangular(80000, 100000, 150000)"  # Min/Mode/Max

6 distributions: Normal, Triangular, Uniform, PERT, Lognormal, Discrete

2. Bootstrap Resampling

Generate confidence intervals from historical data without assuming a distribution.

bootstrap:
  iterations: 10000
  confidence_levels: [0.90, 0.95, 0.99]
  data: [0.05, -0.02, 0.08, 0.03, ...]  # Historical returns

Planned cross-check against R's boot package (see forge-e2e-r).

3. Decision Trees

Model sequential decisions with backward induction. Forge finds the optimal path automatically.

decision_tree:
  root:
    type: decision
    name: "Invest in R&D?"
    branches:
      invest:
        cost: 2000000
        next: tech_outcome
      dont_invest:
        value: 0

4. Real Options Analysis

Quantify the value of managerial flexibility using Black-Scholes and binomial methods.

Unit tests check Black-Scholes and binomial prices against QuantLib reference values.

5. Tornado Diagrams

One-at-a-time sensitivity analysis. Instantly see what drives variance.

NPV Sensitivity Analysis (Base: $1.2M)

Revenue Growth    |████████████████████| ± $450K
Discount Rate     |██████████████      | ± $320K
Operating Margin  |██████████          | ± $180K
Tax Rate          |████                | ± $75K

6. Bayesian Networks

Probabilistic graphical models for causal reasoning. Model how risks cascade.

bayesian_network:
  nodes:
    economic_conditions:
      states: ["good", "neutral", "bad"]
      prior: [0.3, 0.5, 0.2]

    default_probability:
      parents: ["economic_conditions", "management_quality"]
      # Conditional probability tables...

A unit test checks a small network against a hand calculation of a pgmpy example.

7. Scenario Analysis

Probability-weighted scenarios with expected value calculation.

scenarios:
  bull_case:
    probability: 0.30
    scalars:
      revenue_growth: 0.25

  bear_case:
    probability: 0.20
    scalars:
      revenue_growth: -0.10

MCP Integration (Optional)

For Claude Desktop or MCP-compatible hosts, Forge exposes 20 tools via Model Context Protocol:

{
  "mcpServers": {
    "forge": {
      "command": "forge",
      "args": ["mcp"]
    }
  }
}

Available Tools

Core (5)

Analysis (5)

Engines (7)

Discovery (3)

All tools accept inline YAML via content parameter — no host filesystem access required. Works with sandboxed clients (Claude.ai, Cursor, containers).

See docs/MCP.md for the full integration guide.

173 Functions

173 functions: most are Excel-compatible, plus 6 FP&A-native functions Excel doesn't have. Not every Excel function is covered; forge functions lists what is.

Run forge functions for full syntax and examples.

FP&A Functions Excel Doesn't Have

Every analyst builds these manually. Forge has them built-in:

# VARIANCE - What Excel makes you do manually
variance_analysis:
  revenue_var: "=VARIANCE(actual.revenue, budget.revenue)"           # Returns: -5000
  revenue_pct: "=VARIANCE_PCT(actual.revenue, budget.revenue)"       # Returns: -5%
  revenue_status: "=VARIANCE_STATUS(actual.revenue, budget.revenue)" # Returns a numeric status code

# BREAKEVEN - Instant unit economics
breakeven:
  units_required: "=BREAKEVEN_UNITS(500000, 150, 60)"     # Returns: 5,556 units
  revenue_required: "=BREAKEVEN_REVENUE(500000, 0.60)"    # Returns: $833,333

Type-aware variance: Costs use inverted logic (under budget = BEAT).

Quick Start

# Install from source (prebuilt binaries are on the Releases page)
cargo install --path .

# Or use the Makefile
make install-forge

# Validate a model
forge validate model.yaml

# Calculate with scenario
forge calculate model.yaml --scenario optimistic

# Export a simple model to Excel (see known limitations)
forge export model.yaml output.xlsx

Example: 5-Year DCF Model

_forge_version: "5.0.0"

assumptions:
  revenue_y1: {value: 1000000, formula: null}
  growth_rate: {value: 0.15, formula: null}
  gross_margin: {value: 0.65, formula: null}
  opex_pct: {value: 0.30, formula: null}
  tax_rate: {value: 0.25, formula: null}
  discount_rate: {value: 0.10, formula: null}

projections:
  year: [1, 2, 3, 4, 5]
  revenue: "=assumptions.revenue_y1 * (1 + assumptions.growth_rate) ^ (year - 1)"
  gross_profit: "=revenue * assumptions.gross_margin"
  opex: "=revenue * assumptions.opex_pct"
  ebit: "=gross_profit - opex"
  tax: "=ebit * assumptions.tax_rate"
  net_income: "=ebit - tax"

valuation:
  total_revenue:
    value: null
    formula: "=SUM(projections.revenue)"
  avg_gross_margin:
    value: null
    formula: "=SUM(projections.gross_profit) / SUM(projections.revenue)"
  npv_cash_flows:
    value: null
    formula: "=NPV(assumptions.discount_rate, projections.net_income)"

scenarios:
  base:
    growth_rate: 0.15
  bull:
    growth_rate: 0.25
    gross_margin: 0.70
  bear:
    growth_rate: 0.05
    gross_margin: 0.55

forge calculate model.yaml --dry-run                  # preview results without writing the file
forge calculate model.yaml --scenario bull --dry-run
forge sensitivity model.yaml -v assumptions.growth_rate -r 0.05,0.30,0.05 -o valuation.npv_cash_flows

Without --dry-run, forge calculate writes the results back into the file and keeps a .bak copy.

Commands

# Core Operations
forge validate <files...>           # Validate YAML model(s)
forge calculate <file>              # Execute all formulas
forge audit <file> <variable>       # Trace formula dependencies

# Analysis
forge sensitivity <file> -v VAR -r RANGE -o OUTPUT
forge goal-seek <file> --target VAR --value N --vary INPUT
forge break-even <file> -o OUTPUT -v INPUT
forge variance <budget> <actual> --threshold PCT

# Prediction & Simulation
forge simulate <file> --iterations N    # Monte Carlo
forge scenarios <file>                  # Scenario analysis
forge decision-tree <file>              # Decision trees
forge real-options <file>               # Real options
forge tornado <file>                    # Tornado diagrams
forge bootstrap <file>                  # Bootstrap resampling

# Excel Bridge
forge export <yaml> <xlsx>          # YAML → Excel with formulas
forge import <xlsx> <yaml>          # Excel → YAML

# AI Integration
forge mcp                           # Start MCP server
forge serve --port 8080             # Start REST API

# Reference
forge functions                     # List all 173 functions
forge schema v5                     # Show JSON schema
forge examples monte-carlo          # Show example YAML

Documentation Commands

# View JSON schemas for model validation
forge schema                    # List available versions
forge schema v1                 # Show v1.0.0 schema (scalar-only)
forge schema v5                 # Show v5.0.0 schema (full features)
forge schema v5 > schema.json   # Pipe to file for IDE use

# View runnable examples for Forge capabilities
forge examples                  # List all examples
forge examples monte-carlo      # Monte Carlo simulation
forge examples scenarios        # Probability-weighted scenarios
forge examples decision-tree    # Sequential decision modeling
forge examples real-options     # Option pricing for flexibility
forge examples tornado          # Sensitivity analysis
forge examples bootstrap        # Confidence intervals
forge examples bayesian         # Probabilistic graphical models
forge examples variance         # Budget vs actual analysis
forge examples breakeven        # Break-even calculations

forge examples monte-carlo --run  # Show and execute example
forge examples --json             # Machine-readable list

Intended use

Forge is new and there is no adoption data yet. These are the uses it is designed for:

Quality Assurance

Test Architecture

forge (this repo)             validation repos
├── 1,366 unit tests          ├── forge-e2e-gnumeric: 1,301 formula specs
├── #[cfg(test)] modules      └── forge-e2e-r: 77 specs (10 run live)
└── 2 doctests

Documentation

Development

cargo test                              # Run all tests
cargo clippy -- -D warnings             # Lint (pedantic)
make check                              # Full CI check

License

Licensed under either of

• Apache License, Version 2.0
• MIT License

at your option.

This is the standard dual-license used by the Rust ecosystem (rustc, Tokio, Serde, etc.).

Built with Asimov - The AI autonomy framework.