DeepFund Research Framework

repository·main·Indexed 43 days ago

A research framework for evaluating the professional fund investment capabilities of Large Language Models (LLMs). DeepFund provides a simulated trading arena where LLMs ingest financial information, drive multi-agent systems, and make trading decisions. It includes integrations with Alpha Vantage, YFinance, and FinancialDatasets.ai to retrieve stock prices, company fundamentals, insider trading data, and macroeconomic indicators.

Tokens: 8.4K
Snippets: 32
Records: 39
Agent score: 55%

What's inside DeepFund

DeepFund Database Schema
main
The system relies on four primary tables to track its operations:
- Config: Stores user-defined configurations.
- Portfolio: Records portfolio updates.
- Decision: Records trading decisions made by managers.
- Signal: Records signals generated by analysts.
https://github.com/hkustdial/deepfund/blob/main/README.md

Understand the DeepFund Analyst types and outputs

main

DeepFund uses specialized analysts to process different types of financial information. All analysts follow a Unified Output format: Signal=(Bullish, Bearish, Neutral) and a Justification string.

Available Analysts

Name	Function	Upstream Source
`company_news`	Analyzes company news	Lately Company news
`fundamental`	Analyzes financial metrics	Profitability, growth, cashflow, and financial health
`insider`	Analyzes insider trading	Recent insider transactions by key stakeholders
`macroeconomic`	Analyzes macro indicators	US economic indicators (GDP, CPI, rate, unemployment, etc.)
`policy`	Analyzes policy news	Fiscal and monetary policy news
`technical`	Analyzes technical indicators	Trend, mean reversion, RSI, volatility, volume, support/resistance

Historical Data Support

Due to upstream API constraints, only the following analysts support historical data analysis via the trading-date option:

company_news
insider
policy
technical

Other analysts (like fundamental and macroeconomic) can only retrieve the latest available data.

How to add a new base LLM provider
main
To integrate a new LLM provider (e.g., a new API service), follow these steps:
1. Implement Provider Logic: Create a new provider implementation following the pattern in src/llm/new_provider.py.
2. Handle API Keys: Add required environment variables to .env.example and ensure users can add them to their .env file.
3. Update Configuration: Ensure the provider and model names are documented so they can be used in YAML configuration files under the llm: section.
4. Testing: Run the system using a configuration that specifies your new provider to ensure successful LLM calls and agent responses.
Configuration Example:
```
llm:
  provider: "YOUR_NEW_PROVIDER_ID"
  model: "provider-specific-model-name"
```
```
llm:
  provider: ""
  model: ""
```
https://github.com/hkustdial/deepfund/blob/main/TECHNICAL_GUIDE.md
Configure DeepFund Database
main
DeepFund uses a database to track trading status and store LLM reasoning results. You can choose between Supabase (default) or a local SQLite database.
Option 1: Supabase (Cloud PostgreSQL)
DeepFund connects to Supabase by default.
1. Create a free account on Supabase.
2. Execute the SQL in src/database/supabase_setup.sql to create the necessary tables.
3. Update SUPABASE_URL and SUPABASE_KEY in your .env file.
Option 2: SQLite (Local)
For lightweight local storage:
1. Run the setup script:
  cd src python database/sqlite_setup.py
