agents — AI Investor Persona Agents

🎯 Why This Module Exists

Without this module, the system would be a single monolithic trading algorithm with one perspective — a brittle approach that fails whenever market conditions shift away from its narrow worldview. The agents module exists because investment decision-making is inherently multi-perspective: different market conditions favor different philosophies. By encoding 19 distinct investor personas (Warren Buffett’s value focus, Cathie Wood’s innovation thesis, Michael Burry’s contrarian analysis, etc.) as independent AI agents, the system creates an ensemble of diverse viewpoints. Each agent independently analyzes the same stock data through its unique philosophical lens, producing a signal (bullish/bearish/neutral with confidence). This parallel, independent analysis mirrors how real hedge funds operate: analysts research independently, then an investment committee (here, the risk + portfolio managers) synthesizes their views. The module is designed for maximum extensibility — adding a new investor persona requires only creating a new Python file with a system prompt and registering it in analysts.py. The ANALYST_CONFIG dictionary in src/utils/analysts.py serves as the single source of truth for all agent metadata, display names, and function references.

🚶 Step-by-Step Narrated Walkthrough

Follow a single Warren Buffett agent analyzing AAPL as it flows through the entire agents pipeline:

1. State Initialization — AgentState is created with tickers=["AAPL"], a date range, an empty analyst_signals dict, and the current portfolio holdings. This shared state object is the only communication channel between agents.
2. Fan-Out Dispatch — LangGraph dispatches all 19 agents in parallel from start_node. Each agent receives the same AgentState reference but writes to its own key in analyst_signals.
3. Financial Metrics Fetch — warren_buffett_agent calls get_financial_metrics("AAPL", end_date, period="ttm", limit=10) to retrieve trailing-twelve-month fundamentals: ROE, debt ratios, profit margins, current ratio.
4. Line Items Retrieval — The agent calls search_line_items() for 12 specific items: capital expenditure, depreciation, net income, outstanding shares, total assets/liabilities, shareholders’ equity, dividends, share buybacks, gross profit, revenue, and free cash flow.
5. Market Cap Lookup — get_market_cap("AAPL", end_date) returns current market capitalization for intrinsic value comparison.
6. Multi-Factor Analysis — The agent runs seven analysis functions sequentially: analyze_fundamentals, analyze_consistency, analyze_moat, analyze_pricing_power, analyze_book_value_growth, analyze_management_quality, and calculate_intrinsic_value. Each returns a score and detailed breakdown.
7. Prompt Construction — A system prompt encodes Buffett’s value investing philosophy (moat analysis, margin of safety, management quality, circle of competence). The human message contains the raw analysis data and scores for the LLM to interpret.
8. LLM Invocation — call_llm() sends the prompt to GPT-4 with WarrenBuffettSignal as the Pydantic output model, ensuring structured JSON: {"signal": "bullish", "confidence": 75, "reasoning": "..."}.
9. Signal Storage — The parsed signal is written to state["data"]["analyst_signals"]["warren_buffett_agent"]. The agent returns updated state with its message appended.
10. Fan-In Convergence — Once all 19 agents complete, LangGraph routes to risk_management_agent. The risk manager fetches price data for each ticker and calculates volatility metrics (daily vol, annualized vol, percentile rank) and cross-ticker correlation matrices.
11. Risk Assessment — For each ticker, the risk manager computes a volatility-adjusted position limit (low vol: up to 25%, high vol: down to 5%) multiplied by a correlation adjustment factor (high correlation reduces limits to prevent concentrated bets). The result is a dollar-denominated remaining_position_limit.
12. Portfolio Decision — portfolio_management_agent reads all analyst signals and risk limits, computes deterministic allowed actions per ticker (buy/sell/short/cover/hold with max quantities), then sends a compact prompt to the LLM. The LLM returns PortfolioDecision objects with action, quantity, confidence, and reasoning for each ticker.

Signal Aggregation & Risk-Adjusted Position Sizing

The Problem: Given 19 independent agent signals (bullish/bearish/neutral with varying confidence levels) and market data for multiple tickers, determine safe position sizes that account for both individual stock risk and portfolio-level correlation risk.

The Approach: The risk manager operates in three phases. First, it fetches price history for all tickers (including existing portfolio positions) and computes volatility metrics: daily standard deviation of returns, annualized volatility (daily vol × √252), and a percentile rank comparing recent volatility to historical rolling 30-day windows. Second, it builds a cross-ticker correlation matrix from aligned daily returns and computes an average correlation for each ticker against actively held positions. Third, it combines these into a position limit: a base 20% allocation is multiplied by a volatility factor (1.25× for low vol <15%, down to 0.50× for extreme vol >50%) and then by a correlation factor (0.70× for highly correlated assets ≥0.8, up to 1.10× for uncorrelated assets <0.2).

Why This Algorithm: Simple VaR calculations would require distributional assumptions. Fixed percentages ignore market conditions entirely. This tiered approach is interpretable, deterministic, and adapts to both individual asset risk and portfolio concentration — and all computation happens before the LLM step, so position limits are never hallucinated.

graph TD
    A["Fetch prices for all tickers"] --> B["Calculate daily returns"]
    B --> C{"Sufficient data?"}
    C -->|"Yes"| D["Compute annualized volatility"]
    C -->|"No"| E["Use default 5% daily vol"]
    D --> F["Build correlation matrix"]
    E --> F
    F --> G{"Multiple tickers?"}
    G -->|"Yes"| H["Compute avg correlation with active positions"]
    G -->|"No"| I["Correlation multiplier = 1.0"]
    H --> J["Volatility-adjusted limit pct"]
    I --> J
    J --> K["Combined limit = base x vol_factor x corr_factor"]
    K --> L["Position limit in dollars"]
    L --> M["Remaining limit = limit - current exposure"]

Hot Paths

The most performance-sensitive code paths in this module:

• Parallel LLM calls (fan-out phase): 19 agents each making 1–3 API calls to OpenAI/Groq. Total latency is bounded by the slowest agent (typically 3–10 seconds), not the sum, thanks to LangGraph’s parallel execution model.
• Financial data fetching: Each agent makes 2–4 HTTP calls to the Financial Datasets API. With 19 agents × 4 calls × N tickers, this can generate significant API traffic. Agents fetch data independently (no shared cache at the agent level).
• Volatility calculation: calculate_volatility_metrics() computes rolling 30-day standard deviation over the full price history — O(n) where n is the number of price points. Fast for typical 60-day windows.

Resource Usage

• Memory: AgentState holds financial data for all tickers in memory simultaneously. Each agent’s analysis data (metrics, line items, market cap) is scoped to its function and garbage-collected after the signal is stored. The correlation matrix is O(k²) where k is the number of tickers.
• I/O: Dominated by external API calls — Financial Datasets API for market data, OpenAI/Groq for LLM inference. The sequential risk_manager → portfolio_manager phase is fast (single LLM call each) since it operates on pre-computed signals, not raw data.
• Token usage: Each persona agent sends 1 LLM request with ~2,000–5,000 tokens (system prompt + financial data). The portfolio manager sends a compressed prompt (<1,000 tokens) containing only signal/confidence pairs and allowed actions.