How ai-hedge-fund is put together
ai-hedge-fund is an educational, terminal-based AI hedge fund simulator written in Python 3.11. It composes 'funds' from pluggable alpha models (LLM investor agents like Buffett/Munger/Graham-style agents plus quant models such as PEAD), runs them through a cycle pipeline (signals -> risk limits -> portfolio construction -> simulated execution), and supports single-cycle runs and historical backtests at a rebalance cadence. The primary interface is a Textual TUI (hedge_fund.tui.app) plus a non-interactive CLI (hedge_fund.run) driven by YAML 'mandate' files stored under ~/.hedge-fund/mandates. Market data comes from the Financial Datasets API via a caching client; LLM calls go through LangChain provider integrations with a disk cache. No trades are executed against real brokers; a SimBroker fills orders in simulation.
Languages
Frameworks
Infrastructure
Major components
tui
Textual terminal app with HomeScreen, BuilderScreen, BacktestScreen, model picker, and masked API-key prompt screens.
pipeline
Orchestrates one fund cycle (run_cycle.py): invokes agents/signals, applies risk limits, constructs the portfolio, and executes via the broker into a CycleRecord.
signals
Alpha-model registry: quant strategies (pead.py) and LLM investor agents (buffett, munger, graham, lynch, druckenmiller, generic llm_agent).
backtesting
BacktestEngine and fund-level backtesting (backtest_fund, rebalance_grid) producing equity curves, Sharpe, drawdown, and trade records.
data
Financial Datasets API client (FDClient) behind a protocol, plus CachedDataClient for disk-cached market data.
llm
LLM client factory (make_llm), model registry/api_models.json, response cache, and watch tooling for streaming thesis output.
fund
FundSpec/StrategySpec definitions, YAML mandate loading/validation, strategy library, and universe normalization.
brokers / portfolio / risk / event_study / features
SimBroker fill simulation, portfolio construction, risk limit enforcement, earnings event-study analytics, and feature snapshots.
The project was packaged for public release on PyPI as 'hedge-fund' (version 2.2.0), with cleanup of internal tooling.
3 weeksWeek of 2026-08-03
Week of 2026-08-03latest
The project was packaged for public release on PyPI as 'hedge-fund' (version 2.2.0), with cleanup of internal tooling.
Week of 2026-07-27
Version 2.0 became the default experience, with users now choosing which stocks to analyze at run time instead of having them fixed in advance.
Week of 2026-07-20
A new text-based user interface was introduced alongside backtesting capabilities, letting users test their custom-designed funds against historical data.
Over the past three weeks, the project transformed from a research tool into a polished, installable product. The team rebuilt the interface with a modern text-based UI, made the AI fund's stock universe something users pick at run time rather than hard-code into a mandate, and added backtesting so users can test their custom funds against history. The final week focused on packaging and release: renaming the package, cleaning up the backtester, and publishing version 2.2.0 to PyPI under the name 'hedge-fund'.
Week by week
2026-08-03The project was packaged for public release on PyPI as 'hedge-fund' (version 2.2.0), with cleanup of internal tooling.latest6 changes
Chore
Bump version to 2.2.0
The project's version number was raised to 2.2.0 to mark this release.
Refactor
Rename package to aihf
The software's internal package name was shortened to 'aihf' for cleaner installation and imports.
Refactor
Clean up backtester
The tool that tests trading strategies against historical data was tidied up before release.
Chore
Untrack scripts/release.sh; release tooling is local-only
The script used to publish releases was removed from the public repository since it's only needed by maintainers locally.
Docs
Update the command
Instructions were refreshed to reflect the new command users should run.
Feature
Package for PyPI as hedge-fund
The project is now published on Python's public package registry under the name 'hedge-fund', so anyone can install it easily.
2026-07-27Version 2.0 became the default experience, with users now choosing which stocks to analyze at run time instead of having them fixed in advance.6 changes
Chore
Make 2.0.0 the default
The new major version of the product became what users get by default.
Feature
Add thinking
The AI agents can now show their reasoning process while making decisions.
Docs
Update ROADMAP and VISION
The project's planning documents describing where it's headed were revised.
Feature
Add LLM clients
Support was added for connecting to different AI language model providers.
Feature
Add model selector
Users can now choose which AI model powers their analysis.
Feature
Decouple the universe from the mandate: tickers are a run-time input
Instead of stocks being baked into each AI analyst's instructions, users now specify which tickers to analyze when they start a run, with related improvements like saving receipts and browsing or deleting saved funds.
2026-07-20A new text-based user interface was introduced alongside backtesting capabilities, letting users test their custom-designed funds against historical data.6 changes
Feature
Use Textual for UI
The app's interface was rebuilt using Textual, a modern framework for interactive terminal applications.
Feature
Add opus 5
Support was added for a newer, more capable AI model option.
Docs
Update VISION.md
The document explaining the project's long-term goals was refreshed.
Docs
Surface fund backtesting in the v2 intro
The introduction to version 2 now highlights the ability to backtest funds.
Refactor
Trim the backtest UX: drop attribution, date the receipts, remove the demo
The backtesting experience was simplified by removing performance attribution details, adding dates to saved results, and cutting an unnecessary demo mode.
Feature
Backtest the fund you design: run_cycle over history
Users can now take a fund they've configured and replay its decision-making cycle across historical data to see how it would have performed.
Dependencies and code review
Dependency advisories
Security Watch
1 vulnerable package (1 advisories) across 101 scanned dependencies.
langchain-core 0.3.86
1 advisory. Fixed in 1.2.22.
How it can be abusedAn attacker who can control the path of a prompt file loaded through LangChain's old prompt loading helpers could trick the app into reading files from anywhere on disk, such as private keys or config files. In this simulator, prompts are written in code and LLM calls are cached locally, so only someone running untrusted mandates or shared caches that feed paths to those legacy loaders would be exposed.
- highGHSA-qh6h-p6c9-ff54LangChain Core has Path Traversal vulnerabilites in legacy `load_prompt` functions
Code review
No concrete code-level issues confirmed.
Get this report every week for your repos.
GitZoid learns each repo, reports what changed, and flags what needs attention. One flat price for the whole team.
$19 a month, flat · First 10 outputs free · No card required