$ show virattt/ai-hedge-fund
This repository, ai-hedge-fund, is a production-grade simulation engine for running AI-managed hedge funds in educational and research contexts. It provides a dual-mode system supporting both historical backtesting and live paper trading, all adhering to point-in-time data integrity to prevent look-ahead bias. The architecture is modular and protocol-based, with swappable components for data acquisition (Financial Datasets API), LLM providers (Anthropic, OpenAI, DeepSeek, Google, xAI, Kimi, TypeSafe/Jev), broker execution (simulated/paper), signal generation (quant models and LLM agents emulating investors like Buffett, Munger, Graham), and risk management. The engine includes a hash-chained ledger for tamper-evident record keeping, prompt caching to eliminate redundant LLM costs during backtests, and a textual TUI for interactive management. It is explicitly not intended for real trading and is released under MIT license. The codebase is well-structured with clean abstractions, though it carries some technical debt from being a ground-up v2 rebuild that is not yet fully integrated with its predecessor, and contains hardcoded constants and magic numbers that limit configurability.
The LLM identified 4 files worth highlighting for reuse:
Builds a point-in-time fundamentals snapshot from raw financial metrics, ensuring that only data available at a given `as_of` date (based on `filing_date` not `report_period`) is included. It computes derived aggregates like average ROE, margin trends, BVPS CAGR, and EPS YoY growth. The snapshot is content-hashed (excluding the `as_of` field) to serve as a deterministic key for LLM prompt caching. It also implements 'blind rendering' for backtest integrity, withholding absolute ticker names, calendar dates, and dollar amounts when the snapshot is used by LLM agents, preventing the model from reasoning about post-period information.
Implements a per-decision prompt cache for LLM calls. Each cache entry is stored as a JSON file keyed by a hash of (agent, model, prompt string). The content hash from `FundamentalsSnapshot` is embedded in the prompt so that identical fundamentals produce an identical prompt hash, resulting in a cache hit. This eliminates paid LLM calls between filings during backtest replay, making large-scale historical simulations economically feasible. The file naming uses the hash and the cache directory is namespaced by fund name.
Implements an append-only, tamper-evident ledger for paper trading sessions. Each `SessionRecord` contains a `prev_hash` that chains the record to its predecessor, enabling verification of ledger integrity by replaying all records and recomputing the chain. The ledger is stored as a JSON file per fund and supports listing, appending new sessions, and reading all records. The `Ledger` class also exposes a `verify()` method that walks the chain and checks hashes, ensuring no records have been modified or deleted.
Provides a hard constraint system for portfolio risk. After signals are blended into conviction arrays, `apply_limits()` enforces maximum position sizes (`max_position_pct`), maximum gross exposure (`max_gross_exposure`), and blend mode constraints (long_only, long_short, dollar_neutral). It uses a proportional scaling algorithm to reduce all positions while preserving relative conviction if limits are breached. This is a pure function with no side effects, making it easily testable and reusable in different execution contexts.