# How to Use the Market Cap Verification Tool in AI Berkshire: A Complete Guide

> Master AI Berkshire's Market Cap Verification tool. Learn how to precisely validate company valuations by recomputing price x shares and comparing against reported figures.

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

---

**The Market Cap Verification tool in AI Berkshire is a zero-dependency Python utility that validates company valuations by recomputing price × shares and comparing the result against reported market-cap figures using exact-decimal arithmetic.**

AI Berkshire provides a self-contained toolkit for financial research automation, and its market-cap verification feature ensures data integrity before valuation modeling. Located in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), this tool performs high-precision calculations to detect discrepancies between calculated and reported market capitalizations, making it essential for rigorous equity analysis workflows.

## What is the Market Cap Verification Tool?

The **Market Cap Verification tool** is a command-line and programmatic utility designed to eliminate floating-point errors when validating company valuations. Unlike standard floating-point math that introduces rounding drift, the tool uses Python's `decimal` module with a high-precision context (`_CTX`) to compute **price × shares outstanding** exactly.

According to the AI Berkshire source code, the tool serves as a critical checkpoint in automated research pipelines. It is automatically invoked by Claude Code skills at validation stages and can be run standalone without external dependencies.

## How the Verification Algorithm Works

The core logic resides in the `verify_market_cap` function within [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). When executed, the function performs a five-step validation process:

### 1. Exact Decimal Conversion

The tool converts all inputs—`price`, `shares`, and reported market-cap—to `Decimal` objects using an internal `exact` helper function. This conversion happens at lines 31-38 of [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), ensuring no precision loss occurs during subsequent calculations.

### 2. High-Precision Calculation

Using the module's exact-decimal engine (`_CTX`), the function multiplies price by shares via `_CTX.multiply`. This operation at line 67 produces a calculated market-cap value that matches the precision requirements of financial auditing standards.

### 3. Deviation Assessment

The tool computes the percentage deviation between the calculated market-cap and the reported figure. This comparison occurs at lines 68-78, formatting the output for human-readable reporting while maintaining computational exactness.

### 4. Threshold-Based Warnings

The verification logic applies a three-tier warning system based on deviation magnitude:

- **❌ Critical Warning**: Deviation exceeds 5% (indicates potential data-source mismatch or error)
- **⚠️ Caution**: Deviation falls between 1% and 5% (suggests minor inconsistency requiring review)
- **✅ Pass**: Deviation below 1% (verification successful)

These thresholds are implemented at lines 80-91 of the source file.

### 5. Boolean Return Value

The function returns a Boolean indicating success (`True` for deviations ≤ 5%) or failure (`False` for deviations > 5%). This return value enables downstream Claude Code skills to make automated decisions about whether to proceed with valuation modeling.

## Command-Line Usage

The most common entry point uses the `verify-market-cap` sub-command handled by `argparse`. Execute the tool directly from the repository root:

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

```

This command outputs a formatted report displaying the input price, share count, calculated market-cap, reported market-cap, and the percentage deviation between them. The stand-alone nature of the script means it requires no `pip install` steps or external package management.

## Programmatic Integration

For custom research scripts or Claude Code skill development, import the verification function directly:

```python
from tools.financial_rigor import verify_market_cap

# Example values for a 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 Boolean result integrates seamlessly into larger validation pipelines. Chain this check with other AI Berkshire tools—such as `cross-validate` or `benford` analysis—to enforce "must-pass" rules before executing valuation models.

## Integration Architecture

The market-cap verification feature fits into AI Berkshire's broader architecture through several key components:

- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)**: Implements the core verification logic, valuation checks, cross-source validation, Benford analysis, and exact calculator functions
- **[`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py)**: Generates Claude Code skill wrappers that automatically invoke the toolkit during research workflows
- **[`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md)**: Documents the project layout and specifies when to run synchronization scripts for skill updates

As noted in the top-level docstring (lines 1-10) of [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py), these components work together to provide automated validation checkpoints throughout the research process.

## Summary

- The **Market Cap Verification tool** in AI Berkshire uses exact-decimal arithmetic in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to eliminate floating-point errors when validating market capitalizations.
- The **`verify_market_cap`** function converts inputs to `Decimal` objects, computes price × shares using `_CTX.multiply`, and compares results against reported figures.
- **Command-line usage** requires no dependencies—simply run `python3 tools/financial_rigor.py verify-market-cap` with appropriate arguments.
- **Programmatic integration** returns a Boolean value suitable for automated decision-making in Claude Code skills and validation pipelines.
- The tool applies **threshold-based warnings**: critical errors (>5%), cautions (1-5%), and passes (<1%) to flag data quality issues immediately.

## Frequently Asked Questions

### What makes the Market Cap Verification tool in AI Berkshire different from standard calculator tools?

Unlike standard calculators that use floating-point arithmetic, the AI Berkshire tool employs Python's `decimal` module with a high-precision context (`_CTX`) to perform exact calculations. This prevents the rounding errors common in financial computations involving large numbers (billions or trillions), ensuring that price × shares calculations match auditing precision standards.

### Can I use the Market Cap Verification tool without installing Python packages?

Yes. The tool is deliberately **zero-dependency** and self-contained. As implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), it uses only Python standard library modules (`decimal`, `argparse`), making it immediately executable in any Python 3 environment without `pip install` requirements or virtual environment setup.

### How does the tool determine if a market-cap figure is valid or invalid?

The `verify_market_cap` function calculates the percentage deviation between the computed market-cap (price × shares) and the reported figure. It returns `True` for deviations of 5% or less, and `False` for deviations exceeding 5%. Visually, it prints a ❌ for critical mismatches (>5%), a ⚠️ for minor discrepancies (1-5%), and a ✅ for accurate data (<1%).

### Where does the Market Cap Verification tool fit into an AI Berkshire research workflow?

According to the source code documentation, the tool operates at critical validation checkpoints within Claude Code skills. It can be invoked automatically by [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) wrappers or called programmatically before valuation models run. The Boolean return value allows research agents to halt pipelines when market-cap data fails verification, preventing analysis based on incorrect input figures.