Skip to content
salvo8519Public

About

Deterministic valuation engine for analysts and AI agents: exact decimal arithmetic, full audit trail. Rust core with Python SDK, CLI, MCP server and function-calling tools.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

160 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
Fairmark — Fair value, hallmarked.

English · Italiano

The deterministic valuation engine for analysts and AI agents.

Your agent reads the documents and writes the report. Fairmark does the math —
exactly, reproducibly, with every step on the record.

CI Docs PyPI Python Crates.io License

MCP ready Function calling Rust core uv Spec-driven

Documentation · Quickstart · Methods · Roadmap · Contributing


Why Fairmark

Language models are excellent at reading financial statements and drafting an investment memo. They are not reliable calculators: a discount factor rounded the wrong way, a terminal value discounted one year too many, a growth rate read as 20 instead of 0.02. In a valuation, those mistakes change the answer — and nobody can tell.

Fairmark splits the job in two:

flowchart LR
    D["Financial statements<br/>business plan"]:::input --> L["LLM<br/>extracts the inputs"]:::llm
    L --> F["Fairmark<br/>computes · explains · fingerprints"]:::engine
    F --> R["LLM<br/>writes the report, citing every step"]:::llm
    classDef input fill:#F7F8FA,stroke:#475569,color:#0B1F3A
    classDef llm fill:#FFFFFF,stroke:#12325C,color:#0B1F3A
    classDef engine fill:#0B1F3A,stroke:#C8A24A,stroke-width:2px,color:#FFFFFF
Loading
Deterministic Exact decimal arithmetic, fixed solvers. Same input, same output, to the last digit, on every platform.
Auditable Every result carries explain: formula, conventions and each intermediate step — ready for a valuation report.
Reproducible Every result carries an input fingerprint; fairmark verify re-runs it bit for bit.
Agent-native One engine for Python, function calling, MCP, the CLI and Agent Skills for Claude Code and Codex.
Built for private companies Inputs come from financial statements and business plans, not tickers. European practice is first-class.
Private by design The engine never touches the network. Your numbers stay on your machine.

Install

uv add fairmark              # or: pip install fairmark
uv add "fairmark[mcp]"       # + MCP server

Prebuilt wheels for Linux (x86_64 and arm64, glibc and musl), macOS (Intel and Apple silicon) and Windows (x86_64): no compiler needed. Requires Python 3.12 or newer.

Quickstart

import fairmark as fm

r = fm.dcf.fcff(
    [fm.dcf.given([100, 110, 120])],   # one stage: FCFF of years 1 to 3
    cash_flow_terms="nominal",
    discount_rate_terms="nominal",
    wacc="0.10",                       # as a decimal fraction
    timing="end_of_period",
    terminal=fm.dcf.gordon("0.02", first_flow="last_flow_grown"),
    net_financial_position={"gross_debt": 200, "cash": 0},
)

r.value_of_operations    # Decimal('1421.4876033057851239669421487')
r.equity_value           # Decimal('1221.4876033057851239669421487')
r.terminal_value_weight  # Decimal('0.8086680761099365750528541226')
for s in r.steps:                # every step, with the numbers substituted
    print(s.label, s.formula, s.value)
Period 1: discount factor            1 / (1 + 0.10)                0.9090909090909090909090909091
Period 1: present value              100 × 0.9090909090909090...   90.909090909090909090909090910
Terminal value: Terminal value at N  122.40 / (0.10 − 0.02)        1530
Value of operations                  271.9759... + 1149.5116...    1421.4876033057851239669421487
Equity value                         1421.4876... − 200            1221.4876033057851239669421487

(excerpt)

Tip. Pass amounts and rates as strings or Decimal for exactness. Floats are accepted and converted through their shortest representation (0.1 → "0.1").

Use it from an AI agent

Function callingMCP server
resp = client.messages.create(
    model="claude-opus-5-5",
    tools=fm.tools.anthropic(),   # or fm.tools.openai()
    messages=messages,
)
for block in resp.content:
    if block.type == "tool_use":
        out = fm.tools.dispatch(block.name, block.input)
{
  "mcpServers": {
    "fairmark": {
      "command": "uvx",
      "args": ["--from", "fairmark[mcp]", "fairmark-mcp"]
    }
  }
}

Any provider — Anthropic, OpenAI, Google Gemini, OpenRouter, LiteLLM, and open-weight models on Ollama, vLLM or LM Studio: fm.tools.for_provider("ollama") returns the right tool format, fm.tools.dispatch executes the call. LangChain tools and MCP over HTTP (for n8n) are included. See LLM providers.

Claude Code, Codex and other coding agents — copy skills/fairmark into your agent's skills folder, or let it drive the CLI:

fairmark methods                                  # what can I compute?
fairmark schema dcf.fcff                          # which inputs, with units?
fairmark run dcf.fcff --input company.json        # JSON in, JSON out
fairmark verify result.json --input company.json  # reproduce a result bit for bit

Note. Tool definitions are generated from the engine's JSON Schemas, so they never drift from the implementation. Invalid inputs come back as {"error": {"code": "FM-E004", …}} so the model can correct its own call.

Methods

