How to Run the Financial Rigor Tools in AI Berkshire

The financial rigor tools in AI Berkshire are executed via the command-line utility at tools/financial_rigor.py, offering zero-dependency sub-commands for market-cap verification, valuation analysis, and Benford-law detection using exact 28-digit decimal arithmetic.

The AI Berkshire framework includes a self-contained Financial Rigor Toolkit located in the xbtlin/ai-berkshire repository that validates financial data without requiring external dependencies. This pure-Python utility relies exclusively on the standard library (argparse, json, math, decimal, sys) to ensure deterministic calculations across all validation checkpoints. Whether you need to verify market capitalizations or cross-validate revenue figures from multiple sources, you can run the financial rigor tools in AI Berkshire directly from the shell or import them into custom Python pipelines.

Command-Line Interface for Financial Validation

The tools/financial_rigor.py script exposes a modular CLI built with argparse sub-parsers. Each sub-command forwards parsed arguments to a dedicated implementation function that performs exact decimal arithmetic and prints human-readable reports with deviation percentages and status indicators.

Market-Cap Verification

Validate calculated market capitalization against reported values to detect discrepancies in price or share count data.

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

This command multiplies price by shares using a private Decimal context (_CTX) with 28-digit precision and compares the result against the reported value, flagging deviations that exceed validation thresholds.

Valuation Multiple Checks

Compute and verify standard valuation ratios including PE, PB, dividend yield, and free cash flow yields.

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

The tool outputs a structured report containing calculated ratios and emoji status badges indicating whether values fall within expected ranges.

Cross-Source Validation

Reconcile financial data points from multiple sources to identify reporting inconsistencies or data entry errors.

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

This sub-command compares values across dictionaries and reports deviation percentages between sources like annual reports and financial data providers.

Benford-Law Analysis

Detect potential data manipulation or anomalies by testing number distributions against Benford's Law.

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

The analysis examines the frequency distribution of leading digits to flag datasets that deviate significantly from expected logarithmic patterns.

Exact Arithmetic Calculator

Perform precise calculations without floating-point drift using the toolkit's internal Decimal context.

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

This utility converts scientific notation and arithmetic expressions to exact Decimal objects via the exact() helper function before computation.

Three-Scenario Valuation

Generate optimistic, neutral, and pessimistic valuation scenarios using variable growth rates and PE multiples.

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

The command calculates intrinsic value ranges across three scenarios, providing immediate visual feedback on whether the current price falls within fair value bands.

Programmatic Usage in Python

Import the validation functions directly to integrate financial rigor checks into custom analysis pipelines or automated research workflows.

from tools.financial_rigor import verify_market_cap, verify_valuation

# Market-cap check

result = verify_market_cap(price=510, shares=9.11e9, reported_cap=4.65e12, currency="HKD")
print("Market-cap verification passed:", result)

# Valuation ratios

ratios = verify_valuation(price=510, eps=23.5, bvps=120, fcf_per_share=18, dividend=2.4)
print(ratios)   # {'PE': 21.7, 'PB': 4.25, 'Dividend_Yield': 0.47, ...}

When imported, the module uses the same _CTX decimal context and exact() conversion logic to ensure consistency between CLI and programmatic execution.

Architecture and Precision Guarantees

The financial rigor tools implement exact decimal arithmetic through a private Decimal context (_CTX) configured with 28-digit precision. This design eliminates floating-point drift that could compromise financial calculations involving large numbers or precise ratios.

The internal flow follows this deterministic path:

1. CLI entry point → if __name__ == "__main__": main()
2. Argument parsing → Sub-parser selection (verify-market-cap, verify-valuation, etc.)
3. Decimal conversion → exact() function converts all inputs to Decimal objects
4. Core calculation → _CTX.multiply(), _CTX.divide(), or similar context operations
5. Result reporting → Formatted output with computed values and deviation warnings

This architecture ensures that running the financial rigor tools in AI Berkshire produces identical results across different Python versions and operating systems.

Integration with the AI Berkshire Ecosystem

The toolkit operates within a broader validation framework that includes companion utilities for audit aggregation and skill synchronization.

• report_audit.py — Aggregates audit results across multiple AI Berkshire skills; often invoked after rigor checks to compile final research reports with consolidated validation statuses.
• sync-codex-skills.py — Synchronizes Claude-Code skill definitions to ensure automatic calls to the rigor toolkit remain current with the latest validation logic.

These files reside in tools/ (core rigor logic) and scripts/ (skill synchronization) respectively, providing end-to-end workflow integration for rigorous financial data validation.

Summary

• Run the financial rigor tools in AI Berkshire via python3 tools/financial_rigor.py followed by sub-commands like verify-market-cap or cross-validate.
• Zero dependencies — requires only Python standard library modules (decimal, argparse, json).
• Exact arithmetic — uses 28-digit precision Decimal context (_CTX) to prevent floating-point errors.
• Programmatic access — import functions directly from tools.financial_rigor for custom pipeline integration.
• Ecosystem integration — works alongside report_audit.py for comprehensive audit reporting and sync-codex-skills.py for automated skill updates.

Frequently Asked Questions

What Python version is required to run the financial rigor tools?

The tools require Python 3.6 or higher due to the use of f-strings and decimal module features, though they are tested primarily on Python 3.9+ as specified in the AI Berkshire repository. No third-party packages are needed, making the toolkit compatible with standard Python installations across Windows, macOS, and Linux.

Can I use the financial rigor tools without installing any dependencies?

Yes. The tools/financial_rigor.py file is deliberately designed with zero third-party dependencies. It imports only from the Python standard library (argparse, json, math, decimal, sys), allowing you to run the tool immediately after cloning the xbtlin/ai-berkshire repository without creating a virtual environment or installing requirements.txt files.

How does the toolkit ensure calculation accuracy across different systems?

The toolkit creates a private Decimal context (_CTX) with 28-digit precision and uses the exact() function to convert all numeric inputs to Decimal objects before computation. This approach guarantees deterministic, platform-independent results that avoid floating-point representation errors common in standard IEEE 754 arithmetic.

Where are the validation results stored when running programmatically?

When called programmatically, functions like verify_market_cap() and verify_valuation() return dictionaries containing calculated ratios, deviation percentages, and boolean status flags. They do not automatically persist to disk; you must capture the return values and write them to files or databases as needed. For automated audit trails, chain these calls with report_audit.py to generate consolidated validation reports.

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