How to Contribute to the AI Berkshire Project’s Financial Rigor System

You can contribute to the AI Berkshire project’s financial rigor tooling by extending the zero-dependency Python modules in tools/financial_rigor.py and tools/report_audit.py, updating the data-source policies in skills/financial-data.md, and following the repository’s fork-branch-PR workflow with mandatory CI validation.

The AI Berkshire repository enforces strict numeric validation for every figure appearing in investment reports through a pure-Python architecture using only the standard library. To contribute to the ai-berkshire project financial rigor capabilities, you will work with exact-decimal calculations, cross-source validation logic, and automated audit pipelines that guarantee reproducibility on any Python ≥ 3.7 interpreter.

Understanding the Financial Rigor Architecture

The system relies on three tightly-coupled components that form a zero-dependency validation pipeline.

Core Validation Components

The backbone consists of specialized modules with distinct responsibilities:

• tools/financial_rigor.py: A command-line suite performing exact-decimal calculations via the decimal module. It exposes sub-commands including verify-market-cap, verify-valuation, cross-validate, benford, calc, and three-scenario to ensure arithmetic reproducibility.

• tools/report_audit.py: Extracts financial data points from markdown reports, samples a default 15% subset, and produces JSON checklists. Key entry points are the extract and verdict sub-commands.

• skills/financial-data.md: Defines the external data-source policy (e.g., macrotrends + stockanalysis for US equities, aastocks + macrotrends for HK equities) and mandates the 1% deviation tolerance threshold that all validation must respect.

The Four-Stage Validation Pipeline

1. Data Extraction: Authors run python3 tools/report_audit.py extract on a markdown report. The script parses tables, KV lines, and bolded numbers to generate a list of candidate data points.

2. Source Verification: For each sampled point, reviewers fetch values from the two mandated sources listed in skills/financial-data.md, then populate the JSON fields fetched_value and fetched_source.

3. Automated Validation: The populated JSON passes to report_audit.py verdict, which internally calls functions like cross_validate from financial_rigor.py to compute percentage deviations and determine PASS/FAIL status according to the 1% tolerance rule.

4. Result Rendering: A color-coded terminal summary prints to stdout, while a final decision JSON emits for CI pipelines. Any non-PASS verdict triggers a workflow failure, blocking publication until numeric errors resolve.

Where to Add or Improve Functionality

Contributions typically target four specific areas:

• New Valuation Metrics: Add computation branches inside verify_valuation and expose new CLI flags (e.g., --ev and --ebitda). Target file: tools/financial_rigor.py.

• Alternative Data Sources: Update the source tables in skills/financial-data.md and, if necessary, create wrapper scripts (e.g., tools/ashare_data.py) to fetch raw numbers from new APIs like Chinese equity databases.

• Enhanced Report Parsing: Improve the regular expressions in _parse_md_tables within tools/report_audit.py to handle merged cells or multi-row headers.

