# How to Run the Financial Rigor Tools in AI Berkshire

> Run AI Berkshire financial rigor tools from the command line. Verify market cap, analyze valuation, and detect Benford law anomalies with precision using this independent utility.

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

---

**The financial rigor tools in AI Berkshire are executed via the command-line utility at [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), offering zero-dependency sub-commands for market-cap verification, valuation analysis, and Benford-law detection using exact 28-digit decimal arithmetic.**

The AI Berkshire framework includes a self-contained Financial Rigor Toolkit located in the `xbtlin/ai-berkshire` repository that validates financial data without requiring external dependencies. This pure-Python utility relies exclusively on the standard library (`argparse`, `json`, `math`, `decimal`, `sys`) to ensure deterministic calculations across all validation checkpoints. Whether you need to verify market capitalizations or cross-validate revenue figures from multiple sources, you can run the financial rigor tools in AI Berkshire directly from the shell or import them into custom Python pipelines.

## Command-Line Interface for Financial Validation

The [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) script exposes a modular CLI built with `argparse` sub-parsers. Each sub-command forwards parsed arguments to a dedicated implementation function that performs exact decimal arithmetic and prints human-readable reports with deviation percentages and status indicators.

### Market-Cap Verification

Validate calculated market capitalization against reported values to detect discrepancies in price or share count data.

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

```

This command multiplies price by shares using a private `Decimal` context (`_CTX`) with 28-digit precision and compares the result against the reported value, flagging deviations that exceed validation thresholds.

### Valuation Multiple Checks

Compute and verify standard valuation ratios including PE, PB, dividend yield, and free cash flow yields.

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

```

The tool outputs a structured report containing calculated ratios and emoji status badges indicating whether values fall within expected ranges.

### Cross-Source Validation

Reconcile financial data points from multiple sources to identify reporting inconsistencies or data entry errors.

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

```

This sub-command compares values across dictionaries and reports deviation percentages between sources like annual reports and financial data providers.

### Benford-Law Analysis

Detect potential data manipulation or anomalies by testing number distributions against Benford's Law.

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

```

The analysis examines the frequency distribution of leading digits to flag datasets that deviate significantly from expected logarithmic patterns.

### Exact Arithmetic Calculator

Perform precise calculations without floating-point drift using the toolkit's internal `Decimal` context.

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

```

This utility converts scientific notation and arithmetic expressions to exact `Decimal` objects via the `exact()` helper function before computation.

### Three-Scenario Valuation

Generate optimistic, neutral, and pessimistic valuation scenarios using variable growth rates and PE multiples.

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

```

The command calculates intrinsic value ranges across three scenarios, providing immediate visual feedback on whether the current price falls within fair value bands.

## Programmatic Usage in Python

Import the validation functions directly to integrate financial rigor checks into custom analysis pipelines or automated research workflows.

```python
from tools.financial_rigor import verify_market_cap, verify_valuation

# Market-cap check

result = verify_market_cap(price=510, shares=9.11e9, reported_cap=4.65e12, currency="HKD")
print("Market-cap verification passed:", result)

# Valuation ratios

ratios = verify_valuation(price=510, eps=23.5, bvps=120, fcf_per_share=18, dividend=2.4)
print(ratios)   # {'PE': 21.7, 'PB': 4.25, 'Dividend_Yield': 0.47, ...}

```

When imported, the module uses the same `_CTX` decimal context and `exact()` conversion logic to ensure consistency between CLI and programmatic execution.

## Architecture and Precision Guarantees

The financial rigor tools implement **exact decimal arithmetic** through a private `Decimal` context (`_CTX`) configured with 28-digit precision. This design eliminates floating-point drift that could compromise financial calculations involving large numbers or precise ratios.

The internal flow follows this deterministic path:
1. **CLI entry point** → `if __name__ == "__main__": main()`
2. **Argument parsing** → Sub-parser selection (`verify-market-cap`, `verify-valuation`, etc.)
3. **Decimal conversion** → `exact()` function converts all inputs to `Decimal` objects
4. **Core calculation** → `_CTX.multiply()`, `_CTX.divide()`, or similar context operations
5. **Result reporting** → Formatted output with computed values and deviation warnings

This architecture ensures that running the financial rigor tools in AI Berkshire produces identical results across different Python versions and operating systems.

## Integration with the AI Berkshire Ecosystem

The toolkit operates within a broader validation framework that includes companion utilities for audit aggregation and skill synchronization.

- **[`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py)** — Aggregates audit results across multiple AI Berkshire skills; often invoked after rigor checks to compile final research reports with consolidated validation statuses.
- **[`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py)** — Synchronizes Claude-Code skill definitions to ensure automatic calls to the rigor toolkit remain current with the latest validation logic.

These files reside in `tools/` (core rigor logic) and `scripts/` (skill synchronization) respectively, providing end-to-end workflow integration for rigorous financial data validation.

## Summary

- **Run the financial rigor tools in AI Berkshire** via `python3 tools/financial_rigor.py` followed by sub-commands like `verify-market-cap` or `cross-validate`.
- **Zero dependencies** — requires only Python standard library modules (`decimal`, `argparse`, `json`).
- **Exact arithmetic** — uses 28-digit precision `Decimal` context (`_CTX`) to prevent floating-point errors.
- **Programmatic access** — import functions directly from `tools.financial_rigor` for custom pipeline integration.
- **Ecosystem integration** — works alongside [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) for comprehensive audit reporting and [`sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/sync-codex-skills.py) for automated skill updates.

## Frequently Asked Questions

### What Python version is required to run the financial rigor tools?

The tools require Python 3.6 or higher due to the use of f-strings and `decimal` module features, though they are tested primarily on Python 3.9+ as specified in the AI Berkshire repository. No third-party packages are needed, making the toolkit compatible with standard Python installations across Windows, macOS, and Linux.

### Can I use the financial rigor tools without installing any dependencies?

Yes. The [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) file is deliberately designed with **zero third-party dependencies**. It imports only from the Python standard library (`argparse`, `json`, `math`, `decimal`, `sys`), allowing you to run the tool immediately after cloning the `xbtlin/ai-berkshire` repository without creating a virtual environment or installing requirements.txt files.

### How does the toolkit ensure calculation accuracy across different systems?

The toolkit creates a private `Decimal` context (`_CTX`) with 28-digit precision and uses the `exact()` function to convert all numeric inputs to `Decimal` objects before computation. This approach guarantees deterministic, platform-independent results that avoid floating-point representation errors common in standard IEEE 754 arithmetic.

### Where are the validation results stored when running programmatically?

When called programmatically, functions like `verify_market_cap()` and `verify_valuation()` return dictionaries containing calculated ratios, deviation percentages, and boolean status flags. They do not automatically persist to disk; you must capture the return values and write them to files or databases as needed. For automated audit trails, chain these calls with [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) to generate consolidated validation reports.