How AI-Berkshire Handles Different Financial Instruments: A Modular CLI Architecture

AI-Berkshire handles different financial instruments through a modular pipeline of command-line tools that normalize data from diverse sources into a common schema, enabling unified validation across Chinese A-shares, global equities, and other asset classes.

The ai-berkshire repository provides a Python-based toolkit for quantitative investment research that abstracts instrument-specific complexity into dedicated fetcher modules. By isolating source-specific data acquisition while funneling all outputs through a shared validation layer, the codebase treats cross-market analysis as a normalization problem rather than a logic branching problem. This architecture demonstrates precisely how ai-berkshire handles different financial instruments through schema standardization, decimal-based arithmetic verification, and extensible command-line interfaces.

Instrument-Specific Data Acquisition

Rather than maintaining monolithic data connectors, ai-berkshire delegates acquisition to focused CLI tools that each handle a specific market or source type.

Chinese A-Shares via Tencent and Eastmoney APIs

The tools/ashare_data.py module serves as the primary interface for domestic Chinese equities. It retrieves real-time quotes, core five-year financials, and valuation metrics from Tencent 行情 and Eastmoney APIs.

The tool exposes a consistent CLI surface with four primary commands:

• quote – Real-time price and trading data
• financials – Historical financial statements
• valuation – PE, PB, market-cap calculations
• search – Symbol resolution

Raw responses are parsed and normalized into a common schema containing price, market_cap, pe, pb, and dividend fields before output.

# Retrieve real-time valuation metrics for Kweichow Moutai (600519)

python3 tools/ashare_data.py valuation 600519

# Search for symbols by name

python3 tools/ashare_data.py search "贵州茅台"

Global Equities via Xueqiu Scraping

For Hong Kong, US, and other international markets, tools/xueqiu_scraper.py provides a robust scraping layer that extracts price, PE, PB, and dividend yield from Xueqiu pages. The scraper operates without authentication and implements fallback logic to parse HTML directly when API endpoints are unavailable.

# Scrape data for Tencent Holdings (0700.HK)

python3 tools/xueqiu_scraper.py 0700.HK

Unified Validation and Cross-Instrument Analysis

Once normalized, all instrument data flows through tools/financial_rigor.py, a library-style CLI that performs arithmetic validation independent of the original data source. This module uses Python's Decimal type to eliminate floating-point errors, ensuring reliable calculations across any instrument that supplies numeric inputs.

Key validation functions include:

• verify_market_cap – Cross-checks price against shares outstanding and reported market capitalization
• verify_valuation – Validates PE, PB, and price-to-free-cash-flow ratios against underlying EPS and book value per share
• cross_validate – Compares metrics from multiple sources for consistency
• three_scenario_valuation – Projects intrinsic value across bull, base, and bear cases using user-defined growth and multiple assumptions

# Verify market cap calculation for any instrument

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

# Three-scenario DCF-style valuation (works for A-shares, HK, or US equities)

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

Screening and Multi-Instrument Aggregation

The tools/stock_screener.py module operates on locally cached symbol lists that can span multiple markets simultaneously. It applies quantitative filters—including PE range, market-cap thresholds, and sector classifications—to return subsets of tickers that meet specific investment criteria.

Because the screener consumes the normalized schema produced by the fetcher tools, it can filter across heterogeneous instrument types (A-shares alongside Hong Kong listings) without source-specific logic.

# Screen for large-cap equities with PE between 10 and 20

python3 tools/stock_screener.py --pe-min 10 --pe-max 20 --market-cap-min 100b

Cross-Cutting Quality Assurance

The tools/report_audit.py component enforces data-quality standards across all instrument types by scanning generated research reports for missing sources, inconsistent units, and formatting errors. According to the repository's AGENTS.md guidelines, the audit tool requires at least two independent sources for each data point, ensuring that validation logic applied to A-shares meets the same evidentiary standards as analysis applied to global equities.

Summary

• Modular fetchers isolate source complexity: ashare_data.py for Chinese A-shares via Tencent/Eastmoney, xueqiu_scraper.py for global equities.
• Schema normalization converts raw API responses into uniform fields (price, pe, pb, market_cap, dividend) enabling cross-market analysis.
• Decimal-based validation in financial_rigor.py provides arithmetic verification functions (verify_market_cap, three_scenario_valuation) that work with any numeric instrument data.
• Unified screening via stock_screener.py filters portfolios across multiple markets using the normalized data structure.
• Quality gates in report_audit.py enforce dual-source requirements and formatting standards regardless of instrument origin.

Frequently Asked Questions

How does ai-berkshire extend support to new financial instruments like bonds or ETFs?

New asset classes require only a new fetcher module that conforms to the common schema. For example, a bond fetcher would need to output price, market_cap (or notional value), and equivalent valuation metrics, which financial_rigor.py can then validate using existing decimal arithmetic functions. No modifications to the validation or screening layers are necessary.

What distinguishes the A-share data pipeline from global equity scraping in ai-berkshire?

tools/ashare_data.py utilizes authenticated APIs (Tencent 行情 and Eastmoney) with structured JSON responses, while tools/xueqiu_scraper.py relies on HTML parsing with API fallbacks. However, both tools normalize output to identical field names (price, pe, pb, etc.), ensuring that downstream validation logic remains source-agnostic.

Why does ai-berkshire use Decimal arithmetic for cross-instrument validation?

The financial_rigor.py module employs Python's Decimal type to prevent floating-point precision errors during financial calculations. This is critical when verifying market capitalizations or valuation ratios across instruments with different magnitudes (e.g., trillion-cap A-shares versus mid-cap Hong Kong listings), ensuring consistent precision regardless of currency or scale.

How does the report audit tool ensure data quality across different instrument types?

tools/report_audit.py scans final research documents for structural requirements defined in AGENTS.md, including mandatory dual-source citations and unit consistency. Because it operates on the final report rather than raw data, it enforces the same quality standards whether the underlying analysis covers Chinese equities, US securities, or mixed-asset portfolios.

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