Method Status Description
dates.year_fraction Available Year fraction (day count)
dates.schedule Preview Schedule of accrual periods
series.project Preview Value series projected on a timeline
rates.convert Available Rate conversion between compounding conventions
rates.real_nominal Available Real and nominal rates (Fisher)
tvm.npv Available Net present value
tvm.present_value Available Present value with a constant or time-varying rate
tvm.xnpv Available Net present value of dated cash flows (XNPV)
tvm.irr Available Internal rate of return
tvm.xirr Available Internal rate of return of dated cash flows (XIRR)
tvm.mirr Available Modified internal rate of return (MIRR)
tvm.annuity Available Annuity (level or growing, ordinary or due)
tvm.perpetuity Available Perpetuity (level or growing)
tvm.future_value Available Future value of a present amount and level payments
loans.instalment Available Loan instalment (constant instalment, optional balloon)
loans.number_of_instalments Available Number of instalments of a loan
loans.amortisation_schedule Available Amortisation schedule (French, constant principal, bullet)
coc.cost_of_equity Available Cost of equity (CAPM with explicit premia)
coc.beta_relever Available Beta unlevering and relevering
coc.beta_peers Available Beta from comparable companies
coc.cost_of_debt Available Cost of debt
coc.wacc Available Weighted average cost of capital (WACC)
tv.gordon Available Terminal value, stable growth (Gordon)
tv.value_driver Available Terminal value, value driver (growth from reinvestment)
tv.h_model Available Terminal value, H-model (declining growth)
tv.exit_multiple Available Terminal value, exit multiple
tv.limited_horizon Available Terminal value, finite horizon
tv.normalised_income Available Terminal value, capitalised normalised income
tv.liquidation Available Terminal value, liquidation
tv.compare Available Terminal value, comparison of techniques
dcf.fcff Preview DCF — unlevered free cash flow
dcf.fcfe Preview DCF — free cash flow to equity
dcf.free_cash_flows Preview Free cash flow build-up (FCFF and FCFE)
statements.reorganise Preview Financial statements — operating and financing reorganisation
ratios.profitability Preview Ratios — profitability
ratios.capital_structure Preview Ratios — capital structure
ratios.liquidity Preview Ratios — liquidity
ratios.working_capital Preview Ratios — working capital
ratios.debt_service Preview Ratios — debt service
ratios.covenants Preview Ratios — covenants
analysis.goal_seek Available Goal seek
analysis.sensitivity Available Sensitivity table
analysis.scenarios Available Scenario analysis
analysis.tornado Available Tornado

Available: verified independently, with recorded evidence (spec approved, golden cases with sources, numerical audit, code review). Preview: works and is tested; some evidence is still to be recorded. Rule: method status.

What comes next, with its issues and specifications, is in the roadmap, generated from the plan.

Architecture

flowchart TB
    subgraph CORE["fairmark-core · Rust · no I/O"]
        direction LR
        M["Methods<br/>decimal-exact"]:::core --> E["explain + meta<br/>audit trail · input hash"]:::core
        REG["Registry + JSON Schemas<br/>single source of truth"]:::gold
    end
    REG --> PY["Python SDK<br/><code>pip install fairmark</code>"]:::adapter
    REG --> CLI["CLI<br/><code>fairmark run</code>"]:::adapter
    PY --> FC["Function calling<br/>Anthropic · OpenAI"]:::agent
    PY --> MCP["MCP server<br/>local · stdio"]:::agent
    CLI --> SK["Agent Skills<br/>Claude Code · Codex"]:::agent
    REG -.-> N8N["n8n node<br/>on the roadmap"]:::later
    REG -.-> WASM["WASM playground<br/>on the roadmap"]:::later
    classDef core fill:#0B1F3A,stroke:#0B1F3A,color:#FFFFFF
    classDef gold fill:#0B1F3A,stroke:#C8A24A,stroke-width:2px,color:#FFFFFF
    classDef adapter fill:#12325C,stroke:#12325C,color:#FFFFFF
    classDef agent fill:#FFFFFF,stroke:#12325C,color:#0B1F3A
    classDef later fill:#F7F8FA,stroke:#94A3B8,color:#475569,stroke-dasharray:4 4
Loading

One engine, thin adapters. Every channel is generated from the same registry and schemas: a method added to the core is immediately available to Python, the CLI, MCP and every LLM. Details in docs/en/concepts/architecture.md.

The determinism contract

  1. Decimal arithmetic only — no f64 in any calculation path.
  2. Fixed algorithms; tolerances and iteration counts are reported in the result.
  3. No silent defaults: unknown or missing inputs are typed errors with stable codes.
  4. Every result carries meta.input_hash: same hash + same versions = same result.
  5. Any change to a golden result is a reviewed, versioned numerical-change.

Golden cases in tests/golden run against both Rust and Python on every commit. Read the full contract and the project's constitution.

Built in the open, spec-first

Fairmark is developed with spec-driven development and is ready for agentic contributors: every feature starts as a spec with numbered requirements and acceptance criteria (specs/); every acceptance criterion becomes a test; every PR is checked by CI for determinism, schema contracts and golden cases, and reviewed by humans and by AI reviewers with the project's own standards (AGENTS.md).

  • Start with CONTRIBUTING.md and issues labelled good first issue.
  • Valuation professionals are as welcome as developers: a well-sourced test case is a first-class contribution.

License

Apache-2.0. The license covers the code; it grants no rights to use the Fairmark name or logo (Apache-2.0, section 6).

Disclaimer

Fairmark is a calculation tool, not an advisor: it computes, the user decides. Every decision taken with the help of Fairmark, and every use of its results, belongs exclusively to the user, who chooses the method and the inputs, directly or through an AI agent, and verifies the results before relying on them. Fairmark provides no investment, financial, accounting, tax or legal advice, and is provided without warranty of any kind under the Apache License 2.0. Read the full disclaimer.

About

Deterministic valuation engine for analysts and AI agents: exact decimal arithmetic, full audit trail. Rust core with Python SDK, CLI, MCP server and function-calling tools.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages