AI Hedge Fund

This is a proof of concept for an AI-powered hedge fund. The goal of this project is to explore the use of AI to make trading decisions. This project is for educational purposes only and is not intended for real trading or investment.

This system employs several agents working together:

Aswath Damodaran Agent - The Dean of Valuation, focuses on story, numbers, and disciplined valuation
Ben Graham Agent - The godfather of value investing, only buys hidden gems with a margin of safety
Bill Ackman Agent - An activist investor, takes bold positions and pushes for change
Cathie Wood Agent - The queen of growth investing, believes in the power of innovation and disruption
Charlie Munger Agent - Warren Buffett's partner, only buys wonderful businesses at fair prices
Michael Burry Agent - The Big Short contrarian who hunts for deep value
Mohnish Pabrai Agent - The Dhandho investor, who looks for doubles at low risk
Peter Lynch Agent - Practical investor who seeks "ten-baggers" in everyday businesses
Phil Fisher Agent - Meticulous growth investor who uses deep "scuttlebutt" research
Rakesh Jhunjhunwala Agent - The Big Bull of India
Stanley Druckenmiller Agent - Macro legend who hunts for asymmetric opportunities with growth potential
Warren Buffett Agent - The oracle of Omaha, seeks wonderful companies at a fair price
Valuation Agent - Calculates the intrinsic value of a stock and generates trading signals
Sentiment Agent - Analyzes market sentiment and generates trading signals
Fundamentals Agent - Analyzes fundamental data and generates trading signals
Technicals Agent - Analyzes technical indicators and generates trading signals
Risk Manager - Calculates risk metrics and sets position limits
Portfolio Manager - Makes final trading decisions and generates orders

Note: the system does not actually make any trades.

Disclaimer

This project is for educational and research purposes only.

Not intended for real trading or investment
No investment advice or guarantees provided
Creator assumes no liability for financial losses
Consult a financial advisor for investment decisions
Past performance does not indicate future results

By using this software, you agree to use it solely for learning purposes.

How to Install

Before you can run the AI Hedge Fund, install the Python and frontend dependencies first.

1. Clone the Repository

git clone https://github.com/AceInAndroid/ai-hedge-fund.git
cd ai-hedge-fund

2. Install Python Dependencies

This project uses Poetry and supports Python 3.11 and 3.12. The recommended version is 3.11.

If Python is not installed yet, one practical way is to install it with pyenv.

Install pyenv first:

brew install pyenv

Install Python 3.11:

pyenv install 3.11.11
pyenv local 3.11.11
python3 --version

Install Python 3.12:

pyenv install 3.12.9
pyenv local 3.12.9
python3 --version

If poetry is not installed yet, install it first:

curl -sSL https://install.python-poetry.org | python3 -

If the shell still cannot find poetry, add Poetry to your PATH and reopen the terminal:

export PATH="$HOME/.local/bin:$PATH"

Then install project dependencies:

poetry env use python3
poetry install

If poetry install fails, check these common issues first:

poetry: command not found: install Poetry with the command above, then reopen the terminal.
Python version mismatch: make sure python3 --version is compatible with this project.
Broken environment from an earlier install: try poetry env remove --all and then run poetry install again.

3. Install Frontend Dependencies

The web UI lives in app/frontend.

cd app/frontend
npm install
cd ../..

OpenClaw Skill Install

This repository can also be packaged as an OpenClaw-installable skill.

Option 1: Install directly into `~/.agents/skills`

bash scripts/install-openclaw-skill.sh

This installs the skill to:

~/.agents/skills/ai-hedge-fund

Option 2: Generate a distributable package first

bash scripts/package-openclaw-skill.sh

The packaged skill directory will be created at:

dist/openclaw-skill/ai-hedge-fund

You can then copy or symlink it manually:

mkdir -p ~/.agents/skills
cp -R dist/openclaw-skill/ai-hedge-fund ~/.agents/skills/

OpenClaw Notes

The packaged skill contains SKILL.md, SKILL.toon, agents/openai.yaml, and the required references/ files.
The installed skill assumes the active workspace is still the ai-hedge-fund repository root.
Runtime execution still uses this repository's own scripts/ entrypoints.
To expose the skill contract to external controllers, run:

bash scripts/export-skill-manifest.sh

Environment Configuration

1. Create the `.env` File

cp .env.example .env

The .env file must be created in the project root directory, at the same level as README.md, pyproject.toml, and src/.

Example root path:

ai-hedge-fund/
├── .env
├── .env.example
├── README.md
├── pyproject.toml
├── src/
└── app/

You can confirm you are in the project root with:

pwd
ls -la .env .env.example

How to open .env:

VS Code:
```
code .env
```
macOS terminal editor:
```
nano .env
```
Linux terminal editor:
```
nano .env
```
Windows PowerShell:
```
notepad .env
```

If you use nano, edit the file, then press Ctrl+O to save and Ctrl+X to exit.

2. Minimum Required Configuration

At least one LLM provider must be configured, otherwise the agents cannot run.

You can use any one of these methods:

