How to Use financial_rigor.py for Market Cap Verification with Decimal Arithmetic

The financial_rigor.py module in the xbtlin/ai-berkshire repository provides a dependency-free CLI and Python API that uses decimal.Decimal arithmetic to eliminate floating-point errors when verifying reported market capitalization against calculated values.

Accurate market-cap verification is critical for financial research automation. The AI-Berkshire toolkit addresses this through tools/financial_rigor.py, a standard-library-only utility that replaces imprecise float arithmetic with exact decimal calculations. This ensures that trillion-dollar valuations remain mathematically sound when cross-checked against primary sources.

Why Decimal Arithmetic Matters for Financial Verification

Floating-point (float) arithmetic in Python introduces binary representation errors that compound at scale. For example, 0.1 + 0.2 does not equal exactly 0.3 in binary floating-point, and these micro-errors become significant when multiplying billions of shares by share prices.

The decimal module provides arbitrary-precision decimal arithmetic suitable for financial applications. By using decimal.Decimal objects, financial_rigor.py guarantees that price × shares produces an exact mathematical result, ensuring that deviation percentages between calculated and reported market caps are trustworthy and reproducible.

Core Architecture of financial_rigor.py

The module is structured around a shared decimal context and strict input conversion rules to maintain precision throughout the calculation pipeline.

The Decimal Context and exact() Conversion

At lines 28-30 in tools/financial_rigor.py, the module defines a shared context _CTX:

_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

This context provides 28 digits of precision with banker's rounding (round half to even) for all subsequent operations.

The exact() function at lines 31-38 handles all numeric input conversion:

def exact(x):
    """Convert float/int to Decimal via string to avoid binary drift."""
    return Decimal(str(x))

By stringifying inputs before creating Decimal objects, this function prevents the hidden precision loss that occurs when converting binary floats directly to decimals.

The verify_market_cap() Implementation

The verify_market_cap(price, shares, reported_cap, currency) function (lines 61-90) performs the core verification logic:

1. Exact conversion: All inputs pass through exact() to create Decimal objects.
2. Calculation: Uses _CTX.multiply to compute price × shares.
3. Deviation analysis: Calculates absolute deviation as |calc - reported| / reported × 100.
4. Formatting: Applies fmt_number() (lines 40-55) to present values in human-readable units (e.g., "万亿" for trillions).
5. Threshold evaluation: Returns pass/fail status based on deviation magnitude:
   • ≤ 1%: ✅ Pass
   • 1–5%: ⚠️ Warning
   • > 5%: ❌ Fail

CLI Usage for Market Cap Verification

The most common invocation uses the verify-market-cap subcommand parsed by argparse in the main() function (lines 82-88):

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.11e+09
  计算市值:           4.66e+12 HKD
  报告市值:           4.65e+12 HKD
  偏差:               0.21%

  ✅ 验证通过, 偏差仅 0.21%

The tool accepts scientific notation (e.g., 9.11e9) and automatically formats large numbers into appropriate Chinese financial units while preserving exact decimal precision throughout the calculation.

Programmatic Python API

You can import the module directly for use in research scripts or Jupyter notebooks:

from tools import financial_rigor as fr

price = 510          # HKD per share

shares = 9.11e9      # total shares outstanding

reported = 4.65e12   # market cap from exchange data

result = fr.verify_market_cap(price, shares, reported, currency="HKD")

The function returns a boolean (True for pass) and prints the formatted verification report to stdout. This allows programmatic validation within larger data pipelines while maintaining visual audit trails.

Integration with Research Workflows

The tool is designed for integration with Claude Code skills. In skills/investment-research.md, the verification is invoked automatically during research generation:

```bash
python3 ~/ai-berkshire/tools/financial_rigor.py verify-market-cap \
    --price {price} --shares {shares} --reported {reported_cap} --currency HKD

Placeholders `{price}`, `{shares}`, and `{reported_cap}` are populated from extracted financial data, ensuring every research report includes a reproducible market-cap verification block that references exact decimal arithmetic.

## Interpreting Verification Results

The deviation percentage calculated by `verify_market_cap` follows strict financial audit standards:

- **Exact match**: Calculated and reported caps align to 28-digit precision.
- **Acceptable variance (≤ 1%)**: Typical for real-time data snapshots where price movements occur between quote and report generation.
- **Investigation required (> 5%)**: Indicates potential data errors, stock splits not accounted for, or currency mismatches that require manual review.

The use of `ROUND_HALF_EVEN` in the decimal context ensures that rounding operations minimize cumulative bias across large datasets, adhering to IEEE 754 standards for financial computing.

## Summary

- **[`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)** provides exact decimal arithmetic for market-cap verification without external dependencies.
- The **`exact()`** function prevents floating-point drift by stringifying inputs before `Decimal` conversion.
- **`verify_market_cap()`** computes deviation percentages using a 28-digit precision context with banker's rounding.
- CLI and Python APIs both support scientific notation and automatic formatting of large financial units.
- Integration with **[`skills/investment-research.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md)** enables automated validation in Claude Code research workflows.

## Frequently Asked Questions

### Why does financial_rigor.py stringify inputs before Decimal conversion?

The `exact()` function converts numbers to strings before instantiating `Decimal` objects to avoid inheriting binary floating-point errors. When Python creates a `Decimal` directly from a float (e.g., `Decimal(0.1)`), it captures the float's binary representation error. By using `Decimal(str(0.1))`, the conversion preserves the intended decimal value exactly as written.

### What precision does the decimal context use?

The module initializes a shared `_CTX` with **28-digit precision** and `ROUND_HALF_EVEN` rounding at lines 28-30. This exceeds standard double-precision floating-point (53 bits ≈ 15-17 decimal digits), providing sufficient headroom for accurate calculations involving trillions of dollars and billions of shares without rounding artifacts.

### How does the tool determine pass/fail thresholds?

The `verify_market_cap()` function implements three-tier validation: deviations **≤ 1%** return a pass status (✅), deviations between **1-5%** trigger a warning (⚠️), and deviations **> 5%** indicate a failure (❌). These thresholds are hardcoded in the reporting logic at lines 61-90 based on standard financial data tolerance levels.

### Can I use financial_rigor.py without installing external dependencies?

Yes. The module is intentionally dependency-free, using only Python's standard library (`decimal`, `argparse`, and `sys`). This design ensures the tool runs in any Python 3 environment without pip installations, making it suitable for embedded use in Claude Code skills, CI/CD pipelines, or secure research environments where third-party packages are restricted.

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