Can You Use financial_rigor.py Independently? Complete Guide to the Self-Contained Finance Tool

Yes, financial_rigor.py is a fully self-contained Python module with zero external dependencies that functions as both a standalone CLI utility and an importable library for exact-decimal financial analysis.

The financial_rigor.py tool in the xbtlin/ai-berkshire repository provides institutional-grade financial validation utilities that operate without any external dependencies. Because it relies exclusively on the Python standard library, you can deploy this single file into any Python 3.7+ environment to perform market-cap verification, valuation ratio analysis, cross-source data validation, and Benford-law anomaly detection with guaranteed 28-digit precision.

Zero-Dependency Architecture

The module requires no pip install commands or virtual environment setup. As implemented in tools/financial_rigor.py, the script uses only standard library imports (decimal, argparse, json, math, collections, re, and sys), making it truly portable across platforms. There is no hidden state; each function is pure—aside from its printed output—and they all return machine-readable results that can be programmatically consumed.

Running financial_rigor.py from the Command Line

The if __name__ == "__main__" block provides a full CLI interface using argparse. You can invoke the tool directly without installation:

# Verify market capitalization

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

# Calculate valuation ratios

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

# Cross-validate data sources

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

# Benford's law analysis

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

# Exact calculator

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

# Three-scenario valuation model

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

Importing financial_rigor.py as a Python Library

All public functions are defined at module level and return machine-readable data structures (dictionaries, booleans, or floats) alongside printed output. Import the module into your analysis scripts:

from tools.financial_rigor import (
    verify_market_cap,
    verify_valuation,
    cross_validate,
    benford_check,
    exact_calc,
    three_scenario_valuation,
)

# Market-cap verification

ok = verify_market_cap(
    price=510.0,
    shares=9.11e9,
    reported_cap=4.65e12,
    currency="HKD",
)
print("Market-cap check passed?", ok)

# Valuation ratios

ratios = verify_valuation(
    price=510,
    eps=23.5,
    bvps=120,
    fcf_per_share=18,
    dividend=2.4,
)
print("Computed ratios:", ratios)

# Cross-source validation

consensus = cross_validate(
    field_name="revenue",
    source_values={"AnnualReport": 7518, "Yahoo": 7500, "StockAnalysis": 7520},
    unit="亿",
    tolerance_pct=2.0,
)
print("Consensus value:", consensus)

# Benford-law check

benford_result = benford_check([1234, 2345, 3456, 4567, 5678, 6789, 7890, 8912])
print("Benford outcome:", benford_result)

# Exact arithmetic calculator

calc_result = exact_calc("510 * 9.11e9")
print("Exact calc result:", calc_result)

# Three-scenario valuation

scenario = 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.00,
    pe_optimistic=25,
    pe_neutral=20,
    pe_pessimistic=15,
    years=3,
    currency="HKD",
)
print("Three-scenario output:", scenario)

Available Financial Utilities

The module exposes six core functions for rigorous financial analysis:

• verify_market_cap – Validates reported market capitalization against calculated price × shares outstanding
• verify_valuation – Computes PE ratio, price-to-book, price-to-FCF, and dividend yield
• cross_validate – Reconciles numerical values across multiple data sources with configurable tolerance
• benford_check – Applies Benford's Law to detect potential data anomalies in financial series
• exact_calc – Evaluates mathematical expressions using exact Decimal arithmetic to avoid floating-point drift
• three_scenario_valuation – Projects bear/base/bull case valuations using growth and PE assumptions

Precision Guarantees and Implementation Details

According to the source code in tools/financial_rigor.py, the module establishes a shared Decimal context (_CTX) configured with 28-digit precision and ROUND_HALF_EVEN rounding. This ensures reproducible arithmetic across all functions regardless of platform.

The helper function exact() converts floats, strings, or existing Decimal objects into exact-precision Decimals, eliminating the floating-point drift common in financial calculations. Meanwhile, fmt_number() provides uniform human-readable formatting (supporting 亿, 万亿, T, B, M suffixes) while functions return raw numeric results for programmatic consumption.

Summary

• financial_rigor.py requires no external dependencies and runs on Python 3.7+
• Use it as a CLI tool via python3 tools/financial_rigor.py [command] or as a library via standard imports
• All six core functions (verify_market_cap, verify_valuation, cross_validate, benford_check, exact_calc, three_scenario_valuation) return machine-readable data structures
• Built-in 28-digit Decimal precision guarantees reproducible financial arithmetic
• The tools/report_audit.py file in the repository demonstrates integration patterns for automated validation workflows

Frequently Asked Questions

Can I use financial_rigor.py without installing the full ai-berkshire repository?

Yes. The module is entirely self-contained. You only need the single file tools/financial_rigor.py and a Python 3.7+ interpreter. There are no imports from other parts of the repository, allowing you to copy the file into any project or run it standalone.

Does financial_rigor.py require external packages like NumPy or Pandas?

No. The tool uses only the Python standard library (specifically decimal, argparse, json, math, collections, re, and sys). This design choice makes it deployable in restricted environments where external package installation is impossible.

How does the tool prevent floating-point errors in financial calculations?

The source code creates a dedicated Decimal context with 28-digit precision and ROUND_HALF_EVEN rounding. The exact() helper converts all inputs to Decimal objects before calculation, ensuring that operations like verify_market_cap and exact_calc avoid the binary floating-point representation errors inherent in standard Python floats.

Can I integrate financial_rigor.py into an automated reporting pipeline?

Yes. While the functions print human-readable reports to stdout, they simultaneously return dictionaries, booleans, and floats that can be logged, stored, or passed to downstream processors. The tools/report_audit.py file in the ai-berkshire repository demonstrates this pattern, consuming financial_rigor outputs for automated report validation.

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