What Is the verify-market-cap Function in AI Berkshire? Purpose and Usage

The verify-market-cap function validates a company's reported market capitalization by recalculating it from share price and total shares outstanding, flagging discrepancies that exceed a configurable tolerance threshold.

The verify-market-cap command is a critical data integrity tool in the xbtlin/ai-berkshire repository. Located within tools/financial_rigor.py, it serves as a single source of truth for market-cap verification across the research pipeline, preventing data entry errors and ensuring consistency in financial analysis.

Core Purpose of the verify-market-cap Command

The primary objective of this utility is to detect inconsistencies in reported market capitalization values. Analysts feed the tool four key data points, and the function independently recomputes the market cap to verify against the reported figure.

This validation acts as a safeguard against common errors such as:

• Transposed digits in large financial datasets
• Unit mismatches (e.g., millions vs. billions)
• Outdated share counts following stock splits

How the Validation Logic Works

The implementation in tools/financial_rigor.py follows a strict three-step validation pipeline.

Input Parameters

The argument parser at line 383 defines four required inputs:

• --price – Current share price in the specified currency
• --shares – Total shares outstanding (must match the price unit scale)
• --reported – The market-cap value from source data requiring verification
• --currency – Currency code (e.g., CNY, HKD) for explicit unit tracking

Calculation and Tolerance Check

The tool multiplies price × shares to generate an exact calculated market cap. It then measures the percentage deviation between this computed value and the --reported figure.

If the deviation exceeds the default tolerance of 5%, the function outputs a warning prompting the analyst to verify inputs. As noted in skills/financial-data.md at line 109, this threshold catches material data errors while allowing for minor market timing differences.

Unit Safety Controls

By requiring the explicit --currency flag, the command enforces analyst awareness of unit conversion requirements. This prevents errors where price might be in HKD while shares are denominated in millions, a common pitfall in cross-border financial analysis.

Integration in the AI Berkshire Workflow

The verify-market-cap command is deeply embedded in the AI Berkshire research methodology across multiple skill files:

• skills/investment-team.md (line 80) – Documents the market-cap verification step as mandatory in the investment team workflow
• skills/thesis-drift.md (line 83) – Provides example CLI calls for ongoing position monitoring
• reports/藏格矿业/藏格矿业投资研究报告.md (line 289) – Demonstrates real-world usage in the "市值验算" (market cap verification) section of the Zangge Mining investment report

These integration points ensure that every significant financial analysis in the repository includes rigor-checked market cap data.

Command-Line Usage Examples

Basic Verification

Run the command from the repository root to validate a Hong Kong-listed security:

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

Calculation: 510 × 9.11 billion = 4.64 trillion HKD, compared against the reported 4.65 trillion HKD.

Integration in Skill Documentation

Analysts embed the command in markdown skill files using placeholder syntax:

- 市值验算：`python3 tools/financial_rigor.py verify-market-cap \
    --price {价格} --shares {股本} --reported {报告市值} --currency {币种}`

Interpreting Output Results

Successful validation within tolerance displays:

✅ Calculated market cap: 1.1720e11
⚠️ Reported market cap: 1.1720e11
🔍 Deviation: 0.02 % (within tolerance)

When the deviation exceeds 5%, the tool flags the error:

❗ Deviation 7.3 % > 5 %. Please verify the inputs (price, shares, currency units).

Summary

• verify-market-cap is implemented in tools/financial_rigor.py as a sub-command for financial data validation
• The function recomputes market cap from price × shares and compares it against reported values
• A 5% tolerance threshold determines whether deviations trigger warnings
• Required parameters include --price, --shares, --reported, and --currency to ensure unit safety
• The command integrates into AI Berkshire's research workflows through skill files and investment reports

Frequently Asked Questions

What parameters does the verify-market-cap function require?

The command requires four arguments: --price for the current share price, --shares for total shares outstanding, --reported for the source market cap value, and --currency to specify the monetary unit. These parameters are defined in the argument parser at line 383 of tools/financial_rigor.py.

How does the function handle currency mismatches?

The --currency flag acts as a mandatory safety check rather than an automatic converter. By forcing analysts to explicitly state the currency (e.g., CNY, HKD), the tool prevents silent unit errors where price and share count might use different scales or denominations.

Where is the tolerance threshold configured?

The default tolerance of approximately 5% is configured within the implementation logic in tools/financial_rigor.py. This threshold is referenced in skills/financial-data.md at line 109 as the standard for flagging material discrepancies requiring analyst review.

How does AI Berkshire integrate this verification into research workflows?

The command is referenced throughout the repository's skill system, including skills/investment-team.md (line 80) for mandatory verification steps and skills/thesis-drift.md (line 83) for ongoing monitoring. Investment reports such as the Zangge Mining analysis at reports/藏格矿业/藏格矿业投资研究报告.md (line 289) include the verification output to substantiate financial data integrity.

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