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

> Learn how the verify-market-cap function in AI Berkshire recalculates and validates market cap by comparing reported data to actual share price and shares outstanding.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: api-reference
- Published: 2026-07-10

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md)** (line 80) – Documents the market-cap verification step as mandatory in the investment team workflow
- **[`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

```bash
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:

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

```

### Interpreting Output Results

Successful validation within tolerance displays:

```text
✅ 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:

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

```

## Summary

- **`verify-market-cap`** is implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). This threshold is referenced in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md) (line 80) for mandatory verification steps and [`skills/thesis-drift.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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.