udiedrichsen_stock-analysis/scripts/analyze_stock.py

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "yfinance>=0.2.40",
#     "pandas>=2.0.0",
#     "fear-and-greed>=0.4",
#     "edgartools>=2.0.0",
#     "feedparser>=6.0.0",
# ]
# ///
"""
Stock analysis using Yahoo Finance data.

Usage:
    uv run analyze_stock.py TICKER [TICKER2 ...] [--output text|json] [--verbose]
"""

import argparse
import asyncio
import json
import sys
import time
from dataclasses import dataclass, asdict
from datetime import datetime
from typing import Literal

import pandas as pd
import yfinance as yf


# Top 20 supported cryptocurrencies
SUPPORTED_CRYPTOS = {
    "BTC-USD", "ETH-USD", "BNB-USD", "SOL-USD", "XRP-USD",
    "ADA-USD", "DOGE-USD", "AVAX-USD", "DOT-USD", "MATIC-USD",
    "LINK-USD", "ATOM-USD", "UNI-USD", "LTC-USD", "BCH-USD",
    "XLM-USD", "ALGO-USD", "VET-USD", "FIL-USD", "NEAR-USD",
}

# Crypto category mapping for sector-like analysis
CRYPTO_CATEGORIES = {
    "BTC-USD": "Store of Value",
    "ETH-USD": "Smart Contract L1",
    "BNB-USD": "Exchange Token",
    "SOL-USD": "Smart Contract L1",
    "XRP-USD": "Payment",
    "ADA-USD": "Smart Contract L1",
    "DOGE-USD": "Meme",
    "AVAX-USD": "Smart Contract L1",
    "DOT-USD": "Interoperability",
    "MATIC-USD": "Layer 2",
    "LINK-USD": "Oracle",
    "ATOM-USD": "Interoperability",
    "UNI-USD": "DeFi",
    "LTC-USD": "Payment",
    "BCH-USD": "Payment",
    "XLM-USD": "Payment",
    "ALGO-USD": "Smart Contract L1",
    "VET-USD": "Enterprise",
    "FIL-USD": "Storage",
    "NEAR-USD": "Smart Contract L1",
}


def detect_asset_type(ticker: str) -> Literal["stock", "crypto"]:
    """Detect asset type from ticker format."""
    ticker_upper = ticker.upper()
    if ticker_upper.endswith("-USD"):
        base = ticker_upper[:-4]
        if base.isalpha():
            return "crypto"
    return "stock"


@dataclass
class StockData:
    ticker: str
    info: dict
    earnings_history: pd.DataFrame | None
    analyst_info: dict | None
    price_history: pd.DataFrame | None
    asset_type: Literal["stock", "crypto"] = "stock"


@dataclass
class CryptoFundamentals:
    """Crypto-specific fundamentals (replaces P/E, margins for crypto)."""
    market_cap: float | None
    market_cap_rank: str  # "large", "mid", "small"
    volume_24h: float | None
    circulating_supply: float | None
    category: str | None  # "Smart Contract L1", "DeFi", etc.
    btc_correlation: float | None  # 30-day correlation to BTC
    score: float
    explanation: str


@dataclass
class EarningsSurprise:
    score: float
    explanation: str
    actual_eps: float | None = None
    expected_eps: float | None = None
    surprise_pct: float | None = None


@dataclass
class Fundamentals:
    score: float
    key_metrics: dict
    explanation: str


@dataclass
class AnalystSentiment:
    score: float | None
    summary: str
    consensus_rating: str | None = None
    price_target: float | None = None
    current_price: float | None = None
    upside_pct: float | None = None
    num_analysts: int | None = None


@dataclass
class HistoricalPatterns:
    score: float
    pattern_desc: str
    beats_last_4q: int | None = None
    avg_reaction_pct: float | None = None


@dataclass
class MarketContext:
    vix_level: float
    vix_status: str  # "calm", "elevated", "fear"
    spy_trend_10d: float
    qqq_trend_10d: float
    market_regime: str  # "bull", "bear", "choppy"
    score: float
    explanation: str
    # Safe-haven indicators (v4.0.0)
    gld_change_5d: float | None = None  # Gold ETF % change
    tlt_change_5d: float | None = None  # Treasury ETF % change
    uup_change_5d: float | None = None  # USD Index ETF % change
    risk_off_detected: bool = False  # True if flight to safety detected


@dataclass
class SectorComparison:
    sector_name: str
    industry_name: str
    stock_return_1m: float
    sector_return_1m: float
    relative_strength: float
    sector_trend: str  # "strong uptrend", "downtrend", etc.
    score: float
    explanation: str


@dataclass
class EarningsTiming:
    days_until_earnings: int | None
    days_since_earnings: int | None
    next_earnings_date: str | None
    last_earnings_date: str | None
    timing_flag: str  # "pre_earnings", "post_earnings", "safe"
    price_change_5d: float | None
    confidence_adjustment: float
    caveats: list[str]


@dataclass
class MomentumAnalysis:
    rsi_14d: float | None
    rsi_status: str  # "overbought", "oversold", "neutral"
    price_vs_52w_low: float | None
    price_vs_52w_high: float | None
    near_52w_high: bool
    near_52w_low: bool
    volume_ratio: float | None
    relative_strength_vs_sector: float | None
    score: float
    explanation: str


@dataclass
class SentimentAnalysis:
    score: float  # Overall -1.0 to 1.0
    explanation: str  # Human-readable summary

    # Sub-indicator scores
    fear_greed_score: float | None = None
    short_interest_score: float | None = None
    vix_structure_score: float | None = None
    insider_activity_score: float | None = None
    put_call_score: float | None = None

    # Raw data
    fear_greed_value: int | None = None  # 0-100
    fear_greed_status: str | None = None  # "Extreme Fear", etc.
    short_interest_pct: float | None = None
    days_to_cover: float | None = None
    vix_structure: str | None = None  # "contango", "backwardation", "flat"
    vix_slope: float | None = None
    insider_net_shares: int | None = None
    insider_net_value: float | None = None  # Millions USD
    put_call_ratio: float | None = None
    put_volume: int | None = None
    call_volume: int | None = None

    # Metadata
    indicators_available: int = 0
    data_freshness_warnings: list[str] | None = None


@dataclass
class Signal:
    ticker: str
    company_name: str
    recommendation: Literal["BUY", "HOLD", "SELL"]
    confidence: float
    final_score: float
    supporting_points: list[str]
    caveats: list[str]
    timestamp: str
    components: dict


def fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:
    """Fetch stock data from Yahoo Finance with retry logic."""
    max_retries = 3
    for attempt in range(max_retries):
        try:
            if verbose:
                print(f"Fetching data for {ticker}... (attempt {attempt + 1}/{max_retries})", file=sys.stderr)

            stock = yf.Ticker(ticker)
            info = stock.info

            # Validate ticker
            if not info or "regularMarketPrice" not in info:
                return None

            # Fetch earnings history
            try:
                earnings_history = stock.earnings_dates
            except Exception:
                earnings_history = None

            # Fetch analyst info
            try:
                analyst_info = {
                    "recommendations": stock.recommendations,
                    "analyst_price_targets": stock.analyst_price_targets,
                }
            except Exception:
                analyst_info = None

            # Fetch price history (1 year for historical patterns)
            try:
                price_history = stock.history(period="1y")
            except Exception:
                price_history = None

            return StockData(
                ticker=ticker,
                info=info,
                earnings_history=earnings_history,
                analyst_info=analyst_info,
                price_history=price_history,
                asset_type=detect_asset_type(ticker),
            )

        except Exception as e:
            if attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                if verbose:
                    print(f"Error fetching {ticker}: {e}. Retrying in {wait_time}s...", file=sys.stderr)
                time.sleep(wait_time)
            else:
                if verbose:
                    print(f"Failed to fetch {ticker} after {max_retries} attempts", file=sys.stderr)
                return None

    return None


def analyze_earnings_surprise(data: StockData) -> EarningsSurprise | None:
    """Analyze earnings surprise from most recent quarter."""
    if data.earnings_history is None or data.earnings_history.empty:
        return None

    try:
        # Get most recent earnings with actual data
        recent = data.earnings_history.sort_index(ascending=False).head(10)

        for idx, row in recent.iterrows():
            if pd.notna(row.get("Reported EPS")) and pd.notna(row.get("EPS Estimate")):
                actual = float(row["Reported EPS"])
                expected = float(row["EPS Estimate"])

                if expected == 0:
                    continue

                surprise_pct = ((actual - expected) / abs(expected)) * 100

                # Score based on surprise percentage
                if surprise_pct > 10:
                    score = 1.0
                elif surprise_pct > 5:
                    score = 0.7
                elif surprise_pct > 0:
                    score = 0.3
                elif surprise_pct > -5:
                    score = -0.3
                elif surprise_pct > -10:
                    score = -0.7
                else:
                    score = -1.0

                explanation = f"{'Beat' if surprise_pct > 0 else 'Missed'} by {abs(surprise_pct):.1f}%"

                return EarningsSurprise(
                    score=score,
                    explanation=explanation,
                    actual_eps=actual,
                    expected_eps=expected,
                    surprise_pct=surprise_pct,
                )

        return None

    except Exception:
        return None


