core/data-tools/ — Data Models, API Tools & LLM Integration

What is this & why does it exist?

This sub-module bundles the utility layers that every agent depends on but that have no business logic of their own. tools/api.py wraps the Financial Datasets API with functions like get_prices(), get_financial_metrics(), and get_insider_trades(). data/cache.py provides in-memory caching to avoid redundant API calls within a single run. llm/models.py abstracts 14 LLM providers (OpenAI, Groq, Anthropic, DeepSeek, Google, Ollama, etc.) behind a single get_model() factory. cli/input.py handles argument parsing with interactive agent and model selection via questionary.

Why Is It Designed This Way?

The key design decision is separation of infrastructure from intelligence. Agents should focus on analysis logic, not HTTP retries or provider-specific SDK quirks. The get_model() factory uses a simple if/elif chain rather than a plugin registry because the provider list is known at compile time and each provider has unique initialization logic (different env vars, base URLs, authentication flows). The cache uses in-memory dicts rather than Redis/disk because runs are short-lived (seconds to minutes) and the cache only needs to survive within a single run_hedge_fund() invocation. Pydantic models enforce data contracts at the API boundary so agents never receive malformed data.

get_model() — LLM Provider Factory (llm/models.py)

def get_model(model_name: str, model_provider: ModelProvider,
               api_keys: dict = None):
    if model_provider == ModelProvider.GROQ:
        # WHY: Check api_keys dict first (webapp passes keys via API),
        # fall back to env var (CLI usage)
        api_key = (api_keys or {}).get("GROQ_API_KEY") or os.getenv("GROQ_API_KEY")
        if not api_key:
            raise ValueError("Groq API key not found.")
        return ChatGroq(model=model_name, api_key=api_key)

    elif model_provider == ModelProvider.OPENAI:
        api_key = (api_keys or {}).get("OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY")
        base_url = os.getenv("OPENAI_API_BASE")  # WHY: Supports custom endpoints (Azure proxy, etc.)
        if not api_key:
            raise ValueError("OpenAI API key not found.")
        return ChatOpenAI(model=model_name, api_key=api_key, base_url=base_url)

    elif model_provider == ModelProvider.OLLAMA:
        # WHY: Ollama doesn't need an API key - it's local inference
        ollama_host = os.getenv("OLLAMA_HOST", "localhost")
        base_url = os.getenv("OLLAMA_BASE_URL", f"http://{ollama_host}:11434")
        return ChatOllama(model=model_name, base_url=base_url)

    elif model_provider == ModelProvider.OPENROUTER:
        api_key = (api_keys or {}).get("OPENROUTER_API_KEY") or os.getenv("OPENROUTER_API_KEY")
        # WHY: OpenRouter requires extra headers for attribution/ranking
        return ChatOpenAI(
            model=model_name, openai_api_key=api_key,
            openai_api_base="https://openrouter.ai/api/v1",
            model_kwargs={"extra_headers": {"HTTP-Referer": site_url, "X-Title": site_name}}
        )
    # ... 10 more providers follow the same pattern