How to Verify Market Cap and Valuations Using AI Berkshire's Financial Rigor Tools

AI Berkshire's Financial Rigor toolkit provides exact-decimal verification functions that calculate theoretical market caps and valuation ratios, automatically flagging deviations greater than 1% and rejecting calculations with errors exceeding 5%.

The AI Berkshire repository ships with a specialized Financial Rigor toolkit designed to eliminate floating-point drift in equity research. Located in tools/financial_rigor.py, these tools verify market cap and valuations using high-precision decimal arithmetic to ensure every calculation in your investment analysis meets institutional-grade accuracy standards.

The Exact-Decimal Verification Engine

All numeric operations in AI Berkshire's verification tools rely on a shared decimal.Decimal context to prevent floating-point errors. The implementation uses a _CTX object configured with prec=28 and ROUND_HALF_EVEN rounding, accessible via the exact() helper function defined in lines 28-38 of tools/financial_rigor.py.

The toolkit automatically formats large numbers into human-readable units (亿, 万亿, B, T) through the fmt_number() function. This ensures that calculated values and reported values display in identical formats, enabling fair visual comparison during manual review.

How to Verify Market Cap Calculations

The verify_market_cap() function validates whether a reported market capitalization matches the theoretical value calculated from share price and total shares outstanding.

Deviation Thresholds

The function implements a three-tier validation system:

• Greater than 5% deviation: Returns False and triggers a hard warning
• 1% to 5% deviation: Returns True but triggers a soft warning
• Less than or equal to 1% deviation: Returns True with a clean pass

The calculation follows the formula abs(calculated - reported) / reported × 100, where calculated equals price × shares.

Command-Line Usage

Execute market-cap verification directly from the terminal:

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

This invocation returns a structured analysis showing the calculated market cap (4.64e+12 HKD), reported value (4.65e+12 HKD), and percentage deviation (0.22%). Since the deviation falls below the 1% threshold, the function returns True and displays a validation pass message.

Python API Implementation

Import the function for use in research scripts or Jupyter notebooks:

from tools.financial_rigor import verify_market_cap

# Returns True if deviation ≤ 5%, False otherwise

is_valid = verify_market_cap(
    price=510,
    shares=9.11e9,
    reported_cap=4.65e12,
    currency="HKD"
)
print(f"Market cap validation: {is_valid}")

How to Verify Valuation Ratios

The verify_valuation() function computes standard equity valuation metrics from raw financial inputs, returning both human-readable output and a JSON-compatible dictionary for downstream automation.

Supported Metrics

The function calculates the following ratios when provided with the corresponding inputs:

• PE (TTM): Price divided by EPS
• PB: Price divided by book value per share
• P/FCF: Price divided by free cash flow per share
• ROE: Earnings per share divided by book value per share
• Dividend Yield: Dividend per share divided by price
• FCF Yield: Free cash flow per share divided by price

CLI Valuation Verification

Run a comprehensive valuation check from the command line:

python3 tools/financial_rigor.py verify-valuation \
  --price 510 \
  --eps 23.5 \
  --bvps 120 \
  --fcf-per-share 18 \
  --dividend 2.4

The output displays each calculation step with exact-decimal precision:

------------------------------------------------------------
估值指标验算 (Valuation Verification)
------------------------------------------------------------
  当前股价: 510

  PE (TTM):  510 / 23.5 = 21.70x
  盈利收益率: 4.60%
  PB:        510 / 120 = 4.25x
  ROE:       23.5 / 120 = 19.58%
  P/FCF:     510 / 18 = 28.33x
  FCF Yield: 3.53%
  股息率:    2.4 / 510 = 0.47%
✅ 以上指标均使用精确十进制计算, 无浮点误差

Programmatic Dictionary Output

When called programmatically, the function returns a Python dictionary suitable for JSON serialization:

from tools.financial_rigor import verify_valuation

ratios = verify_valuation(
    price=510,
    eps=23.5,
    bvps=120,
    fcf_per_share=18,
    dividend=2.4
)

# Returns: {

#   "PE": 21.70,

#   "PB": 4.25, 

#   "ROE": 19.58,

#   "P_FCF": 28.33,

#   "FCF_Yield": 3.53,

#   "Dividend_Yield": 0.47

# }

print(ratios)

Integration with AI Berkshire's Research Pipeline

The Financial Rigor toolkit integrates with Claude-Code skills through the scripts/sync-codex-skills.py script, which generates automatic validation checkpoints. When AI Berkshire's research agents generate reports, they invoke verify_market_cap() and verify_valuation() at critical validation stages to ensure zero manual calculation errors.

For complementary data extraction workflows, the tools/report_audit.py module provides random sampling and verification capabilities that work alongside the financial rigor functions to validate extracted numbers before they enter the calculation pipeline.

Summary

• Primary Location: All verification functions reside in tools/financial_rigor.py within the xbtlin/ai-berkshire repository
• Precision Standard: Uses decimal.Decimal with 28-digit precision and ROUND_HALF_EVEN to eliminate floating-point drift
• Market Cap Validation: Multiplies price by shares, compares against reported cap, and flags deviations using 1% and 5% thresholds
• Valuation Metrics: Calculates PE, PB, P/FCF, ROE, and yield metrics from raw inputs, returning both formatted strings and JSON-compatible dictionaries
• CLI and API Support: Functions work as command-line tools via argparse or as importable Python modules for Jupyter notebooks and automation scripts
• AI Integration: Designed for automatic invocation by Claude-Code skills during research report generation

Frequently Asked Questions

What precision does AI Berkshire use for financial calculations?

AI Berkshire uses decimal.Decimal with a precision of 28 digits and ROUND_HALF_EVEN rounding mode through a shared _CTX context object. This configuration, defined in lines 28-38 of tools/financial_rigor.py, ensures that percentage deviations and ratio calculations remain accurate to the second decimal place without floating-point representation errors.

Can I verify market cap and valuations programmatically instead of using the CLI?

Yes. Import verify_market_cap and verify_valuation directly from tools.financial_rigor. The market cap function accepts price, shares, reported_cap, and currency parameters, returning a boolean. The valuation function accepts metrics like eps, bvps, fcf_per_share, and dividend, returning a dictionary of calculated ratios suitable for JSON serialization or database storage.

What deviation thresholds trigger warnings in the market cap verification?

The verify_market_cap() function implements a tiered system: deviations exceeding 5% return False and trigger a hard warning; deviations between 1% and 5% return True with a soft warning; deviations at or below 1% return True with a clean pass. These thresholds ensure that only materially accurate market caps proceed through the validation pipeline.

How does the toolkit integrate with AI Berkshire's automated research agents?

The scripts/sync-codex-skills.py script generates Claude-Code skill wrappers that automatically invoke verify_market_cap() and verify_valuation() at specific checkpoints during report generation. This integration ensures that every research report generated by AI Berkshire's agents undergoes exact-decimal verification without requiring manual intervention from the user.

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