agents/quantitative/ — Quantitative Analysis Agents

📚 What is this & why does it exist?

While the persona agents bring qualitative judgment, the quantitative agents provide systematic, data-driven analysis. The fundamentals agent examines financial statements, the technicals agent analyzes price and volume patterns, the sentiment agent gauges market mood from insider trades and news, and the valuation agent calculates intrinsic value using DCF and comparables. Together they form a comprehensive quantitative foundation that the persona agents' qualitative insights build upon.

🤔 Why Is It Designed This Way?

The quantitative agents use a fundamentally different approach from the persona agents. Instead of sending data to an LLM with a philosophical prompt, they compute signals algorithmically using threshold-based scoring and weighted ensemble methods. The fundamentals agent checks whether ROE exceeds 15%, the technicals agent calculates moving average crossovers, and the sentiment agent counts bullish vs. bearish insider trades. This deterministic approach makes the quantitative agents faster, cheaper (no LLM calls for most), and reproducible. The valuation agent is the exception — it uses four mathematical models (Owner Earnings, DCF with WACC, comparable multiples, and residual income) and aggregates them with configurable weights. The trade-off is less nuance than LLM-based agents, but the consistency and speed are worth it for systematic metrics.

fundamentals_analyst_agent — Threshold-Based Analysis

def fundamentals_analyst_agent(state: AgentState, agent_id: str = "fundamentals_analyst_agent"):
    """Analyzes fundamental data and generates trading signals for multiple tickers."""
    data = state["data"]
    end_date = data["end_date"]
    tickers = data["tickers"]
    api_key = get_api_key_from_state(state, "FINANCIAL_DATASETS_API_KEY")
    fundamental_analysis = {}

    for ticker in tickers:
        financial_metrics = get_financial_metrics(
            ticker=ticker, end_date=end_date, period="ttm", limit=10, api_key=api_key,
        )
        if not financial_metrics:
            continue

        metrics = financial_metrics[0]  # Most recent period
        signals = []
        reasoning = {}

        # 1. Profitability Analysis
        return_on_equity = metrics.return_on_equity
        net_margin = metrics.net_margin
        operating_margin = metrics.operating_margin

        thresholds = [
            (return_on_equity, 0.15),   # Strong ROE above 15%
            (net_margin, 0.20),          # Healthy profit margins
            (operating_margin, 0.15),    # Strong operating efficiency
        ]
        profitability_score = sum(
            metric is not None and metric > threshold
            for metric, threshold in thresholds
        )

        signals.append(
            "bullish" if profitability_score >= 2
            else "bearish" if profitability_score == 0
            else "neutral"
        )

        # 2. Growth Analysis
        revenue_growth = metrics.revenue_growth
        earnings_growth = metrics.earnings_growth
        book_value_growth = metrics.book_value_growth

        thresholds = [
            (revenue_growth, 0.10),    # 10% revenue growth
            (earnings_growth, 0.10),   # 10% earnings growth
            (book_value_growth, 0.10), # 10% book value growth
        ]
        growth_score = sum(
            metric is not None and metric > threshold
            for metric, threshold in thresholds
        )

        # 3. Financial Health
        current_ratio = metrics.current_ratio
        debt_to_equity = metrics.debt_to_equity
        health_score = 0
        if current_ratio and current_ratio > 1.5:
            health_score += 1
        if debt_to_equity and debt_to_equity < 0.5:
            health_score += 1

Weighted Signal Combination

# Five independent strategies, each producing its own signal
strategy_weights = {
    "trend": 0.25,          # EMA crossovers, MACD
    "mean_reversion": 0.20, # Bollinger Bands, z-score
    "momentum": 0.25,       # RSI, rate of change
    "volatility": 0.15,     # ATR, vol regime
    "stat_arb": 0.15,       # Hurst exponent, half-life
}

# Each strategy returns {signal, confidence, metrics}
combined_signal = weighted_signal_combination(
    {
        "trend": trend_signals,
        "mean_reversion": mean_reversion_signals,
        "momentum": momentum_signals,
        "volatility": volatility_signals,
        "stat_arb": stat_arb_signals,
    },
    strategy_weights,
)