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

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, 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. 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, 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:

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:

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: Implements the core verification logic, valuation checks, cross-source validation, Benford analysis, and exact calculator functions
• scripts/sync-codex-skills.py: Generates Claude Code skill wrappers that automatically invoke the toolkit during research workflows
• 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, 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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}