# How to Use financial_rigor.py for Market Cap Validation in AI-Berkshire

> Learn to use financial_rigor.py for market cap validation in AI-Berkshire. This script ensures accuracy by comparing calculated and reported figures against a 5% threshold, returning a clear pass or fail.

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

---

**The `verify_market_cap` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) validates market capitalization by comparing calculated price × shares against reported figures, returning a Boolean pass/fail based on a 5% deviation threshold.**

The `ai-berkshire` repository by xbtlin provides rigorous financial validation tools for AI-driven investment research. The [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) module serves as the command-line utility for ensuring data integrity, with its **market cap validation** functionality providing mathematically exact arithmetic to catch discrepancies between calculated and reported valuations.

## Understanding the Market Cap Validation Logic

### High-Precision Decimal Arithmetic

The script implements an **Exact Decimal Engine** to eliminate floating-point drift. In [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) lines 24-38, the module creates a high-precision context `_CTX` and defines the `exact()` helper function. This ensures that all price, share count, and market cap calculations maintain mathematical exactness rather than relying on standard IEEE 754 floating-point operations.

### The verify_market_cap Function

Located at lines 61-90, the `verify_market_cap()` function executes the core validation workflow:

1. Converts inputs to `Decimal` objects via `exact()` (lines 31-38)
2. Calculates market cap using exact multiplication: `calculated = _CTX.multiply(p, s)` (line 67)
3. Computes absolute deviation: `abs(float(calculated - r) / float(r)) * 100` (line 68)
4. Returns a Boolean indicating pass/fail based on deviation thresholds

## Running Market Cap Validation

### Command Line Interface

The script exposes a `verify-market-cap` subcommand through `argparse` (lines 67-88). This interface accepts four required arguments: `--price`, `--shares`, `--reported`, and `--currency`.

Example validation for a Hong Kong-listed security:

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

```

The CLI prints a color-coded report via `fmt_number()` (lines 40-55), which formats large numbers into human-readable units (亿, 万亿, B, T), and exits with code 0 for pass or 1 for fail.

### Programmatic Python Usage

Import the module directly to integrate validation into existing research scripts:

```python
from tools import financial_rigor as fr

# Example: Tencent validation

price = 510                # HKD per share

shares = 9.11e9           # total shares outstanding

reported_cap = 4.65e12    # reported market cap in HKD

# Execute validation

passed = fr.verify_market_cap(price, shares, reported_cap, currency="HKD")

if passed:
    print("Market cap validation passed")
else:
    print("Market cap validation failed - check for outdated share counts or currency mismatches")

```

## Interpreting Validation Thresholds

The function implements a three-tier tolerance system (lines 80-91):

- **≤ 1% deviation**: ✅ Pass (mathematically verified)
- **> 1% and ≤ 5% deviation**: ⚠️ Acceptable with warning (passes but flags potential data staleness)
- **> 5% deviation**: ❌ Fail (indicates outdated share counts, currency mismatches, or stale price data)

## Integration with AI-Berkshire Workflows

According to the header comments in [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), the tool is designed for automatic invocation by Claude Code skills at critical research checkpoints. The [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file documents how these skills interact with the toolkit, while [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) generates Codex-compatible wrappers that enforce validation before report publication.

Pseudo-code for skill integration:

```python
def validate_before_report(price, shares, reported_cap, currency):
    ok = financial_rigor.verify_market_cap(price, shares, reported_cap, currency)
    if not ok:
        raise ValueError("Market cap validation failed – aborting skill execution")
    return True

```

## Summary

- **`verify_market_cap`** in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (lines 61-90) performs rigorous market cap validation using exact decimal arithmetic
- The **Exact Decimal Engine** (`_CTX` and `exact()` at lines 24-38) prevents floating-point errors in financial calculations
- Validation accepts CLI arguments via `verify-market-cap` subcommand or Python function calls
- Results show **color-coded deviation percentages** with a 5% hard failure threshold
- The tool integrates automatically with Claude Code skills for pre-publication quality checks

## Frequently Asked Questions

### What deviation threshold triggers a failure in financial_rigor.py?

The validation fails when the absolute deviation between calculated and reported market cap exceeds **5%**. Deviations between 1% and 5% generate warnings but pass validation, while deviations under 1% pass cleanly.

### Why does financial_rigor.py use Decimal instead of float?

The module implements an **Exact Decimal Engine** (`_CTX` context and `exact()` helper at lines 24-38) to avoid floating-point drift errors common in IEEE 754 arithmetic. This ensures mathematically exact calculations when multiplying price by shares and comparing against reported values.

### Can I validate market caps in currencies other than USD?

Yes. The `--currency` CLI argument and `currency` Python parameter accept any currency code (e.g., HKD, CNY, EUR). The `fmt_number()` function (lines 40-55) automatically formats output using appropriate units (亿, 万亿 for Asian markets; B, T for Western).

### How do I integrate this into automated research pipelines?

The script is designed for automatic invocation by Claude Code skills as documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md). You can also import `financial_rigor` as a module in Python scripts or shell out to the CLI in bash workflows. The function returns a Boolean and exit codes (0 for pass, 1 for fail) suitable for CI/CD gates.