What Is financial_rigor.py? The AI-Berkshire Financial Validation Toolkit

financial_rigor.py is a zero-dependency Python script in the xbtlin/ai-berkshire repository that enforces exact-decimal arithmetic and programmatic verification of financial data, ensuring every calculation used in investment research is reproducible, traceable, and free from floating-point drift.

The financial_rigor.py tool serves as the central "Financial Rigor Toolkit" for the AI-Berkshire project. Located at /tools/financial_rigor.py, this script eliminates LLM "mental math" by requiring that all numeric outputs pass through a rigorous validation engine before appearing in research reports.

Exact-Decimal Architecture

The toolkit avoids floating-point imprecision by relying exclusively on the Python standard library.

High-precision context – The script initializes a Decimal context (_CTX) at lines 2-9 to handle financial calculations without rounding errors. This context ensures that operations involving stock prices, shares outstanding, and valuation multiples maintain exact precision throughout the computation chain.

Zero-dependency design – By using only decimal, json, math, and argparse, the tool remains portable and deterministic across different environments, removing external library versioning risks from critical financial calculations.

CLI Commands and Verification Functions

The script exposes six primary sub-commands through its command-line interface, each mapped to specific validation functions within the source code.

verify_market_cap: Reconciling Price and Shares

The verify-market-cap command confirms that price × shares matches the reported market capitalization. According to the implementation at lines 61-90, the function calculates the implied market cap and flags any deviation exceeding 5 percent.

python3 tools/financial_rigor.py verify-market-cap \
    --price 510 --shares 9.11e9 --reported 4.65e12 --currency HKD

verify_valuation: Exact Ratio Calculations

The verify-valuation command (implemented in the verify_valuation function) computes PE, PB, ROE, P/FCF, and dividend yield using exact decimals. This prevents the subtle rounding errors that accumulate when calculating valuation multiples across large datasets.

python3 tools/financial_rigor.py verify-valuation \
    --price 510 --eps 23.5 --bvps 120 --fcf-per-share 18 --dividend 2.4

cross_validate: Multi-Source Consensus

The cross-validate command (lines 67-99) takes a JSON dictionary of values from multiple data providers, computes the median consensus, and highlights any source deviating beyond a specified tolerance percentage. This catches data entry errors or stale quotes from different financial APIs.

python3 tools/financial_rigor.py cross-validate \
    --field revenue \
    --values '{"年报": 7518, "Yahoo": 7500, "StockAnalysis": 7520}' \
    --unit 亿

benford_check: Fraud Detection via Benford's Law

The benford command (lines 108-165) implements benford_check to detect possible data fabrication. It compares the leading-digit distribution of a dataset against Benford's expected frequencies, flagging distributions that suggest manual manipulation rather than natural financial data.

python3 tools/financial_rigor.py benford \
    --values '[1234, 2345, 3456, 4567, 5678, 6789, 7890]'

exact_calc: Safe Arithmetic Evaluation

The calc command (lines 88-111) provides exact_calc, which safely evaluates arithmetic expressions with decimal precision. This prevents floating-point drift when computing compound expressions like weighted averages or multi-year growth rates.

python3 tools/financial_rigor.py calc \
    --expr '510 * 9.11e9'

three_scenario_valuation: Projected Target Prices

The three-scenario command (lines 120-166) runs three_scenario_valuation to project EPS growth under optimistic, neutral, and pessimistic scenarios. It then computes target prices using user-specified PE multiples, providing a standardized valuation range for buy/hold/sell decisions.

python3 tools/financial_rigor.py three-scenario \
    --price 510 --eps 23.5 --shares 9.11 \
    --growth 0.15 0.08 0.00 \
    --pe 25 20 15 \
    --years 3 --currency HKD

Integration with Claude-Code Skills

The tool is deliberately invoked from the repository's skill files to enforce data integrity across the AI-Berkshire workflow.

Primary orchestration – skills/investment-research.md at lines 57-83 demonstrates how the toolkit is called automatically after data collection to verify all numeric inputs before generating analysis.

Portfolio reviews – skills/portfolio-review.md utilizes verify-valuation and three-scenario commands to ensure position-sizing calculations are mathematically sound.

Thesis drift protection – skills/thesis-drift.md mandates strict use of financial_rigor.py for all numeric transformations, preventing gradual calculation errors from corrupting investment theses over time.

Output Format and Auditability

All commands produce human-readable and audit-ready outputs. Each result includes clear deviation percentages, consensus values, and calculation summaries formatted for direct inclusion in research reports. This transparency ensures that every figure in an AI-Berkshire report can be traced back to a specific, reproducible command invocation.

Summary

• financial_rigor.py provides exact-decimal validation for all financial data in the AI-Berkshire project, eliminating floating-point errors from investment calculations.
• The toolkit supports six primary verification modes: market-cap reconciliation, valuation ratio calculation, cross-source validation, Benford's Law fraud detection, safe arithmetic evaluation, and three-scenario valuation modeling.
• Located at /tools/financial_rigor.py, the script relies solely on Python's standard library to ensure zero-dependency reproducibility.
• Skills files such as skills/investment-research.md automatically invoke these checks to prevent LLM "mental math" from contaminating research outputs.
• Every function outputs audit-ready results with explicit deviation percentages and consensus values.

Frequently Asked Questions

What is the primary purpose of financial_rigor.py?

financial_rigor.py serves as the computational gatekeeper for the AI-Berkshire project. Its primary purpose is to validate financial calculations using exact-decimal arithmetic, ensuring that metrics like market capitalization, PE ratios, and revenue figures are mathematically accurate before being used in investment research reports.

How does financial_rigor.py prevent calculation errors?

The tool prevents errors by using Python's Decimal class with a high-precision context (_CTX) instead of standard floating-point numbers. This eliminates rounding drift during multiplication and division operations. Additionally, functions like cross_validate compare data across multiple external sources to identify outliers or stale information before it enters the analysis pipeline.

What CLI commands does financial_rigor.py support?

The script supports six sub-commands: verify-market-cap for reconciling share prices with reported market caps; verify-valuation for calculating exact PE, PB, and ROE ratios; cross-validate for multi-source consensus checking; benford for statistical fraud detection; calc for safe arithmetic expression evaluation; and three-scenario for projecting target prices under different growth assumptions.

How is financial_rigor.py integrated into the AI-Berkshire workflow?

According to the project's skill files, financial_rigor.py is called programmatically by Claude-Code skills (specifically in skills/investment-research.md at lines 57-83) immediately after data collection. This integration ensures that no未经核实的 numeric data flows into the analysis phase, enforcing a strict "verify first, analyze second" protocol across all research activities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}