Supported LLM Providers and Configuration in ai-hedge-fund: Complete Integration Guide

The ai-hedge-fund repository supports 29 LLM providers including OpenAI, Anthropic, Google, and Groq, with configuration resolved through a hierarchy of agent-specific overrides, system metadata, and environment variables managed in src/llm/models.py and src/utils/llm.py.

The ai-hedge-fund project implements a flexible, provider-agnostic abstraction layer for large language models that allows trading agents to invoke models from any supported service. This system handles provider enumeration, API key resolution, and automatic retry logic through a centralized configuration framework defined in the core source files.

Core Architecture and Provider Enumeration

The foundation of the LLM system resides in src/llm/models.py, which defines the ModelProvider enum and LLMModel data class. The codebase currently supports 29 distinct providers, including:

• OpenAI, Anthropic, Google, Groq, DeepSeek, OpenRouter
• Ollama (local deployment)
• Meta, Mistral, Azure OpenAI, GigaChat, xAI, Alibaba

Available models are declaratively specified in two JSON configuration files:

• src/llm/api_models.json – Cloud-based API models with display names and identifiers
• src/llm/ollama_models.json – Local Ollama model catalog

The LLM_ORDER list used by the UI is dynamically generated from these files at runtime via [model.to_choice_tuple() for model in AVAILABLE_MODELS], ensuring the interface automatically reflects any additions without code changes.

ModelProvider Enum and Data Structures

The ModelProvider enum in src/llm/models.py provides type-safe provider identification, while the LLMModel dataclass encapsulates display names, model identifiers, and provider associations. The get_model factory function constructs the appropriate LangChain client based on these definitions.

Configuration Resolution Hierarchy

The call_llm helper in src/utils/llm.py implements a three-tier configuration resolution strategy (lines 24-48):

1. Agent-specific overrides – If the request object in AgentState implements get_agent_model_config(agent_name), the function extracts model_name and model_provider specific to that agent.

2. System-wide metadata fallback – When no per-agent config exists, the system falls back to state["metadata"]["model_name"] and state["metadata"]["model_provider"].

3. Global defaults – If neither override is present, the system defaults to gpt-4.1 with provider OPENAI (lines 33-40).

API Key Resolution

The get_model function retrieves API keys through two mechanisms:

• From the api_keys dictionary passed within the request state
• From environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, etc.)

Missing keys raise a ValueError directing users to configure the variable in a .env file at the repository root.

Runtime Model Selection and Usage

Agents invoke models through the call_llm utility, which accepts Pydantic schemas for structured output and handles retries with progress indicators. The following example demonstrates overriding the default provider with Anthropic:

from src.utils.llm import call_llm
from src.graph.state import AgentState
from src.utils.llm import get_agent_model_config
from src.utils.progress import progress
from pydantic import BaseModel

class Forecast(BaseModel):
    price: float
    confidence: float

state = AgentState({
    "metadata": {
        "model_name": "claude-sonnet-4-5-20250929",
        "model_provider": "ANTHROPIC"
    }
})

response = call_llm(
    prompt="Predict the closing price of AAPL tomorrow.",
    pydantic_model=Forecast,
    agent_name="price_forecaster",
    state=state,
    max_retries=2
)

print(response)  # → Forecast(price=..., confidence=...)

This implementation automatically retrieves ANTHROPIC_API_KEY from environment variables and validates the response against the Forecast schema.

Extending the System with Custom Providers

Adding support for new LLM providers requires three modifications:

1. Extend the enum – Add a new value to ModelProvider in src/llm/models.py
2. Update model catalog – Append entries to src/llm/api_models.json (or ollama_models.json for local models)
3. Implement client factory – Add a branch in get_model to instantiate the appropriate LangChain client following the existing API key extraction pattern

The UI automatically incorporates new models because LLM_ORDER regenerates from the JSON catalog on application startup.

Environment Variables Reference

Configure access credentials in a .env file at the repository root. The system loads these automatically via python-dotenv:

• OpenAI: OPENAI_API_KEY, optional OPENAI_API_BASE
• Anthropic: ANTHROPIC_API_KEY
• Groq: GROQ_API_KEY
• DeepSeek: DEEPSEEK_API_KEY
• Google: GOOGLE_API_KEY
• OpenRouter: OPENROUTER_API_KEY
• Azure OpenAI: AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT_NAME
• GigaChat: GIGACHAT_API_KEY or GIGACHAT_CREDENTIALS
• xAI: XAI_API_KEY
• Ollama: OLLAMA_HOST or OLLAMA_BASE_URL (defaults to http://localhost:11434)

Summary

• The ai-hedge-fund system supports 29 LLM providers through a unified abstraction layer defined in src/llm/models.py
• Configuration follows a strict hierarchy: agent-specific overrides → system metadata → global defaults (gpt-4.1 via OpenAI)
• The call_llm function in src/utils/llm.py handles model instantiation, API key resolution from state or environment, and retry logic
• Model definitions live declaratively in src/llm/api_models.json and ollama_models.json, enabling automatic UI generation via LLM_ORDER
• Adding providers requires only enum extension, JSON updates, and factory implementation without modifying core agent logic

Frequently Asked Questions

How many LLM providers does ai-hedge-fund support?

The repository supports 29 distinct providers including OpenAI, Anthropic, Google, Groq, DeepSeek, OpenRouter, Ollama, Azure OpenAI, GigaChat, and xAI. The complete list is enumerated in the ModelProvider class within src/llm/models.py.

Where are the supported models defined in the codebase?

Supported models are declared in two JSON files: src/llm/api_models.json for cloud providers and src/llm/ollama_models.json for local Ollama deployments. These files map display names to model identifiers and providers, dynamically populating the LLM_ORDER list used by the Gradio interface.

How do I configure a specific model for an individual agent?

Pass a configuration object implementing get_agent_model_config(agent_name) in your AgentState, or set model_name and model_provider keys in state["metadata"]. If neither is specified, the agent automatically falls back to the global defaults specified in lines 33-40 of src/utils/llm.py.

What environment variables are required to run models from different providers?

Each provider requires its own API key environment variable (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY). The system automatically loads these from a .env file via python-dotenv, or accepts them directly through the api_keys dictionary passed in the request state to call_llm.

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