How to Use financial_rigor.py to Verify Market Cap in HKD, USD, and CNY

The verify_market_cap function in tools/financial_rigor.py validates market capitalization by comparing the product of share price and total shares against the reported cap using high-precision Decimal arithmetic, accepting any currency code as a free-form string without performing automatic FX conversion.

The financial_rigor.py module in the xbtlin/ai-berkshire repository provides a robust CLI and Python API for financial verification tasks. This tool eliminates floating-point errors by using exact decimal calculations when checking whether a company's reported market capitalization matches the mathematical product of its share price and outstanding shares.

How verify_market_cap Works

The core verification logic resides in verify_market_cap at lines 74-90 of tools/financial_rigor.py.

The function performs four critical steps:

1. Normalizes inputs – All numeric arguments are converted to exact Decimal values via the exact() helper to avoid floating-point drift
2. Computes theoretical cap – Calculates price × shares using the high-precision decimal context (_CTX)
3. Calculates deviation – Measures the percentage difference between the computed value and the reported market cap
4. Returns validation status – Returns True if deviation is ≤ 5%, otherwise False, while printing a detailed report that includes the supplied currency symbol

Because the currency parameter accepts any free-form string, the same routine works for HKD, USD, CNY, or any other monetary unit. The tool does not perform automatic FX conversion—all inputs must be expressed in the same currency unit.

Command-Line Usage for Multi-Currency Verification

The CLI entry point (lines 95-103) parses the --currency flag and forwards it directly to the verification function. This design allows you to validate market caps across different currencies without modifying the underlying logic.

Verifying Market Cap in Hong Kong Dollars (HKD)

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

Output:

市值验算 (Market Cap Verification)
  股价 (Price):       510 HKD
  总股本 (Shares):    9.11B
  计算市值:           4.65T HKD
  报告市值:           4.65T HKD
  偏差:               0.00%
  ✅ 验证通过, 偏差仅 0.00%

Verifying Market Cap in US Dollars (USD)

python3 tools/financial_rigor.py verify-market-cap \
    --price 65.2 \
    --shares 9.11e9 \
    --reported 5.94e11 \
    --currency USD

Verifying Market Cap in Chinese Yuan (CNY)

python3 tools/financial_rigor.py verify-market-cap \
    --price 3510 \
    --shares 9.11e9 \
    --reported 3.20e13 \
    --currency CNY

Programmatic Usage in Python

You can import the module directly for use in data pipelines or Jupyter notebooks:

from tools import financial_rigor as fr

# All values must be in the same currency (CNY example)

valid = fr.verify_market_cap(
    price=3510,
    shares=9.11e9,
    reported_cap=3.20e13,
    currency="CNY"
)

if valid:
    print("Market cap check passed.")
else:
    print("Market cap discrepancy detected.")

Handling Cross-Currency Comparisons

The tool deliberately avoids external dependencies for FX conversion. If your price and reported market cap are denominated in different currencies (e.g., price in HKD but reported cap in USD), you must convert them beforehand:

from forex_python.converter import CurrencyRates
from tools import financial_rigor as fr

c = CurrencyRates()
rate_hkd_usd = c.get_rate('HKD', 'USD')   # e.g. 0.128

price_hkd = 510
price_usd = price_hkd * rate_hkd_usd
shares = 9.11e9
reported_usd = 4.65e12 * rate_hkd_usd

fr.verify_market_cap(
    price=price_usd,
    shares=shares,
    reported_cap=reported_usd,
    currency="USD"
)

Summary

• The verify_market_cap function in tools/financial_rigor.py (lines 74-90) performs high-precision validation using Decimal arithmetic to prevent floating-point errors
• The CLI accepts any currency string via --currency but requires that price, shares, and reported cap share the same monetary unit
• No automatic FX conversion is performed; normalize currencies externally before verification whenever cross-currency comparisons are needed
• The function returns a Boolean (True if deviation ≤ 5%) and prints a detailed diagnostic report including the currency symbol
• The module can be imported as a library or invoked from the command line (lines 95-103)

Frequently Asked Questions

Does financial_rigor.py automatically convert between HKD, USD, and CNY?

No, the tool does not perform automatic FX conversion. You must convert all values to a common currency before passing them to verify_market_cap. The currency parameter is purely for display and labeling purposes in the output report.

What is the acceptable deviation threshold for market cap verification?

The function considers a deviation of ≤ 5% between the calculated (price × shares) and reported market cap as valid, returning True. Larger discrepancies return False, indicating potential data inconsistencies or rounding errors that warrant investigation.

Why does the tool use Decimal instead of float for calculations?

The exact() helper function converts inputs to Decimal objects under a high-precision context (_CTX) to avoid floating-point drift errors. This is critical for financial calculations where precision losses from binary floating-point representation could invalidate verification results.

Can I use financial_rigor.py as a library in my own Python scripts?

Yes, you can import tools.financial_rigor and call verify_market_cap(price, shares, reported_cap, currency) directly. This makes the verification logic reusable in data pipelines, quantitative analysis workflows, or automated testing suites outside the CLI environment.

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