Official OpenAI
Official Anthropic
OpenAI-compatible API
Anthropic-compatible API
LM Studio local server

3. Environment Variable Examples

All environment variable examples below must be written into the root .env file you just created.

Each line uses this format:

KEY=value

Do not wrap values in JSON. Do not add commas at the end of lines.

Example:

OPENAI_API_KEY=sk-xxxxx
OPENAI_API_BASE=https://api.openai.com/v1

Example A: Official OpenAI

OPENAI_API_KEY=your-openai-api-key
OPENAI_API_BASE=https://api.openai.com/v1

Example B: DashScope Anthropic-Compatible

ANTHROPIC_AUTH_TOKEN=your-dashscope-api-key
ANTHROPIC_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic
ANTHROPIC_MODEL=qwen3.5-plus

Example C: OpenAI-Compatible Gateway

OPENAI_COMPATIBLE_API_KEY=your-compatible-api-key
OPENAI_COMPATIBLE_BASE_URL=https://your-openai-compatible-host/v1
OPENAI_COMPATIBLE_MODEL=your-model-name

Example D: Anthropic-Compatible Gateway

ANTHROPIC_COMPATIBLE_API_KEY=your-compatible-api-key
ANTHROPIC_COMPATIBLE_BASE_URL=https://your-anthropic-compatible-host/v1
ANTHROPIC_COMPATIBLE_MODEL=your-model-name

Example E: LM Studio

LM_STUDIO_BASE_URL=http://127.0.0.1:1234/v1
LM_STUDIO_API_KEY=lm-studio
LM_STUDIO_MODEL=your-local-model-name

Complete `.env` Example

This is a valid example of what the root .env file can look like:

# LLM provider: DashScope Anthropic-compatible
ANTHROPIC_AUTH_TOKEN=your-dashscope-api-key
ANTHROPIC_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic
ANTHROPIC_MODEL=qwen3.5-plus

# Financial data
FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

# A-share price fallback order
PRICE_DATA_SOURCES=financial_datasets,akshare,baostock,tushare,tencent,xueqiu,baidu
TUSHARE_TOKEN=your-tushare-token

After editing .env, save the file and restart the CLI command or web backend so the new values are loaded.

3.2 Directly Inject External Data Into CLI

If another system already prepared detailed market or fundamental data, you can pass it directly to the scripts and skip repeated fetching.

Use:

--data-file ./sample-data.json

Add:

--data-only

when you want to disable all external fetching and use only the supplied file.

Example:

bash scripts/run-analysis.sh 600519.SH,000001.SZ --data-file ./sample-data.json --data-only

The JSON file can contain per-ticker prices, financial_metrics, line_items, company_news, insider_trades, and market_cap. See the skill reference file references/preloaded-data.md for the full schema.

3.1 How CLI Model Selection Works

The CLI no longer requires you to choose from a built-in model catalog first.

Current behavior:

CLI reads the configured provider from .env
CLI reads the configured model name from the matching *_MODEL variable
If only one provider is configured, it is selected automatically
If multiple providers are configured, CLI asks you to choose among the configured providers only
If a provider is configured but its *_MODEL value is missing, CLI asks you to type the model name manually

For example, if your .env contains:

ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
ANTHROPIC_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic
ANTHROPIC_MODEL=qwen3.5-plus

then running:

poetry run python src/main.py --ticker AAPL,MSFT,NVDA

will use:

provider: Anthropic
model: qwen3.5-plus

without asking you to pick from built-in Claude or GPT model lists.

4. Financial Data Configuration

For US tickers, the existing FINANCIAL_DATASETS_API_KEY flow remains the main source.

FINANCIAL_DATASETS_API_KEY=your-financial-datasets-api-key

5. A-Share Price Fallback Configuration

For mainland China tickers, the project now supports price fallback across:

financial_datasets
akshare
baostock
tushare
tencent
xueqiu
baidu

Use this configuration in .env if you want to control the fallback order:

PRICE_DATA_SOURCES=financial_datasets,akshare,baostock,tushare,tencent,xueqiu,baidu
TUSHARE_TOKEN=your-tushare-token

Notes:

TUSHARE_TOKEN is only required if tushare is included in PRICE_DATA_SOURCES.
Akshare, Baostock, and Tushare are declared in pyproject.toml; run poetry install after pulling the latest changes.
The A-share fallback currently applies to price data. Financial metrics, company news, and insider trades still use the original financial data flow.

6. Web Settings Page vs `.env`

If you use the web application:

.env is the easiest way to set default configuration for local development.
The Settings page in the web UI can also save provider keys, URLs, PRICE_DATA_SOURCES, and TUSHARE_TOKEN.
Web-saved settings are passed into the backend request and can override missing environment values.

Where to configure what:

Want defaults for local development: edit the root .env file.
Want to change configuration from the browser: open the Web app, then go to Settings.
Want both: keep stable defaults in .env, and use the Settings page for temporary or per-environment adjustments.

How to Run

⌨️ Command Line Interface

You can run the AI Hedge Fund directly from the terminal for research, scripting, or debugging.

List Available Agents and Capabilities

