# The Role of `models.py` in AI Berkshire: Repository Architecture Explained

> Discover why AI Berkshire lacks a models.py file. Learn how financial modeling logic is integrated within the tools directory for effective repository architecture.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: architecture
- Published: 2026-07-09

---

**The AI Berkshire codebase does not contain a [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) file; instead, financial modeling logic is embedded directly in utility scripts within the `tools/` directory.**

The `xbtlin/ai-berkshire` repository is an investment research pipeline system that departs from conventional software architecture patterns. Unlike typical machine learning or web application projects that centralize data schemas and algorithms in a dedicated [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) module, this codebase distributes modeling responsibilities across specialized financial tools and declarative skill definitions.

## Searching for [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) in AI Berkshire

A comprehensive search of the entire repository—including all subdirectories and Python modules—returns zero matches for [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) or any module named `model*`. This absence is intentional and reflects the project's focus on **investment research pipelines** rather than traditional machine learning model training or ORM-based data management.

## Where Financial Modeling Logic Lives

Instead of a centralized [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py), AI Berkshire organizes its domain logic within the `tools/` directory. These Python scripts encapsulate the financial calculations and data processing that would typically reside in a models module.

### Core Valuation Functions in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py)

The [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) file serves as the primary computational engine according to the repository source code. It contains functions that calculate enterprise values and perform rigorous financial analysis.

```python

# tools/financial_rigor.py – core valuation routine

from decimal import Decimal

def equity_value(market_cap: Decimal, cash: Decimal, debt: Decimal) -> Decimal:
    """Simple enterprise‑value calculation used throughout the reports."""
    return market_cap + cash - debt

```

This function represents the domain-specific "model" logic for equity valuation, implemented as a standalone utility rather than a class-based model definition.

### Fair Value Calculations in [`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py)

Similarly, [`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py) contains the discounted cash flow logic used to generate fair value estimates in research reports.

```python

# tools/morningstar_fair_value.py – computes a fair-value estimate

def fair_value(price: float, growth_rate: float, discount_rate: float) -> float:
    """Discounted cash‑flow based fair value."""
    return price * (1 + growth_rate) / (discount_rate - growth_rate)

```

These financial modeling functions are invoked by the AI agent's skill definitions to produce the quantitative sections stored in the `reports/` directory.

## Data Schemas Without ORM Models

In the absence of a [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) defining data classes or ORM objects, AI Berkshire uses JSON files within the `data/` directory as the source of truth for company-level information. Files such as [`watchlist.json`](https://github.com/xbtlin/ai-berkshire/blob/main/watchlist.json) and [`fundamentals.json`](https://github.com/xbtlin/ai-berkshire/blob/main/fundamentals.json) provide the structured data that the tools process, eliminating the need for a Python-based schema definition file.

## The Skills-Based Architecture

The repository's unique architecture delegates workflow orchestration to Markdown-based skill definitions in the `skills/` and `codex-prompts/` directories. These declarative files describe how the Python tools should be invoked, effectively replacing the imperative model-layer logic found in traditional applications. The [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility ensures these skill definitions remain synchronized with the underlying tool implementations.

## Summary

- **AI Berkshire contains no [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) file**—searching the repository returns zero matches for this module.
- **Financial modeling logic is implemented** in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) and [`tools/morningstar_fair_value.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/morningstar_fair_value.py) as functional utilities rather than class-based models.
- **Data schemas are handled via JSON files** in the `data/` directory rather than Python ORM classes.
- **The architecture prioritizes investment research pipelines** over machine learning model training, making a traditional [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) unnecessary.

## Frequently Asked Questions

### Does AI Berkshire use machine learning models?

No, AI Berkshire does not implement machine learning models in the traditional sense. The repository focuses on **financial modeling and valuation calculations** implemented as deterministic functions in the `tools/` directory, providing automated investment research rather than predictive ML.

### Where are data structures defined if there is no [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py)?

Data structures are defined implicitly through **JSON schema files** located in the `data/` directory, such as [`watchlist.json`](https://github.com/xbtlin/ai-berkshire/blob/main/watchlist.json) and [`fundamentals.json`](https://github.com/xbtlin/ai-berkshire/blob/main/fundamentals.json). These files serve as the source of truth for company data, while the `tools/` scripts handle data validation and transformation programmatically.

### How does the AI agent invoke financial calculations without a models module?

The AI agent invokes calculations through **skill definitions** stored in `skills/` and `codex-prompts/`. These Markdown files declare which functions from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) to execute, with the [`scripts/sync-codex-skills.py`](https://github.com/xbtlin/ai-berkshire/blob/main/scripts/sync-codex-skills.py) utility ensuring the skill definitions remain synchronized with the available tool functions.

### Is AI Berkshire planning to add a [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) in the future?

Based on the current architecture documented in [`AGENTS.md`](https://github.com/xbtlin/ai-berkshire/blob/main/AGENTS.md), there is no indication that a traditional [`models.py`](https://github.com/xbtlin/ai-berkshire/blob/main/models.py) will be introduced. The existing **tools-based architecture** effectively handles all modeling requirements for the investment research workflow.