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

> Explore financial_rigor.py, a Python script for exact-decimal arithmetic and verifiable financial data. Ensure reproducible, traceable calculations in investment research, free from floating-point drift.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: api-reference
- Published: 2026-07-29

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) tool serves as the central "Financial Rigor Toolkit" for the AI-Berkshire project. Located at [`/tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main//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.

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

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

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

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

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

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/thesis-drift.md) mandates strict use of [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main//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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.