How Does the financial_rigor.py Tool Verify Financial Data in AI-Berkshire?

The financial_rigor.py tool verifies financial data through an exact decimal engine and six specialized verification primitives that validate market caps, valuation multiples, cross-source consensus, and even detect potential data fabrication using Benford's Law.

The financial_rigor.py utility in the xbtlin/ai-berkshire repository is a self-contained Python 3 command-line tool designed to ensure every financial figure entering an AI-Berkshire report is cross-checked, precisely calculated, and reproducibly audited. Understanding how this tool verifies financial data reveals a rigorous three-layer architecture that eliminates floating-point drift and provides audit-ready validation.

The Three-Layer Verification Architecture

The tool's implementation in tools/financial_rigor.py divides its logic into three distinct layers that work together to guarantee numeric integrity.

Exact Decimal Engine

All numeric computations avoid floating-point drift by using Decimal objects with a custom context (_CTX) defined in lines 28-33. This context guarantees 28-digit precision and round-half-even behavior, ensuring that ratio calculations remain exactly reproducible across different execution environments.

Six Verification Primitives

The core functionality resides in six high-level functions, each targeting a specific validation need:

• verify_market_cap – Confirms that price × shares matches a reported market-cap value, computes percentage deviation, and flags out-of-tolerance cases (lines 61-90).
• verify_valuation – Derives common valuation multiples (P/E, P/B, P/FCF, dividend yield, P/S, etc.) from raw inputs, printing each computed ratio and returning a dictionary of results (lines 98-161).
• cross_validate – Takes values from multiple data sources, calculates a median reference, measures each source's deviation, and reports a consensus value with a pass/fail flag based on a tolerance percentage (lines 167-204).
• benford_check – Performs a quick Benford's Law analysis on numeric entries, reporting sample size, MAD (Mean Absolute Deviation), chi-square, and per-digit deviations to spot possible data fabrication (lines 112-182).
• exact_calc – Evaluates arbitrary arithmetic expressions safely using the exact decimal engine, returning the numeric result for downstream scripts (lines 188-213).
• three_scenario_valuation – Projects EPS growth under optimistic, neutral, and pessimistic scenarios, applies target P/E multiples, and returns three target prices with percentage changes from the current price (lines 219-290).

CLI Dispatcher

An argparse sub-command tree defined in main() (lines 66-130) routes user or skill calls to the appropriate verification primitive. The tool is invoked automatically by Claude-Code skills at key checkpoints, though manual execution remains fully supported.

Verification Functions Explained

Each primitive implements specific mathematical checks to validate different aspects of financial data.

Market-Cap Verification

The verify_market_cap function (lines 61-90) accepts price, shares outstanding, and a reported market-cap figure. It calculates the theoretical market cap using exact decimal arithmetic, compares it against the reported value, and flags deviations that exceed tolerance thresholds.

Valuation Multiple Validation

verify_valuation (lines 98-161) computes standard equity valuation metrics. It takes inputs like price, EPS, book value per share, free cash flow per share, and dividend payments, then derives ratios such as P/E, P/B, P/FCF, dividend yield, and P/S.

Cross-Source Consensus

The cross_validate function (lines 167-204) solves the problem of conflicting data sources. It accepts a dictionary of values from multiple providers (e.g., annual reports, Yahoo Finance, StockAnalysis), calculates the median as a reference point, measures each source's deviation from this median, and determines whether the consensus falls within acceptable bounds.

Fraud Detection via Benford's Law

benford_check (lines 112-182) implements statistical fraud detection. It analyzes the distribution of leading digits in a dataset and compares them against Benford's expected logarithmic distribution. High deviations in the chi-square or MAD metrics suggest potential data manipulation or fabrication.

Exact Arithmetic Calculator

exact_calc (lines 188-213) provides a safe evaluation environment for arbitrary mathematical expressions. Unlike standard Python evaluation that might use floating-point arithmetic, this function ensures all operations use the 28-digit precision decimal context.

Three-Scenario Valuation

three_scenario_valuation (lines 219-290) performs forward-looking analysis. It requires current price, EPS, growth rates for three scenarios (optimistic, neutral, pessimistic), corresponding P/E multiples, and a time horizon. It returns projected target prices and percentage upside/downside for each scenario.

Practical Usage Examples

The following commands demonstrate how to invoke the verification primitives from the command line:

Verify a market-cap figure (price = ¥510, shares = 9.11B, reported = 4.65T HKD):

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

Compute valuation multiples for a stock:

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

Cross-validate a revenue figure from three sources:

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

Run a Benford-Law sanity check on cash-flow numbers:

python3 tools/financial_rigor.py benford \
    --values '[123400, 234500, 345600, 456700, 567800, 678900, 789000]'

Perform exact arithmetic calculations:

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

Run three-scenario valuation projections:

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

Summary

• Exact Decimal Arithmetic: All calculations use a custom Decimal context with 28-digit precision to eliminate floating-point errors.
• Six Validation Primitives: The tool provides specialized functions for market-cap verification, valuation metrics, cross-source validation, fraud detection, exact calculation, and scenario analysis.
• Audit-Ready Outputs: Each function returns structured data with deviation metrics and pass/fail flags suitable for automated pipelines.
• Dual Invocation: The tool supports both automated skill-based execution and manual CLI usage via argparse sub-commands.
• Fraud Detection: Built-in Benford's Law analysis provides statistical checks against data fabrication.

Frequently Asked Questions

What precision does financial_rigor.py use for calculations?

The tool uses Python's Decimal class with a custom context (_CTX) configured for 28-digit precision and round-half-even rounding behavior. This configuration, defined in lines 28-33 of tools/financial_rigor.py, ensures that financial ratios and market-cap calculations remain exactly reproducible without floating-point drift.

How does the cross_validate function determine consensus?

cross_validate calculates the median value from all provided data sources as the reference point. It then measures each source's percentage deviation from this median. If the median falls within the specified tolerance percentage, the validation passes; otherwise, it flags the data for review. This approach is implemented in lines 167-204.

What is Benford's Law and how does it detect fraud?

Benford's Law states that in naturally occurring datasets, the digit 1 appears as the leading digit approximately 30% of the time, with decreasing frequency for higher digits. The benford_check function (lines 112-182) compares the actual distribution of leading digits in a dataset against this expected distribution, reporting chi-square and MAD statistics. Significant deviations suggest potential data manipulation or fabrication.

Can I run financial_rigor.py manually or is it automated only?

While the tool is automatically invoked by Claude-Code skills at key checkpoints in the AI-Berkshire pipeline, it is fully designed for manual execution. The argparse sub-command tree in main() (lines 66-130) provides a complete CLI interface, allowing researchers to run individual verification primitives from the command line using standard Python 3.

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