pecunia 0.1.0

A blazing-fast, type-safe CLI for finance and quant formulas.

pecunia

A blazing-fast, type-safe, AI-friendly CLI for finance and quant formulas.

Pecunia (Latin for money — the root of English pecuniary) computes the formulas you reach for every day in finance: enterprise value, free cash flow, discounted cash flow, WACC, returns, ratios. It runs in your terminal, prints clean tables (or structured JSON for piping and agents), and uses decimal.Decimal throughout so you never lose a cent to floating-point rounding.

Built on the modern Astral toolchain — uv, ruff, ty — with strict type checking, 100% formula coverage, and Hypothesis property tests on every invariant.

Status: early alpha. Today: Enterprise Value, Free Cash Flow, schema discovery. The rest of the formula library (DCF, WACC, ratios, returns) is landing next.

Install

uv tool install pecunia

Or run without installing:

uvx pecunia --help

Quickstart

# Enterprise Value
$ pecunia valuation ev --market-cap 500 --total-debt 200 --cash 50
Enterprise Value  650

# Free Cash Flow
$ pecunia cash-flow fcf --operating-cash-flow 100 --capital-expenditures 30
Free Cash Flow  70

Output formats

Every command supports --format / -f:

Format	What you get	Use case
table	Rich-rendered table (default)	Reading in the terminal
json	Structured envelope with command, inputs, result	Agents, pipelines, jq
plain	The bare value, nothing else	x=$(pecunia ... -f plain)

$ pecunia valuation ev --market-cap 500 --total-debt 200 --cash 50 -f json
{"schema_version":"1","command":"valuation.ev","formula":"Enterprise Value",
 "result":{"value":"650","type":"decimal"},
 "inputs":{"market_cap":"500","total_debt":"200","cash":"50",
           "minority_interest":"0","preferred_equity":"0"}}

For AI agents

Pecunia is designed to be driven by LLMs and autonomous agents. See AGENTS.md for the terse machine-oriented spec: JSON schema, exit codes, error envelopes, and the pecunia schema discovery command.

$ pecunia schema | jq '.commands[].path'
["valuation","ev"]
["cash-flow","fcf"]
["schema"]

Development

See CONTRIBUTING.md. Quick version:

git clone https://github.com/nsollazzo/pecunia.git
cd pecunia
uv sync
uv run pre-commit install
uv run pre-commit install --hook-type commit-msg
uv run pytest --cov=pecunia

Security

Please report vulnerabilities privately via GitHub Security Advisories — see SECURITY.md.

License

MIT — see LICENSE.