Before selecting analysts, you can inspect the built-in capability catalog:

bash scripts/list-agents.sh

For JSON output that another controller or script can consume:

bash scripts/list-agents.sh --format json

For a full external-skill manifest that another controller can consume directly:

bash scripts/export-skill-manifest.sh

This catalog includes:

selectable analyst agents
always-on system agents such as risk_manager and portfolio_manager
each agent's strategy family, analysis method, execution mode, best-fit use case, A-share readiness, and data requirements
a repo-managed external interface where callers do not need to supply LLM keys or model names by default

Analyze Tickers

poetry run python src/main.py --ticker AAPL,MSFT,NVDA

If your .env already contains model settings, CLI uses them directly.

Example with DashScope Anthropic-compatible:

ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY
ANTHROPIC_BASE_URL=https://coding.dashscope.aliyuncs.com/apps/anthropic
ANTHROPIC_MODEL=qwen3.5-plus

Run:

poetry run python src/main.py --ticker AAPL,MSFT,NVDA

CLI will use qwen3.5-plus automatically.

With external preloaded data:

bash scripts/run-analysis.sh 600519.SH,000001.SZ --data-file ./sample-data.json --data-only

Analyze A-Share Tickers

poetry run python src/main.py --ticker 600519.SH,000001.SZ

You can optionally pass a time range:

poetry run python src/main.py --ticker AAPL,MSFT,NVDA --start-date 2024-01-01 --end-date 2024-03-01

If you want to use local models through Ollama:

poetry run python src/main.py --ticker AAPL,MSFT,NVDA --ollama

Run the Backtester

poetry run python src/backtester.py --ticker AAPL,MSFT,NVDA

Backtester also supports --start-date, --end-date, and --ollama.

Common CLI Usage Notes

--ticker uses a comma-separated list.
A-share tickers can be written as 600519.SH, 000001.SZ, or six-digit codes such as 600519.
Make sure your .env is configured before running CLI commands.
--model-provider and --model are optional overrides for CLI runs.
If .env already defines ANTHROPIC_MODEL, OPENAI_COMPATIBLE_MODEL, LM_STUDIO_MODEL, and similar variables, CLI uses those values directly.

Example override:

poetry run python src/main.py --ticker AAPL,MSFT,NVDA --model-provider anthropic --model qwen3.5-plus

Example with direct injected data:

bash scripts/run-analysis.sh 600519.SH,000001.SZ --data-file ./sample-data.json --data-only

Example with explicit analyst selection:

bash scripts/run-analysis.sh KO,AXP --analysts ben_graham,warren_buffett,valuation_analyst

🖥️ Web Application

The web application is the easiest way to switch models, edit flows, and manage saved settings.

Method 1: Start Both Services with One Command

macOS / Linux:

bash app/run.sh

Windows:

app\run.bat

Method 2: Start Backend and Frontend Manually

Backend:

poetry run uvicorn app.backend.main:app --reload --host 127.0.0.1 --port 8000

Frontend:

cd app/frontend
npm run dev

After startup:

Frontend: http://localhost:5173
Backend API: http://localhost:8000
Swagger docs: http://localhost:8000/docs

Web Usage Flow

Open the Settings page and fill in your LLM/data-source configuration.
Choose model provider and model for each node if needed.
Enter tickers and date range.
Run the analysis or the backtest from the UI.

You can still find app-specific details in app/README.md.

How to Contribute

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

Important: Please keep your pull requests small and focused. This will make it easier to review and merge.

Feature Requests

If you have a feature request, please open an issue and make sure it is tagged with enhancement.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 813 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
agents		agents
app		app
docker		docker
references		references
scripts		scripts
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
SKILL.md		SKILL.md
SKILL.toon		SKILL.toon
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

AI Hedge Fund

Disclaimer

Table of Contents

How to Install

1. Clone the Repository

2. Install Python Dependencies

3. Install Frontend Dependencies

OpenClaw Skill Install

Option 1: Install directly into ~/.agents/skills

Option 2: Generate a distributable package first

OpenClaw Notes

Environment Configuration

1. Create the .env File

2. Minimum Required Configuration

3. Environment Variable Examples

Example A: Official OpenAI

Example B: DashScope Anthropic-Compatible

Example C: OpenAI-Compatible Gateway

Example D: Anthropic-Compatible Gateway

Example E: LM Studio

Complete .env Example

3.2 Directly Inject External Data Into CLI

3.1 How CLI Model Selection Works

4. Financial Data Configuration

5. A-Share Price Fallback Configuration

6. Web Settings Page vs .env

How to Run

⌨️ Command Line Interface

List Available Agents and Capabilities

Analyze Tickers

Analyze A-Share Tickers

Run the Backtester

Common CLI Usage Notes

🖥️ Web Application

Method 1: Start Both Services with One Command

Method 2: Start Backend and Frontend Manually

Web Usage Flow

How to Contribute

Feature Requests

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Option 1: Install directly into `~/.agents/skills`

1. Create the `.env` File

Complete `.env` Example

6. Web Settings Page vs `.env`

Packages