def analyze_fundamentals(data: StockData) -> Fundamentals | None:
    """Analyze fundamental metrics."""
    info = data.info
    scores = []
    metrics = {}
    explanations = []

    try:
        # P/E Ratio (lower is better, but consider growth)
        pe_ratio = info.get("trailingPE") or info.get("forwardPE")
        if pe_ratio and pe_ratio > 0:
            metrics["pe_ratio"] = round(pe_ratio, 2)
            if pe_ratio < 15:
                scores.append(0.5)
                explanations.append(f"Attractive P/E: {pe_ratio:.1f}x")
            elif pe_ratio > 30:
                scores.append(-0.3)
                explanations.append(f"Elevated P/E: {pe_ratio:.1f}x")
            else:
                scores.append(0.1)

        # Operating Margin
        op_margin = info.get("operatingMargins")
        if op_margin:
            metrics["operating_margin"] = round(op_margin, 3)
            if op_margin > 0.15:
                scores.append(0.5)
                explanations.append(f"Strong margin: {op_margin*100:.1f}%")
            elif op_margin < 0.05:
                scores.append(-0.5)
                explanations.append(f"Weak margin: {op_margin*100:.1f}%")

        # Revenue Growth
        rev_growth = info.get("revenueGrowth")
        if rev_growth:
            metrics["revenue_growth_yoy"] = round(rev_growth, 3)
            if rev_growth > 0.20:
                scores.append(0.5)
                explanations.append(f"Strong growth: {rev_growth*100:.1f}% YoY")
            elif rev_growth < 0.05:
                scores.append(-0.3)
                explanations.append(f"Slow growth: {rev_growth*100:.1f}% YoY")
            else:
                scores.append(0.2)

        # Debt to Equity
        debt_equity = info.get("debtToEquity")
        if debt_equity is not None:
            metrics["debt_to_equity"] = round(debt_equity / 100, 2)
            if debt_equity < 50:
                scores.append(0.3)
            elif debt_equity > 200:
                scores.append(-0.5)
                explanations.append(f"High debt: D/E {debt_equity/100:.1f}x")

        if not scores:
            return None

        # Average and normalize
        avg_score = sum(scores) / len(scores)
        normalized_score = max(-1.0, min(1.0, avg_score))

        explanation = "; ".join(explanations) if explanations else "Mixed fundamentals"

        return Fundamentals(
            score=normalized_score,
            key_metrics=metrics,
            explanation=explanation,
        )

    except Exception:
        return None


def analyze_crypto_fundamentals(data: StockData, verbose: bool = False) -> CryptoFundamentals | None:
    """Analyze crypto-specific fundamentals (market cap, supply, category)."""
    if data.asset_type != "crypto":
        return None

    info = data.info
    ticker = data.ticker.upper()

    try:
        # Market cap analysis
        market_cap = info.get("marketCap")
        if not market_cap:
            return None

        # Categorize by market cap
        if market_cap >= 10_000_000_000:  # $10B+
            market_cap_rank = "large"
            cap_score = 0.3  # Large caps are more stable
        elif market_cap >= 1_000_000_000:  # $1B-$10B
            market_cap_rank = "mid"
            cap_score = 0.1
        else:
            market_cap_rank = "small"
            cap_score = -0.2  # Small caps are riskier

        # Volume analysis
        volume_24h = info.get("volume") or info.get("volume24Hr")
        volume_score = 0.0
        if volume_24h and market_cap:
            volume_to_cap = volume_24h / market_cap
            if volume_to_cap > 0.05:  # >5% daily turnover
                volume_score = 0.2  # High liquidity
            elif volume_to_cap < 0.01:
                volume_score = -0.2  # Low liquidity

        # Circulating supply
        circulating_supply = info.get("circulatingSupply")

        # Get crypto category
        category = CRYPTO_CATEGORIES.get(ticker, "Unknown")

        # Calculate BTC correlation (30 days)
        btc_correlation = None
        try:
            if ticker != "BTC-USD" and data.price_history is not None:
                btc = yf.Ticker("BTC-USD")
                btc_hist = btc.history(period="1mo")
                if not btc_hist.empty and len(data.price_history) > 5:
                    # Align dates and calculate correlation
                    crypto_returns = data.price_history["Close"].pct_change().dropna()
                    btc_returns = btc_hist["Close"].pct_change().dropna()
                    # Simple correlation on overlapping dates
                    common_dates = crypto_returns.index.intersection(btc_returns.index)
                    if len(common_dates) > 10:
                        btc_correlation = crypto_returns.loc[common_dates].corr(btc_returns.loc[common_dates])
        except Exception:
            pass

        # BTC correlation scoring (high correlation = less diversification benefit)
        corr_score = 0.0
        if btc_correlation is not None:
            if btc_correlation > 0.8:
                corr_score = -0.1  # Very correlated to BTC
            elif btc_correlation < 0.3:
                corr_score = 0.1  # Good diversification

        # Total score
        total_score = cap_score + volume_score + corr_score

        # Build explanation
        explanations = []
        explanations.append(f"Market cap: ${market_cap/1e9:.1f}B ({market_cap_rank})")
        if category != "Unknown":
            explanations.append(f"Category: {category}")
        if btc_correlation is not None:
            explanations.append(f"BTC corr: {btc_correlation:.2f}")

        return CryptoFundamentals(
            market_cap=market_cap,
            market_cap_rank=market_cap_rank,
            volume_24h=volume_24h,
            circulating_supply=circulating_supply,
            category=category,
            btc_correlation=round(btc_correlation, 2) if btc_correlation else None,
            score=max(-1.0, min(1.0, total_score)),
            explanation="; ".join(explanations),
        )

    except Exception as e:
        if verbose:
            print(f"Error analyzing crypto fundamentals: {e}", file=sys.stderr)
        return None


def analyze_analyst_sentiment(data: StockData) -> AnalystSentiment | None:
    """Analyze analyst sentiment and price targets."""
    info = data.info

    try:
        # Get current price
        current_price = info.get("regularMarketPrice") or info.get("currentPrice")
        if not current_price:
            return None

        # Get target price
        target_price = info.get("targetMeanPrice")

        # Get number of analysts
        num_analysts = info.get("numberOfAnalystOpinions")

        # Get recommendation
        recommendation = info.get("recommendationKey")

        if not target_price or not recommendation:
            return AnalystSentiment(
                score=None,
                summary="No analyst coverage available",
            )

        # Calculate upside
        upside_pct = ((target_price - current_price) / current_price) * 100

        # Score based on recommendation and upside
        rec_scores = {
            "strong_buy": 1.0,
            "buy": 0.7,
            "hold": 0.0,
            "sell": -0.7,
            "strong_sell": -1.0,
        }

        base_score = rec_scores.get(recommendation, 0.0)

        # Adjust based on upside
        if upside_pct > 20:
            score = min(1.0, base_score + 0.3)
        elif upside_pct > 10:
            score = min(1.0, base_score + 0.15)
        elif upside_pct < -10:
            score = max(-1.0, base_score - 0.3)
        else:
            score = base_score

        # Format recommendation
        rec_display = recommendation.replace("_", " ").title()

        summary = f"{rec_display} with {abs(upside_pct):.1f}% {'upside' if upside_pct > 0 else 'downside'}"
        if num_analysts:
            summary += f" ({num_analysts} analysts)"

        return AnalystSentiment(
            score=score,
            summary=summary,
            consensus_rating=rec_display,
            price_target=target_price,
            current_price=current_price,
            upside_pct=upside_pct,
            num_analysts=num_analysts,
        )

    except Exception:
        return AnalystSentiment(
            score=None,
            summary="Error analyzing analyst sentiment",
        )


def analyze_historical_patterns(data: StockData) -> HistoricalPatterns | None:
    """Analyze historical earnings patterns."""
    if data.earnings_history is None or data.price_history is None:
        return None

    if data.earnings_history.empty or data.price_history.empty:
        return None

    try:
        # Get last 4 quarters earnings dates
        earnings_dates = data.earnings_history.sort_index(ascending=False).head(4)

        beats = 0
        reactions = []

        for earnings_date, row in earnings_dates.iterrows():
            if pd.notna(row.get("Reported EPS")) and pd.notna(row.get("EPS Estimate")):
                actual = float(row["Reported EPS"])
                expected = float(row["EPS Estimate"])

                if actual > expected:
                    beats += 1

                # Try to get price reaction (day of earnings)
                try:
                    earnings_day = pd.Timestamp(earnings_date).date()

                    # Find closest trading day
                    price_data = data.price_history[data.price_history.index.date == earnings_day]

                    if not price_data.empty:
                        day_change = ((price_data["Close"].iloc[0] - price_data["Open"].iloc[0]) / price_data["Open"].iloc[0]) * 100
                        reactions.append(day_change)
                except Exception:
                    continue

        total_quarters = len(earnings_dates)
        if total_quarters == 0:
            return None

        # Score based on beat rate
        beat_rate = beats / total_quarters

        if beat_rate == 1.0:
            score = 0.8
        elif beat_rate >= 0.75:
            score = 0.5
        elif beat_rate >= 0.5:
            score = 0.0
        elif beat_rate >= 0.25:
            score = -0.5
        else:
            score = -0.8

        # Pattern description
        pattern_desc = f"{beats}/{total_quarters} quarters beat expectations"

        if reactions:
            avg_reaction = sum(reactions) / len(reactions)
            pattern_desc += f", avg reaction {avg_reaction:+.1f}%"
        else:
            avg_reaction = None

        return HistoricalPatterns(
            score=score,
            pattern_desc=pattern_desc,
            beats_last_4q=beats,
            avg_reaction_pct=avg_reaction,
        )

    except Exception:
        return None


