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

> Contribute to AI Berkshire's financial rigor. Enhance Python modules, update data policies, and improve report audits. Join the xbtlin/ai-berkshire project today and strengthen AI financial transparency.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-04

---

**You can contribute to the AI Berkshire project’s financial rigor tooling by extending the zero-dependency Python modules in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py), updating the data-source policies in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py).

- **Alternative Data Sources**: Update the source tables in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md) and, if necessary, create wrapper scripts (e.g., [`tools/ashare_data.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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:

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

2. **Create a feature branch**:

   ```bash
   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:

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

5. **Add unit tests** for new functions:

   ```bash
   pytest tests/test_financial_rigor.py
   ```

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

   ```bash
   python3 scripts/sync-codex-skills.py
   ```

7. **Commit and push**:

   ```bash
   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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py), insert the following calculation logic using the `_CTX` decimal context:

```python

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

```python
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:

```bash
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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md):

```markdown
| 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`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/report_audit.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/report_audit.py), with policies defined in [`skills/financial-data.md`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/skills/financial-data.md) and enforced by the `cross_validate` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/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`](https://github.com/xbtlin/ai-berkshire/blob/main/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.