Financial Data Sources for Analyst Agents in the AI Hedge Fund System

TLDR: The ai-hedge-fund repository sources financial data from the Financial Datasets API, wrapping it in a cached, type-safe layer within src/tools/api.py for consumption by LLM-driven analyst agents.

The virattt/ai-hedge-fund project implements a modular, LLM-driven investment platform where specialized analyst agents perform quantitative research using real-time market data. These agents rely on a centralized data infrastructure that handles external API integration, response validation, and intelligent caching. Understanding the financial data sources for analyst agents is essential for extending the platform or integrating alternative datasets into the backtesting pipeline.

Core Data Architecture

The system employs a layered architecture that separates raw data retrieval from business logic. This design ensures type safety, reduces redundant API calls, and provides a consistent interface for all analyst agents across the platform.

Data Models Layer

Located in src/data/models.py, this layer defines Pydantic schemas for all financial entities including FinancialMetrics, LineItem, Price, and InsiderTrade. These models enforce strict type validation when parsing JSON responses from the external API, ensuring that agents receive consistently structured data regardless of the raw response format.

Caching Layer

The src/data/cache.py module implements a simple in-memory key-value store. It provides deterministic cache keys based on query parameters (ticker symbol, date range, metric type), preventing redundant calls to the Financial Datasets API during batch backtesting or multi-agent simulations.

API Wrapper Layer

The src/tools/api.py file contains the core integration logic. The _make_api_request function (lines 26-57) handles HTTP requests with built-in 429 rate-limit handling and exponential backoff, ensuring reliable financial data sources for analyst agents even during high-frequency polling or large-scale historical simulations.

The Financial Datasets API Integration

All analyst agents consume data from the Financial Datasets API (https://api.financialdatasets.ai/). This external service provides the historical and fundamental data required for quantitative analysis across multiple categories:

• Price Data: OHLCV (Open, High, Low, Close, Volume) time series for technical analysis
• Financial Metrics: Standardized valuation ratios, growth statistics, and profitability indicators
• Line Items: Granular financial statement data extracted from income statements, balance sheets, and cash flow statements
• Insider Trades: Regulatory filing data for sentiment analysis and momentum signals
• Company News: Textual data for natural language processing and sentiment scoring

Data Retrieval Workflow

When an analyst agent requests data, the system follows a six-step pipeline that prioritizes cached results and maintains type safety:

1. Agent Request: An analyst calls helper functions such as get_financial_metrics() or search_line_items() from src/tools/api.py.
2. Cache Lookup: The request checks src/data/cache.py using a deterministic key constructed from all query parameters.
3. API Call: Upon cache miss, _make_api_request() performs an authenticated HTTP GET/POST to the Financial Datasets API.
4. Response Parsing: Raw JSON converts to typed Pydantic models (FinancialMetrics, LineItem, etc.) defined in src/data/models.py.
5. Cache Store: Parsed data persists in the in-memory cache for subsequent identical requests.
6. Agent Logic: The agent processes structured data through valuation formulas, sentiment algorithms, or technical indicators.

Working with Financial Data: Code Examples

The following examples demonstrate how analyst agents interact with the data layer to retrieve financial data sources for analyst agents in practice.

Fetching Price Data for Technical Analysis

from src.tools.api import get_price_data

# Retrieve daily OHLCV for Apple (AAPL) over the last month

df = get_price_data(
    ticker="AAPL",
    start_date="2024-02-01",
    end_date="2024-03-01",
    api_key="YOUR_FINANCIAL_DATASETS_API_KEY",
)

print(df.head())

The get_price_data() function combines get_prices() with prices_to_df() (lines 55-59 in src/tools/api.py) to return a pandas DataFrame directly suitable for technical indicator calculations.

Retrieving Fundamental Metrics for Valuation

The Valuation agent in src/agents/valuation.py demonstrates complex data aggregation, fetching both standardized metrics and detailed line items for discounted cash flow (DCF) analysis:

from src.tools.api import get_financial_metrics, search_line_items

# Fetch standardized financial metrics (P/E, debt-to-equity, etc.)

financial_metrics = get_financial_metrics(
    ticker="MSFT",
    end_date="2024-03-01",
    period="ttm",
    limit=8,
    api_key=api_key,
)

# Fetch specific line items for detailed valuation models

line_items = search_line_items(
    ticker="MSFT",
    line_items=[
        "free_cash_flow", "net_income", "depreciation_and_amortization",
        "capital_expenditure", "working_capital", "total_debt",
        "cash_and_equivalents", "interest_expense", "revenue",
        "operating_income", "ebit", "ebitda",
    ],
    end_date="2024-03-01",
    period="ttm",
    limit=8,
    api_key=api_key,
)

These calls invoke the cache-aware API wrapper before returning FinancialMetrics and LineItem model instances to the agent's business logic.

Accessing the Analyst Registry

To inspect which agents consume these financial data sources for analyst agents:

from src.utils.analysts import get_agents_list

for agent in get_agents_list():
    print(f"{agent['display_name']}: {agent['description']}")

The registry in src/utils/analysts.py (lines 81-90) maintains the ANALYST_CONFIG dictionary, mapping agent display names (e.g., "Warren Buffett", "Cathie Wood") to their specific data requirements and LLM processing functions.

Summary

• Financial Datasets API serves as the primary external data provider for all analyst agents in the ai-hedge-fund system, accessed through src/tools/api.py.
• Type-safe models in src/data/models.py enforce consistent data structures across the application using Pydantic validation.
• Intelligent caching via src/data/cache.py eliminates redundant API calls during batch processing, backtesting, and multi-agent simulations.
• Resilient API wrapper handles authentication, rate limiting (429 errors), and exponential backoff automatically through _make_api_request().
• Modular architecture allows analyst agents in src/agents/ to consume standardized financial data without managing HTTP logic or raw JSON parsing.

Frequently Asked Questions

What financial data API does the ai-hedge-fund project use?

The system exclusively uses the Financial Datasets API (api.financialdatasets.ai), integrated through the centralized wrapper in src/tools/api.py. According to the source code, this API provides historical prices, fundamental metrics, insider trades, and company news required for the platform's quantitative analysis workflows.

How does the caching mechanism prevent API rate limits?

The src/data/cache.py module implements an in-memory store with deterministic keys based on query parameters including ticker symbol, date range, and metric type. Before any external HTTP call, the system checks the cache via methods like get_financial_metrics() and get_prices(), significantly reducing redundant requests during multi-agent backtests or repeated simulations.

Can I integrate alternative data sources like Yahoo Finance or Alpha Vantage?

Yes, the modular architecture supports swapping or extending financial data sources for analyst agents. You would implement new endpoint functions in src/tools/api.py or modify _make_api_request to route specific tickers to alternative providers, while maintaining the existing Pydantic models in src/data/models.py to ensure type consistency across the agent ecosystem.

What specific financial metrics are available to analyst agents?

Agents can access standardized metrics (P/E ratios, debt-to-equity, revenue growth, ROIC) via get_financial_metrics(), and granular line items (free cash flow, EBITDA, working capital, capital expenditure) via search_line_items(). The complete schema definitions reside in src/data/models.py within the FinancialMetrics and LineItem classes, ensuring all agents work with consistently typed data structures.

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