def analyze_market_context(verbose: bool = False) -> MarketContext | None:
    """Analyze overall market conditions using VIX, SPY, QQQ, and safe-havens with 1h cache."""
    # Check cache first
    cached = _get_cached("market_context")
    if cached is not None:
        if verbose:
            print("Using cached market context (< 1h old)", file=sys.stderr)
        return cached

    try:
        if verbose:
            print("Fetching market indicators (VIX, SPY, QQQ)...", file=sys.stderr)

        # Fetch market indicators
        vix = yf.Ticker("^VIX")
        spy = yf.Ticker("SPY")
        qqq = yf.Ticker("QQQ")

        # Get current VIX level
        vix_info = vix.info
        vix_level = vix_info.get("regularMarketPrice") or vix_info.get("currentPrice")

        if not vix_level:
            return None

        # Determine VIX status
        if vix_level < 20:
            vix_status = "calm"
            vix_score = 0.2
        elif vix_level < 30:
            vix_status = "elevated"
            vix_score = 0.0
        else:
            vix_status = "fear"
            vix_score = -0.5

        # Get SPY and QQQ 10-day trends
        spy_hist = spy.history(period="1mo")
        qqq_hist = qqq.history(period="1mo")

        if spy_hist.empty or qqq_hist.empty:
            return None

        # Calculate 10-day price changes
        spy_10d_ago = spy_hist["Close"].iloc[-min(10, len(spy_hist))]
        spy_current = spy_hist["Close"].iloc[-1]
        spy_trend_10d = ((spy_current - spy_10d_ago) / spy_10d_ago) * 100

        qqq_10d_ago = qqq_hist["Close"].iloc[-min(10, len(qqq_hist))]
        qqq_current = qqq_hist["Close"].iloc[-1]
        qqq_trend_10d = ((qqq_current - qqq_10d_ago) / qqq_10d_ago) * 100

        # Determine market regime
        avg_trend = (spy_trend_10d + qqq_trend_10d) / 2

        if avg_trend > 3:
            market_regime = "bull"
            regime_score = 0.3
        elif avg_trend < -3:
            market_regime = "bear"
            regime_score = -0.4
        else:
            market_regime = "choppy"
            regime_score = -0.1

        # Calculate overall score
        overall_score = (vix_score + regime_score) / 2

        # NEW v4.0.0: Fetch safe-haven indicators (GLD, TLT, UUP)
        gld_change_5d = None
        tlt_change_5d = None
        uup_change_5d = None
        risk_off_detected = False

        try:
            if verbose:
                print("Fetching safe-haven indicators (GLD, TLT, UUP)...", file=sys.stderr)

            # Fetch safe-haven ETFs
            gld = yf.Ticker("GLD")  # Gold
            tlt = yf.Ticker("TLT")  # 20+ Year Treasury
            uup = yf.Ticker("UUP")  # USD Index

            gld_hist = gld.history(period="10d")
            tlt_hist = tlt.history(period="10d")
            uup_hist = uup.history(period="10d")

            # Calculate 5-day changes
            if not gld_hist.empty and len(gld_hist) >= 5:
                gld_5d_ago = gld_hist["Close"].iloc[-min(5, len(gld_hist))]
                gld_current = gld_hist["Close"].iloc[-1]
                gld_change_5d = ((gld_current - gld_5d_ago) / gld_5d_ago) * 100

            if not tlt_hist.empty and len(tlt_hist) >= 5:
                tlt_5d_ago = tlt_hist["Close"].iloc[-min(5, len(tlt_hist))]
                tlt_current = tlt_hist["Close"].iloc[-1]
                tlt_change_5d = ((tlt_current - tlt_5d_ago) / tlt_5d_ago) * 100

            if not uup_hist.empty and len(uup_hist) >= 5:
                uup_5d_ago = uup_hist["Close"].iloc[-min(5, len(uup_hist))]
                uup_current = uup_hist["Close"].iloc[-1]
                uup_change_5d = ((uup_current - uup_5d_ago) / uup_5d_ago) * 100

            # Risk-off detection: All three safe-havens rising together
            if (gld_change_5d is not None and gld_change_5d >= 2.0 and
                tlt_change_5d is not None and tlt_change_5d >= 1.0 and
                uup_change_5d is not None and uup_change_5d >= 1.0):
                risk_off_detected = True
                overall_score -= 0.5  # Reduce score significantly
                if verbose:
                    print(f"    🛡️ RISK-OFF DETECTED: GLD {gld_change_5d:+.1f}%, TLT {tlt_change_5d:+.1f}%, UUP {uup_change_5d:+.1f}%", file=sys.stderr)

        except Exception as e:
            if verbose:
                print(f"    Safe-haven indicators unavailable: {e}", file=sys.stderr)

        # Build explanation
        explanation = f"VIX {vix_level:.1f} ({vix_status}), Market {market_regime} (SPY {spy_trend_10d:+.1f}%, QQQ {qqq_trend_10d:+.1f}% 10d)"
        if risk_off_detected:
            explanation += " ⚠️ RISK-OFF MODE"

        result = MarketContext(
            vix_level=vix_level,
            vix_status=vix_status,
            spy_trend_10d=spy_trend_10d,
            qqq_trend_10d=qqq_trend_10d,
            market_regime=market_regime,
            score=overall_score,
            explanation=explanation,
            gld_change_5d=gld_change_5d,
            tlt_change_5d=tlt_change_5d,
            uup_change_5d=uup_change_5d,
            risk_off_detected=risk_off_detected,
        )

        # Cache the result for 1 hour
        _set_cache("market_context", result)
        return result

    except Exception as e:
        if verbose:
            print(f"Error analyzing market context: {e}", file=sys.stderr)
        return None


def get_sector_etf_ticker(sector: str) -> str | None:
    """Map sector name to corresponding sector ETF ticker."""
    sector_map = {
        "Financial Services": "XLF",
        "Financials": "XLF",
        "Technology": "XLK",
        "Healthcare": "XLV",
        "Consumer Cyclical": "XLY",
        "Consumer Defensive": "XLP",
        "Utilities": "XLU",
        "Basic Materials": "XLB",
        "Real Estate": "XLRE",
        "Communication Services": "XLC",
        "Industrials": "XLI",
        "Energy": "XLE",
    }

    return sector_map.get(sector)


# ============================================================================
# Breaking News Check (v4.0.0)
# ============================================================================

# Crisis keywords by category
CRISIS_KEYWORDS = {
    "war": ["war", "invasion", "military strike", "attack", "conflict", "combat"],
    "economic": ["recession", "crisis", "collapse", "default", "bankruptcy", "crash"],
    "regulatory": ["sanctions", "embargo", "ban", "investigation", "fraud", "probe"],
    "disaster": ["earthquake", "hurricane", "pandemic", "outbreak", "disaster", "catastrophe"],
    "financial": ["emergency rate", "fed emergency", "bailout", "circuit breaker", "trading halt"],
}

# Geopolitical event → sector mapping (v4.0.0)
GEOPOLITICAL_RISK_MAP = {
    "taiwan": {
        "keywords": ["taiwan", "tsmc", "strait"],
        "sectors": ["Technology", "Communication Services"],
        "sector_etfs": ["XLK", "XLC"],
        "impact": "Semiconductor supply chain disruption",
        "affected_tickers": ["NVDA", "AMD", "TSM", "INTC", "QCOM", "AVGO", "MU"],
    },
    "china": {
        "keywords": ["china", "beijing", "tariff", "trade war"],
        "sectors": ["Technology", "Consumer Cyclical", "Consumer Defensive"],
        "sector_etfs": ["XLK", "XLY", "XLP"],
        "impact": "Tech supply chain and consumer market exposure",
        "affected_tickers": ["AAPL", "QCOM", "NKE", "SBUX", "MCD", "YUM", "TGT", "WMT"],
    },
    "russia_ukraine": {
        "keywords": ["russia", "ukraine", "putin", "kyiv", "moscow"],
        "sectors": ["Energy", "Materials"],
        "sector_etfs": ["XLE", "XLB"],
        "impact": "Energy and commodity price volatility",
        "affected_tickers": ["XOM", "CVX", "COP", "SLB", "MOS", "CF", "NTR", "ADM"],
    },
    "middle_east": {
        "keywords": ["iran", "israel", "gaza", "saudi", "middle east", "gulf"],
        "sectors": ["Energy", "Industrials"],
        "sector_etfs": ["XLE", "XLI"],
        "impact": "Oil price volatility and defense spending",
        "affected_tickers": ["XOM", "CVX", "COP", "LMT", "RTX", "NOC", "GD", "BA"],
    },
    "banking_crisis": {
        "keywords": ["bank failure", "credit crisis", "liquidity crisis", "bank run"],
        "sectors": ["Financials"],
        "sector_etfs": ["XLF"],
        "impact": "Financial sector contagion risk",
        "affected_tickers": ["JPM", "BAC", "WFC", "C", "GS", "MS", "USB", "PNC"],
    },
}


def check_breaking_news(verbose: bool = False) -> list[str] | None:
    """
    Check Google News RSS for breaking market/economic crisis events (last 24h).
    Returns list of alert strings or None.
    Uses 1h cache to avoid excessive API calls.
    """
    # Check cache first
    cached = _get_cached("breaking_news")
    if cached is not None:
        return cached

    alerts = []

    try:
        import feedparser
        from datetime import datetime, timezone, timedelta

        if verbose:
            print("Checking breaking news (Google News RSS)...", file=sys.stderr)

        # Google News RSS feeds for finance/business
        rss_urls = [
            "https://news.google.com/rss/search?q=stock+market+when:24h&hl=en-US&gl=US&ceid=US:en",
            "https://news.google.com/rss/search?q=economy+crisis+when:24h&hl=en-US&gl=US&ceid=US:en",
        ]

        now = datetime.now(timezone.utc)
        cutoff_time = now - timedelta(hours=24)

        for url in rss_urls:
            try:
                feed = feedparser.parse(url)

                for entry in feed.entries[:20]:  # Check top 20 headlines
                    # Parse publication date
                    pub_date = None
                    if hasattr(entry, "published_parsed") and entry.published_parsed:
                        pub_date = datetime(*entry.published_parsed[:6], tzinfo=timezone.utc)

                    # Skip if older than 24h
                    if pub_date and pub_date < cutoff_time:
                        continue

                    title = entry.get("title", "").lower()
                    summary = entry.get("summary", "").lower()
                    text = f"{title} {summary}"

                    # Check for crisis keywords
                    for category, keywords in CRISIS_KEYWORDS.items():
                        for keyword in keywords:
                            if keyword in text:
                                alert_text = entry.get("title", "Unknown alert")
                                hours_ago = int((now - pub_date).total_seconds() / 3600) if pub_date else None
                                time_str = f"{hours_ago}h ago" if hours_ago is not None else "recent"

                                alert = f"{alert_text} ({time_str})"
                                if alert not in alerts:  # Deduplicate
                                    alerts.append(alert)
                                    if verbose:
                                        print(f"    ⚠️ Alert: {alert}", file=sys.stderr)
                                break
                        if len(alerts) >= 3:  # Limit to 3 alerts
                            break

                    if len(alerts) >= 3:
                        break

            except Exception as e:
                if verbose:
                    print(f"    Failed to fetch {url}: {e}", file=sys.stderr)
                continue

        # Cache results (even if empty) for 1 hour
        result = alerts if alerts else None
        _set_cache("breaking_news", result)
        return result

    except Exception as e:
        if verbose:
            print(f"    Breaking news check failed: {e}", file=sys.stderr)
        return None


