How AI Berkshire Performs Financial Rigor Checks: A Deep Dive into the Validation Toolkit

AI Berkshire enforces data integrity throughout its research pipeline by using a deterministic, zero-dependency Financial Rigor Toolkit that validates market caps, valuation metrics, and cross-source data using exact decimal arithmetic.

The xbtlin/ai-berkshire repository implements a pure-Python validation layer in tools/financial_rigor.py to eliminate floating-point drift and guarantee mathematical accuracy across all financial calculations. Every check runs deterministically with no external APIs, producing both human-readable console output and structured Python dictionaries for downstream consumption.

The Financial Rigor Toolkit Architecture

The toolkit operates as a command-line utility built entirely on Python's decimal.Decimal engine. By centralizing all arithmetic in a shared _CTX context configured with prec=28 and ROUND_HALF_EVEN, the system avoids binary-float rounding errors that could distort buy or sell signals. The module exposes six core validation functions, each designed to catch specific categories of data corruption or calculation errors before they propagate into research reports.

Core Validation Checks

Market-Cap Verification

The verify_market_cap() function (lines 61-90) confirms that price × shares matches the reported market capitalization. The implementation converts all inputs to exact Decimal objects via an exact() helper, then multiplies price by shares using _CTX.multiply. It calculates the percentage deviation from the reported cap, emitting color-coded warnings if the deviation exceeds 5% (critical) or 1% (acceptable).

Valuation Metric Verification

The verify_valuation() function (lines 98-161) computes standard ratios including PE, PB, P/FCF, dividend yield, PS, and ROE. For each metric, the function converts inputs to Decimal, performs exact division or multiplication through the shared context, and stores results in a dictionary for downstream use. This ensures that valuation multiples are calculated with the same precision standards used in professional accounting software.

Cross-Source Data Validation

The cross_validate() function (lines 167-204) detects inconsistencies across multiple data providers. It accepts a JSON map of {source: value} pairs, computes a median reference value, and flags any source whose deviation from the median exceeds a configurable tolerance (defaulting to 2%). The function returns both a consensus value and a boolean all_consistent flag, allowing the research pipeline to automatically trigger manual audits when data sources disagree.

Benford's Law Statistical Testing

The benford_check() function (lines 211-281) provides a statistical sanity check for data fabrication. It extracts leading digits from positive values, compares the observed distribution against Benford’s expected distribution (_BENFORD), and calculates Mean Absolute Deviation (MAD) and chi-square statistics. Results are classified as Close, Acceptable, Marginal, or Non-conforming, giving researchers an immediate signal when numerical data appears artificially generated.

Exact Arithmetic and Scenario Modeling

The toolkit includes two specialized utilities for advanced calculations:

• exact_calc() (lines 288-314): Executes arbitrary arithmetic expressions with full decimal precision by whitelisting characters (0123456789.+-*/() eE) and using Python’s eval in a sandboxed globals dictionary. Results are wrapped with exact() and formatted for clean console output.

• three_scenario_valuation() (lines 316-388): Projects target prices under optimistic, neutral, and pessimistic assumptions. The function takes current price, EPS, share count, three growth rates, and three PE targets, compounds EPS over the configured horizon, and multiplies by scenario-specific PEs to generate target prices and percentage changes from the current price.

Decimal Precision Implementation

Financial calculations require exactness—a 0.01% deviation could alter a buy or sell signal. The toolkit avoids classic floating-point errors by routing all arithmetic through a centralized _CTX context with 28-digit precision and banker's rounding. This design ensures that operations like division or multiplication of large market-cap figures maintain accuracy to the last decimal place, eliminating the drift that plagues naive implementations using standard Python floats.

Integration with Research Workflows

The validation layer is wired into the Claude Code skill system via files in the skills/ directory. When a research skill gathers raw data (price, EPS, share count), it invokes the appropriate sub-command of financial_rigor.py and receives a boolean pass/fail result plus a metrics dictionary. This allows the pipeline to decide whether to continue processing, flag a data-quality issue, or request manual intervention.

The Report Audit tool (tools/report_audit.py) reuses the same validation logic to cross-check numbers in generated markdown reports, ensuring end-to-end traceability. Results from both tools are recorded in the final research output, creating an auditable trail of every validation step.

Command-Line Usage Examples

Verify market-cap calculations against reported values:

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

Validate valuation ratios including PE and dividend yield:

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

Cross-validate financial fields from multiple data providers:

python3 tools/financial_rigor.py cross-validate \
    --field revenue \
    --values '{"AnnualReport": 7518, "Yahoo": 7500, "StockAnalysis": 7520}' \
    --unit 亿

Run a Benford-Law sanity check on a dataset:

python3 tools/financial_rigor.py benford \
    --values '[1234, 2345, 3456, 4567, 5678, 6789, 7890]'

Perform exact arithmetic with full precision:

python3 tools/financial_rigor.py calc \
    --expr '510 * 9.11e9'

Generate three-scenario valuation projections:

python3 tools/financial_rigor.py three-scenario \
    --price 510 --eps 23.5 --shares 9.11 \
    --growth 0.15 0.08 0.00 \
    --pe 25 20 15 \
    --years 3 --currency HKD

Summary

• AI Berkshire financial rigor checks are implemented in tools/financial_rigor.py as a zero-dependency, deterministic toolkit.
• All calculations use decimal.Decimal with a 28-digit precision context to eliminate floating-point errors.
• The system validates market caps, valuation metrics, cross-source consistency, and Benford’s Law compliance.
• Validation results flow through the Claude Code skill layer and are audited by tools/report_audit.py for end-to-end traceability.
• Each check provides both human-readable output and structured Python dictionaries for automated pipeline decisions.

Frequently Asked Questions

What makes AI Berkshire financial rigor checks deterministic?

The toolkit contains no external API calls, random number generation, or network dependencies. Every function—from verify_market_cap() to three_scenario_valuation()—produces identical output for identical inputs by using fixed-precision decimal.Decimal arithmetic rather than floating-point operations, ensuring reproducible results across all research sessions.

How does the toolkit handle floating-point precision?

All arithmetic routes through a shared _CTX context configured with prec=28 and ROUND_HALF_EVEN. This context wraps every multiplication, division, and addition in exact decimal logic, preventing the binary-float rounding errors that accumulate in standard Python float calculations and could distort financial signals by fractions of a percent.

What is the tolerance threshold for cross-source validation?

The cross_validate() function uses a default tolerance of 2% when comparing values from different data providers against the median reference. Sources deviating beyond this threshold are flagged as inconsistent, though this parameter is configurable via command-line arguments to accommodate different data quality requirements.

How does Benford's Law detection prevent data fabrication?

The benford_check() function analyzes the distribution of leading digits in numerical datasets and compares them against the expected Benford distribution. Real financial data naturally follows this logarithmic distribution, while fabricated data typically shows uniform or anomalous leading-digit patterns. The function calculates Mean Absolute Deviation (MAD) and chi-square statistics to classify conformity levels, alerting researchers when data appears artificially constructed.

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