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

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 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 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 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 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 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 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 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

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

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

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

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

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 provides exact-decimal validation for market caps, valuation ratios, and Benford’s law compliance.
• report_audit.py creates systematic audit trails by sampling report data and rendering PASS/FAIL verdicts.
• xueqiu_scraper.py, stock_screener.py, momentum_backtest.py, and 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 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 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.

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