def check_sector_geopolitical_risk(
    ticker: str,
    sector: str | None,
    breaking_news: list[str] | None,
    verbose: bool = False
) -> tuple[str | None, float]:
    """
    Check if ticker is exposed to geopolitical risks based on breaking news.
    Returns (warning_message, confidence_penalty).

    Args:
        ticker: Stock ticker symbol
        sector: Stock sector (from yfinance)
        breaking_news: List of breaking news alerts
        verbose: Print debug info

    Returns:
        (warning_message, confidence_penalty) where:
        - warning_message: None or string like "⚠️ SECTOR RISK: Taiwan tensions affect semiconductors"
        - confidence_penalty: 0.0 (no risk) to 0.5 (high risk)
    """
    if not breaking_news:
        return None, 0.0

    # Combine all breaking news into single text for keyword matching
    news_text = " ".join(breaking_news).lower()

    # Check each geopolitical event
    for event_name, event_data in GEOPOLITICAL_RISK_MAP.items():
        # Check if any keywords from this event appear in breaking news
        keywords_found = []
        for keyword in event_data["keywords"]:
            if keyword in news_text:
                keywords_found.append(keyword)

        if not keywords_found:
            continue

        # Check if ticker is in affected list
        if ticker in event_data["affected_tickers"]:
            # Direct ticker exposure
            warning = f"⚠️ SECTOR RISK: {event_data['impact']} (detected: {', '.join(keywords_found)})"
            penalty = 0.3  # Reduce BUY confidence by 30%

            if verbose:
                print(f"    Geopolitical risk detected: {event_name} affects {ticker}", file=sys.stderr)

            return warning, penalty

        # Check if sector is affected (even if ticker not in list)
        if sector and sector in event_data["sectors"]:
            # Sector exposure (weaker signal)
            warning = f"⚠️ SECTOR RISK: {sector} sector exposed to {event_data['impact']}"
            penalty = 0.15  # Reduce BUY confidence by 15%

            if verbose:
                print(f"    Sector risk detected: {event_name} affects {sector} sector", file=sys.stderr)

            return warning, penalty

    return None, 0.0


def analyze_sector_performance(data: StockData, verbose: bool = False) -> SectorComparison | None:
    """Compare stock performance to its sector."""
    try:
        sector = data.info.get("sector")
        industry = data.info.get("industry")

        if not sector:
            return None

        sector_etf_ticker = get_sector_etf_ticker(sector)

        if not sector_etf_ticker:
            if verbose:
                print(f"No sector ETF mapping for {sector}", file=sys.stderr)
            return None

        if verbose:
            print(f"Comparing to sector ETF: {sector_etf_ticker}", file=sys.stderr)

        # Fetch sector ETF data
        sector_etf = yf.Ticker(sector_etf_ticker)
        sector_hist = sector_etf.history(period="3mo")

        if sector_hist.empty or data.price_history is None or data.price_history.empty:
            return None

        # Calculate 1-month returns
        stock_1m_ago = data.price_history["Close"].iloc[-min(22, len(data.price_history))]
        stock_current = data.price_history["Close"].iloc[-1]
        stock_return_1m = ((stock_current - stock_1m_ago) / stock_1m_ago) * 100

        sector_1m_ago = sector_hist["Close"].iloc[-min(22, len(sector_hist))]
        sector_current = sector_hist["Close"].iloc[-1]
        sector_return_1m = ((sector_current - sector_1m_ago) / sector_1m_ago) * 100

        # Calculate relative strength
        relative_strength = stock_return_1m / sector_return_1m if sector_return_1m != 0 else 1.0

        # Sector 10-day trend
        sector_10d_ago = sector_hist["Close"].iloc[-min(10, len(sector_hist))]
        sector_trend_10d = ((sector_current - sector_10d_ago) / sector_10d_ago) * 100

        if sector_trend_10d > 5:
            sector_trend = "strong uptrend"
        elif sector_trend_10d > 2:
            sector_trend = "uptrend"
        elif sector_trend_10d < -5:
            sector_trend = "downtrend"
        elif sector_trend_10d < -2:
            sector_trend = "weak"
        else:
            sector_trend = "neutral"

        # Calculate score
        score = 0.0

        # Relative performance score
        if relative_strength > 1.05:  # Outperforming by >5%
            score += 0.3
        elif relative_strength < 0.95:  # Underperforming by >5%
            score -= 0.3

        # Sector trend score
        if sector_trend_10d > 5:
            score += 0.2
        elif sector_trend_10d < -5:
            score -= 0.2

        explanation = f"{sector} sector {sector_trend} ({sector_return_1m:+.1f}% 1m), stock {stock_return_1m:+.1f}% vs sector"

        return SectorComparison(
            sector_name=sector,
            industry_name=industry or "Unknown",
            stock_return_1m=stock_return_1m,
            sector_return_1m=sector_return_1m,
            relative_strength=relative_strength,
            sector_trend=sector_trend,
            score=score,
            explanation=explanation,
        )

    except Exception as e:
        if verbose:
            print(f"Error analyzing sector performance: {e}", file=sys.stderr)
        return None


def analyze_earnings_timing(data: StockData) -> EarningsTiming | None:
    """Check earnings timing and flag pre/post-earnings periods."""
    try:
        from datetime import datetime, timedelta

        if data.earnings_history is None or data.earnings_history.empty:
            return None

        current_date = datetime.now()
        earnings_dates = data.earnings_history.sort_index(ascending=False)

        # Find next and last earnings dates
        next_earnings_date = None
        last_earnings_date = None

        for earnings_date in earnings_dates.index:
            earnings_dt = pd.Timestamp(earnings_date).to_pydatetime()

            if earnings_dt > current_date and next_earnings_date is None:
                next_earnings_date = earnings_dt
            elif earnings_dt <= current_date and last_earnings_date is None:
                last_earnings_date = earnings_dt
                break

        # Calculate days until/since earnings
        days_until_earnings = None
        days_since_earnings = None

        if next_earnings_date:
            days_until_earnings = (next_earnings_date - current_date).days

        if last_earnings_date:
            days_since_earnings = (current_date - last_earnings_date).days

        # Determine timing flag
        timing_flag = "safe"
        confidence_adjustment = 0.0
        caveats = []

        # Pre-earnings check (< 14 days)
        if days_until_earnings is not None and days_until_earnings <= 14:
            timing_flag = "pre_earnings"
            confidence_adjustment = -0.3
            caveats.append(f"Earnings in {days_until_earnings} days - high volatility expected")

        # Post-earnings check (< 5 days)
        price_change_5d = None
        if days_since_earnings is not None and days_since_earnings <= 5:
            # Calculate 5-day price change
            if data.price_history is not None and len(data.price_history) >= 5:
                price_5d_ago = data.price_history["Close"].iloc[-5]
                price_current = data.price_history["Close"].iloc[-1]
                price_change_5d = ((price_current - price_5d_ago) / price_5d_ago) * 100

                if price_change_5d > 15:
                    timing_flag = "post_earnings"
                    confidence_adjustment = -0.2
                    caveats.append(f"Up {price_change_5d:.1f}% in 5 days - gains may be priced in")

        return EarningsTiming(
            days_until_earnings=days_until_earnings,
            days_since_earnings=days_since_earnings,
            next_earnings_date=next_earnings_date.strftime("%Y-%m-%d") if next_earnings_date else None,
            last_earnings_date=last_earnings_date.strftime("%Y-%m-%d") if last_earnings_date else None,
            timing_flag=timing_flag,
            price_change_5d=price_change_5d,
            confidence_adjustment=confidence_adjustment,
            caveats=caveats,
        )

    except Exception:
        return None


def calculate_rsi(prices: pd.Series, period: int = 14) -> float | None:
    """Calculate RSI (Relative Strength Index)."""
    try:
        if len(prices) < period + 1:
            return None

        # Calculate price changes
        delta = prices.diff()

        # Separate gains and losses
        gains = delta.where(delta > 0, 0)
        losses = -delta.where(delta < 0, 0)

        # Calculate average gains and losses
        avg_gain = gains.rolling(window=period).mean()
        avg_loss = losses.rolling(window=period).mean()

        # Calculate RS
        rs = avg_gain / avg_loss

        # Calculate RSI
        rsi = 100 - (100 / (1 + rs))

        return float(rsi.iloc[-1])

    except Exception:
        return None


def analyze_momentum(data: StockData) -> MomentumAnalysis | None:
    """Analyze momentum indicators (RSI, 52w range, volume, relative strength)."""
    try:
        if data.price_history is None or data.price_history.empty:
            return None

        # Calculate RSI
        rsi_14d = calculate_rsi(data.price_history["Close"], period=14)

        if rsi_14d:
            if rsi_14d > 70:
                rsi_status = "overbought"
            elif rsi_14d < 30:
                rsi_status = "oversold"
            else:
                rsi_status = "neutral"
        else:
            rsi_status = "unknown"

        # Get 52-week high/low
        high_52w = data.info.get("fiftyTwoWeekHigh")
        low_52w = data.info.get("fiftyTwoWeekLow")
        current_price = data.info.get("regularMarketPrice") or data.info.get("currentPrice")

        price_vs_52w_low = None
        price_vs_52w_high = None
        near_52w_high = False
        near_52w_low = False

        if high_52w and low_52w and current_price:
            price_range = high_52w - low_52w
            if price_range > 0:
                price_vs_52w_low = ((current_price - low_52w) / price_range) * 100
                price_vs_52w_high = ((high_52w - current_price) / price_range) * 100

                near_52w_high = price_vs_52w_low > 90
                near_52w_low = price_vs_52w_low < 10

        # Volume analysis
        volume_ratio = None
        if "Volume" in data.price_history.columns and len(data.price_history) >= 60:
            recent_vol = data.price_history["Volume"].iloc[-5:].mean()
            avg_vol = data.price_history["Volume"].iloc[-60:].mean()
            volume_ratio = recent_vol / avg_vol if avg_vol > 0 else None

        # Calculate score
        score = 0.0
        explanations = []

        if rsi_14d:
            if rsi_14d > 70:
                score -= 0.5
                explanations.append(f"RSI {rsi_14d:.0f} (overbought)")
            elif rsi_14d < 30:
                score += 0.5
                explanations.append(f"RSI {rsi_14d:.0f} (oversold)")

        if near_52w_high:
            score -= 0.3
            explanations.append("Near 52w high")
        elif near_52w_low:
            score += 0.3
            explanations.append("Near 52w low")

        if volume_ratio and volume_ratio > 1.5:
            explanations.append(f"Volume {volume_ratio:.1f}x average")

        explanation = "; ".join(explanations) if explanations else "Momentum indicators neutral"

        return MomentumAnalysis(
            rsi_14d=rsi_14d,
            rsi_status=rsi_status,
            price_vs_52w_low=price_vs_52w_low,
            price_vs_52w_high=price_vs_52w_high,
            near_52w_high=near_52w_high,
            near_52w_low=near_52w_low,
            volume_ratio=volume_ratio,
            relative_strength_vs_sector=None,  # Could be enhanced with sector comparison
            score=score,
            explanation=explanation,
        )

    except Exception:
        return None


