Documentation of Algorithms in AI Berkshire's `financial_rigor.py`: A Complete Technical Guide

The financial_rigor.py module in the xbtlin/ai-berkshire repository implements six production-grade financial algorithms built on Python's decimal module, providing exact arithmetic for market-cap verification, valuation metrics calculation, cross-source validation, Benford's law fraud detection, exact arithmetic evaluation, and multi-scenario valuation projection.

The AI Berkshire project provides a self-contained "Financial Rigor Toolkit" within tools/financial_rigor.py designed to eliminate floating-point drift in financial calculations. This module serves as the computational backbone for AI-driven investment research, ensuring reproducible, audit-ready results through high-precision decimal arithmetic and standardized validation patterns.

The Exact Decimal Foundation

Before examining the algorithms, understand the underlying infrastructure. The module establishes a high-precision Decimal context at line 28 (_CTX) configured with 28-digit precision and ROUND_HALF_EVEN rounding. The exact() helper function (lines 28-38) converts any input—including floats, strings, or scientific notation—to Decimal without precision loss, serving as the mandatory gateway for all numeric operations in the toolkit.

Six Core Algorithms in financial_rigor.py

Market-Cap Verification (verify_market_cap)

Located at lines 61-90, this algorithm validates whether price × shares matches a reported market-cap value. It uses exact() to create Decimal values, multiplies them via _CTX.multiply, computes percentage deviation, and triggers color-coded warnings at 5% and 1% thresholds. The function returns a boolean indicating whether the calculated cap falls within acceptable tolerance of the reported value.

Valuation Metrics Verification (verify_valuation)

Implemented at lines 98-160, this function derives PE, PB, ROE, P/FCF, dividend yield, and PS ratios from raw inputs. It computes ratios using _CTX.divide and scales percentages by 100 where required, returning results in a dictionary for downstream programmatic consumption. Each metric calculates only when its corresponding argument is supplied, making the function flexible for partial data scenarios.

Cross-Source Data Validation (cross_validate)

Found at lines 67-104, this algorithm aggregates numeric fields from multiple data sources, compares each to a median reference, and flags outliers beyond a configurable tolerance (default 2%). It converts all source values via exact(), computes the median (lines 78-81), and returns a consensus value alongside a boolean consistency flag indicating overall data agreement.

Benford's Law Fraud Detection (benford_check)

At lines 11-57, this statistical sanity-check detects possible data fabrication by comparing leading-digit distributions against expected Benford probabilities (_BENFORD). It requires at least 50 samples, computes observed frequencies, Mean Absolute Deviation (MAD), and Chi-square statistics, categorizing conformity into four levels to flag potentially manipulated datasets.

Exact Arithmetic Calculator (exact_calc)

Located at lines 88-110, this safely evaluates expressions like "510 * 9.11e9" using exact decimal arithmetic rather than native floating-point. It whitelists safe characters, evaluates with an empty __builtins__ namespace, converts results via exact(), and displays both formatted and raw decimal values for audit trails.

Three-Scenario Valuation Modeling (three_scenario_valuation)

Implemented at lines 20-58, this projects target share prices under optimistic, neutral, and pessimistic growth assumptions. It iteratively compounds EPS using _CTX.multiply and _CTX.add over a user-defined forecast horizon, multiplies by target PE multiples, and calculates percentage change versus current price. The function prints a formatted table and returns None.

Common Design Patterns in financial_rigor.py

All algorithms share four architectural patterns according to the source:

1. Input sanitization – Each public function receives primitive types (floats, strings, JSON) and immediately normalizes them using exact().

2. Exact arithmetic – All mathematical operations are performed via the global _CTX context, guaranteeing reproducible results.

3. Human-readable reporting – The fmt_number() helper converts large numbers into culturally appropriate units (e.g., "亿" for Chinese-style reporting) before printing.

4. Programmatic returns – Besides printing, functions return plain Python structures (dicts, bools, floats) for downstream consumption.

Practical Usage Examples

Below are practical invocations of the financial_rigor.py algorithms. All examples assume the repository root is on PYTHONPATH.

from tools import financial_rigor as fr

# Market-cap verification (returns bool)

ok = fr.verify_market_cap(
    price=510, 
    shares=9.11e9,
    reported_cap=4.65e12, 
    currency="HKD"
)
print("Cap OK:", ok)

# Valuation ratios (returns dict)

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

# Cross-validation of revenue figures

consensus = fr.cross_validate(
    field_name="Revenue",
    source_values={
        "AnnualReport": 7518, 
        "Yahoo": 7500, 
        "StockAnalysis": 7520
    },
    unit="亿", 
    tolerance_pct=2.0
)
print(consensus)

# Benford's law sanity check

benford = fr.benford_check([
    1234, 2345, 3456, 4567, 5678,
    6789, 7890, 8901, 9012, 1023
] * 6)
print(benford)

# Exact arithmetic calculator

result = fr.exact_calc("510 * 9.11e9")
print("Exact result:", result)

# Three-scenario valuation (prints table, returns None)

fr.three_scenario_valuation(
    current_price=510, 
    current_eps=23.5, 
    shares_billion=9.11,
    growth_optimistic=0.15, 
    growth_neutral=0.08, 
    growth_pessimistic=0.0,
    pe_optimistic=25, 
    pe_neutral=20, 
    pe_pessimistic=15,
    years=3, 
    currency="HKD"
)

Summary

• tools/financial_rigor.py implements six exact-decimal algorithms for financial analysis in the AI Berkshire repository.
• All calculations use Python's decimal module with 28-digit precision and ROUND_HALF_EVEN rounding to prevent floating-point errors.
• Key functions include verify_market_cap, verify_valuation, cross_validate, benford_check, exact_calc, and three_scenario_valuation.
• The toolkit follows consistent architectural patterns: input sanitization via exact(), exact arithmetic via _CTX, formatted output via fmt_number(), and structured returns for programmatic use.

Frequently Asked Questions

What precision does financial_rigor.py use for calculations?

The module initializes a global _CTX context with 28-digit precision and ROUND_HALF_EVEN rounding at line 28. All numeric operations route through this context using the exact() helper function, ensuring no floating-point drift occurs in financial calculations.

How does the Benford's Law check detect data fabrication?

The benford_check function compares the leading-digit distribution of a dataset against theoretical Benford probabilities. It computes Mean Absolute Deviation and Chi-square statistics, requiring at least 50 samples, and categorizes results into four conformity levels to flag potentially manipulated data.

Can I use financial_rigor.py for real-time market data validation?

Yes. The cross_validate function accepts multiple data source values (e.g., from different APIs), computes a median consensus, and flags outliers beyond a configurable tolerance (default 2%). This makes it suitable for real-time validation of streaming financial data.

Where is the exact decimal arithmetic implemented in the source code?

The foundation resides in lines 28-38 of tools/financial_rigor.py, where the _CTX context is defined. Individual algorithms like verify_market_cap (lines 61-90) and verify_valuation (lines 98-160) consume this infrastructure via the exact() function and _CTX operations.

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