Financial Rigor Tools in AI Berkshire: A Complete Guide to Deterministic Validation

AI Berkshire provides a self-contained Financial Rigor Toolkit in tools/financial_rigor.py that delivers deterministic, exact-decimal financial validation through six command-line utilities including market-cap verification, valuation ratio calculation, cross-validation, Benford's Law analysis, exact arithmetic, and three-scenario projection.

AI Berkshire ships with a comprehensive Financial Rigor Toolkit designed to eliminate floating-point drift in financial analysis. This pure-Python command-line utility, located at tools/financial_rigor.py, provides deterministic validation helpers that safeguard the quantitative backbone of investment research. The toolkit operates without external dependencies, making it immediately deployable in any Python environment.

The Exact-Decimal Architecture

The foundation of AI Berkshire's financial rigor rests on an Exact-Decimal Engine that eliminates floating-point precision errors. At line 31 of tools/financial_rigor.py, the helper function exact() coerces any numeric input—whether float, string, or Decimal—into a canonical Decimal type under a fixed-precision context _CTX.

This approach ensures that all arithmetic operations remain deterministic and auditable. Unlike standard floating-point calculations that accumulate rounding errors, the exact() function maintains precision throughout complex financial calculations, providing the reliability required for investment-grade analysis.

Human-Readable Output Formatting

Financial data requires clear presentation for both automated systems and human review. The fmt_number() function at line 40 automatically scales large numbers into culturally appropriate units, including Chinese financial notation (亿 for hundred-million, 万亿 for trillion) alongside standard Western suffixes (M, B, T).

This dual-formatting capability ensures that output remains legible across different reporting contexts while maintaining the underlying exact-decimal precision in all calculations.

The Six Financial Rigor Commands

The toolkit implements an argparse sub-command dispatcher at lines 66-78 that maps six top-level commands to pure-Python validation functions. Each command produces standardized output with section dividers and clear ✅/⚠️/❌ status indicators suitable for automated consumption by Claude Code skills.

Market-Cap Verification

The verify-market-cap command validates that price × shares matches a reported market capitalization, flagging deviations greater than 5%. Implemented in verify_market_cap() at line 61, this tool catches discrepancies between calculated and reported valuations that might indicate data entry errors or split-adjustment issues.

Valuation Ratio Analysis

The verify-valuation command computes exact-decimal versions of key valuation metrics including PE ratio, PB ratio, P/FCF, and dividend yield. The verify_valuation() function at line 98 performs these calculations using the exact-decimal engine, eliminating the rounding errors common in spreadsheet-based financial modeling.

Cross-Validation Consensus

When financial data comes from multiple sources, the cross-validate command identifies discrepancies and calculates consensus values. Implemented in cross_validate() at line 167, this tool reports median-based consensus values and per-source deviations, helping analysts identify outlier data points in financial statements sourced from different providers.

Benford's Law Fraud Detection

The benford command applies Benford's Law to lists of financial numbers to detect anomalous digit distributions that may indicate manipulation or data quality issues. The benford_check() function at line 214 analyzes the first-digit frequency distribution of numerical datasets, flagging deviations from the expected logarithmic distribution that naturally occurs in authentic financial data.

Exact Arithmetic Calculator

For ad-hoc calculations requiring precision, the calc command provides a safe exact calculator for arbitrary arithmetic expressions. The exact_calc() function at line 286 handles addition, subtraction, multiplication, and division while maintaining decimal precision, serving as a reliable alternative to standard floating-point calculators.

Three-Scenario Valuation

The three-scenario command projects EPS and target prices under optimistic, neutral, and pessimistic growth assumptions. Implemented in three_scenario_valuation() at line 316, this tool accepts varying growth rates and PE multiples for each scenario, generating comparable valuation ranges that support probabilistic investment theses.

Integration and Usage Examples

The Financial Rigor Toolkit integrates seamlessly with AI Berkshire's research workflow. Below are practical examples demonstrating each sub-command:

# Verify market cap calculation against reported value

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

# Calculate exact valuation ratios

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

# Cross-validate revenue figures from multiple sources

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

# Apply Benford's Law analysis to financial series

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

# Perform exact arithmetic calculation

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

# Generate 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.0 \
    --pe 25 20 15 \
    --years 3 \
    --currency HKD

Supporting Infrastructure

The financial rigor layer extends beyond the core toolkit through additional integration files:

• tools/report_audit.py – Example consumer that orchestrates the toolkit as part of comprehensive research-report validation workflows
• AGENTS.md – Project documentation describing how Claude Code skills invoke the toolkit for automated financial verification

These files demonstrate how the deterministic validation layer integrates into AI Berkshire's broader quantitative research methodology.

Summary

• AI Berkshire's Financial Rigor Toolkit resides in tools/financial_rigor.py as a zero-dependency command-line utility
• Exact-decimal arithmetic via the exact() function and _CTX context eliminates floating-point drift in all calculations
• Six validation commands cover market-cap verification, valuation ratios, cross-validation, Benford's Law analysis, exact arithmetic, and scenario modeling
• Human-readable formatting supports both Chinese (亿, 万亿) and Western (M, B, T) numeric notation
• Standardized output with clear status symbols (✅/⚠️/❌) enables automated consumption by downstream AI skills

Frequently Asked Questions

What makes AI Berkshire's financial calculations deterministic?

The toolkit uses Python's decimal.Decimal type under a fixed-precision context (_CTX) rather than floating-point numbers. The exact() function at line 31 normalizes all inputs to this exact-decimal format, ensuring that operations like multiplication and division produce identical results across all runs, eliminating the rounding errors inherent in IEEE 754 floating-point arithmetic.

How does the cross-validation tool handle conflicting data sources?

The cross_validate() function calculates the median value across all provided sources and reports each source's deviation from this consensus. It accepts JSON-formatted inputs mapping source names to values, then outputs both the median consensus and per-source variance percentages, allowing analysts to identify which data provider might contain transcription errors or timing differences.

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

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 through digit 9. The benford_check() function at line 214 analyzes first-digit distributions in financial series and flags deviations from this expected logarithmic pattern, which can indicate fabricated numbers, rounding bias, or data quality issues in financial statements.

Can I use the Financial Rigor Toolkit without installing dependencies?

Yes. The toolkit is implemented as pure Python with no external dependencies beyond the standard library. It relies only on decimal, argparse, json, statistics, and collections modules that ship with Python 3, making it immediately executable in any standard Python environment without pip installations or virtual environment setup.

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