# ============================================================================
# Sentiment Analysis Helper Functions
# ============================================================================

# Simple cache for shared indicators (Fear & Greed, VIX)
# Format: {key: (value, timestamp)}
_SENTIMENT_CACHE = {}
_CACHE_TTL_SECONDS = 3600  # 1 hour


def _get_cached(key: str):
    """Get cached value if still valid (within TTL)."""
    if key in _SENTIMENT_CACHE:
        value, timestamp = _SENTIMENT_CACHE[key]
        if time.time() - timestamp < _CACHE_TTL_SECONDS:
            return value
    return None


def _set_cache(key: str, value):
    """Set cached value with current timestamp."""
    _SENTIMENT_CACHE[key] = (value, time.time())


async def get_fear_greed_index() -> tuple[float, int | None, str | None] | None:
    """
    Fetch CNN Fear & Greed Index (contrarian indicator) with 1h cache.
    Returns: (score, value, status) or None on failure.
    """
    # Check cache first
    cached = _get_cached("fear_greed")
    if cached is not None:
        return cached

    def _fetch():
        try:
            from fear_and_greed import get as get_fear_greed
            result = get_fear_greed()
            return result
        except Exception:
            return None

    try:
        result = await asyncio.to_thread(_fetch)
        if result is None:
            return None

        value = result.value  # 0-100
        status = result.description  # "Extreme Fear", "Fear", etc.

        # Contrarian scoring
        if value <= 25:
            score = 0.5  # Extreme fear = buy opportunity
        elif value <= 45:
            score = 0.2  # Fear = mild buy signal
        elif value <= 55:
            score = 0.0  # Neutral
        elif value <= 75:
            score = -0.2  # Greed = caution
        else:
            score = -0.5  # Extreme greed = warning

        result_tuple = (score, value, status)
        _set_cache("fear_greed", result_tuple)
        return result_tuple
    except Exception:
        return None


async def get_short_interest(data: StockData) -> tuple[float, float | None, float | None] | None:
    """
    Analyze short interest (from yfinance).
    Returns: (score, short_interest_pct, days_to_cover) or None.
    """
    # This is already synchronous data access (no API call), but make it async for consistency
    try:
        short_pct = data.info.get("shortPercentOfFloat")
        if short_pct is None:
            return None

        short_pct_float = float(short_pct) * 100  # Convert to percentage

        # Estimate days to cover (simplified - actual calculation needs volume data)
        short_ratio = data.info.get("shortRatio")  # Days to cover
        days_to_cover = float(short_ratio) if short_ratio else None

        # Scoring logic
        if short_pct_float > 20:
            if days_to_cover and days_to_cover > 10:
                score = 0.4  # High short interest + high days to cover = squeeze potential
            else:
                score = -0.3  # High short interest but justified
        elif short_pct_float < 5:
            score = 0.2  # Low short interest = bullish sentiment
        else:
            score = 0.0  # Normal range

        return (score, short_pct_float, days_to_cover)
    except Exception:
        return None


async def get_vix_term_structure() -> tuple[float, str | None, float | None] | None:
    """
    Analyze VIX futures term structure (contango vs backwardation) with 1h cache.
    Returns: (score, structure, slope) or None.
    """
    # Check cache first
    cached = _get_cached("vix_structure")
    if cached is not None:
        return cached

    def _fetch():
        try:
            import yfinance as yf
            vix = yf.Ticker("^VIX")
            vix_data = vix.history(period="5d")
            if vix_data.empty:
                return None
            return vix_data["Close"].iloc[-1]
        except Exception:
            return None

    try:
        vix_spot = await asyncio.to_thread(_fetch)
        if vix_spot is None:
            return None

        # Simplified: assume normal contango when VIX < 20, backwardation when VIX > 30
        if vix_spot < 15:
            structure = "contango"
            slope = 10.0  # Steep contango
            score = 0.3  # Complacency/bullish
        elif vix_spot < 20:
            structure = "contango"
            slope = 5.0
            score = 0.1
        elif vix_spot > 30:
            structure = "backwardation"
            slope = -5.0
            score = -0.3  # Stress/bearish
        else:
            structure = "flat"
            slope = 0.0
            score = 0.0

        result_tuple = (score, structure, slope)
        _set_cache("vix_structure", result_tuple)
        return result_tuple
    except Exception:
        return None


async def get_insider_activity(ticker: str, period_days: int = 90) -> tuple[float, int | None, float | None] | None:
    """
    Analyze insider trading from SEC Form 4 filings using edgartools.
    Returns: (score, net_shares, net_value_millions) or None.

    Scoring logic:
    - Strong buying (>100K shares or >$1M): +0.8
    - Moderate buying (>10K shares or >$0.1M): +0.4
    - Neutral: 0
    - Moderate selling: -0.4
    - Strong selling: -0.8

    Note: SEC EDGAR API requires User-Agent with email.
    """
    def _fetch():
        try:
            from edgar import Company, set_identity
            from datetime import datetime, timedelta

            # Set SEC-required identity
            set_identity("stock-analysis@clawd.bot")

            # Get company and Form 4 filings
            company = Company(ticker)
            filings = company.get_filings(form="4")

            if filings is None or len(filings) == 0:
                return None

            # Calculate cutoff date
            cutoff_date = datetime.now() - timedelta(days=period_days)

            # Aggregate transactions
            total_bought_shares = 0
            total_sold_shares = 0
            total_bought_value = 0.0
            total_sold_value = 0.0

            # Process recent filings (iterate, don't slice due to pyarrow compatibility)
            count = 0
            for filing in filings:
                if count >= 50:
                    break
                count += 1

                try:
                    # Check filing date
                    filing_date = filing.filing_date
                    if hasattr(filing_date, 'to_pydatetime'):
                        filing_date = filing_date.to_pydatetime()
                    elif isinstance(filing_date, str):
                        filing_date = datetime.strptime(filing_date, "%Y-%m-%d")

                    # Convert date object to datetime for comparison
                    if hasattr(filing_date, 'year') and not hasattr(filing_date, 'hour'):
                        filing_date = datetime.combine(filing_date, datetime.min.time())

                    if filing_date < cutoff_date:
                        continue

                    # Get Form 4 object
                    form4 = filing.obj()
                    if form4 is None:
                        continue

                    # Process purchases (edgartools returns DataFrames)
                    if hasattr(form4, 'common_stock_purchases'):
                        purchases = form4.common_stock_purchases
                        if isinstance(purchases, pd.DataFrame) and not purchases.empty:
                            if 'Shares' in purchases.columns:
                                total_bought_shares += int(purchases['Shares'].sum())
                            if 'Price' in purchases.columns and 'Shares' in purchases.columns:
                                total_bought_value += float((purchases['Shares'] * purchases['Price']).sum())

                    # Process sales
                    if hasattr(form4, 'common_stock_sales'):
                        sales = form4.common_stock_sales
                        if isinstance(sales, pd.DataFrame) and not sales.empty:
                            if 'Shares' in sales.columns:
                                total_sold_shares += int(sales['Shares'].sum())
                            if 'Price' in sales.columns and 'Shares' in sales.columns:
                                total_sold_value += float((sales['Shares'] * sales['Price']).sum())

                except Exception:
                    continue

            # Calculate net values
            net_shares = total_bought_shares - total_sold_shares
            net_value = (total_bought_value - total_sold_value) / 1_000_000  # Millions

            # Apply scoring logic
            if net_shares > 100_000 or net_value > 1.0:
                score = 0.8  # Strong buying
            elif net_shares > 10_000 or net_value > 0.1:
                score = 0.4  # Moderate buying
            elif net_shares < -100_000 or net_value < -1.0:
                score = -0.8  # Strong selling
            elif net_shares < -10_000 or net_value < -0.1:
                score = -0.4  # Moderate selling
            else:
                score = 0.0  # Neutral

            return (score, net_shares, net_value)

        except ImportError:
            # edgartools not installed
            return None
        except Exception:
            return None

    try:
        result = await asyncio.to_thread(_fetch)
        return result
    except Exception:
        return None


async def get_put_call_ratio(data: StockData) -> tuple[float, float | None, int | None, int | None] | None:
    """
    Calculate put/call ratio from options chain (contrarian indicator).
    Returns: (score, ratio, put_volume, call_volume) or None.
    """
    def _fetch():
        try:
            if data.ticker_obj is None:
                return None

            # Get options chain for nearest expiration
            expirations = data.ticker_obj.options
            if not expirations or len(expirations) == 0:
                return None

            nearest_exp = expirations[0]
            opt_chain = data.ticker_obj.option_chain(nearest_exp)

            # Calculate total put and call volume
            put_volume = opt_chain.puts["volume"].sum() if "volume" in opt_chain.puts.columns else 0
            call_volume = opt_chain.calls["volume"].sum() if "volume" in opt_chain.calls.columns else 0

            if call_volume == 0 or put_volume == 0:
                return None

            ratio = put_volume / call_volume
            return (ratio, int(put_volume), int(call_volume))
        except Exception:
            return None

    try:
        result = await asyncio.to_thread(_fetch)
        if result is None:
            return None

        ratio, put_volume, call_volume = result

        # Contrarian scoring
        if ratio > 1.5:
            score = 0.3  # Excessive fear = bullish
        elif ratio > 1.0:
            score = 0.1  # Mild fear
        elif ratio > 0.7:
            score = -0.1  # Normal
        else:
            score = -0.3  # Complacency = bearish

        return (score, ratio, put_volume, call_volume)
    except Exception:
        return None


