AI-Berkshire Architecture Explained: A Three-Layer System for Master-Investor Research

AI-Berkshire implements a three-layer architecture that cleanly separates declarative research workflows (Skills), parallel AI agents emulating master investors (Agents), and rigorous financial verification utilities (Tools).

The xbtlin/ai-berkshire repository structures investment research as a reproducible, multi-agent system inspired by the analytical frameworks of Warren Buffett, Charlie Munger, and other value investing masters. This architecture ensures that every research request flows through specialized layers, from high-level intent definition to data verification and final report synthesis.

The Three-Layer Architecture

At its core, AI-Berkshire is organized into three distinct layers that handle what the user wants (Skills), how the analysis is performed (Agents), and how data integrity is guaranteed (Tools). This separation allows for parallel execution, viewpoint diversification, and mathematical rigor in financial calculations.

Skill Layer: Declarative Research Primitives

The Skill layer defines 18 concrete research workflows that act as entry points for user requests. Each skill is implemented as a markdown file in the skills/ directory, mapping natural language commands to structured research pipelines.

Key skills include:

• /investment-research – Full-company deep dives using the four-master framework (source: skills/investment-research.md)
• /investment-team – Multi-agent parallel research team coordination (source: skills/investment-team.md)
• /industry-funnel – Funnel-style stock-screening pipeline (source: skills/industry-funnel.md)
• /quality-screen – Quick "hard-filter" applying 7 rules to eliminate weak stocks (source: skills/quality-screen.md)
• /news-pulse – 10-minute price-movement attribution analysis (source: skills/news-pulse.md)

Additional skills cover portfolio analysis, thesis tracking, earnings reviews, industry chain scans, and private company research. According to the repository's README, these skills register as commands in AI coding assistants like Codex or Claude Code.

Agent Layer: Parallel Master-Investor Viewpoints

When a skill is invoked, the Agent layer spawns four parallel "researchers" that independently gather data, validate sources, and produce partial conclusions. Each agent adopts a distinct master-investor perspective:

1. 段永平 (Duan Yongping) – Focuses on business model quality and moat durability
2. 巴菲特 (Buffett) – Emphasizes economic moats and margin of safety
3. 芒格 (Munger) – Applies inverse thinking and mental models
4. 李录 (Li Lu) – Analyzes through the lens of civilization-level trends

These agents execute independent web searches, cross-validate data against multiple sources, and challenge each other's assumptions. A "Team Lead" Agent then aggregates their outputs into a unified structured report containing a "四维评分总表" (four-dimensional scoring matrix) summarizing each viewpoint.

This parallel architecture is visualized in assets/architecture.mmd (Mermaid source) and rendered in assets/architecture.png.

Tool Layer: Financial Rigor and Data Integrity

The Tool layer provides precise, reproducible Python utilities that perform financial calculations and data-quality checks. Implemented as scripts under tools/, these utilities guarantee that all numerical work is auditable and exact.

Core utilities in tools/financial_rigor.py include:

• verify-market-cap – Sanity-checks market capitalization using price × shares outstanding, with tolerance thresholds
• cross-validate – Compares a datum across multiple sources and raises alerts if deviation exceeds defined limits
• three-scenario – Generates optimistic, base-case, and pessimistic valuation targets
• benford – Applies Benford's Law to detect statistical anomalies in financial tables

All calculations use Python's decimal.Decimal to prevent floating-point errors. Additional integrity checkers reside in tools/report_audit.py and data fetchers in tools/ashare_data.py.

How the Layers Interact in Practice

The architecture comes together through command-line interfaces that route user requests through the three layers. Below are practical examples showing the system flow:

Install the skill set (once):

git clone https://github.com/xbtlin/ai-berkshire.git
cd ai-berkshire
./scripts/install-codex-skills.sh   # registers all markdown skills as Codex skills

Run a single-skill deep research (Skill + Agent + Tool layers):

codex /investment-research 腾讯

# → launches four agents simultaneously

# → includes market-cap verification via financial_rigor.py

# → outputs structured report with Team Lead synthesis

Run parallel-team research:

codex /investment-team 美团

# → four agents execute simultaneously

# → final output contains "四维评分总表" (four-dimensional scoring table)

Use the Tool layer directly for verification:

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

# → prints: "✅ 验证通过, 偏差仅 0.08%"

Key Implementation Files

Path	Purpose
skills/	Directory containing all 18 skill definitions (markdown sources)
tools/financial_rigor.py	Core financial calculation utilities with Decimal precision
tools/report_audit.py	Report integrity checker automatically invoked by agents
assets/architecture.mmd	Mermaid source diagram showing layer interactions
scripts/sync-codex-skills.py	Synchronization script maintaining codex-skills/ packages
codex-skills/	Generated directory containing Codex-compatible skill packages

Summary

• AI-Berkshire architecture separates concerns into three layers: Skills (declarative workflows), Agents (parallel master-investor viewpoints), and Tools (financial verification).
• 18 markdown-defined skills in skills/ provide research primitives ranging from deep-dive analysis to quick quality screens.
• Four parallel agents emulate Duan Yongping, Buffett, Munger, and Li Lu, with a Team Lead synthesizing their outputs into unified reports.
• Python utilities in tools/financial_rigor.py ensure reproducibility using decimal.Decimal for exact arithmetic, cross-validation, and statistical anomaly detection.
• The system is designed for integration with AI coding assistants like Codex, with skills auto-generated from markdown sources via scripts/sync-codex-skills.py.

Frequently Asked Questions

What makes AI-Berkshire different from other investment AI systems?

Unlike monolithic AI tools, AI-Berkshire implements a multi-agent architecture where four specialized agents operate independently using distinct investment philosophies. This parallel structure, combined with mandatory tool-layer verification via financial_rigor.py, ensures that conclusions are cross-validated and mathematically sound rather than relying on single-model outputs.

How does the Tool layer ensure data accuracy?

The Tool layer mandates exact arithmetic using Python's decimal.Decimal instead of floating-point math. Utilities like verify-market-cap and cross-validate automatically check calculations against source data with configurable tolerance thresholds. The benford function provides statistical validation to detect potential data anomalies in financial statements.

Can I use AI-Berkshire without the Codex client?

While the repository provides codex-skills/ packages and scripts/install-codex-skills.sh for Codex integration, the underlying markdown skill definitions in skills/ and Python tools in tools/ are platform-agnostic. You can invoke the Python utilities directly or adapt the markdown workflows for Claude Code or other AI assistants that support skill definitions.

Which file should I modify to add a new investment skill?

Create a new markdown file in the skills/ directory following the existing structure (see skills/investment-research.md as a template). After editing, run scripts/sync-codex-skills.py to regenerate the Codex-compatible packages in codex-skills/. The architecture automatically picks up new skills from the skills/ directory during the synchronization process.

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