• Testing and CI: Write unit tests using pytest under tests/ and update .github/workflows/*.yml to exercise new functions against the 1% tolerance requirements.

Step-by-Step Contribution Workflow

Follow this standardized process to ensure your changes integrate with the Claude-Code compatibility layer and CI pipelines:

1. Fork and clone the repository:

   git clone https://github.com/<your-username>/ai-berkshire.git
   cd ai-berkshire

2. Create a feature branch:

   git checkout -b feat/ev-ebitda-metric

3. Implement the change in the identified files, following PEP 8 and adding type hints where feasible.

4. Run local verification to ensure the tool behaves correctly:

   python3 tools/financial_rigor.py verify-valuation --price 120 --eps 5 --bvps 30

5. Add unit tests for new functions:

   pytest tests/test_financial_rigor.py

6. Execute the sync script to maintain Claude-Code compatibility:

   python3 scripts/sync-codex-skills.py

7. Commit and push:

   git add .
   git commit -m "Add EV/EBITDA metric to financial_rigor"
   git push origin feat/ev-ebitda-metric

8. Open a Pull Request describing the motivation, files changed, and how the new metric respects the 1% tolerance rule. Link to any relevant issues.

9. Address CI feedback: The GitHub Actions workflow will automatically validate your changes against the existing rigor suite before approval.

Code Implementation Examples

Adding an EV/EBITDA Metric

To extend verify_valuation in tools/financial_rigor.py, insert the following calculation logic using the _CTX decimal context:

# Inside tools/financial_rigor.py, after the existing PE/PB block

if ev is not None and ebitda is not None:
    ev_val = exact(ev)
    ebitda_val = exact(ebitda)
    if ebitda_val != 0:
        ev_ebitda = _CTX.divide(ev_val, ebitda_val)
        print(f"  EV/EBITDA: {ev_val} / {ebitda_val} = {ev_ebitda:.2f}x")
        results["EV/EBITDA"] = float(ev_ebitda)

Then add the corresponding CLI arguments:

val.add_argument("--ev", type=float, default=None, help="Enterprise Value")
val.add_argument("--ebitda", type=float, default=None, help="EBITDA")

Test the new metric locally:

python3 tools/financial_rigor.py verify-valuation \
    --price 140 --eps 7.2 --bvps 45 \
    --ev 2.1e12 --ebitda 1.6e10

Updating Data Source Policies

When adding a new regional source, update the table in skills/financial-data.md:

| Region | Primary | URL | Notes |
|--------|---------|-----|-------|
| US     | macrotrends | https://www.macrotrends.net/stocks/charts/GOOGL/alphabet/market-cap | |
| US     | stockanalysis | https://stockanalysis.com/stocks/GOOGL/financials/ | |
| HK     | aastocks | https://www.aastocks.com/tc/stock/quote.aspx?symbol=0700 | |
| HK     | macrotrends (ADR) | https://www.macrotrends.net/stocks/charts/0700.hk/tencent/market-cap | |
| CN     | eastmoney | https://quote.eastmoney.com/sh600519.html | |
| CN     | cninfo | http://static.cninfo.com.cn/… | |

Summary

• Core modules: All financial rigor logic resides in tools/financial_rigor.py and tools/report_audit.py, with policies defined in skills/financial-data.md.
• Zero-dependency constraint: Use only Python stdlib (decimal, json, argparse) to ensure reproducibility across Python ≥ 3.7 environments.
• Tolerance standard: Every numeric validation must respect the 1% deviation threshold enforced by the cross_validate logic.
• Contribution path: Fork, branch, implement with inline documentation, run scripts/sync-codex-skills.py, test with pytest, and submit a PR for CI validation.
• Extensibility: New valuation metrics require updates to verify_valuation, while new data sources require edits to skills/financial-data.md and potential wrapper scripts in tools/.

Frequently Asked Questions

What Python version is required to contribute to the financial rigor tools?

The AI Berkshire project requires Python 3.7 or higher. The tools/financial_rigor.py module uses only standard library components (decimal, json, argparse) to guarantee that calculations are reproducible across all supported interpreter versions without external dependency conflicts.

How does the 1% tolerance rule work in practice?

The 1% tolerance is defined in skills/financial-data.md and enforced by the cross_validate function in tools/financial_rigor.py. When report_audit.py verdict processes a JSON checklist, it calculates the percentage deviation between the reported value and the fetched_value from dual sources. If the deviation exceeds 1%, the system returns a FAIL status, blocking the report from publication in CI pipelines.

Can I add external dependencies like pandas or numpy to the financial rigor tools?

No. The financial rigor architecture strictly prohibits third-party dependencies. All calculations must use the decimal.Decimal class for exact arithmetic to prevent floating-point errors in financial valuations. If you need data manipulation, extend the existing stdlib-based logic or create separate preprocessing scripts that output to the JSON format expected by report_audit.py.

How do I test my changes before submitting a pull request?

First, run the specific tool locally with sample arguments (e.g., python3 tools/financial_rigor.py verify-market-cap --value 1.5e12). Second, execute pytest tests/test_financial_rigor.py if you have added unit tests. Finally, run python3 scripts/sync-codex-skills.py to ensure Claude-Code compatibility, then commit and push to your fork for GitHub Actions to perform the full CI validation suite.

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