# How to Verify Market Cap and Valuations Using AI Berkshire's Financial Rigor Tools

> Verify market cap and valuations with AI Berkshire's Financial Rigor toolkit. Get exact-decimal calculations and automatic deviation flagging for enhanced financial oversight.

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

---

**AI Berkshire's Financial Rigor toolkit provides exact-decimal verification functions that calculate theoretical market caps and valuation ratios, automatically flagging deviations greater than 1% and rejecting calculations with errors exceeding 5%.**

The AI Berkshire repository ships with a specialized **Financial Rigor toolkit** designed to eliminate floating-point drift in equity research. Located in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), these tools verify market cap and valuations using high-precision decimal arithmetic to ensure every calculation in your investment analysis meets institutional-grade accuracy standards.

## The Exact-Decimal Verification Engine

All numeric operations in AI Berkshire's verification tools rely on a shared `decimal.Decimal` context to prevent floating-point errors. The implementation uses a `_CTX` object configured with `prec=28` and `ROUND_HALF_EVEN` rounding, accessible via the `exact()` helper function defined in lines 28-38 of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py).

The toolkit automatically formats large numbers into human-readable units (亿, 万亿, B, T) through the `fmt_number()` function. This ensures that calculated values and reported values display in identical formats, enabling fair visual comparison during manual review.

## How to Verify Market Cap Calculations

The `verify_market_cap()` function validates whether a reported market capitalization matches the theoretical value calculated from share price and total shares outstanding.

### Deviation Thresholds

The function implements a three-tier validation system:

- **Greater than 5% deviation**: Returns `False` and triggers a hard warning
- **1% to 5% deviation**: Returns `True` but triggers a soft warning  
- **Less than or equal to 1% deviation**: Returns `True` with a clean pass

The calculation follows the formula `abs(calculated - reported) / reported × 100`, where `calculated` equals `price × shares`.

### Command-Line Usage

Execute market-cap verification directly from the terminal:

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

```

This invocation returns a structured analysis showing the calculated market cap (4.64e+12 HKD), reported value (4.65e+12 HKD), and percentage deviation (0.22%). Since the deviation falls below the 1% threshold, the function returns `True` and displays a validation pass message.

### Python API Implementation

Import the function for use in research scripts or Jupyter notebooks:

```python
from tools.financial_rigor import verify_market_cap

# Returns True if deviation ≤ 5%, False otherwise

is_valid = verify_market_cap(
    price=510,
    shares=9.11e9,
    reported_cap=4.65e12,
    currency="HKD"
)
print(f"Market cap validation: {is_valid}")

```

## How to Verify Valuation Ratios

The `verify_valuation()` function computes standard equity valuation metrics from raw financial inputs, returning both human-readable output and a JSON-compatible dictionary for downstream automation.

### Supported Metrics

The function calculates the following ratios when provided with the corresponding inputs:

- **PE (TTM)**: Price divided by EPS
- **PB**: Price divided by book value per share  
- **P/FCF**: Price divided by free cash flow per share
- **ROE**: Earnings per share divided by book value per share
- **Dividend Yield**: Dividend per share divided by price
- **FCF Yield**: Free cash flow per share divided by price

### CLI Valuation Verification

Run a comprehensive valuation check from the command line:

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

```

The output displays each calculation step with exact-decimal precision:

```

------------------------------------------------------------
估值指标验算 (Valuation Verification)
------------------------------------------------------------
  当前股价: 510

  PE (TTM):  510 / 23.5 = 21.70x
  盈利收益率: 4.60%
  PB:        510 / 120 = 4.25x
  ROE:       23.5 / 120 = 19.58%
  P/FCF:     510 / 18 = 28.33x
  FCF Yield: 3.53%
  股息率:    2.4 / 510 = 0.47%
✅ 以上指标均使用精确十进制计算, 无浮点误差

```

### Programmatic Dictionary Output

When called programmatically, the function returns a Python dictionary suitable for JSON serialization:

```python
from tools.financial_rigor import verify_valuation

ratios = verify_valuation(
    price=510,
    eps=23.5,
    bvps=120,
    fcf_per_share=18,
    dividend=2.4
)

# Returns: {

#   "PE": 21.70,

#   "PB": 4.25, 

#   "ROE": 19.58,

#   "P_FCF": 28.33,

#   "FCF_Yield": 3.53,

#   "Dividend_Yield": 0.47

# }

print(ratios)

```

## Integration with AI Berkshire's Research Pipeline

The Financial Rigor toolkit integrates with Claude-Code skills through the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script, which generates automatic validation checkpoints. When AI Berkshire's research agents generate reports, they invoke `verify_market_cap()` and `verify_valuation()` at critical validation stages to ensure zero manual calculation errors.

For complementary data extraction workflows, the [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) module provides random sampling and verification capabilities that work alongside the financial rigor functions to validate extracted numbers before they enter the calculation pipeline.

## Summary

- **Primary Location**: All verification functions reside in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) within the xbtlin/ai-berkshire repository
- **Precision Standard**: Uses `decimal.Decimal` with 28-digit precision and `ROUND_HALF_EVEN` to eliminate floating-point drift
- **Market Cap Validation**: Multiplies price by shares, compares against reported cap, and flags deviations using 1% and 5% thresholds
- **Valuation Metrics**: Calculates PE, PB, P/FCF, ROE, and yield metrics from raw inputs, returning both formatted strings and JSON-compatible dictionaries
- **CLI and API Support**: Functions work as command-line tools via `argparse` or as importable Python modules for Jupyter notebooks and automation scripts
- **AI Integration**: Designed for automatic invocation by Claude-Code skills during research report generation

## Frequently Asked Questions

### What precision does AI Berkshire use for financial calculations?

AI Berkshire uses `decimal.Decimal` with a precision of 28 digits and `ROUND_HALF_EVEN` rounding mode through a shared `_CTX` context object. This configuration, defined in lines 28-38 of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), ensures that percentage deviations and ratio calculations remain accurate to the second decimal place without floating-point representation errors.

### Can I verify market cap and valuations programmatically instead of using the CLI?

Yes. Import `verify_market_cap` and `verify_valuation` directly from `tools.financial_rigor`. The market cap function accepts `price`, `shares`, `reported_cap`, and `currency` parameters, returning a boolean. The valuation function accepts metrics like `eps`, `bvps`, `fcf_per_share`, and `dividend`, returning a dictionary of calculated ratios suitable for JSON serialization or database storage.

### What deviation thresholds trigger warnings in the market cap verification?

The `verify_market_cap()` function implements a tiered system: deviations exceeding 5% return `False` and trigger a hard warning; deviations between 1% and 5% return `True` with a soft warning; deviations at or below 1% return `True` with a clean pass. These thresholds ensure that only materially accurate market caps proceed through the validation pipeline.

### How does the toolkit integrate with AI Berkshire's automated research agents?

The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) script generates Claude-Code skill wrappers that automatically invoke `verify_market_cap()` and `verify_valuation()` at specific checkpoints during report generation. This integration ensures that every research report generated by AI Berkshire's agents undergoes exact-decimal verification without requiring manual intervention from the user.