How to Use AI Berkshire Tools for Market Cap Verification

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

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.

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

• ❌ 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, which generates Claude Code skill wrappers that automatically invoke the toolkit during research workflows. The top-level 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.
• 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 and follows integration rules documented in 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, 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.

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