# What Is the Purpose of the Tool Files in AI Berkshire? A Complete Guide

> Discover the purpose of tool files in AI Berkshire. These Python utilities validate, audit, and enrich financial data for Claude Code skills, ensuring accuracy in research reports.

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

---

**The tool files in AI Berkshire are self-contained Python command-line utilities that provide the validation infrastructure for Claude Code skills to verify, audit, and enrich financial data before it appears in research reports.**

The `tools/` directory in the [xbtlin/ai-berkshire](https://github.com/xbtlin/ai-berkshire) repository houses a collection of dependency-free scripts that form the mathematical backbone of the AI-driven research pipeline. These utilities ensure every figure in a generated report is reproducible, auditable, and compliant with financial rigor standards.

## What Are the AI Berkshire Tool Files?

The tool files are standalone Python scripts located in the `tools/` directory. Unlike the research generation logic found elsewhere in the repository, these utilities serve as the **validation layer** that Claude Code skills invoke at critical checkpoints. Each tool uses only the Python standard library, allowing execution in minimal CI environments without external dependencies.

According to the source code, the tools perform three primary functions:

- **Data validation** – Precise numeric checks using `Decimal` arithmetic to eliminate floating-point errors
- **Report auditing** – Random sampling and systematic verification of published figures
- **Data acquisition** – Lightweight scraping and normalization of raw market data

## The Six Core Tool Files and Their Functions

### financial_rigor.py

The [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) file implements exact-decimal financial sanity checks. It validates market-cap calculations, valuation ratios (PE, PB, P/FCF), and Benford’s law consistency.

Key capabilities include:

- `verify-market-cap` – Cross-checks price × shares against reported market cap
- `verify-valuation` – Computes PE, PB, dividend yield, and FCF ratios
- `benford` – Performs first-digit analysis to detect data anomalies

This tool guarantees that numbers in reports are mathematically sound and reproducible.

### report_audit.py

The [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py) file provides systematic quality control for published research. It randomly extracts approximately 15% of financial figures from a markdown report, formats a JSON template for manual cross-checking, and renders a final PASS/FAIL verdict.

Workflow steps:

1. `extract` – Samples data points and generates a verification template
2. Manual review – A reviewer fills in fetched values from external sources
3. `verdict` – Compares reported vs. fetched values and exits with code `0` (PASS) or `1` (FAIL)

This creates an audit trail that each report must pass before publication.

### xueqiu_scraper.py

The [`tools/xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/xueqiu_scraper.py) file pulls raw market data from public sites like Xueqiu without requiring external dependencies such as `requests` or `beautifulsoup4`. It supplies the source numbers that the audit tool expects, ensuring the validation pipeline has fresh inputs.

### stock_screener.py

The [`tools/stock_screener.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py) file provides quick stock-screening filters (e.g., by PE ratio or market cap) that can be reused in research notebooks. This enables rapid hypothesis testing without needing a full analytics stack.

### momentum_backtest.py

The [`tools/momentum_backtest.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/momentum_backtest.py) file implements a momentum-strategy back-testing framework with both single-stock and multi-stock variants. Researchers use this to validate trading hypotheses before including them in reports.

### ashare_data.py

The [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/ashare_data.py) file normalizes Chinese A-share financial statements, handling unit conversions and formatting conventions specific to local markets. This makes downstream validation steps tolerant to regional data variations.

## How the Tools Integrate with the Claude Code Workflow

The tool files do not run continuously as services. Instead, Claude Code skills invoke them as subprocesses at specific validation checkpoints:

1. **Research phase** – Skills gather narrative and raw data
2. **Validation checkpoint** – The skill calls a tool (e.g., `python3 tools/financial_rigor.py verify-market-cap`)
3. **Tool execution** – The tool prints a human-readable summary and returns an exit code
4. **Pipeline decision** – Exit code `0` allows the workflow to continue; non-zero triggers a failure flag

For comprehensive audits, the `report_audit` tool extracts data points into a JSON structure. After manual cross-checking against sources like Macrotrends or StockAnalysis, the `verdict` subcommand determines whether the report meets publication standards.

## Why Dependency-Free Design Matters

Every tool in the `tools/` directory uses only the Python standard library. This architectural choice serves two critical purposes:

- **CI/CD compatibility** – Scripts run in minimal container environments without pip installations
- **Reliability** – Claude Code skills can call tools from any machine without managing virtual environments or dependency conflicts

This design ensures that financial validation remains robust even when external package repositories are unavailable.

## Practical Command-Line Examples

### Verify Market Cap Calculation

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

```

This computes the theoretical market cap, calculates percentage deviation from the reported figure, and exits with code `0` if within tolerance.

### Run Full Valuation Check

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

```

The output displays PE, PB, P/FCF, and dividend yield using exact `Decimal` arithmetic to prevent floating-point errors.

### Extract Audit Points from a Report

```bash
python3 tools/report_audit.py extract \
  --report reports/腾讯/腾讯-research-20260408.md \
  --ratio 0.15 \
  --seed 42

```

This randomly samples 15% of financial figures and emits a JSON template for manual verification.

### Render Audit Verdict

```bash
python3 tools/report_audit.py verdict \
  --results '[{"id":1,"label":"营业收入","reported_value":7518,"unit":"亿","fetched_value":7518,"fetched_source":"macrotrends","fetched_value2":7500,"fetched_source2":"stockanalysis"}]' \
  --report "腾讯‑Research‑20260408"

```

The tool prints a colored PASS/FAIL summary and exits with code `0` (PASS) or `1` (FAIL).

### Benford’s Law Sanity Check

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

```

This reports the Mean Absolute Deviation (MAD), chi-square statistic, and conformity verdict to detect anomalous data distributions.

## Summary

- The **tool files** in AI Berkshire are self-contained Python utilities under `tools/` that enforce financial rigor and data quality.
- **[`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py)** provides exact-decimal validation for market caps, valuation ratios, and Benford’s law compliance.
- **[`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py)** creates systematic audit trails by sampling report data and rendering PASS/FAIL verdicts.
- **[`xueqiu_scraper.py`](https://github.com/xbtlin/ai-berkshire/blob/main/xueqiu_scraper.py)**, **[`stock_screener.py`](https://github.com/xbtlin/ai-berkshire/blob/main/stock_screener.py)**, **[`momentum_backtest.py`](https://github.com/xbtlin/ai-berkshire/blob/main/momentum_backtest.py)**, and **[`ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/ashare_data.py)** handle data acquisition, screening, back-testing, and normalization.
- All tools use **only the Python standard library**, ensuring reliable execution in minimal environments.
- Claude Code skills invoke these tools at validation checkpoints, using exit codes (`0` = pass, non-zero = fail) to gate the research pipeline.

## Frequently Asked Questions

### What is the purpose of the tool files in AI Berkshire?

The tool files provide the **validation infrastructure** that Claude Code skills use to verify, audit, and enrich financial data before it appears in research reports. They ensure mathematical accuracy, create audit trails, and normalize raw market data while remaining dependency-free.

### How does the report_audit.py tool ensure report accuracy?

The [`report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/report_audit.py) tool randomly extracts approximately 15% of financial figures from a markdown report using the `extract` subcommand, generates a JSON template for manual cross-checking against external sources, and then uses the `verdict` subcommand to compare reported values against fetched values. It exits with code `0` for PASS and `1` for FAIL, creating a systematic quality gate.

### Why are the AI Berkshire tools designed without external dependencies?

The tools use only the Python standard library to ensure they can execute in minimal CI/CD environments without pip installations or virtual environment management. This dependency-free design guarantees that Claude Code skills can invoke validation scripts reliably from any machine, regardless of external package availability.

### Which tool should I use to validate market capitalization calculations?

Use [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) with the `verify-market-cap` subcommand. It accepts `--price`, `--shares`, and `--reported` arguments, performs exact `Decimal` arithmetic to calculate the theoretical market cap, and reports the percentage deviation with a pass/fail determination.