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

> Explore the AI Berkshire financial tools with our complete guide to zero-dependency validation. Discover this self-contained Python suite for exact-decimal enforcement via CLI.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: documentation
- Published: 2026-06-28

---

**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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) invocation succeeded and flags calculations that fall outside acceptable tolerance thresholds.

### Data Source Utilities

- **[`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py)**: Executes bulk equity filters (market-cap, ROE, dividend yield) against the internal CSV data store.
- **[`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py)**: Reads China A-share fundamentals from [`data/fundamentals.json`](https://github.com/xbtlin/ai-berkshire/blob/main/data/fundamentals.json) and provides specialized helpers for Chinese-market research.
- **[`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/xueqiu_scraper.py)**: Retrieves price and valuation snapshots from Xueqiu (雪球) for real-time sanity checks.

### Backtesting Framework

[`tools/momentum_backtest.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/momentum_backtest.py) and [`tools/momentum_backtest_v2.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.

```bash

# 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

```

```bash

# 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

```

```bash

# Cross-validate revenue figures across three data sources

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

```

```bash

# Run Benford's Law sanity check on financial digits

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

```

```bash

# Exact arithmetic calculator for ad-hoc expressions

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

```

```bash

# 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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) parses the final markdown to verify that all [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) checks passed before finalizing the report.

## Key Source Files Reference

| Tool | Purpose | Source Location |
|------|---------|-----------------|
| [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) | Core validation toolkit with exact-decimal arithmetic | [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) |
| [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) | Automated audit of markdown reports | [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) |
| [`morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/morningstar_fair_value.py) | Morningstar fair-value API wrapper | [`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py) |
| [`stock_screener.py`](https://github.com/xbtlin/ai-berkshire/blob/main/stock_screener.py) | Bulk equity filter utility | [`tools/stock_screener.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py) |
| [`ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/ashare_data.py) | China A-share fundamentals helpers | [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py) |
| [`xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/xueqiu_scraper.py) | Xueqiu price scraper | [`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/xueqiu_scraper.py) |
| [`momentum_backtest.py`](https://github.com/xbtlin/ai-berkshire/blob/main/momentum_backtest.py) | Momentum strategy back-testing | [`tools/momentum_backtest.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/momentum_backtest.py) |
| [`momentum_backtest_v2.py`](https://github.com/xbtlin/ai-berkshire/blob/main/momentum_backtest_v2.py) | Enhanced momentum back-testing | [`tools/momentum_backtest_v2.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/momentum_backtest_v2.py) |
| [`log-command.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/log-command.sh) | Timestamped command wrapper | [`tools/log-command.sh`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/log-command.sh) wrapper provides timestamped logging for manual reproducibility.

### What is the purpose of [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py)?

According to the AI Berkshire source code, [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) check invoked during the research process actually passed before the report is finalized.