async def analyze_sentiment(data: StockData, verbose: bool = False, skip_insider: bool = False) -> SentimentAnalysis | None:
    """
    Analyze market sentiment using 5 sub-indicators in parallel.
    Requires at least 2 of 5 indicators for valid sentiment.
    Returns overall sentiment score (-1.0 to +1.0) with sub-metrics.
    """
    scores = []
    explanations = []
    warnings = []

    # Initialize all raw data fields
    fear_greed_score = None
    fear_greed_value = None
    fear_greed_status = None

    short_interest_score = None
    short_interest_pct = None
    days_to_cover = None

    vix_structure_score = None
    vix_structure = None
    vix_slope = None

    insider_activity_score = None
    insider_net_shares = None
    insider_net_value = None

    put_call_score = None
    put_call_ratio = None
    put_volume = None
    call_volume = None

    # Fetch all 5 indicators in parallel with 10s timeout per indicator
    # (or 4 if skip_insider=True for faster analysis)
    try:
        tasks = [
            asyncio.wait_for(get_fear_greed_index(), timeout=10),
            asyncio.wait_for(get_short_interest(data), timeout=10),
            asyncio.wait_for(get_vix_term_structure(), timeout=10),
        ]
        
        if skip_insider:
            tasks.append(asyncio.sleep(0))  # Placeholder - returns None
            if verbose:
                print("    Skipping insider trading analysis (--no-insider)", file=sys.stderr)
        else:
            tasks.append(asyncio.wait_for(get_insider_activity(data.ticker, period_days=90), timeout=10))
        
        tasks.append(asyncio.wait_for(get_put_call_ratio(data), timeout=10))
        
        results = await asyncio.gather(*tasks, return_exceptions=True)

        # Process Fear & Greed Index
        fear_greed_result = results[0]
        if isinstance(fear_greed_result, tuple) and fear_greed_result is not None:
            fear_greed_score, fear_greed_value, fear_greed_status = fear_greed_result
            scores.append(fear_greed_score)
            explanations.append(f"{fear_greed_status} ({fear_greed_value})")
            if verbose:
                print(f"    Fear & Greed: {fear_greed_status} ({fear_greed_value}) → score {fear_greed_score:+.2f}", file=sys.stderr)
        elif verbose and isinstance(fear_greed_result, Exception):
            print(f"    Fear & Greed: Failed ({fear_greed_result})", file=sys.stderr)

        # Process Short Interest
        short_interest_result = results[1]
        if isinstance(short_interest_result, tuple) and short_interest_result is not None:
            short_interest_score, short_interest_pct, days_to_cover = short_interest_result
            scores.append(short_interest_score)
            if days_to_cover:
                explanations.append(f"Short interest {short_interest_pct:.1f}% (days to cover: {days_to_cover:.1f})")
            else:
                explanations.append(f"Short interest {short_interest_pct:.1f}%")
            warnings.append("Short interest data typically ~2 weeks old (FINRA lag)")
            if verbose:
                print(f"    Short Interest: {short_interest_pct:.1f}% → score {short_interest_score:+.2f}", file=sys.stderr)
        elif verbose and isinstance(short_interest_result, Exception):
            print(f"    Short Interest: Failed ({short_interest_result})", file=sys.stderr)

        # Process VIX Term Structure
        vix_result = results[2]
        if isinstance(vix_result, tuple) and vix_result is not None:
            vix_structure_score, vix_structure, vix_slope = vix_result
            scores.append(vix_structure_score)
            explanations.append(f"VIX {vix_structure}")
            if verbose:
                print(f"    VIX Structure: {vix_structure} (slope {vix_slope:.1f}%) → score {vix_structure_score:+.2f}", file=sys.stderr)
        elif verbose and isinstance(vix_result, Exception):
            print(f"    VIX Structure: Failed ({vix_result})", file=sys.stderr)

        # Process Insider Activity
        insider_result = results[3]
        if isinstance(insider_result, tuple) and insider_result is not None:
            insider_activity_score, insider_net_shares, insider_net_value = insider_result
            scores.append(insider_activity_score)
            if insider_net_value:
                explanations.append(f"Insider net: ${insider_net_value:.1f}M")
            warnings.append("Insider trades may lag filing by 2-3 days")
            if verbose:
                print(f"    Insider Activity: Net ${insider_net_value:.1f}M → score {insider_activity_score:+.2f}", file=sys.stderr)
        elif verbose and isinstance(insider_result, Exception):
            print(f"    Insider Activity: Failed ({insider_result})", file=sys.stderr)

        # Process Put/Call Ratio
        put_call_result = results[4]
        if isinstance(put_call_result, tuple) and put_call_result is not None:
            put_call_score, put_call_ratio, put_volume, call_volume = put_call_result
            scores.append(put_call_score)
            explanations.append(f"Put/call ratio {put_call_ratio:.2f}")
            if verbose:
                print(f"    Put/Call Ratio: {put_call_ratio:.2f} → score {put_call_score:+.2f}", file=sys.stderr)
        elif verbose and isinstance(put_call_result, Exception):
            print(f"    Put/Call Ratio: Failed ({put_call_result})", file=sys.stderr)

    except Exception as e:
        if verbose:
            print(f"    Sentiment analysis error: {e}", file=sys.stderr)
        return None

    # Require at least 2 of 5 indicators for valid sentiment
    indicators_available = len(scores)
    if indicators_available < 2:
        if verbose:
            print(f"    Sentiment: Insufficient data ({indicators_available}/5 indicators)", file=sys.stderr)
        return None

    # Calculate overall score as simple average
    overall_score = sum(scores) / len(scores)
    explanation = "; ".join(explanations)

    return SentimentAnalysis(
        score=overall_score,
        explanation=explanation,
        fear_greed_score=fear_greed_score,
        short_interest_score=short_interest_score,
        vix_structure_score=vix_structure_score,
        insider_activity_score=insider_activity_score,
        put_call_score=put_call_score,
        fear_greed_value=fear_greed_value,
        fear_greed_status=fear_greed_status,
        short_interest_pct=short_interest_pct,
        days_to_cover=days_to_cover,
        vix_structure=vix_structure,
        vix_slope=vix_slope,
        insider_net_shares=insider_net_shares,
        insider_net_value=insider_net_value,
        put_call_ratio=put_call_ratio,
        put_volume=put_volume,
        call_volume=call_volume,
        indicators_available=indicators_available,
        data_freshness_warnings=warnings if warnings else None,
    )


