AI Berkshire Financial Tools Documentation: Complete Guide to Zero-Dependency Validation

AI Berkshire ships a self-contained suite of Python utilities in the tools/ directory that enforce exact-decimal financial validation through a command-line interface, requiring only the Python standard library.

The AI Berkshire financial tools documentation covers a modular architecture designed for rigorous equity research workflows. Located in the xbtlin/ai-berkshire repository, these utilities eliminate floating-point arithmetic errors and provide deterministic validation for market capitalization, valuation multiples, and cross-source data reconciliation.

Core Financial Tools Architecture

The toolkit resides entirely within the tools/ directory and operates without third-party dependencies. Each module performs a specific validation or data retrieval function, exposing a unified CLI interface that Claude Code skills invoke automatically.

Financial Rigor Engine

The tools/financial_rigor.py module serves as the core validation engine. In lines 31-38, the exact() function converts all numeric inputs to Decimal objects using a context configured with prec=28 and rounding=ROUND_HALF_EVEN. This ensures that market-cap calculations and valuation multiples avoid floating-point drift.

The module also provides fmt_number() (lines 40-54) for human-readable output formatting, supporting both Chinese units (亿, 万亿) and Western abbreviations (M, B, T). For cross-source verification, cross_validate() (lines 167-204) computes median references, tolerance bands, and consensus values across multiple data providers.

Report Audit System

tools/report_audit.py scans generated markdown research reports for missing citations, inconsistent units, and unvalidated financial figures. It verifies that every financial_rigor.py invocation succeeded and flags calculations that fall outside acceptable tolerance thresholds.

Data Source Utilities

• tools/morningstar_fair_value.py: Pulls raw fair-value estimates from Morningstar and normalizes them into JSON feeds for downstream consumption.
• tools/stock_screener.py: Executes bulk equity filters (market-cap, ROE, dividend yield) against the internal CSV data store.
• tools/ashare_data.py: Reads China A-share fundamentals from data/fundamentals.json and provides specialized helpers for Chinese-market research.
• tools/xueqiu_scraper.py: Retrieves price and valuation snapshots from Xueqiu (雪球) for real-time sanity checks.

Backtesting Framework

tools/momentum_backtest.py and tools/momentum_backtest_v2.py run historical momentum strategies against price series stored in data/. Both versions calculate rolling-window returns and Sharpe ratios using exact-decimal arithmetic.

Logging Utility

tools/log-command.sh provides a timestamped wrapper for CLI invocations, ensuring full reproducibility of research workflows.

Architectural Patterns and Design Philosophy

Exact Decimal Precision

All numeric operations funnel through the Decimal engine with a fixed 28-digit precision context. This design choice prevents the rounding errors common in standard floating-point arithmetic when calculating large market capitalizations or compound growth rates.

Modular Command Structure

The argparse sub-parser pattern maps each validation type to a dedicated function: verify-market-cap, verify-valuation, cross-validate, benford, calc, and three-scenario. This keeps the CLI surface clean while allowing granular access to specific financial checks.

Cross-Source Consensus Validation

Rather than trusting a single data provider, the toolkit computes consensus values across multiple sources. The cross_validate() function automatically flags discrepancies exceeding predefined tolerance bands, forcing manual review of conflicting data points.

CLI Usage Examples for AI Berkshire Financial Tools

The following commands demonstrate the most common invocations used in research skill scripts. Replace placeholder values with your target equity data.

# Verify market capitalization against price × shares outstanding

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

# Check valuation multiples (PE, PB, ROE, 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 revenue figures across three data sources

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

# Run Benford's Law sanity check on financial digits

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

# Exact arithmetic calculator for ad-hoc expressions

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

# Three-scenario valuation (optimistic/neutral/pessimistic)

python3 tools/financial_rigor.py three-scenario \
    --price 510 \
    --eps 23.5 \
    --shares 9.11e9 \
    --growth-optimistic 0.12 \
    --growth-neutral 0.07 \
    --growth-pessimistic 0.02 \
    --pe-optimistic 30 \
    --pe-neutral 20 \
    --pe-pessimistic 15 \
    --years 3 \
    --currency HKD

Each command prints a structured report including input parameters, computed results, and a final ✅ or ❌ status indicating tolerance compliance. Output can be copied verbatim into markdown research files.

Integration with Claude Code Skills

Research workflows in AI Berkshire follow a deterministic pipeline:

1. Skill Definition: Each skills/*.md file (e.g., skills/investment-research.md) contains bash-style code blocks that invoke the appropriate tool at validation checkpoints.
2. CLI Execution: The skill runner expands ~ to the repository root and executes the Python entry point.
3. Deterministic Output: Because every operation uses exact-decimal arithmetic, results are reproducible to the last digit, eliminating "LLM mental-math" errors.
4. Audit Trail: report_audit.py parses the final markdown to verify that all financial_rigor.py checks passed before finalizing the report.

Key Source Files Reference

Tool	Purpose	Source Location
financial_rigor.py	Core validation toolkit with exact-decimal arithmetic	tools/financial_rigor.py
report_audit.py	Automated audit of markdown reports	tools/report_audit.py
morningstar_fair_value.py	Morningstar fair-value API wrapper	tools/morningstar_fair_value.py
stock_screener.py	Bulk equity filter utility	tools/stock_screener.py
ashare_data.py	China A-share fundamentals helpers	tools/ashare_data.py
xueqiu_scraper.py	Xueqiu price scraper	tools/xueqiu_scraper.py
momentum_backtest.py	Momentum strategy back-testing	tools/momentum_backtest.py
momentum_backtest_v2.py	Enhanced momentum back-testing	tools/momentum_backtest_v2.py
log-command.sh	Timestamped command wrapper	tools/log-command.sh

Summary

• AI Berkshire financial tools reside in tools/ and require zero external dependencies, using only Python's standard library.
• Exact-decimal precision is enforced via Decimal context with 28-digit precision, preventing floating-point errors in financial calculations.
• Modular CLI interface exposes sub-commands for market-cap verification, valuation checks, cross-validation, and scenario analysis.
• Automated audit trail via report_audit.py ensures all financial figures in research reports pass validation checks.
• Direct skill integration allows Claude Code to invoke these tools deterministically, producing reproducible, audit-ready equity research.

Frequently Asked Questions

Do the AI Berkshire financial tools require external Python libraries?

No. The entire toolkit uses only the Python standard library (decimal, json, argparse, math, and built-in types). This zero-dependency design ensures the tools run in any Python 3 environment without installation steps or version conflicts.

How does financial_rigor.py prevent calculation errors?

The module initializes a Decimal context with prec=28 and rounding=ROUND_HALF_EVEN (as seen in the source at line 31). All numeric inputs pass through the exact() function (lines 31-38), which converts floats or strings to Decimal objects before any arithmetic operations, eliminating floating-point rounding errors common in financial calculations.

Can I run these tools outside of Claude Code?

Yes. While designed for integration with Claude Code skills, every tool functions as a standalone CLI script. Navigate to the repository root and execute python3 tools/<tool_name>.py --help to view available commands and parameters. The log-command.sh wrapper provides timestamped logging for manual reproducibility.

What is the purpose of report_audit.py?

According to the AI Berkshire source code, report_audit.py performs post-generation verification of research markdown files. It scans for missing citations, inconsistent units, and unvalidated financial figures, ensuring that every financial_rigor.py check invoked during the research process actually passed before the report is finalized.

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