# xbtlin/ai-berkshire architecture

> Architecture diagram of the GitHub repository xbtlin/ai-berkshire, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xbtlin/ai-berkshire
- Repository: https://github.com/xbtlin/ai-berkshire

## Overview

#### Purpose and Entry Points
AI Berkshire is a repository of AI-agent investment-research workflows, reusable skills/prompts, precision financial tools, and generated research artifacts. It is not a deployed application or service. Users install skills into Claude Code or Codex, then invoke research workflows by name. Primary entry points are `skills/*.md` for Claude Code, `codex-skills/*/SKILL.md` for Codex, and optional Codex slash prompts in `codex-prompts/*.md`.

#### Canonical Workflow Distribution
The Claude-oriented Markdown skills are the canonical workflow definitions; Codex skill packages are generated copies. Installation scripts put these assets into client-specific global directories, while synchronization scripts maintain parity.
- `skills/investment-research.md`
- `scripts/sync-codex-skills.py`
- `scripts/install-codex-skills.sh`

This boundary matters: workflow edits should originate in `skills/`, then be propagated rather than independently changed in generated Codex skill directories.

#### Research Orchestration Layer
Skills encode task-specific control flows for company research, earnings review, industry discovery, screening, portfolio review, news triage, and publication. The deepest flows use four independent value-investing perspectives—business model, financial/valuation, contrarian risk, and long-term trend—then synthesize a decision. Team-oriented workflows delegate parallel agent work; lightweight workflows go directly to tools and structured outputs.
- `skills/investment-team.md`
- `skills/earnings-team.md`
- `skills/industry-funnel.md`

#### Data Acquisition and Quantitative Validation
The tool layer provides local Python CLIs for financial calculations, data retrieval, screens, backtests, and report checking. `financial_rigor.py` is the central correctness boundary: it uses `decimal.Decimal` for market-cap, valuation, cross-source, and scenario calculations, preventing LLM arithmetic or unit errors. Data inputs are persisted locally as CSV/JSON rather than behind a database.
- `tools/financial_rigor.py`
- `tools/stock_screener.py`
- `data/fundamentals.json`

External data is obtained by tools or agent research from market/public sources; visible integrations include Morningstar-oriented data, A-share/Taiwan-stock access, and Xueqiu scraping. No always-on data pipeline or credentials-managed service is represented in the tree.
- `tools/morningstar_fair_value.py`
- `tools/ashare_data.py`
- `tools/xueqiu_scraper.py`

#### Evidence, Audit, and Reproducibility
High-stakes reports commonly preserve a research package alongside the prose: original PDFs/text, source registries, assumptions, model inputs, calculation outputs, audit samples, verdicts, and Python reproduction scripts. This creates a file-based provenance boundary between claims, inputs, and independently rerunnable verification.
- `reports/腾讯/审计-20260906/复核计算.py`
- `reports/泡泡玛特/审计-20260906/audit-results.json`
- `reports/快手/《看懂快手》-20260906/审计/reproduce.py`

Generic report-level quality checks are implemented separately and tested, supporting consistency across the large report corpus.
- `tools/report_audit.py`
- `tests/test_financial_rigor.py`
- `tests/test_report_audit.py`

#### Research Corpus and Indexing
`reports/` is the principal product store: Markdown investment reports organized by company, sector, screening universe, and recurring research series. It also contains generated audit evidence and occasional publishable PDF artifacts. Index files expose the corpus; `reports_index.py` updates README/index material rather than serving a runtime search API.
- `reports/README.md`
- `reports/index.json`
- `tools/reports_index.py`

#### Runtime and Operational Model
The material runtimes are Python 3 for tools, synchronization, audits, and report builds; shell/batch scripts for installation; and user-installed Claude Code or OpenAI Codex clients for agent execution. One specialized publication pipeline builds a bilingual survey manuscript into LaTeX/PDF outputs.
- `reports/RSI-survey-20260906/build.py`
- `reports/RSI-survey-20260906/arxiv/main.tex`
- `output/pdf/rsi-survey-en-20260906.pdf`

There is no web server, database, queue, container, or cloud infrastructure represented. GitHub provides repository hosting and issue intake; agent clients and external public/market-data sources are the primary execution dependencies.