def synthesize_signal(
    ticker: str,
    company_name: str,
    earnings: EarningsSurprise | None,
    fundamentals: Fundamentals | None,
    analysts: AnalystSentiment | None,
    historical: HistoricalPatterns | None,
    market_context: MarketContext | None,
    sector: SectorComparison | None,
    earnings_timing: EarningsTiming | None,
    momentum: MomentumAnalysis | None,
    sentiment: SentimentAnalysis | None,
    breaking_news: list[str] | None = None,  # NEW v4.0.0
    geopolitical_risk_warning: str | None = None,  # NEW v4.0.0
    geopolitical_risk_penalty: float = 0.0,  # NEW v4.0.0
) -> Signal:
    """Synthesize all components into a final signal."""

    # Collect available components with weights
    components = []
    weights = []

    if earnings:
        components.append(("earnings", earnings.score))
        weights.append(0.30)  # reduced from 0.35

    if fundamentals:
        components.append(("fundamentals", fundamentals.score))
        weights.append(0.20)  # reduced from 0.25

    if analysts and analysts.score is not None:
        components.append(("analysts", analysts.score))
        weights.append(0.20)  # reduced from 0.25

    if historical:
        components.append(("historical", historical.score))
        weights.append(0.10)  # reduced from 0.15

    # NEW COMPONENTS
    if market_context:
        components.append(("market", market_context.score))
        weights.append(0.10)

    if sector:
        components.append(("sector", sector.score))
        weights.append(0.15)

    if momentum:
        components.append(("momentum", momentum.score))
        weights.append(0.15)

    if sentiment:
        components.append(("sentiment", sentiment.score))
        weights.append(0.10)

    # Require at least 2 components
    if len(components) < 2:
        return Signal(
            ticker=ticker,
            company_name=company_name,
            recommendation="HOLD",
            confidence=0.0,
            final_score=0.0,
            supporting_points=["Insufficient data for analysis"],
            caveats=["Limited data available"],
            timestamp=datetime.now().isoformat(),
            components={},
        )

    # Normalize weights
    total_weight = sum(weights)
    normalized_weights = [w / total_weight for w in weights]

    # Calculate weighted score
    final_score = sum(score * weight for (_, score), weight in zip(components, normalized_weights))

    # Determine recommendation
    if final_score > 0.33:
        recommendation = "BUY"
    elif final_score < -0.33:
        recommendation = "SELL"
    else:
        recommendation = "HOLD"

    confidence = abs(final_score)

    # Apply earnings timing adjustments and overrides
    if earnings_timing:
        confidence *= (1.0 + earnings_timing.confidence_adjustment)

        # Override recommendation if needed
        if earnings_timing.timing_flag == "pre_earnings":
            if recommendation == "BUY":
                recommendation = "HOLD"

        elif earnings_timing.timing_flag == "post_earnings":
            if earnings_timing.price_change_5d and earnings_timing.price_change_5d > 15:
                if recommendation == "BUY":
                    recommendation = "HOLD"

    # Check overbought + near 52w high
    if momentum and momentum.rsi_14d and momentum.rsi_14d > 70 and momentum.near_52w_high:
        if recommendation == "BUY":
            recommendation = "HOLD"
            confidence *= 0.7

    # NEW v4.0.0: Risk-off confidence penalty
    if market_context and market_context.risk_off_detected:
        if recommendation == "BUY":
            confidence *= 0.7  # Reduce BUY confidence by 30%

    # NEW v4.0.0: Geopolitical sector risk penalty
    if geopolitical_risk_penalty > 0:
        if recommendation == "BUY":
            confidence *= (1.0 - geopolitical_risk_penalty)  # Apply penalty

    # Generate supporting points
    supporting_points = []

    if earnings and earnings.actual_eps is not None:
        supporting_points.append(
            f"{earnings.explanation} - EPS ${earnings.actual_eps:.2f} vs ${earnings.expected_eps:.2f} expected"
        )

    if fundamentals and fundamentals.explanation:
        supporting_points.append(fundamentals.explanation)

    if analysts and analysts.summary:
        supporting_points.append(f"Analyst consensus: {analysts.summary}")

    if historical and historical.pattern_desc:
        supporting_points.append(f"Historical pattern: {historical.pattern_desc}")

    if market_context and market_context.explanation:
        supporting_points.append(f"Market: {market_context.explanation}")

    if sector and sector.explanation:
        supporting_points.append(f"Sector: {sector.explanation}")

    if momentum and momentum.explanation:
        supporting_points.append(f"Momentum: {momentum.explanation}")

    if sentiment and sentiment.explanation:
        supporting_points.append(f"Sentiment: {sentiment.explanation}")

    # Generate caveats
    caveats = []

    # Add earnings timing caveats first (most important)
    if earnings_timing and earnings_timing.caveats:
        caveats.extend(earnings_timing.caveats)

    # Add sentiment warnings
    if sentiment and sentiment.data_freshness_warnings:
        caveats.extend(sentiment.data_freshness_warnings)

    # Add momentum warnings
    if momentum and momentum.rsi_14d:
        if momentum.rsi_14d > 70 and momentum.near_52w_high:
            caveats.append("Overbought conditions - high risk entry")

    # Add sector warnings
    if sector and sector.score < -0.2:
        caveats.append(f"Sector {sector.sector_name} is weak despite stock fundamentals")

    # Add market warnings
    if market_context and market_context.vix_status == "fear":
        caveats.append(f"High market volatility (VIX {market_context.vix_level:.0f})")

    # NEW v4.0.0: Risk-off warnings
    if market_context and market_context.risk_off_detected:
        caveats.append(f"🛡️ RISK-OFF MODE: Flight to safety detected (GLD {market_context.gld_change_5d:+.1f}%, TLT {market_context.tlt_change_5d:+.1f}%, UUP {market_context.uup_change_5d:+.1f}%)")

    # NEW v4.0.0: Breaking news alerts
    if breaking_news:
        for alert in breaking_news[:2]:  # Limit to 2 alerts to avoid overwhelming
            caveats.append(f"⚠️ BREAKING NEWS: {alert}")

    # NEW v4.0.0: Geopolitical sector risk warnings
    if geopolitical_risk_warning:
        caveats.append(geopolitical_risk_warning)

    # Original caveats
    if not analysts or analysts.score is None:
        caveats.append("Limited or no analyst coverage")

    if not earnings:
        caveats.append("No recent earnings data available")

    if len(components) < 4:
        caveats.append("Analysis based on limited data components")

    if not caveats:
        caveats.append("Market conditions can change rapidly")

    # Limit to 5 caveats
    caveats = caveats[:5]

    # Build components dict for output
    components_dict = {}
    if earnings:
        components_dict["earnings_surprise"] = {
            "score": earnings.score,
            "actual_eps": earnings.actual_eps,
            "expected_eps": earnings.expected_eps,
            "surprise_pct": earnings.surprise_pct,
            "explanation": earnings.explanation,
        }

    if fundamentals:
        components_dict["fundamentals"] = {
            "score": fundamentals.score,
            **fundamentals.key_metrics,
        }

    if analysts:
        components_dict["analyst_sentiment"] = {
            "score": analysts.score,
            "consensus_rating": analysts.consensus_rating,
            "price_target": analysts.price_target,
            "current_price": analysts.current_price,
            "upside_pct": analysts.upside_pct,
            "num_analysts": analysts.num_analysts,
        }

    if historical:
        components_dict["historical_patterns"] = {
            "score": historical.score,
            "beats_last_4q": historical.beats_last_4q,
            "avg_reaction_pct": historical.avg_reaction_pct,
        }

    if market_context:
        components_dict["market_context"] = {
            "score": market_context.score,
            "vix_level": market_context.vix_level,
            "vix_status": market_context.vix_status,
            "spy_trend_10d": market_context.spy_trend_10d,
            "qqq_trend_10d": market_context.qqq_trend_10d,
            "market_regime": market_context.market_regime,
            "gld_change_5d": market_context.gld_change_5d,
            "tlt_change_5d": market_context.tlt_change_5d,
            "uup_change_5d": market_context.uup_change_5d,
            "risk_off_detected": market_context.risk_off_detected,
        }

    if sector:
        components_dict["sector_performance"] = {
            "score": sector.score,
            "sector_name": sector.sector_name,
            "stock_return_1m": sector.stock_return_1m,
            "sector_return_1m": sector.sector_return_1m,
            "relative_strength": sector.relative_strength,
            "sector_trend": sector.sector_trend,
        }

    if earnings_timing:
        components_dict["earnings_timing"] = {
            "days_until_earnings": earnings_timing.days_until_earnings,
            "days_since_earnings": earnings_timing.days_since_earnings,
            "timing_flag": earnings_timing.timing_flag,
            "price_change_5d": earnings_timing.price_change_5d,
            "confidence_adjustment": earnings_timing.confidence_adjustment,
        }

    if momentum:
        components_dict["momentum"] = {
            "score": momentum.score,
            "rsi_14d": momentum.rsi_14d,
            "rsi_status": momentum.rsi_status,
            "near_52w_high": momentum.near_52w_high,
            "near_52w_low": momentum.near_52w_low,
            "volume_ratio": momentum.volume_ratio,
        }

    if sentiment:
        components_dict["sentiment_analysis"] = {
            "score": sentiment.score,
            "indicators_available": sentiment.indicators_available,
            "fear_greed_value": sentiment.fear_greed_value,
            "fear_greed_status": sentiment.fear_greed_status,
            "short_interest_pct": sentiment.short_interest_pct,
            "days_to_cover": sentiment.days_to_cover,
            "vix_structure": sentiment.vix_structure,
            "vix_slope": sentiment.vix_slope,
            "insider_net_value": sentiment.insider_net_value,
            "put_call_ratio": sentiment.put_call_ratio,
            "data_freshness_warnings": sentiment.data_freshness_warnings,
        }

    return Signal(
        ticker=ticker,
        company_name=company_name,
        recommendation=recommendation,
        confidence=confidence,
        final_score=final_score,
        supporting_points=supporting_points[:5],  # Limit to 5
        caveats=caveats,  # Already limited to 5 earlier
        timestamp=datetime.now().isoformat(),
        components=components_dict,
    )


def format_output_text(signal: Signal) -> str:
    """Format signal as text output."""
    lines = [
        "=" * 77,
        f"STOCK ANALYSIS: {signal.ticker} ({signal.company_name})",
        f"Generated: {signal.timestamp}",
        "=" * 77,
        "",
        f"RECOMMENDATION: {signal.recommendation} (Confidence: {signal.confidence*100:.0f}%)",
        "",
        "SUPPORTING POINTS:",
    ]

    for point in signal.supporting_points:
        lines.append(f"• {point}")

    lines.extend([
        "",
        "CAVEATS:",
    ])

    for caveat in signal.caveats:
        lines.append(f"• {caveat}")

    lines.extend([
        "",
        "=" * 77,
        "DISCLAIMER: This analysis is for informational purposes only and does NOT",
        "constitute financial advice. Consult a licensed financial advisor before",
        "making investment decisions. Data provided by Yahoo Finance.",
        "=" * 77,
    ])

    return "\n".join(lines)


def format_output_json(signal: Signal) -> str:
    """Format signal as JSON output."""
    output = {
        **asdict(signal),
        "disclaimer": "NOT FINANCIAL ADVICE. For informational purposes only.",
    }
    return json.dumps(output, indent=2)


