# How to Use AI Berkshire Tools for Market Cap Verification

> Verify market cap accurately with AI Berkshire tools. This Python utility uses exact decimal arithmetic to recompute price x shares and flags deviations. Learn how to use it.

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

---

**AI Berkshire provides a self-contained, zero-dependency Python utility that rigorously checks market capitalization by recomputing price × shares using exact decimal arithmetic and comparing results against reported figures with automated deviation warnings.**

The `xbtlin/ai-berkshire` repository offers **AI Berkshire tools for market cap verification** that ensure data integrity through rigorous equity research validation. These utilities detect discrepancies between calculated and reported market values using high-precision decimal math instead of error-prone floating-point operations.

## Command-Line Verification with `verify-market-cap`

The fastest way to validate market capitalization data is through the command-line interface implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). This script exposes a `verify-market-cap` sub-command via `argparse` (lines 58-68) that accepts price, share count, and reported market cap as arguments.

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

```

When executed, this command performs exact decimal multiplication and prints a formatted report showing the calculated market cap, reported value, and percentage deviation. The tool exits with status indicators based on deviation thresholds, making it suitable for shell script integration.

## Programmatic Market Cap Verification

For integration into custom research scripts or Claude Code skills, import the `verify_market_cap` function directly from the financial rigor module.

```python
from tools.financial_rigor import verify_market_cap

# Example: Hong Kong-listed company

price = 510          # HKD per share

shares = 9.11e9      # total shares outstanding

reported_cap = 4.65e12  # reported market cap in HKD

# Returns True if deviation ≤ 5%, False otherwise

is_valid = verify_market_cap(price, shares, reported_cap, currency="HKD")
print("Market cap verification passed?", is_valid)

```

The function returns a Boolean value indicating validation success, enabling downstream automation to enforce "must-pass" rules before proceeding to valuation models or cross-source validation checks.

### Exact Decimal Arithmetic Engine

To prevent floating-point drift during financial calculations, the tool uses Python's `decimal` module with a dedicated high-precision context (`_CTX`). According to the source code in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), the `exact` helper function (lines 31-38) converts all inputs to `Decimal` objects. The core calculation uses `_CTX.multiply` (line 67) to ensure exact arithmetic when computing price × shares outstanding.

### Automated Deviation Thresholds

The verification logic applies strict tolerance bands to flag potential data-source mismatches. As implemented in lines 80-91 of [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py):

- **❌ Error**: Deviation exceeds 5% (indicates significant data discrepancy requiring immediate investigation)
- **⚠️ Warning**: Deviation between 1% and 5% (suggests minor inconsistency or rounding differences)
- **✅ Pass**: Deviation below 1% (calculation matches reported value within acceptable tolerance)

These thresholds help researchers quickly identify stale data, currency conversion errors, or split-adjustment mistakes in reported market capitalization figures.

## Integration with AI Berkshire Research Workflows

The `verify_market_cap` function serves as a critical validation checkpoint within AI Berkshire's automated research pipeline. The repository includes [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py), which generates Claude Code skill wrappers that automatically invoke the toolkit during research workflows. The top-level [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md) file documents integration rules specifying when to run these validation checks relative to other analysis steps.

Because the tool maintains zero external dependencies, you can embed it in Jupyter notebooks, automated trading systems, or CI/CD pipelines without package management overhead or version conflicts.

## Summary

- **AI Berkshire tools for market cap verification** provide zero-dependency, high-precision validation via [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py).
- The **`verify_market_cap`** function uses exact decimal arithmetic (`_CTX`) and an `exact` helper to eliminate floating-point errors when calculating price × shares.
- Command-line access is available through the **`verify-market-cap`** sub-command with `--price`, `--shares`, `--reported`, and `--currency` arguments.
- Automated threshold warnings flag deviations exceeding 1% (⚠️) or 5% (❌), returning Boolean values for seamless pipeline integration.
- The tool integrates with Claude Code skills through [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) and follows integration rules documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md).

## Frequently Asked Questions

### What file contains the market cap verification logic in AI Berkshire?

The core implementation resides in **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**, which contains the `verify_market_cap` function and the exact-decimal calculation engine (`_CTX`). This file also handles command-line argument parsing for the `verify-market-cap` sub-command and implements the deviation threshold warnings.

### How does AI Berkshire prevent calculation errors during market cap verification?

The tool uses Python's `decimal` module with a high-precision context (`_CTX`) and an `exact` helper function (lines 31-38) to convert all inputs to `Decimal` objects. This approach eliminates floating-point drift by performing exact arithmetic operations via `_CTX.multiply` (line 67) when computing price × shares outstanding.

### What deviation thresholds trigger warnings in the verification tool?

The system flags a **❌ failure** when deviation exceeds 5%, a **⚠️ warning** for deviations between 1% and 5%, and a **✅ pass** for deviations below 1%. These thresholds help identify potential data-source mismatches or input errors in reported market capitalization figures.

### Can I use the market cap verifier in automated trading or research scripts?

Yes. The `verify_market_cap` function returns a Boolean (`True` for deviation ≤ 5%, `False` otherwise), making it suitable for automated pipelines. The tool is automatically invoked by Claude Code skills at validation checkpoints and can be embedded in custom scripts without external dependencies.