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

The AI Berkshire codebase does not contain a 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 module, this codebase distributes modeling responsibilities across specialized financial tools and declarative skill definitions.

Searching for models.py in AI Berkshire

A comprehensive search of the entire repository—including all subdirectories and Python modules—returns zero matches for 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, 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

The 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.

# 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

Similarly, tools/morningstar_fair_value.py contains the discounted cash flow logic used to generate fair value estimates in research reports.

# 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 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 and 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 utility ensures these skill definitions remain synchronized with the underlying tool implementations.

Summary

• AI Berkshire contains no models.py file—searching the repository returns zero matches for this module.
• Financial modeling logic is implemented in tools/financial_rigor.py and 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 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?

Data structures are defined implicitly through JSON schema files located in the data/ directory, such as watchlist.json and 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 to execute, with the 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 in the future?

Based on the current architecture documented in AGENTS.md, there is no indication that a traditional models.py will be introduced. The existing tools-based architecture effectively handles all modeling requirements for the investment research workflow.

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