def main():
    parser = argparse.ArgumentParser(
        description="Analyze stocks using Yahoo Finance data"
    )
    parser.add_argument(
        "tickers",
        nargs="*",
        help="Stock/crypto ticker(s) to analyze"
    )
    parser.add_argument(
        "--output",
        choices=["text", "json"],
        default="text",
        help="Output format (default: text)"
    )
    parser.add_argument(
        "--verbose",
        action="store_true",
        help="Verbose output to stderr"
    )
    parser.add_argument(
        "--portfolio", "-p",
        type=str,
        help="Analyze all assets in a portfolio"
    )
    parser.add_argument(
        "--period",
        choices=["daily", "weekly", "monthly", "quarterly", "yearly"],
        help="Period for portfolio performance analysis"
    )
    parser.add_argument(
        "--no-insider",
        action="store_true",
        help="Skip insider trading analysis (faster, SEC EDGAR is slow)"
    )
    parser.add_argument(
        "--fast",
        action="store_true",
        help="Fast mode: skip slow analyses (insider, breaking news)"
    )

    args = parser.parse_args()
    
    # Fast mode shortcuts
    if args.fast:
        args.no_insider = True

    # Handle portfolio mode
    portfolio_assets = []
    portfolio_name = None
    if args.portfolio:
        try:
            from portfolio import PortfolioStore
            store = PortfolioStore()
            portfolio = store.get_portfolio(args.portfolio)
            if not portfolio:
                # Try to find default portfolio if name not found
                default_name = store.get_default_portfolio_name()
                if default_name and args.portfolio.lower() == "default":
                    portfolio = store.get_portfolio(default_name)
                    portfolio_name = default_name
                else:
                    print(f"Error: Portfolio '{args.portfolio}' not found", file=sys.stderr)
                    sys.exit(1)
            else:
                portfolio_name = portfolio.name

            if not portfolio.assets:
                print(f"Portfolio '{portfolio_name}' has no assets", file=sys.stderr)
                sys.exit(1)

            portfolio_assets = [(a.ticker, a.quantity, a.cost_basis, a.type) for a in portfolio.assets]
            args.tickers = [a.ticker for a in portfolio.assets]

            if args.verbose:
                print(f"Analyzing portfolio: {portfolio_name} ({len(portfolio_assets)} assets)", file=sys.stderr)

        except ImportError:
            print("Error: portfolio.py not found", file=sys.stderr)
            sys.exit(1)
        except Exception as e:
            print(f"Error loading portfolio: {e}", file=sys.stderr)
            sys.exit(1)

    if not args.tickers:
        parser.print_help()
        sys.exit(1)

    # NEW v4.0.0: Check for breaking news (market-wide, check once before analyzing tickers)
    # Check breaking news (skip in fast mode)
    breaking_news = None
    if not args.fast:
        if args.verbose:
            print(f"Checking breaking news (last 24h)...", file=sys.stderr)
        breaking_news = check_breaking_news(verbose=args.verbose)
    elif args.verbose:
        print(f"Skipping breaking news check (--fast mode)", file=sys.stderr)
    if breaking_news and args.verbose:
        print(f"  Found {len(breaking_news)} breaking news alert(s)\n", file=sys.stderr)

    results = []

    for ticker in args.tickers:
        ticker = ticker.upper()

        if args.verbose:
            print(f"\n=== Analyzing {ticker} ===\n", file=sys.stderr)

        # Fetch data
        data = fetch_stock_data(ticker, verbose=args.verbose)

        if data is None:
            print(f"Error: Invalid ticker '{ticker}' or data unavailable", file=sys.stderr)
            sys.exit(2)

        # Get company name
        company_name = data.info.get("longName") or data.info.get("shortName") or ticker

        # Detect asset type (crypto vs stock)
        is_crypto = data.asset_type == "crypto"

        if args.verbose and is_crypto:
            print(f"  Asset type: CRYPTO (using crypto-specific analysis)", file=sys.stderr)

        # Analyze components (different for crypto vs stock)
        if is_crypto:
            # Crypto: Skip stock-specific analyses
            earnings = None
            fundamentals = None
            analysts = None
            historical = None
            earnings_timing = None
            sector = None

            # Crypto fundamentals (market cap, category, BTC correlation)
            if args.verbose:
                print(f"Analyzing crypto fundamentals...", file=sys.stderr)
            crypto_fundamentals = analyze_crypto_fundamentals(data, verbose=args.verbose)

            # Convert crypto fundamentals to regular Fundamentals for synthesize_signal
            if crypto_fundamentals:
                fundamentals = Fundamentals(
                    score=crypto_fundamentals.score,
                    key_metrics={
                        "market_cap": crypto_fundamentals.market_cap,
                        "market_cap_rank": crypto_fundamentals.market_cap_rank,
                        "category": crypto_fundamentals.category,
                        "btc_correlation": crypto_fundamentals.btc_correlation,
                    },
                    explanation=crypto_fundamentals.explanation,
                )
        else:
            # Stock: Full analysis
            earnings = analyze_earnings_surprise(data)
            fundamentals = analyze_fundamentals(data)
            analysts = analyze_analyst_sentiment(data)
            historical = analyze_historical_patterns(data)

            # Analyze earnings timing (stocks only)
            if args.verbose:
                print(f"Checking earnings timing...", file=sys.stderr)
            earnings_timing = analyze_earnings_timing(data)

            # Analyze sector performance (stocks only)
            if args.verbose:
                print(f"Analyzing sector performance...", file=sys.stderr)
            sector = analyze_sector_performance(data, verbose=args.verbose)

        # Market context (both crypto and stock)
        if args.verbose:
            print(f"Analyzing market context...", file=sys.stderr)
        market_context = analyze_market_context(verbose=args.verbose)

        # Momentum (both crypto and stock)
        if args.verbose:
            print(f"Analyzing momentum...", file=sys.stderr)
        momentum = analyze_momentum(data)

        # Sentiment (stocks get full sentiment, crypto gets limited)
        if args.verbose:
            print(f"Analyzing market sentiment...", file=sys.stderr)
        if is_crypto:
            # Skip insider trading and put/call for crypto
            sentiment = None
        else:
            sentiment = asyncio.run(analyze_sentiment(data, verbose=args.verbose, skip_insider=args.no_insider))

        # Geopolitical risks (stocks only)
        if is_crypto:
            geopolitical_risk_warning = None
            geopolitical_risk_penalty = 0.0
        else:
            sector_name = data.info.get("sector")
            geopolitical_risk_warning, geopolitical_risk_penalty = check_sector_geopolitical_risk(
                ticker=ticker,
                sector=sector_name,
                breaking_news=breaking_news,
                verbose=args.verbose
            )

        if args.verbose:
            print(f"Components analyzed:", file=sys.stderr)
            if is_crypto:
                print(f"  Crypto Fundamentals: {'✓' if fundamentals else '✗'}", file=sys.stderr)
                print(f"  Market Context: {'✓' if market_context else '✗'}", file=sys.stderr)
                print(f"  Momentum: {'✓' if momentum else '✗'}", file=sys.stderr)
                print(f"  (Earnings, Sector, Sentiment: N/A for crypto)\n", file=sys.stderr)
            else:
                print(f"  Earnings: {'✓' if earnings else '✗'}", file=sys.stderr)
                print(f"  Fundamentals: {'✓' if fundamentals else '✗'}", file=sys.stderr)
                print(f"  Analysts: {'✓' if analysts and analysts.score else '✗'}", file=sys.stderr)
                print(f"  Historical: {'✓' if historical else '✗'}", file=sys.stderr)
                print(f"  Market Context: {'✓' if market_context else '✗'}", file=sys.stderr)
                print(f"  Sector: {'✓' if sector else '✗'}", file=sys.stderr)
                print(f"  Earnings Timing: {'✓' if earnings_timing else '✗'}", file=sys.stderr)
                print(f"  Momentum: {'✓' if momentum else '✗'}", file=sys.stderr)
                print(f"  Sentiment: {'✓' if sentiment else '✗'}\n", file=sys.stderr)

        # Synthesize signal
        signal = synthesize_signal(
            ticker=ticker,
            company_name=company_name,
            earnings=earnings,
            fundamentals=fundamentals,
            analysts=analysts,
            historical=historical,
            market_context=market_context,  # NEW
            sector=sector,  # NEW
            earnings_timing=earnings_timing,  # NEW
            momentum=momentum,  # NEW
            sentiment=sentiment,  # NEW
            breaking_news=breaking_news,  # NEW v4.0.0
            geopolitical_risk_warning=geopolitical_risk_warning,  # NEW v4.0.0
            geopolitical_risk_penalty=geopolitical_risk_penalty,  # NEW v4.0.0
        )

        results.append(signal)

    # Output results
    if args.output == "json":
        if len(results) == 1:
            print(format_output_json(results[0]))
        else:
            output_data = [asdict(r) for r in results]
            # Add portfolio summary if in portfolio mode
            if portfolio_assets:
                portfolio_summary = generate_portfolio_summary(
                    results, portfolio_assets, portfolio_name, args.period
                )
                output_data = {
                    "portfolio": portfolio_name,
                    "assets": output_data,
                    "summary": portfolio_summary,
                }
            print(json.dumps(output_data, indent=2))
    else:
        for i, signal in enumerate(results):
            if i > 0:
                print("\n")
            print(format_output_text(signal))

        # Print portfolio summary if in portfolio mode
        if portfolio_assets:
            print_portfolio_summary(results, portfolio_assets, portfolio_name, args.period)


def generate_portfolio_summary(
    results: list,
    portfolio_assets: list[tuple[str, float, float, str]],
    portfolio_name: str,
    period: str | None = None,
) -> dict:
    """Generate portfolio summary data."""
    # Map results by ticker
    result_map = {r.ticker: r for r in results}

    # Calculate portfolio metrics
    total_cost = 0.0
    total_value = 0.0
    asset_values = []

    for ticker, quantity, cost_basis, asset_type in portfolio_assets:
        cost_total = quantity * cost_basis
        total_cost += cost_total

        # Get current price from yfinance
        try:
            stock = yf.Ticker(ticker)
            current_price = stock.info.get("regularMarketPrice", 0) or 0
            current_value = quantity * current_price
            total_value += current_value
            asset_values.append((ticker, current_value, cost_total, asset_type))
        except Exception:
            asset_values.append((ticker, 0, cost_total, asset_type))

    # Calculate period returns if requested
    period_return = None
    if period and total_value > 0:
        period_days = {
            "daily": 1,
            "weekly": 7,
            "monthly": 30,
            "quarterly": 90,
            "yearly": 365,
        }.get(period, 30)

        period_return = calculate_portfolio_period_return(portfolio_assets, period_days)

    # Concentration analysis
    concentrations = []
    if total_value > 0:
        for ticker, value, _, asset_type in asset_values:
            if value > 0:
                pct = value / total_value * 100
                if pct > 30:
                    concentrations.append(f"{ticker}: {pct:.1f}%")

    # Build summary
    total_pnl = total_value - total_cost
    total_pnl_pct = (total_pnl / total_cost * 100) if total_cost > 0 else 0

    summary = {
        "portfolio_name": portfolio_name,
        "total_cost": total_cost,
        "total_value": total_value,
        "total_pnl": total_pnl,
        "total_pnl_pct": total_pnl_pct,
        "asset_count": len(portfolio_assets),
        "concentration_warnings": concentrations if concentrations else None,
    }

    if period_return is not None:
        summary["period"] = period
        summary["period_return_pct"] = period_return

    return summary


def calculate_portfolio_period_return(
    portfolio_assets: list[tuple[str, float, float, str]],
    period_days: int,
) -> float | None:
    """Calculate portfolio return over a period using historical prices."""
    try:
        total_start_value = 0.0
        total_current_value = 0.0

        for ticker, quantity, _, _ in portfolio_assets:
            stock = yf.Ticker(ticker)
            hist = stock.history(period=f"{period_days + 5}d")

            if hist.empty or len(hist) < 2:
                continue

            # Get price at period start and now
            current_price = hist["Close"].iloc[-1]
            start_price = hist["Close"].iloc[0]

            total_current_value += quantity * current_price
            total_start_value += quantity * start_price

        if total_start_value > 0:
            return (total_current_value - total_start_value) / total_start_value * 100

    except Exception:
        pass

    return None


def print_portfolio_summary(
    results: list,
    portfolio_assets: list[tuple[str, float, float, str]],
    portfolio_name: str,
    period: str | None = None,
) -> None:
    """Print portfolio summary in text format."""
    summary = generate_portfolio_summary(results, portfolio_assets, portfolio_name, period)

    print("\n" + "=" * 77)
    print(f"PORTFOLIO SUMMARY: {portfolio_name}")
    print("=" * 77)

    # Value overview
    total_cost = summary["total_cost"]
    total_value = summary["total_value"]
    total_pnl = summary["total_pnl"]
    total_pnl_pct = summary["total_pnl_pct"]

    print(f"\nTotal Cost:    ${total_cost:,.2f}")
    print(f"Current Value: ${total_value:,.2f}")
    pnl_sign = "+" if total_pnl >= 0 else ""
    print(f"Total P&L:     {pnl_sign}${total_pnl:,.2f} ({pnl_sign}{total_pnl_pct:.1f}%)")

    # Period return
    if "period_return_pct" in summary:
        period_return = summary["period_return_pct"]
        period_sign = "+" if period_return >= 0 else ""
        print(f"{summary['period'].capitalize()} Return: {period_sign}{period_return:.1f}%")

    # Concentration warnings
    if summary.get("concentration_warnings"):
        print("\n⚠️ CONCENTRATION WARNINGS:")
        for warning in summary["concentration_warnings"]:
            print(f"   • {warning} (>30% of portfolio)")

    # Recommendation summary
    recommendations = {"BUY": 0, "HOLD": 0, "SELL": 0}
    for r in results:
        recommendations[r.recommendation] = recommendations.get(r.recommendation, 0) + 1

    print(f"\nRECOMMENDATIONS: {recommendations['BUY']} BUY | {recommendations['HOLD']} HOLD | {recommendations['SELL']} SELL")
    print("=" * 77)


if __name__ == "__main__":
    main()