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

> Discover AI Berkshire's comprehensive Financial Rigor Toolkit. This guide details six command-line validators that ensure precise financial calculations by eliminating floating-point drift.

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

---

**AI Berkshire ships a self-contained Financial Rigor Toolkit in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) that provides six command-line validators using exact-decimal arithmetic to eliminate floating-point drift in financial calculations.**

The `xbtlin/ai-berkshire` repository provides a deterministic, auditable layer for investment research through its **Financial Rigor Toolkit**. This pure-Python utility requires no external dependencies and safeguards quantitative analysis by enforcing exact-precision arithmetic across all validation workflows. Whether you are verifying market capitalization figures or stress-testing valuation models, these financial rigor tools ensure that every calculation is mathematically sound and reproducible.

## Core Architecture of the Financial Rigor Toolkit

The toolkit’s architecture rests on three pillars: exact-decimal computation, human-readable output formatting, and a sub-command dispatcher that maps CLI arguments to pure Python functions.

### Exact-Decimal Engine

All numeric operations in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) execute within a fixed-precision `decimal.Decimal` context (`_CTX`) to eliminate floating-point drift. The helper function `exact()` coerces any input—whether float, string, or Decimal—into a canonical `Decimal` instance before processing. This guarantees that calculations like price-to-market-cap verification remain deterministic and free from IEEE 754 representation errors.

### Human-Readable Formatting

The `fmt_number()` function automatically scales large numbers into Chinese units (`亿`, `万亿`) or international suffixes (`M`, `B`, `T`). This ensures that CLI output is immediately interpretable by analysts while maintaining the underlying exact-decimal precision for downstream processing.

### Command Dispatcher

An `argparse` sub-command dispatcher at the bottom of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (lines 66–78) exposes six top-level commands. Each command maps to a single pure-Python function that performs a specific financial validation, outputting results with clear ✅/⚠️/❌ indicators suitable for automated consumption by Claude Code skills or CI pipelines.

## Available Financial Validation Commands

The toolkit provides six distinct validators, each accessible as a CLI sub-command.

### verify-market-cap

The `verify_market_cap()` function validates that **price × shares** matches a reported market capitalization, flagging deviations greater than 5%. This catches data entry errors and reconciliation mismatches in equity research datasets.

### verify-valuation

Use `verify_valuation()` to compute and display key valuation ratios—including PE, PB, P/FCF, and dividend yield—using exact arithmetic. This command ensures that ratio calculations across different data sources remain consistent and precisely rounded.

### cross-validate

The `cross_validate()` function accepts a data point from multiple sources (e.g., annual reports, Yahoo Finance, StockAnalysis), calculates a median-based consensus, and reports per-source deviation. This identifies outliers in financial datasets before they contaminate investment models.

### benford

`benford_check()` applies Benford’s Law to a series of financial numbers, flagging suspicious digit distributions that may indicate data manipulation or accounting irregularities. This serves as a forensic sanity check on revenue, expense, or transaction datasets.

### calc

The `exact_calc()` function provides a safe “exact calculator” for arbitrary arithmetic expressions. It supports addition, subtraction, multiplication, and division while maintaining decimal precision throughout the computation chain, preventing cumulative rounding errors in multi-step analyses.

### three-scenario

`three_scenario_valuation()` projects EPS and target prices under optimistic, neutral, and pessimistic growth and PE assumptions. By accepting arrays of growth rates and PE multiples, this tool enables standardized sensitivity analysis for equity valuation reports.

## Practical Usage Examples

Each command follows a consistent interface pattern. Below are runnable examples demonstrating the full capabilities of the financial rigor tools.

Verify market capitalization calculations:

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

```

Check valuation ratios for fundamental analysis:

```bash
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 across multiple data providers:

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

```

Apply Benford’s Law to detect anomalous distributions:

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

```

Perform exact arithmetic without floating-point errors:

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

```

Run three-scenario valuation projections:

```bash
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

```

## Integration with AI Berkshire Workflows

The financial rigor tools integrate directly into the broader AI Berkshire ecosystem. The file [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) demonstrates how to invoke the toolkit as part of automated research-report validation pipelines. Additionally, [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) documents how Claude Code skills should call these utilities to ensure that all quantitative outputs in the repository meet strict deterministic standards.

According to the `xbtlin/ai-berkshire` source code, these utilities share a common output format featuring section dividers and human-readable scaling, making them equally suitable for human review and machine parsing.

## Summary

- **Exact-Decimal Engine**: All calculations in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) use `decimal.Decimal` with a fixed-precision context (`_CTX`) to eliminate floating-point drift via the `exact()` helper.
- **Six Validation Commands**: The toolkit provides `verify-market-cap`, `verify-valuation`, `cross-validate`, `benford`, `calc`, and `three-scenario` for comprehensive financial data validation.
- **Zero Dependencies**: The utility is implemented as pure Python with no external requirements, ensuring portability across environments.
- **Automation-Ready**: Output formatting with clear status symbols (✅/⚠️/❌) and `fmt_number()` scaling supports both human review and automated Claude Code skill consumption.
- **Integration Points**: [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) and [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) demonstrate production usage patterns for research validation workflows.

## Frequently Asked Questions

### What is the Financial Rigor Toolkit in AI Berkshire?

The Financial Rigor Toolkit is a self-contained Python module located at [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) in the `xbtlin/ai-berkshire` repository. It provides deterministic, exact-decimal financial validation helpers accessible via command-line sub-commands, designed to safeguard quantitative investment research against computational errors and data inconsistencies.

### How does the toolkit prevent floating-point errors?

The toolkit prevents floating-point errors by performing all arithmetic within a fixed-precision `decimal.Decimal` context defined as `_CTX`. The `exact()` function coerces all numeric inputs—whether floats, strings, or Decimals—into canonical `Decimal` instances before any calculation occurs, ensuring that operations like market-cap verification remain free from IEEE 754 representation drift.

### Can I use the financial rigor tools outside of AI Berkshire?

Yes. The toolkit is a pure-Python command-line utility with no external dependencies, making it fully portable. You can run `python3 tools/financial_rigor.py` from any environment with Python 3 installed, independent of the broader AI Berkshire agent framework or Claude Code integration.

### Where are the validation functions implemented?

All validation functions—including `verify_market_cap()`, `verify_valuation()`, `cross_validate()`, `benford_check()`, `exact_calc()`, and `three_scenario_valuation()`—are implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). The command-line interface dispatches to these functions via an `argparse` sub-command parser defined at lines 66–78 of the same file.