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

> Explore AI Berkshire's Financial Rigor Toolkit for deterministic validation. Discover tools for market-cap verification, valuation ratios, Benford's Law analysis, and more to ensure accurate financial calculations.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-06-27

---

**AI Berkshire provides a self-contained Financial Rigor Toolkit in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash

# 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

```

```bash

# 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

```

```bash

# Cross-validate revenue figures from multiple sources

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

```

```bash

# Apply Benford's Law analysis to financial series

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

```

```bash

# Perform exact arithmetic calculation

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

```

```bash

# 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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py)** – Example consumer that orchestrates the toolkit as part of comprehensive research-report validation workflows
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.