2. The database will be created at src/assets/deepfund.db.
3. Use the --local-db flag when running the system to use this database.
```
cd src
python database/sqlite_setup.py
```
https://github.com/hkustdial/deepfund/blob/main/README.md
Run the DeepFund System
main
To execute the trading simulation, navigate to the src directory and run main.py.
Command Syntax:
```
python main.py --config <config_path> --trading-date YYYY-MM-DD [--local-db]
```
Arguments:
- --config: Path to a YAML configuration file (located in src/config).
- --trading-date: The date for the simulation (YYYY-MM-DD). Note: To replay trading history correctly, you must run dates in chronological order as the portfolio updates daily.
- --local-db: (Optional) Use this flag to switch from the default Supabase connection to a local SQLite database.
```
cd src
python main.py --config my_config.yaml --trading-date 2025-01-01 --local-db
```
https://github.com/hkustdial/deepfund/blob/main/README.md
How to add a new analyst to DeepFund
main
To extend the system with a custom analyst, follow these steps:
1. Build the Analyst: Create a new Python file in src/agents/analysts/. Implement an agent function that accepts inputs (e.g., tickers, market data) and returns the standard signal/justification format.
2. Define Prompts: If using an LLM, add the required prompts to src/llm/prompt.py.
3. Register the Analyst: Add the analyst's name to the central registry in src/graph/constants.py or src/agents/registry.py.
4. Update Configuration: Add the analyst's unique name to the workflow_analysts list in your configuration file (e.g., src/config/my_config.yaml).
5. Add Data Dependencies: If the analyst needs new data, implement the API client in src/apis/ and add any necessary keys to .env.
6. Testing: Run the system with your new configuration and verify outputs in the Decision and Signal database tables.
https://github.com/hkustdial/deepfund/blob/main/TECHNICAL_GUIDE.md
Install and Setup DeepFund
main
Follow these steps to set up the DeepFund environment using either Anaconda or uv.
1. Clone the repository
```
git clone https://github.com/HKUSTDial/DeepFund.git
cd DeepFund
```
2. Create a virtual environment
Using Anaconda:
```
conda env create -f environment.yml
```
Using uv:
```
uv sync
source .venv/bin/activate
```
3. Configure API Keys
Create a .env file from the template to store your LLM provider keys (e.g., OpenAI, DeepSeek):
```
cp .env.example .env
```
```
git clone https://github.com/HKUSTDial/DeepFund.git
cd DeepFund
conda env create -f environment.yml
cp .env.example .env
```
https://github.com/hkustdial/deepfund/blob/main/README.md
Configure DeepFund via YAML
main
Configuration files are stored in src/config. Each experiment should have a unique exp_name to avoid overwriting results.
Configuration Schema:
```
# Deep Fund Configuration
exp_name: "my_unique_exp_name"

# Trading settings
tickers:
  - ticker_a
  - ticker_b

# Analysts to run, refer to graph.constants.py
planner_mode: true/false
workflow_analysts:
  - analyst_a
  - analyst_b
  - analyst_c

# LLM model settings, refer to llm/inference.py
llm:
  provider: "provider_name" 
  model: "model_name"
```
Key Options:
- exp_name: A unique identifier for the experiment.
- tickers: A list of financial tickers to trade.
- planner_mode:
  true: A Planner agent orchestrates which analysts from workflow_analysts to run.
  false: All analysts in workflow_analysts run in parallel without orchestration.
- workflow_analysts: A list of analysts to include in the workflow.
- llm: Configuration for the LLM provider and specific model name.
```
exp_name: "my_unique_exp_name"
tickers:
  - AAPL
  - MSFT
planner_mode: true
workflow_analysts:
  - analyst_a
llm:
  provider: "openai"
  model: "gpt-4"
```
https://github.com/hkustdial/deepfund/blob/main/README.md
Configure AlphaVantageAPI via environment variables
main
To use the AlphaVantageAPI client, you must provide your API credentials via environment variables. The client uses these to construct the base request URL.
Required:
- ALPHA_VANTAGE_API_KEY: Your Alpha Vantage API key.
Optional:
- ALPHA_VANTAGE_ENTITLEMENT: Used for premium features. If provided, it is appended to the request URL.
```
export ALPHA_VANTAGE_API_KEY='your_api_key'
export ALPHA_VANTAGE_ENTITLEMENT='your_entitlement_token'
```
https://github.com/hkustdial/deepfund/blob/main/src/apis/alphavantage/api.py
Initialize FinancialDatasetAPI
main
To use the FinancialDatasetAPI, you must first set the FINANCIAL_DATASETS_API_KEY environment variable. The client automatically retrieves this key during initialization to authenticate requests to https://api.financialdatasets.ai.
```
import os
from src.apis.financialdataset.api import FinancialDatasetAPI

# Ensure the API key is set in your environment
os.environ["FINANCIAL_DATASETS_API_KEY"] = "your_api_key_here"

api = FinancialDatasetAPI()
```
https://github.com/hkustdial/deepfund/blob/main/src/apis/financialdataset/api.py
DeepFund System Dependencies Reference
main
DeepFund relies on the following external services for LLM capabilities and financial data:
LLM Providers
- Official APIs: OpenAI, DeepSeek, Anthropic, Grok, etc.
- Proxy APIs: Fireworks AI, AiHubMix, etc.
- Local APIs: Ollama, etc.
Financial Data Sources
- Alpha Vantage API: Used for Stock Market Data.
- YFinance API: Used to download market data from Yahoo! Finance.
https://github.com/hkustdial/deepfund/blob/main/TECHNICAL_GUIDE.md
Troubleshoot LLM API Key errors
main
If the LLM provider requires an API key and it is not found in the environment, get_model will raise a ValueError.
Error Message: [Provider Name] API key not found. Please set [ENV_KEY] in .env file.
Solution: Ensure that the specific environment variable required by your provider (e.g., OPENAI_API_KEY) is correctly defined in your .env file.
https://github.com/hkustdial/deepfund/blob/main/src/llm/inference.py

DeepFund Research Framework

What's inside DeepFund

Available Analysts

Historical Data Support

Option 1: Supabase (Cloud PostgreSQL)

Option 2: SQLite (Local)

1. Clone the repository

2. Create a virtual environment

3. Configure API Keys

LLM Providers

Financial Data Sources