Main entry points: [`reports/README.md`](https://github.com/xbtlin/ai-berkshire/blob/main/reports/README.md) (Research report corpus), [`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py) (Market-data tools), [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (Financial rigor), [`data/fundamentals.json`](https://github.com/xbtlin/ai-berkshire/blob/main/data/fundamentals.json) (Fundamentals data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Workflow Distribution"]
  node_claude_skills["Claude skill definitions<br/>Markdown workflows"]
  node_team_workflows["Team research workflows<br/>Markdown workflows<br/>[investment-team.md]"]
  node_earnings_workflow["Earnings team workflow<br/>Markdown workflow<br/>[earnings-team.md]"]
  node_industry_workflow["Industry funnel workflow<br/>Markdown workflow<br/>[industry-funnel.md]"]
  node_codex_sync["Codex skill synchronizer<br/>Python script"]
  node_codex_install["Codex installer<br/>Shell script"]
end

subgraph group_research["Research Execution"]
  node_agent_clients{{"Claude Code and Codex<br/>User-installed clients"}}
  node_external_sources{{"Public market sources<br/>External data"}}
  node_data_tools["Market-data tools<br/>Python CLIs"]
  node_financial_rigor["Financial rigor<br/>Python CLI<br/>[financial_rigor.py]"]
  node_screener["Stock screener<br/>Python CLI<br/>[stock_screener.py]"]
  node_fundamentals[("Fundamentals data<br/>JSON data<br/>[fundamentals.json]")]
  node_report_audit["Report quality audit<br/>Python CLI<br/>[report_audit.py]"]
end

subgraph group_artifacts["Research Artifacts"]
  node_reports["Research report corpus<br/>Markdown and evidence store<br/>[README.md]"]
  node_audit_evidence["Audit and reproduction packages<br/>File-based provenance<br/>[复核计算.py]"]
  node_report_index["Corpus indexes<br/>JSON and index builder<br/>[index.json]"]
  node_publication_build["RSI survey build<br/>Python publication pipeline<br/>[build.py]"]
  node_pdf_output["Published survey PDF<br/>PDF artifact"]
end

node_claude_skills -->|"source for generation"| node_codex_sync
node_codex_sync -->|"generated skills"| node_codex_install
node_codex_install -->|"installs into"| node_agent_clients
node_claude_skills -->|"installed for Claude"| node_agent_clients
node_team_workflows -->|"invoked by"| node_agent_clients
node_earnings_workflow -->|"invoked by"| node_agent_clients
node_industry_workflow -->|"invoked by"| node_agent_clients
node_agent_clients -->|"uses"| node_data_tools
node_agent_clients -->|"validates calculations with"| node_financial_rigor
node_agent_clients -->|"runs"| node_screener
node_agent_clients -->|"creates research"| node_reports
node_external_sources -->|"data retrieval"| node_data_tools
node_data_tools -->|"persists inputs"| node_fundamentals
node_fundamentals -->|"calculation inputs"| node_financial_rigor
node_screener -->|"screens"| node_fundamentals
node_financial_rigor -->|"calculation outputs"| node_audit_evidence
node_reports -->|"preserves provenance"| node_audit_evidence
node_report_audit -->|"checks"| node_reports
node_reports -->|"indexed by"| node_report_index
node_reports -->|"survey source"| node_publication_build
node_publication_build -->|"builds"| node_pdf_output

click node_claude_skills "https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md"
click node_team_workflows "https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md"
click node_earnings_workflow "https://github.com/xbtlin/ai-berkshire/blob/main/skills/earnings-team.md"
click node_industry_workflow "https://github.com/xbtlin/ai-berkshire/blob/main/skills/industry-funnel.md"
click node_codex_sync "https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py"
click node_codex_install "https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh"
click node_data_tools "https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py"
click node_financial_rigor "https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py"
click node_screener "https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py"
click node_fundamentals "https://github.com/xbtlin/ai-berkshire/blob/main/data/fundamentals.json"
click node_reports "https://github.com/xbtlin/ai-berkshire/blob/main/reports/README.md"
click node_audit_evidence "https://github.com/xbtlin/ai-berkshire/blob/main/reports/%E8%85%BE%E8%AE%AF/%E5%AE%A1%E8%AE%A1-20260906/%E5%A4%8D%E6%A0%B8%E8%AE%A1%E7%AE%97.py"
click node_report_audit "https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py"
click node_report_index "https://github.com/xbtlin/ai-berkshire/blob/main/reports/index.json"
click node_publication_build "https://github.com/xbtlin/ai-berkshire/blob/main/reports/RSI-survey-20260906/build.py"
click node_pdf_output "https://github.com/xbtlin/ai-berkshire/blob/main/output/pdf/rsi-survey-en-20260906.pdf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_skills,node_team_workflows,node_earnings_workflow,node_industry_workflow,node_codex_sync,node_codex_install toneBlue
class node_agent_clients,node_external_sources,node_data_tools,node_financial_rigor,node_screener,node_fundamentals,node_report_audit toneAmber
class node_reports,node_audit_evidence,node_report_index,node_publication_build,node_pdf_output toneMint
```

## Components

### Workflow Distribution

Canonical skills and generated client packages.

- [Claude skill definitions](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-research.md): Markdown workflows · Canonical definitions edited by authors. · `skills/investment-research.md`
- [Team research workflows](https://github.com/xbtlin/ai-berkshire/blob/main/skills/investment-team.md): Markdown workflows · Parallel perspectives are synthesized into an investment decision. · `skills/investment-team.md`
- [Earnings team workflow](https://github.com/xbtlin/ai-berkshire/blob/main/skills/earnings-team.md): Markdown workflow · `skills/earnings-team.md`
- [Industry funnel workflow](https://github.com/xbtlin/ai-berkshire/blob/main/skills/industry-funnel.md): Markdown workflow · `skills/industry-funnel.md`
- [Codex skill synchronizer](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py): Python script · Propagates canonical Claude skills into generated Codex packages. · `scripts/sync-codex-skills.py`
- [Codex installer](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/install-codex-skills.sh): Shell script · Installs skill assets into the user's Codex directory. · `scripts/install-codex-skills.sh`

### Research Execution

Agent-led workflows and local validation tools.

- **Claude Code and Codex**: User-installed clients · Users invoke installed workflows by name.
- **Public market sources**: External data · Agent research and tools obtain market and public information.
- [Market-data tools](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py): Python CLIs · Retrieves Morningstar, A-share/Taiwan, and Xueqiu-oriented data. · `tools/morningstar_fair_value.py`
- [Financial rigor](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py): Python CLI · Decimal-based valuation, cross-source, and scenario correctness boundary. · `tools/financial_rigor.py`
- [Stock screener](https://github.com/xbtlin/ai-berkshire/blob/main/tools/stock_screener.py): Python CLI · `tools/stock_screener.py`
- [Fundamentals data](https://github.com/xbtlin/ai-berkshire/blob/main/data/fundamentals.json): JSON data · Local persisted financial inputs. · `data/fundamentals.json`
- [Report quality audit](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py): Python CLI · Applies generic report-level consistency checks. · `tools/report_audit.py`

### Research Artifacts

File-based reports, evidence, indexes, and publication outputs.

- [Research report corpus](https://github.com/xbtlin/ai-berkshire/blob/main/reports/README.md): Markdown and evidence store · Principal product store for company, sector, screen, and series research. · `reports/README.md`
- [Audit and reproduction packages](https://github.com/xbtlin/ai-berkshire/blob/main/reports/%E8%85%BE%E8%AE%AF/%E5%AE%A1%E8%AE%A1-20260906/%E5%A4%8D%E6%A0%B8%E8%AE%A1%E7%AE%97.py): File-based provenance · Preserves inputs, calculations, verdicts, and rerunnable verification. · `reports/腾讯/审计-20260906/复核计算.py`
- [Corpus indexes](https://github.com/xbtlin/ai-berkshire/blob/main/reports/index.json): JSON and index builder · Updates repository index material; it is not a search service. · `reports/index.json`
- [RSI survey build](https://github.com/xbtlin/ai-berkshire/blob/main/reports/RSI-survey-20260906/build.py): Python publication pipeline · Builds a bilingual survey manuscript into publication artifacts. · `reports/RSI-survey-20260906/build.py`
- [Published survey PDF](https://github.com/xbtlin/ai-berkshire/blob/main/output/pdf/rsi-survey-en-20260906.pdf): PDF artifact · `output/pdf/rsi-survey-en-20260906.pdf`

## Connections

- Claude skill definitions → Codex skill synchronizer: source for generation
- Codex skill synchronizer → Codex installer: generated skills
- Codex installer → Claude Code and Codex: installs into
- Claude skill definitions → Claude Code and Codex: installed for Claude
- Team research workflows → Claude Code and Codex: invoked by
- Earnings team workflow → Claude Code and Codex: invoked by
- Industry funnel workflow → Claude Code and Codex: invoked by
- Claude Code and Codex → Market-data tools: uses
- Claude Code and Codex → Financial rigor: validates calculations with
- Claude Code and Codex → Stock screener: runs
- Claude Code and Codex → Research report corpus: creates research
- Public market sources → Market-data tools: data retrieval
- Market-data tools → Fundamentals data: persists inputs
- Fundamentals data → Financial rigor: calculation inputs
- Stock screener → Fundamentals data: screens
- Financial rigor → Audit and reproduction packages: calculation outputs
- Research report corpus → Audit and reproduction packages: preserves provenance
- Report quality audit → Research report corpus: checks
- Research report corpus → Corpus indexes: indexed by
- Research report corpus → RSI survey build: survey source
- RSI survey build → Published survey PDF: builds