1#!/usr/bin/env python3
2# /// script
3# requires-python = ">=3.10"
4# dependencies = [
5#     "yfinance>=0.2.40",
6#     "pandas>=2.0.0",
7#     "fear-and-greed>=0.4",
8#     "edgartools>=2.0.0",
9#     "feedparser>=6.0.0",
10# ]
11# ///
12"""
13Stock analysis using Yahoo Finance data.
14 
15Usage:
16    uv run analyze_stock.py TICKER [TICKER2 ...] [--output text|json] [--verbose]
17"""
18 
19import argparse
20import asyncio
21import json
22import sys
23import time
24from dataclasses import dataclass, asdict
25from datetime import datetime
26from typing import Literal
27 
28import pandas as pd
29import yfinance as yf
30 
31 
32# Top 20 supported cryptocurrencies
33SUPPORTED_CRYPTOS = {
34    "BTC-USD", "ETH-USD", "BNB-USD", "SOL-USD", "XRP-USD",
35    "ADA-USD", "DOGE-USD", "AVAX-USD", "DOT-USD", "MATIC-USD",
36    "LINK-USD", "ATOM-USD", "UNI-USD", "LTC-USD", "BCH-USD",
37    "XLM-USD", "ALGO-USD", "VET-USD", "FIL-USD", "NEAR-USD",
38}
39 
40# Crypto category mapping for sector-like analysis
41CRYPTO_CATEGORIES = {
42    "BTC-USD": "Store of Value",
43    "ETH-USD": "Smart Contract L1",
44    "BNB-USD": "Exchange Token",
45    "SOL-USD": "Smart Contract L1",
46    "XRP-USD": "Payment",
47    "ADA-USD": "Smart Contract L1",
48    "DOGE-USD": "Meme",
49    "AVAX-USD": "Smart Contract L1",
50    "DOT-USD": "Interoperability",
51    "MATIC-USD": "Layer 2",
52    "LINK-USD": "Oracle",
53    "ATOM-USD": "Interoperability",
54    "UNI-USD": "DeFi",
55    "LTC-USD": "Payment",
56    "BCH-USD": "Payment",
57    "XLM-USD": "Payment",
58    "ALGO-USD": "Smart Contract L1",
59    "VET-USD": "Enterprise",
60    "FIL-USD": "Storage",
61    "NEAR-USD": "Smart Contract L1",
62}
63 
64 
65def detect_asset_type(ticker: str) -> Literal["stock", "crypto"]:
66    """Detect asset type from ticker format."""
67    ticker_upper = ticker.upper()
68    if ticker_upper.endswith("-USD"):
69        base = ticker_upper[:-4]
70        if base.isalpha():
71            return "crypto"
72    return "stock"
73 
74 
75@dataclass
76class StockData:
77    ticker: str
78    info: dict
79    earnings_history: pd.DataFrame | None
80    analyst_info: dict | None
81    price_history: pd.DataFrame | None
82    asset_type: Literal["stock", "crypto"] = "stock"
83 
84 
85@dataclass
86class CryptoFundamentals:
87    """Crypto-specific fundamentals (replaces P/E, margins for crypto)."""
88    market_cap: float | None
89    market_cap_rank: str  # "large", "mid", "small"
90    volume_24h: float | None
91    circulating_supply: float | None
92    category: str | None  # "Smart Contract L1", "DeFi", etc.
93    btc_correlation: float | None  # 30-day correlation to BTC
94    score: float
95    explanation: str
96 
97 
98@dataclass
99class EarningsSurprise:
100    score: float
101    explanation: str
102    actual_eps: float | None = None
103    expected_eps: float | None = None
104    surprise_pct: float | None = None
105 
106 
107@dataclass
108class Fundamentals:
109    score: float
110    key_metrics: dict
111    explanation: str
112 
113 
114@dataclass
115class AnalystSentiment:
116    score: float | None
117    summary: str
118    consensus_rating: str | None = None
119    price_target: float | None = None
120    current_price: float | None = None
121    upside_pct: float | None = None
122    num_analysts: int | None = None
123 
124 
125@dataclass
126class HistoricalPatterns:
127    score: float
128    pattern_desc: str
129    beats_last_4q: int | None = None
130    avg_reaction_pct: float | None = None
131 
132 
133@dataclass
134class MarketContext:
135    vix_level: float
136    vix_status: str  # "calm", "elevated", "fear"
137    spy_trend_10d: float
138    qqq_trend_10d: float
139    market_regime: str  # "bull", "bear", "choppy"
140    score: float
141    explanation: str
142    # Safe-haven indicators (v4.0.0)
143    gld_change_5d: float | None = None  # Gold ETF % change
144    tlt_change_5d: float | None = None  # Treasury ETF % change
145    uup_change_5d: float | None = None  # USD Index ETF % change
146    risk_off_detected: bool = False  # True if flight to safety detected
147 
148 
149@dataclass
150class SectorComparison:
151    sector_name: str
152    industry_name: str
153    stock_return_1m: float
154    sector_return_1m: float
155    relative_strength: float
156    sector_trend: str  # "strong uptrend", "downtrend", etc.
157    score: float
158    explanation: str
159 
160 
161@dataclass
162class EarningsTiming:
163    days_until_earnings: int | None
164    days_since_earnings: int | None
165    next_earnings_date: str | None
166    last_earnings_date: str | None
167    timing_flag: str  # "pre_earnings", "post_earnings", "safe"
168    price_change_5d: float | None
169    confidence_adjustment: float
170    caveats: list[str]
171 
172 
173@dataclass
174class MomentumAnalysis:
175    rsi_14d: float | None
176    rsi_status: str  # "overbought", "oversold", "neutral"
177    price_vs_52w_low: float | None
178    price_vs_52w_high: float | None
179    near_52w_high: bool
180    near_52w_low: bool
181    volume_ratio: float | None
182    relative_strength_vs_sector: float | None
183    score: float
184    explanation: str
185 
186 
187@dataclass
188class SentimentAnalysis:
189    score: float  # Overall -1.0 to 1.0
190    explanation: str  # Human-readable summary
191 
192    # Sub-indicator scores
193    fear_greed_score: float | None = None
194    short_interest_score: float | None = None
195    vix_structure_score: float | None = None
196    insider_activity_score: float | None = None
197    put_call_score: float | None = None
198 
199    # Raw data
200    fear_greed_value: int | None = None  # 0-100
201    fear_greed_status: str | None = None  # "Extreme Fear", etc.
202    short_interest_pct: float | None = None
203    days_to_cover: float | None = None
204    vix_structure: str | None = None  # "contango", "backwardation", "flat"
205    vix_slope: float | None = None
206    insider_net_shares: int | None = None
207    insider_net_value: float | None = None  # Millions USD
208    put_call_ratio: float | None = None
209    put_volume: int | None = None
210    call_volume: int | None = None
211 
212    # Metadata
213    indicators_available: int = 0
214    data_freshness_warnings: list[str] | None = None
215 
216 
217@dataclass
218class Signal:
219    ticker: str
220    company_name: str
221    recommendation: Literal["BUY", "HOLD", "SELL"]
222    confidence: float
223    final_score: float
224    supporting_points: list[str]
225    caveats: list[str]
226    timestamp: str
227    components: dict
228 
229 
230def fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:
231    """Fetch stock data from Yahoo Finance with retry logic."""
232    max_retries = 3
233    for attempt in range(max_retries):
234        try:
235            if verbose:
236                print(f"Fetching data for {ticker}... (attempt {attempt + 1}/{max_retries})", file=sys.stderr)
237 
238            stock = yf.Ticker(ticker)
239            info = stock.info
240 
241            # Validate ticker
242            if not info or "regularMarketPrice" not in info:
243                return None
244 
245            # Fetch earnings history
246            try:
247                earnings_history = stock.earnings_dates
248            except Exception:
249                earnings_history = None
250 
251            # Fetch analyst info
252            try:
253                analyst_info = {
254                    "recommendations": stock.recommendations,
255                    "analyst_price_targets": stock.analyst_price_targets,
256                }
257            except Exception:
258                analyst_info = None
259 
260            # Fetch price history (1 year for historical patterns)
261            try:
262                price_history = stock.history(period="1y")
263            except Exception:
264                price_history = None
265 
266            return StockData(
267                ticker=ticker,
268                info=info,
269                earnings_history=earnings_history,
270                analyst_info=analyst_info,
271                price_history=price_history,
272                asset_type=detect_asset_type(ticker),
273            )
274 
275        except Exception as e:
276            if attempt < max_retries - 1:
277                wait_time = 2 ** attempt  # Exponential backoff
278                if verbose:
279                    print(f"Error fetching {ticker}: {e}. Retrying in {wait_time}s...", file=sys.stderr)
280                time.sleep(wait_time)
281            else:
282                if verbose:
283                    print(f"Failed to fetch {ticker} after {max_retries} attempts", file=sys.stderr)
284                return None
285 
286    return None
287 
288 
289def analyze_earnings_surprise(data: StockData) -> EarningsSurprise | None:
290    """Analyze earnings surprise from most recent quarter."""
291    if data.earnings_history is None or data.earnings_history.empty:
292        return None
293 
294    try:
295        # Get most recent earnings with actual data
296        recent = data.earnings_history.sort_index(ascending=False).head(10)
297 
298        for idx, row in recent.iterrows():
299            if pd.notna(row.get("Reported EPS")) and pd.notna(row.get("EPS Estimate")):
300                actual = float(row["Reported EPS"])
301                expected = float(row["EPS Estimate"])
302 
303                if expected == 0:
304                    continue
305 
306                surprise_pct = ((actual - expected) / abs(expected)) * 100
307 
308                # Score based on surprise percentage
309                if surprise_pct > 10:
310                    score = 1.0
311                elif surprise_pct > 5:
312                    score = 0.7
313                elif surprise_pct > 0:
314                    score = 0.3
315                elif surprise_pct > -5:
316                    score = -0.3
317                elif surprise_pct > -10:
318                    score = -0.7
319                else:
320                    score = -1.0
321 
322                explanation = f"{'Beat' if surprise_pct > 0 else 'Missed'} by {abs(surprise_pct):.1f}%"
323 
324                return EarningsSurprise(
325                    score=score,
326                    explanation=explanation,
327                    actual_eps=actual,
328                    expected_eps=expected,
329                    surprise_pct=surprise_pct,
330                )
331 
332        return None
333 
334    except Exception:
335        return None
336 
337 
338def analyze_fundamentals(data: StockData) -> Fundamentals | None:
339    """Analyze fundamental metrics."""
340    info = data.info
341    scores = []
342    metrics = {}
343    explanations = []
344 
345    try:
346        # P/E Ratio (lower is better, but consider growth)
347        pe_ratio = info.get("trailingPE") or info.get("forwardPE")
348        if pe_ratio and pe_ratio > 0:
349            metrics["pe_ratio"] = round(pe_ratio, 2)
350            if pe_ratio < 15:
351                scores.append(0.5)
352                explanations.append(f"Attractive P/E: {pe_ratio:.1f}x")
353            elif pe_ratio > 30:
354                scores.append(-0.3)
355                explanations.append(f"Elevated P/E: {pe_ratio:.1f}x")
356            else:
357                scores.append(0.1)
358 
359        # Operating Margin
360        op_margin = info.get("operatingMargins")
361        if op_margin:
362            metrics["operating_margin"] = round(op_margin, 3)
363            if op_margin > 0.15:
364                scores.append(0.5)
365                explanations.append(f"Strong margin: {op_margin*100:.1f}%")
366            elif op_margin < 0.05:
367                scores.append(-0.5)
368                explanations.append(f"Weak margin: {op_margin*100:.1f}%")
369 
370        # Revenue Growth
371        rev_growth = info.get("revenueGrowth")
372        if rev_growth:
373            metrics["revenue_growth_yoy"] = round(rev_growth, 3)
374            if rev_growth > 0.20:
375                scores.append(0.5)
376                explanations.append(f"Strong growth: {rev_growth*100:.1f}% YoY")
377            elif rev_growth < 0.05:
378                scores.append(-0.3)
379                explanations.append(f"Slow growth: {rev_growth*100:.1f}% YoY")
380            else:
381                scores.append(0.2)
382 
383        # Debt to Equity
384        debt_equity = info.get("debtToEquity")
385        if debt_equity is not None:
386            metrics["debt_to_equity"] = round(debt_equity / 100, 2)
387            if debt_equity < 50:
388                scores.append(0.3)
389            elif debt_equity > 200:
390                scores.append(-0.5)
391                explanations.append(f"High debt: D/E {debt_equity/100:.1f}x")
392 
393        if not scores:
394            return None
395 
396        # Average and normalize
397        avg_score = sum(scores) / len(scores)
398        normalized_score = max(-1.0, min(1.0, avg_score))
399 
400        explanation = "; ".join(explanations) if explanations else "Mixed fundamentals"
401 
402        return Fundamentals(
403            score=normalized_score,
404            key_metrics=metrics,
405            explanation=explanation,
406        )
407 
408    except Exception:
409        return None
410 
411 
412def analyze_crypto_fundamentals(data: StockData, verbose: bool = False) -> CryptoFundamentals | None:
413    """Analyze crypto-specific fundamentals (market cap, supply, category)."""
414    if data.asset_type != "crypto":
415        return None
416 
417    info = data.info
418    ticker = data.ticker.upper()
419 
420    try:
421        # Market cap analysis
422        market_cap = info.get("marketCap")
423        if not market_cap:
424            return None
425 
426        # Categorize by market cap
427        if market_cap >= 10_000_000_000:  # $10B+
428            market_cap_rank = "large"
429            cap_score = 0.3  # Large caps are more stable
430        elif market_cap >= 1_000_000_000:  # $1B-$10B
431            market_cap_rank = "mid"
432            cap_score = 0.1
433        else:
434            market_cap_rank = "small"
435            cap_score = -0.2  # Small caps are riskier
436 
437        # Volume analysis
438        volume_24h = info.get("volume") or info.get("volume24Hr")
439        volume_score = 0.0
440        if volume_24h and market_cap:
441            volume_to_cap = volume_24h / market_cap
442            if volume_to_cap > 0.05:  # >5% daily turnover
443                volume_score = 0.2  # High liquidity
444            elif volume_to_cap < 0.01:
445                volume_score = -0.2  # Low liquidity
446 
447        # Circulating supply
448        circulating_supply = info.get("circulatingSupply")
449 
450        # Get crypto category
451        category = CRYPTO_CATEGORIES.get(ticker, "Unknown")
452 
453        # Calculate BTC correlation (30 days)
454        btc_correlation = None
455        try:
456            if ticker != "BTC-USD" and data.price_history is not None:
457                btc = yf.Ticker("BTC-USD")
458                btc_hist = btc.history(period="1mo")
459                if not btc_hist.empty and len(data.price_history) > 5:
460                    # Align dates and calculate correlation
461                    crypto_returns = data.price_history["Close"].pct_change().dropna()
462                    btc_returns = btc_hist["Close"].pct_change().dropna()
463                    # Simple correlation on overlapping dates
464                    common_dates = crypto_returns.index.intersection(btc_returns.index)
465                    if len(common_dates) > 10:
466                        btc_correlation = crypto_returns.loc[common_dates].corr(btc_returns.loc[common_dates])
467        except Exception:
468            pass
469 
470        # BTC correlation scoring (high correlation = less diversification benefit)
471        corr_score = 0.0
472        if btc_correlation is not None:
473            if btc_correlation > 0.8:
474                corr_score = -0.1  # Very correlated to BTC
475            elif btc_correlation < 0.3:
476                corr_score = 0.1  # Good diversification
477 
478        # Total score
479        total_score = cap_score + volume_score + corr_score
480 
481        # Build explanation
482        explanations = []
483        explanations.append(f"Market cap: ${market_cap/1e9:.1f}B ({market_cap_rank})")
484        if category != "Unknown":
485            explanations.append(f"Category: {category}")
486        if btc_correlation is not None:
487            explanations.append(f"BTC corr: {btc_correlation:.2f}")
488 
489        return CryptoFundamentals(
490            market_cap=market_cap,
491            market_cap_rank=market_cap_rank,
492            volume_24h=volume_24h,
493            circulating_supply=circulating_supply,
494            category=category,
495            btc_correlation=round(btc_correlation, 2) if btc_correlation else None,
496            score=max(-1.0, min(1.0, total_score)),
497            explanation="; ".join(explanations),
498        )
499 
500    except Exception as e:
501        if verbose:
502            print(f"Error analyzing crypto fundamentals: {e}", file=sys.stderr)
503        return None
504 
505 
506def analyze_analyst_sentiment(data: StockData) -> AnalystSentiment | None:
507    """Analyze analyst sentiment and price targets."""
508    info = data.info
509 
510    try:
511        # Get current price
512        current_price = info.get("regularMarketPrice") or info.get("currentPrice")
513        if not current_price:
514            return None
515 
516        # Get target price
517        target_price = info.get("targetMeanPrice")
518 
519        # Get number of analysts
520        num_analysts = info.get("numberOfAnalystOpinions")
521 
522        # Get recommendation
523        recommendation = info.get("recommendationKey")
524 
525        if not target_price or not recommendation:
526            return AnalystSentiment(
527                score=None,
528                summary="No analyst coverage available",
529            )
530 
531        # Calculate upside
532        upside_pct = ((target_price - current_price) / current_price) * 100
533 
534        # Score based on recommendation and upside
535        rec_scores = {
536            "strong_buy": 1.0,
537            "buy": 0.7,
538            "hold": 0.0,
539            "sell": -0.7,
540            "strong_sell": -1.0,
541        }
542 
543        base_score = rec_scores.get(recommendation, 0.0)
544 
545        # Adjust based on upside
546        if upside_pct > 20:
547            score = min(1.0, base_score + 0.3)
548        elif upside_pct > 10:
549            score = min(1.0, base_score + 0.15)
550        elif upside_pct < -10:
551            score = max(-1.0, base_score - 0.3)
552        else:
553            score = base_score
554 
555        # Format recommendation
556        rec_display = recommendation.replace("_", " ").title()
557 
558        summary = f"{rec_display} with {abs(upside_pct):.1f}% {'upside' if upside_pct > 0 else 'downside'}"
559        if num_analysts:
560            summary += f" ({num_analysts} analysts)"
561 
562        return AnalystSentiment(
563            score=score,
564            summary=summary,
565            consensus_rating=rec_display,
566            price_target=target_price,
567            current_price=current_price,
568            upside_pct=upside_pct,
569            num_analysts=num_analysts,
570        )
571 
572    except Exception:
573        return AnalystSentiment(
574            score=None,
575            summary="Error analyzing analyst sentiment",
576        )
577 
578 
579def analyze_historical_patterns(data: StockData) -> HistoricalPatterns | None:
580    """Analyze historical earnings patterns."""
581    if data.earnings_history is None or data.price_history is None:
582        return None
583 
584    if data.earnings_history.empty or data.price_history.empty:
585        return None
586 
587    try:
588        # Get last 4 quarters earnings dates
589        earnings_dates = data.earnings_history.sort_index(ascending=False).head(4)
590 
591        beats = 0
592        reactions = []
593 
594        for earnings_date, row in earnings_dates.iterrows():
595            if pd.notna(row.get("Reported EPS")) and pd.notna(row.get("EPS Estimate")):
596                actual = float(row["Reported EPS"])
597                expected = float(row["EPS Estimate"])
598 
599                if actual > expected:
600                    beats += 1
601 
602                # Try to get price reaction (day of earnings)
603                try:
604                    earnings_day = pd.Timestamp(earnings_date).date()
605 
606                    # Find closest trading day
607                    price_data = data.price_history[data.price_history.index.date == earnings_day]
608 
609                    if not price_data.empty:
610                        day_change = ((price_data["Close"].iloc[0] - price_data["Open"].iloc[0]) / price_data["Open"].iloc[0]) * 100
611                        reactions.append(day_change)
612                except Exception:
613                    continue
614 
615        total_quarters = len(earnings_dates)
616        if total_quarters == 0:
617            return None
618 
619        # Score based on beat rate
620        beat_rate = beats / total_quarters
621 
622        if beat_rate == 1.0:
623            score = 0.8
624        elif beat_rate >= 0.75:
625            score = 0.5
626        elif beat_rate >= 0.5:
627            score = 0.0
628        elif beat_rate >= 0.25:
629            score = -0.5
630        else:
631            score = -0.8
632 
633        # Pattern description
634        pattern_desc = f"{beats}/{total_quarters} quarters beat expectations"
635 
636        if reactions:
637            avg_reaction = sum(reactions) / len(reactions)
638            pattern_desc += f", avg reaction {avg_reaction:+.1f}%"
639        else:
640            avg_reaction = None
641 
642        return HistoricalPatterns(
643            score=score,
644            pattern_desc=pattern_desc,
645            beats_last_4q=beats,
646            avg_reaction_pct=avg_reaction,
647        )
648 
649    except Exception:
650        return None
651 
652 
653def analyze_market_context(verbose: bool = False) -> MarketContext | None:
654    """Analyze overall market conditions using VIX, SPY, QQQ, and safe-havens with 1h cache."""
655    # Check cache first
656    cached = _get_cached("market_context")
657    if cached is not None:
658        if verbose:
659            print("Using cached market context (< 1h old)", file=sys.stderr)
660        return cached
661 
662    try:
663        if verbose:
664            print("Fetching market indicators (VIX, SPY, QQQ)...", file=sys.stderr)
665 
666        # Fetch market indicators
667        vix = yf.Ticker("^VIX")
668        spy = yf.Ticker("SPY")
669        qqq = yf.Ticker("QQQ")
670 
671        # Get current VIX level
672        vix_info = vix.info
673        vix_level = vix_info.get("regularMarketPrice") or vix_info.get("currentPrice")
674 
675        if not vix_level:
676            return None
677 
678        # Determine VIX status
679        if vix_level < 20:
680            vix_status = "calm"
681            vix_score = 0.2
682        elif vix_level < 30:
683            vix_status = "elevated"
684            vix_score = 0.0
685        else:
686            vix_status = "fear"
687            vix_score = -0.5
688 
689        # Get SPY and QQQ 10-day trends
690        spy_hist = spy.history(period="1mo")
691        qqq_hist = qqq.history(period="1mo")
692 
693        if spy_hist.empty or qqq_hist.empty:
694            return None
695 
696        # Calculate 10-day price changes
697        spy_10d_ago = spy_hist["Close"].iloc[-min(10, len(spy_hist))]
698        spy_current = spy_hist["Close"].iloc[-1]
699        spy_trend_10d = ((spy_current - spy_10d_ago) / spy_10d_ago) * 100
700 
701        qqq_10d_ago = qqq_hist["Close"].iloc[-min(10, len(qqq_hist))]
702        qqq_current = qqq_hist["Close"].iloc[-1]
703        qqq_trend_10d = ((qqq_current - qqq_10d_ago) / qqq_10d_ago) * 100
704 
705        # Determine market regime
706        avg_trend = (spy_trend_10d + qqq_trend_10d) / 2
707 
708        if avg_trend > 3:
709            market_regime = "bull"
710            regime_score = 0.3
711        elif avg_trend < -3:
712            market_regime = "bear"
713            regime_score = -0.4
714        else:
715            market_regime = "choppy"
716            regime_score = -0.1
717 
718        # Calculate overall score
719        overall_score = (vix_score + regime_score) / 2
720 
721        # NEW v4.0.0: Fetch safe-haven indicators (GLD, TLT, UUP)
722        gld_change_5d = None
723        tlt_change_5d = None
724        uup_change_5d = None
725        risk_off_detected = False
726 
727        try:
728            if verbose:
729                print("Fetching safe-haven indicators (GLD, TLT, UUP)...", file=sys.stderr)
730 
731            # Fetch safe-haven ETFs
732            gld = yf.Ticker("GLD")  # Gold
733            tlt = yf.Ticker("TLT")  # 20+ Year Treasury
734            uup = yf.Ticker("UUP")  # USD Index
735 
736            gld_hist = gld.history(period="10d")
737            tlt_hist = tlt.history(period="10d")
738            uup_hist = uup.history(period="10d")
739 
740            # Calculate 5-day changes
741            if not gld_hist.empty and len(gld_hist) >= 5:
742                gld_5d_ago = gld_hist["Close"].iloc[-min(5, len(gld_hist))]
743                gld_current = gld_hist["Close"].iloc[-1]
744                gld_change_5d = ((gld_current - gld_5d_ago) / gld_5d_ago) * 100
745 
746            if not tlt_hist.empty and len(tlt_hist) >= 5:
747                tlt_5d_ago = tlt_hist["Close"].iloc[-min(5, len(tlt_hist))]
748                tlt_current = tlt_hist["Close"].iloc[-1]
749                tlt_change_5d = ((tlt_current - tlt_5d_ago) / tlt_5d_ago) * 100
750 
751            if not uup_hist.empty and len(uup_hist) >= 5:
752                uup_5d_ago = uup_hist["Close"].iloc[-min(5, len(uup_hist))]
753                uup_current = uup_hist["Close"].iloc[-1]
754                uup_change_5d = ((uup_current - uup_5d_ago) / uup_5d_ago) * 100
755 
756            # Risk-off detection: All three safe-havens rising together
757            if (gld_change_5d is not None and gld_change_5d >= 2.0 and
758                tlt_change_5d is not None and tlt_change_5d >= 1.0 and
759                uup_change_5d is not None and uup_change_5d >= 1.0):
760                risk_off_detected = True
761                overall_score -= 0.5  # Reduce score significantly
762                if verbose:
763                    print(f"    🛡️ RISK-OFF DETECTED: GLD {gld_change_5d:+.1f}%, TLT {tlt_change_5d:+.1f}%, UUP {uup_change_5d:+.1f}%", file=sys.stderr)
764 
765        except Exception as e:
766            if verbose:
767                print(f"    Safe-haven indicators unavailable: {e}", file=sys.stderr)
768 
769        # Build explanation
770        explanation = f"VIX {vix_level:.1f} ({vix_status}), Market {market_regime} (SPY {spy_trend_10d:+.1f}%, QQQ {qqq_trend_10d:+.1f}% 10d)"
771        if risk_off_detected:
772            explanation += " ⚠️ RISK-OFF MODE"
773 
774        result = MarketContext(
775            vix_level=vix_level,
776            vix_status=vix_status,
777            spy_trend_10d=spy_trend_10d,
778            qqq_trend_10d=qqq_trend_10d,
779            market_regime=market_regime,
780            score=overall_score,
781            explanation=explanation,
782            gld_change_5d=gld_change_5d,
783            tlt_change_5d=tlt_change_5d,
784            uup_change_5d=uup_change_5d,
785            risk_off_detected=risk_off_detected,
786        )
787 
788        # Cache the result for 1 hour
789        _set_cache("market_context", result)
790        return result
791 
792    except Exception as e:
793        if verbose:
794            print(f"Error analyzing market context: {e}", file=sys.stderr)
795        return None
796 
797 
798def get_sector_etf_ticker(sector: str) -> str | None:
799    """Map sector name to corresponding sector ETF ticker."""
800    sector_map = {
801        "Financial Services": "XLF",
802        "Financials": "XLF",
803        "Technology": "XLK",
804        "Healthcare": "XLV",
805        "Consumer Cyclical": "XLY",
806        "Consumer Defensive": "XLP",
807        "Utilities": "XLU",
808        "Basic Materials": "XLB",
809        "Real Estate": "XLRE",
810        "Communication Services": "XLC",
811        "Industrials": "XLI",
812        "Energy": "XLE",
813    }
814 
815    return sector_map.get(sector)
816 
817 
818# ============================================================================
819# Breaking News Check (v4.0.0)
820# ============================================================================
821 
822# Crisis keywords by category
823CRISIS_KEYWORDS = {
824    "war": ["war", "invasion", "military strike", "attack", "conflict", "combat"],
825    "economic": ["recession", "crisis", "collapse", "default", "bankruptcy", "crash"],
826    "regulatory": ["sanctions", "embargo", "ban", "investigation", "fraud", "probe"],
827    "disaster": ["earthquake", "hurricane", "pandemic", "outbreak", "disaster", "catastrophe"],
828    "financial": ["emergency rate", "fed emergency", "bailout", "circuit breaker", "trading halt"],
829}
830 
831# Geopolitical event → sector mapping (v4.0.0)
832GEOPOLITICAL_RISK_MAP = {
833    "taiwan": {
834        "keywords": ["taiwan", "tsmc", "strait"],
835        "sectors": ["Technology", "Communication Services"],
836        "sector_etfs": ["XLK", "XLC"],
837        "impact": "Semiconductor supply chain disruption",
838        "affected_tickers": ["NVDA", "AMD", "TSM", "INTC", "QCOM", "AVGO", "MU"],
839    },
840    "china": {
841        "keywords": ["china", "beijing", "tariff", "trade war"],
842        "sectors": ["Technology", "Consumer Cyclical", "Consumer Defensive"],
843        "sector_etfs": ["XLK", "XLY", "XLP"],
844        "impact": "Tech supply chain and consumer market exposure",
845        "affected_tickers": ["AAPL", "QCOM", "NKE", "SBUX", "MCD", "YUM", "TGT", "WMT"],
846    },
847    "russia_ukraine": {
848        "keywords": ["russia", "ukraine", "putin", "kyiv", "moscow"],
849        "sectors": ["Energy", "Materials"],
850        "sector_etfs": ["XLE", "XLB"],
851        "impact": "Energy and commodity price volatility",
852        "affected_tickers": ["XOM", "CVX", "COP", "SLB", "MOS", "CF", "NTR", "ADM"],
853    },
854    "middle_east": {
855        "keywords": ["iran", "israel", "gaza", "saudi", "middle east", "gulf"],
856        "sectors": ["Energy", "Industrials"],
857        "sector_etfs": ["XLE", "XLI"],
858        "impact": "Oil price volatility and defense spending",
859        "affected_tickers": ["XOM", "CVX", "COP", "LMT", "RTX", "NOC", "GD", "BA"],
860    },
861    "banking_crisis": {
862        "keywords": ["bank failure", "credit crisis", "liquidity crisis", "bank run"],
863        "sectors": ["Financials"],
864        "sector_etfs": ["XLF"],
865        "impact": "Financial sector contagion risk",
866        "affected_tickers": ["JPM", "BAC", "WFC", "C", "GS", "MS", "USB", "PNC"],
867    },
868}
869 
870 
871def check_breaking_news(verbose: bool = False) -> list[str] | None:
872    """
873    Check Google News RSS for breaking market/economic crisis events (last 24h).
874    Returns list of alert strings or None.
875    Uses 1h cache to avoid excessive API calls.
876    """
877    # Check cache first
878    cached = _get_cached("breaking_news")
879    if cached is not None:
880        return cached
881 
882    alerts = []
883 
884    try:
885        import feedparser
886        from datetime import datetime, timezone, timedelta
887 
888        if verbose:
889            print("Checking breaking news (Google News RSS)...", file=sys.stderr)
890 
891        # Google News RSS feeds for finance/business
892        rss_urls = [
893            "https://news.google.com/rss/search?q=stock+market+when:24h&hl=en-US&gl=US&ceid=US:en",
894            "https://news.google.com/rss/search?q=economy+crisis+when:24h&hl=en-US&gl=US&ceid=US:en",
895        ]
896 
897        now = datetime.now(timezone.utc)
898        cutoff_time = now - timedelta(hours=24)
899 
900        for url in rss_urls:
901            try:
902                feed = feedparser.parse(url)
903 
904                for entry in feed.entries[:20]:  # Check top 20 headlines
905                    # Parse publication date
906                    pub_date = None
907                    if hasattr(entry, "published_parsed") and entry.published_parsed:
908                        pub_date = datetime(*entry.published_parsed[:6], tzinfo=timezone.utc)
909 
910                    # Skip if older than 24h
911                    if pub_date and pub_date < cutoff_time:
912                        continue
913 
914                    title = entry.get("title", "").lower()
915                    summary = entry.get("summary", "").lower()
916                    text = f"{title} {summary}"
917 
918                    # Check for crisis keywords
919                    for category, keywords in CRISIS_KEYWORDS.items():
920                        for keyword in keywords:
921                            if keyword in text:
922                                alert_text = entry.get("title", "Unknown alert")
923                                hours_ago = int((now - pub_date).total_seconds() / 3600) if pub_date else None
924                                time_str = f"{hours_ago}h ago" if hours_ago is not None else "recent"
925 
926                                alert = f"{alert_text} ({time_str})"
927                                if alert not in alerts:  # Deduplicate
928                                    alerts.append(alert)
929                                    if verbose:
930                                        print(f"    ⚠️ Alert: {alert}", file=sys.stderr)
931                                break
932                        if len(alerts) >= 3:  # Limit to 3 alerts
933                            break
934 
935                    if len(alerts) >= 3:
936                        break
937 
938            except Exception as e:
939                if verbose:
940                    print(f"    Failed to fetch {url}: {e}", file=sys.stderr)
941                continue
942 
943        # Cache results (even if empty) for 1 hour
944        result = alerts if alerts else None
945        _set_cache("breaking_news", result)
946        return result
947 
948    except Exception as e:
949        if verbose:
950            print(f"    Breaking news check failed: {e}", file=sys.stderr)
951        return None
952 
953 
954def check_sector_geopolitical_risk(
955    ticker: str,
956    sector: str | None,
957    breaking_news: list[str] | None,
958    verbose: bool = False
959) -> tuple[str | None, float]:
960    """
961    Check if ticker is exposed to geopolitical risks based on breaking news.
962    Returns (warning_message, confidence_penalty).
963 
964    Args:
965        ticker: Stock ticker symbol
966        sector: Stock sector (from yfinance)
967        breaking_news: List of breaking news alerts
968        verbose: Print debug info
969 
970    Returns:
971        (warning_message, confidence_penalty) where:
972        - warning_message: None or string like "⚠️ SECTOR RISK: Taiwan tensions affect semiconductors"
973        - confidence_penalty: 0.0 (no risk) to 0.5 (high risk)
974    """
975    if not breaking_news:
976        return None, 0.0
977 
978    # Combine all breaking news into single text for keyword matching
979    news_text = " ".join(breaking_news).lower()
980 
981    # Check each geopolitical event
982    for event_name, event_data in GEOPOLITICAL_RISK_MAP.items():
983        # Check if any keywords from this event appear in breaking news
984        keywords_found = []
985        for keyword in event_data["keywords"]:
986            if keyword in news_text:
987                keywords_found.append(keyword)
988 
989        if not keywords_found:
990            continue
991 
992        # Check if ticker is in affected list
993        if ticker in event_data["affected_tickers"]:
994            # Direct ticker exposure
995            warning = f"⚠️ SECTOR RISK: {event_data['impact']} (detected: {', '.join(keywords_found)})"
996            penalty = 0.3  # Reduce BUY confidence by 30%
997 
998            if verbose:
999                print(f"    Geopolitical risk detected: {event_name} affects {ticker}", file=sys.stderr)
1000 
1001            return warning, penalty
1002 
1003        # Check if sector is affected (even if ticker not in list)
1004        if sector and sector in event_data["sectors"]:
1005            # Sector exposure (weaker signal)
1006            warning = f"⚠️ SECTOR RISK: {sector} sector exposed to {event_data['impact']}"
1007            penalty = 0.15  # Reduce BUY confidence by 15%
1008 
1009            if verbose:
1010                print(f"    Sector risk detected: {event_name} affects {sector} sector", file=sys.stderr)
1011 
1012            return warning, penalty
1013 
1014    return None, 0.0
1015 
1016 
1017def analyze_sector_performance(data: StockData, verbose: bool = False) -> SectorComparison | None:
1018    """Compare stock performance to its sector."""
1019    try:
1020        sector = data.info.get("sector")
1021        industry = data.info.get("industry")
1022 
1023        if not sector:
1024            return None
1025 
1026        sector_etf_ticker = get_sector_etf_ticker(sector)
1027 
1028        if not sector_etf_ticker:
1029            if verbose:
1030                print(f"No sector ETF mapping for {sector}", file=sys.stderr)
1031            return None
1032 
1033        if verbose:
1034            print(f"Comparing to sector ETF: {sector_etf_ticker}", file=sys.stderr)
1035 
1036        # Fetch sector ETF data
1037        sector_etf = yf.Ticker(sector_etf_ticker)
1038        sector_hist = sector_etf.history(period="3mo")
1039 
1040        if sector_hist.empty or data.price_history is None or data.price_history.empty:
1041            return None
1042 
1043        # Calculate 1-month returns
1044        stock_1m_ago = data.price_history["Close"].iloc[-min(22, len(data.price_history))]
1045        stock_current = data.price_history["Close"].iloc[-1]
1046        stock_return_1m = ((stock_current - stock_1m_ago) / stock_1m_ago) * 100
1047 
1048        sector_1m_ago = sector_hist["Close"].iloc[-min(22, len(sector_hist))]
1049        sector_current = sector_hist["Close"].iloc[-1]
1050        sector_return_1m = ((sector_current - sector_1m_ago) / sector_1m_ago) * 100
1051 
1052        # Calculate relative strength
1053        relative_strength = stock_return_1m / sector_return_1m if sector_return_1m != 0 else 1.0
1054 
1055        # Sector 10-day trend
1056        sector_10d_ago = sector_hist["Close"].iloc[-min(10, len(sector_hist))]
1057        sector_trend_10d = ((sector_current - sector_10d_ago) / sector_10d_ago) * 100
1058 
1059        if sector_trend_10d > 5:
1060            sector_trend = "strong uptrend"
1061        elif sector_trend_10d > 2:
1062            sector_trend = "uptrend"
1063        elif sector_trend_10d < -5:
1064            sector_trend = "downtrend"
1065        elif sector_trend_10d < -2:
1066            sector_trend = "weak"
1067        else:
1068            sector_trend = "neutral"
1069 
1070        # Calculate score
1071        score = 0.0
1072 
1073        # Relative performance score
1074        if relative_strength > 1.05:  # Outperforming by >5%
1075            score += 0.3
1076        elif relative_strength < 0.95:  # Underperforming by >5%
1077            score -= 0.3
1078 
1079        # Sector trend score
1080        if sector_trend_10d > 5:
1081            score += 0.2
1082        elif sector_trend_10d < -5:
1083            score -= 0.2
1084 
1085        explanation = f"{sector} sector {sector_trend} ({sector_return_1m:+.1f}% 1m), stock {stock_return_1m:+.1f}% vs sector"
1086 
1087        return SectorComparison(
1088            sector_name=sector,
1089            industry_name=industry or "Unknown",
1090            stock_return_1m=stock_return_1m,
1091            sector_return_1m=sector_return_1m,
1092            relative_strength=relative_strength,
1093            sector_trend=sector_trend,
1094            score=score,
1095            explanation=explanation,
1096        )
1097 
1098    except Exception as e:
1099        if verbose:
1100            print(f"Error analyzing sector performance: {e}", file=sys.stderr)
1101        return None
1102 
1103 
1104def analyze_earnings_timing(data: StockData) -> EarningsTiming | None:
1105    """Check earnings timing and flag pre/post-earnings periods."""
1106    try:
1107        from datetime import datetime, timedelta
1108 
1109        if data.earnings_history is None or data.earnings_history.empty:
1110            return None
1111 
1112        current_date = datetime.now()
1113        earnings_dates = data.earnings_history.sort_index(ascending=False)
1114 
1115        # Find next and last earnings dates
1116        next_earnings_date = None
1117        last_earnings_date = None
1118 
1119        for earnings_date in earnings_dates.index:
1120            earnings_dt = pd.Timestamp(earnings_date).to_pydatetime()
1121 
1122            if earnings_dt > current_date and next_earnings_date is None:
1123                next_earnings_date = earnings_dt
1124            elif earnings_dt <= current_date and last_earnings_date is None:
1125                last_earnings_date = earnings_dt
1126                break
1127 
1128        # Calculate days until/since earnings
1129        days_until_earnings = None
1130        days_since_earnings = None
1131 
1132        if next_earnings_date:
1133            days_until_earnings = (next_earnings_date - current_date).days
1134 
1135        if last_earnings_date:
1136            days_since_earnings = (current_date - last_earnings_date).days
1137 
1138        # Determine timing flag
1139        timing_flag = "safe"
1140        confidence_adjustment = 0.0
1141        caveats = []
1142 
1143        # Pre-earnings check (< 14 days)
1144        if days_until_earnings is not None and days_until_earnings <= 14:
1145            timing_flag = "pre_earnings"
1146            confidence_adjustment = -0.3
1147            caveats.append(f"Earnings in {days_until_earnings} days - high volatility expected")
1148 
1149        # Post-earnings check (< 5 days)
1150        price_change_5d = None
1151        if days_since_earnings is not None and days_since_earnings <= 5:
1152            # Calculate 5-day price change
1153            if data.price_history is not None and len(data.price_history) >= 5:
1154                price_5d_ago = data.price_history["Close"].iloc[-5]
1155                price_current = data.price_history["Close"].iloc[-1]
1156                price_change_5d = ((price_current - price_5d_ago) / price_5d_ago) * 100
1157 
1158                if price_change_5d > 15:
1159                    timing_flag = "post_earnings"
1160                    confidence_adjustment = -0.2
1161                    caveats.append(f"Up {price_change_5d:.1f}% in 5 days - gains may be priced in")
1162 
1163        return EarningsTiming(
1164            days_until_earnings=days_until_earnings,
1165            days_since_earnings=days_since_earnings,
1166            next_earnings_date=next_earnings_date.strftime("%Y-%m-%d") if next_earnings_date else None,
1167            last_earnings_date=last_earnings_date.strftime("%Y-%m-%d") if last_earnings_date else None,
1168            timing_flag=timing_flag,
1169            price_change_5d=price_change_5d,
1170            confidence_adjustment=confidence_adjustment,
1171            caveats=caveats,
1172        )
1173 
1174    except Exception:
1175        return None
1176 
1177 
1178def calculate_rsi(prices: pd.Series, period: int = 14) -> float | None:
1179    """Calculate RSI (Relative Strength Index)."""
1180    try:
1181        if len(prices) < period + 1:
1182            return None
1183 
1184        # Calculate price changes
1185        delta = prices.diff()
1186 
1187        # Separate gains and losses
1188        gains = delta.where(delta > 0, 0)
1189        losses = -delta.where(delta < 0, 0)
1190 
1191        # Calculate average gains and losses
1192        avg_gain = gains.rolling(window=period).mean()
1193        avg_loss = losses.rolling(window=period).mean()
1194 
1195        # Calculate RS
1196        rs = avg_gain / avg_loss
1197 
1198        # Calculate RSI
1199        rsi = 100 - (100 / (1 + rs))
1200 
1201        return float(rsi.iloc[-1])
1202 
1203    except Exception:
1204        return None
1205 
1206 
1207def analyze_momentum(data: StockData) -> MomentumAnalysis | None:
1208    """Analyze momentum indicators (RSI, 52w range, volume, relative strength)."""
1209    try:
1210        if data.price_history is None or data.price_history.empty:
1211            return None
1212 
1213        # Calculate RSI
1214        rsi_14d = calculate_rsi(data.price_history["Close"], period=14)
1215 
1216        if rsi_14d:
1217            if rsi_14d > 70:
1218                rsi_status = "overbought"
1219            elif rsi_14d < 30:
1220                rsi_status = "oversold"
1221            else:
1222                rsi_status = "neutral"
1223        else:
1224            rsi_status = "unknown"
1225 
1226        # Get 52-week high/low
1227        high_52w = data.info.get("fiftyTwoWeekHigh")
1228        low_52w = data.info.get("fiftyTwoWeekLow")
1229        current_price = data.info.get("regularMarketPrice") or data.info.get("currentPrice")
1230 
1231        price_vs_52w_low = None
1232        price_vs_52w_high = None
1233        near_52w_high = False
1234        near_52w_low = False
1235 
1236        if high_52w and low_52w and current_price:
1237            price_range = high_52w - low_52w
1238            if price_range > 0:
1239                price_vs_52w_low = ((current_price - low_52w) / price_range) * 100
1240                price_vs_52w_high = ((high_52w - current_price) / price_range) * 100
1241 
1242                near_52w_high = price_vs_52w_low > 90
1243                near_52w_low = price_vs_52w_low < 10
1244 
1245        # Volume analysis
1246        volume_ratio = None
1247        if "Volume" in data.price_history.columns and len(data.price_history) >= 60:
1248            recent_vol = data.price_history["Volume"].iloc[-5:].mean()
1249            avg_vol = data.price_history["Volume"].iloc[-60:].mean()
1250            volume_ratio = recent_vol / avg_vol if avg_vol > 0 else None
1251 
1252        # Calculate score
1253        score = 0.0
1254        explanations = []
1255 
1256        if rsi_14d:
1257            if rsi_14d > 70:
1258                score -= 0.5
1259                explanations.append(f"RSI {rsi_14d:.0f} (overbought)")
1260            elif rsi_14d < 30:
1261                score += 0.5
1262                explanations.append(f"RSI {rsi_14d:.0f} (oversold)")
1263 
1264        if near_52w_high:
1265            score -= 0.3
1266            explanations.append("Near 52w high")
1267        elif near_52w_low:
1268            score += 0.3
1269            explanations.append("Near 52w low")
1270 
1271        if volume_ratio and volume_ratio > 1.5:
1272            explanations.append(f"Volume {volume_ratio:.1f}x average")
1273 
1274        explanation = "; ".join(explanations) if explanations else "Momentum indicators neutral"
1275 
1276        return MomentumAnalysis(
1277            rsi_14d=rsi_14d,
1278            rsi_status=rsi_status,
1279            price_vs_52w_low=price_vs_52w_low,
1280            price_vs_52w_high=price_vs_52w_high,
1281            near_52w_high=near_52w_high,
1282            near_52w_low=near_52w_low,
1283            volume_ratio=volume_ratio,
1284            relative_strength_vs_sector=None,  # Could be enhanced with sector comparison
1285            score=score,
1286            explanation=explanation,
1287        )
1288 
1289    except Exception:
1290        return None
1291 
1292 
1293# ============================================================================
1294# Sentiment Analysis Helper Functions
1295# ============================================================================
1296 
1297# Simple cache for shared indicators (Fear & Greed, VIX)
1298# Format: {key: (value, timestamp)}
1299_SENTIMENT_CACHE = {}
1300_CACHE_TTL_SECONDS = 3600  # 1 hour
1301 
1302 
1303def _get_cached(key: str):
1304    """Get cached value if still valid (within TTL)."""
1305    if key in _SENTIMENT_CACHE:
1306        value, timestamp = _SENTIMENT_CACHE[key]
1307        if time.time() - timestamp < _CACHE_TTL_SECONDS:
1308            return value
1309    return None
1310 
1311 
1312def _set_cache(key: str, value):
1313    """Set cached value with current timestamp."""
1314    _SENTIMENT_CACHE[key] = (value, time.time())
1315 
1316 
1317async def get_fear_greed_index() -> tuple[float, int | None, str | None] | None:
1318    """
1319    Fetch CNN Fear & Greed Index (contrarian indicator) with 1h cache.
1320    Returns: (score, value, status) or None on failure.
1321    """
1322    # Check cache first
1323    cached = _get_cached("fear_greed")
1324    if cached is not None:
1325        return cached
1326 
1327    def _fetch():
1328        try:
1329            from fear_and_greed import get as get_fear_greed
1330            result = get_fear_greed()
1331            return result
1332        except Exception:
1333            return None
1334 
1335    try:
1336        result = await asyncio.to_thread(_fetch)
1337        if result is None:
1338            return None
1339 
1340        value = result.value  # 0-100
1341        status = result.description  # "Extreme Fear", "Fear", etc.
1342 
1343        # Contrarian scoring
1344        if value <= 25:
1345            score = 0.5  # Extreme fear = buy opportunity
1346        elif value <= 45:
1347            score = 0.2  # Fear = mild buy signal
1348        elif value <= 55:
1349            score = 0.0  # Neutral
1350        elif value <= 75:
1351            score = -0.2  # Greed = caution
1352        else:
1353            score = -0.5  # Extreme greed = warning
1354 
1355        result_tuple = (score, value, status)
1356        _set_cache("fear_greed", result_tuple)
1357        return result_tuple
1358    except Exception:
1359        return None
1360 
1361 
1362async def get_short_interest(data: StockData) -> tuple[float, float | None, float | None] | None:
1363    """
1364    Analyze short interest (from yfinance).
1365    Returns: (score, short_interest_pct, days_to_cover) or None.
1366    """
1367    # This is already synchronous data access (no API call), but make it async for consistency
1368    try:
1369        short_pct = data.info.get("shortPercentOfFloat")
1370        if short_pct is None:
1371            return None
1372 
1373        short_pct_float = float(short_pct) * 100  # Convert to percentage
1374 
1375        # Estimate days to cover (simplified - actual calculation needs volume data)
1376        short_ratio = data.info.get("shortRatio")  # Days to cover
1377        days_to_cover = float(short_ratio) if short_ratio else None
1378 
1379        # Scoring logic
1380        if short_pct_float > 20:
1381            if days_to_cover and days_to_cover > 10:
1382                score = 0.4  # High short interest + high days to cover = squeeze potential
1383            else:
1384                score = -0.3  # High short interest but justified
1385        elif short_pct_float < 5:
1386            score = 0.2  # Low short interest = bullish sentiment
1387        else:
1388            score = 0.0  # Normal range
1389 
1390        return (score, short_pct_float, days_to_cover)
1391    except Exception:
1392        return None
1393 
1394 
1395async def get_vix_term_structure() -> tuple[float, str | None, float | None] | None:
1396    """
1397    Analyze VIX futures term structure (contango vs backwardation) with 1h cache.
1398    Returns: (score, structure, slope) or None.
1399    """
1400    # Check cache first
1401    cached = _get_cached("vix_structure")
1402    if cached is not None:
1403        return cached
1404 
1405    def _fetch():
1406        try:
1407            import yfinance as yf
1408            vix = yf.Ticker("^VIX")
1409            vix_data = vix.history(period="5d")
1410            if vix_data.empty:
1411                return None
1412            return vix_data["Close"].iloc[-1]
1413        except Exception:
1414            return None
1415 
1416    try:
1417        vix_spot = await asyncio.to_thread(_fetch)
1418        if vix_spot is None:
1419            return None
1420 
1421        # Simplified: assume normal contango when VIX < 20, backwardation when VIX > 30
1422        if vix_spot < 15:
1423            structure = "contango"
1424            slope = 10.0  # Steep contango
1425            score = 0.3  # Complacency/bullish
1426        elif vix_spot < 20:
1427            structure = "contango"
1428            slope = 5.0
1429            score = 0.1
1430        elif vix_spot > 30:
1431            structure = "backwardation"
1432            slope = -5.0
1433            score = -0.3  # Stress/bearish
1434        else:
1435            structure = "flat"
1436            slope = 0.0
1437            score = 0.0
1438 
1439        result_tuple = (score, structure, slope)
1440        _set_cache("vix_structure", result_tuple)
1441        return result_tuple
1442    except Exception:
1443        return None
1444 
1445 
1446async def get_insider_activity(ticker: str, period_days: int = 90) -> tuple[float, int | None, float | None] | None:
1447    """
1448    Analyze insider trading from SEC Form 4 filings using edgartools.
1449    Returns: (score, net_shares, net_value_millions) or None.
1450 
1451    Scoring logic:
1452    - Strong buying (>100K shares or >$1M): +0.8
1453    - Moderate buying (>10K shares or >$0.1M): +0.4
1454    - Neutral: 0
1455    - Moderate selling: -0.4
1456    - Strong selling: -0.8
1457 
1458    Note: SEC EDGAR API requires User-Agent with email.
1459    """
1460    def _fetch():
1461        try:
1462            from edgar import Company, set_identity
1463            from datetime import datetime, timedelta
1464 
1465            # Set SEC-required identity
1466            set_identity("[email protected]")
1467 
1468            # Get company and Form 4 filings
1469            company = Company(ticker)
1470            filings = company.get_filings(form="4")
1471 
1472            if filings is None or len(filings) == 0:
1473                return None
1474 
1475            # Calculate cutoff date
1476            cutoff_date = datetime.now() - timedelta(days=period_days)
1477 
1478            # Aggregate transactions
1479            total_bought_shares = 0
1480            total_sold_shares = 0
1481            total_bought_value = 0.0
1482            total_sold_value = 0.0
1483 
1484            # Process recent filings (iterate, don't slice due to pyarrow compatibility)
1485            count = 0
1486            for filing in filings:
1487                if count >= 50:
1488                    break
1489                count += 1
1490 
1491                try:
1492                    # Check filing date
1493                    filing_date = filing.filing_date
1494                    if hasattr(filing_date, 'to_pydatetime'):
1495                        filing_date = filing_date.to_pydatetime()
1496                    elif isinstance(filing_date, str):
1497                        filing_date = datetime.strptime(filing_date, "%Y-%m-%d")
1498 
1499                    # Convert date object to datetime for comparison
1500                    if hasattr(filing_date, 'year') and not hasattr(filing_date, 'hour'):
1501                        filing_date = datetime.combine(filing_date, datetime.min.time())
1502 
1503                    if filing_date < cutoff_date:
1504                        continue
1505 
1506                    # Get Form 4 object
1507                    form4 = filing.obj()
1508                    if form4 is None:
1509                        continue
1510 
1511                    # Process purchases (edgartools returns DataFrames)
1512                    if hasattr(form4, 'common_stock_purchases'):
1513                        purchases = form4.common_stock_purchases
1514                        if isinstance(purchases, pd.DataFrame) and not purchases.empty:
1515                            if 'Shares' in purchases.columns:
1516                                total_bought_shares += int(purchases['Shares'].sum())
1517                            if 'Price' in purchases.columns and 'Shares' in purchases.columns:
1518                                total_bought_value += float((purchases['Shares'] * purchases['Price']).sum())
1519 
1520                    # Process sales
1521                    if hasattr(form4, 'common_stock_sales'):
1522                        sales = form4.common_stock_sales
1523                        if isinstance(sales, pd.DataFrame) and not sales.empty:
1524                            if 'Shares' in sales.columns:
1525                                total_sold_shares += int(sales['Shares'].sum())
1526                            if 'Price' in sales.columns and 'Shares' in sales.columns:
1527                                total_sold_value += float((sales['Shares'] * sales['Price']).sum())
1528 
1529                except Exception:
1530                    continue
1531 
1532            # Calculate net values
1533            net_shares = total_bought_shares - total_sold_shares
1534            net_value = (total_bought_value - total_sold_value) / 1_000_000  # Millions
1535 
1536            # Apply scoring logic
1537            if net_shares > 100_000 or net_value > 1.0:
1538                score = 0.8  # Strong buying
1539            elif net_shares > 10_000 or net_value > 0.1:
1540                score = 0.4  # Moderate buying
1541            elif net_shares < -100_000 or net_value < -1.0:
1542                score = -0.8  # Strong selling
1543            elif net_shares < -10_000 or net_value < -0.1:
1544                score = -0.4  # Moderate selling
1545            else:
1546                score = 0.0  # Neutral
1547 
1548            return (score, net_shares, net_value)
1549 
1550        except ImportError:
1551            # edgartools not installed
1552            return None
1553        except Exception:
1554            return None
1555 
1556    try:
1557        result = await asyncio.to_thread(_fetch)
1558        return result
1559    except Exception:
1560        return None
1561 
1562 
1563async def get_put_call_ratio(data: StockData) -> tuple[float, float | None, int | None, int | None] | None:
1564    """
1565    Calculate put/call ratio from options chain (contrarian indicator).
1566    Returns: (score, ratio, put_volume, call_volume) or None.
1567    """
1568    def _fetch():
1569        try:
1570            if data.ticker_obj is None:
1571                return None
1572 
1573            # Get options chain for nearest expiration
1574            expirations = data.ticker_obj.options
1575            if not expirations or len(expirations) == 0:
1576                return None
1577 
1578            nearest_exp = expirations[0]
1579            opt_chain = data.ticker_obj.option_chain(nearest_exp)
1580 
1581            # Calculate total put and call volume
1582            put_volume = opt_chain.puts["volume"].sum() if "volume" in opt_chain.puts.columns else 0
1583            call_volume = opt_chain.calls["volume"].sum() if "volume" in opt_chain.calls.columns else 0
1584 
1585            if call_volume == 0 or put_volume == 0:
1586                return None
1587 
1588            ratio = put_volume / call_volume
1589            return (ratio, int(put_volume), int(call_volume))
1590        except Exception:
1591            return None
1592 
1593    try:
1594        result = await asyncio.to_thread(_fetch)
1595        if result is None:
1596            return None
1597 
1598        ratio, put_volume, call_volume = result
1599 
1600        # Contrarian scoring
1601        if ratio > 1.5:
1602            score = 0.3  # Excessive fear = bullish
1603        elif ratio > 1.0:
1604            score = 0.1  # Mild fear
1605        elif ratio > 0.7:
1606            score = -0.1  # Normal
1607        else:
1608            score = -0.3  # Complacency = bearish
1609 
1610        return (score, ratio, put_volume, call_volume)
1611    except Exception:
1612        return None
1613 
1614 
1615async def analyze_sentiment(data: StockData, verbose: bool = False) -> SentimentAnalysis | None:
1616    """
1617    Analyze market sentiment using 5 sub-indicators in parallel.
1618    Requires at least 2 of 5 indicators for valid sentiment.
1619    Returns overall sentiment score (-1.0 to +1.0) with sub-metrics.
1620    """
1621    scores = []
1622    explanations = []
1623    warnings = []
1624 
1625    # Initialize all raw data fields
1626    fear_greed_score = None
1627    fear_greed_value = None
1628    fear_greed_status = None
1629 
1630    short_interest_score = None
1631    short_interest_pct = None
1632    days_to_cover = None
1633 
1634    vix_structure_score = None
1635    vix_structure = None
1636    vix_slope = None
1637 
1638    insider_activity_score = None
1639    insider_net_shares = None
1640    insider_net_value = None
1641 
1642    put_call_score = None
1643    put_call_ratio = None
1644    put_volume = None
1645    call_volume = None
1646 
1647    # Fetch all 5 indicators in parallel with 10s timeout per indicator
1648    try:
1649        results = await asyncio.gather(
1650            asyncio.wait_for(get_fear_greed_index(), timeout=10),
1651            asyncio.wait_for(get_short_interest(data), timeout=10),
1652            asyncio.wait_for(get_vix_term_structure(), timeout=10),
1653            asyncio.wait_for(get_insider_activity(data.ticker, period_days=90), timeout=10),
1654            asyncio.wait_for(get_put_call_ratio(data), timeout=10),
1655            return_exceptions=True  # Don't fail if one indicator fails
1656        )
1657 
1658        # Process Fear & Greed Index
1659        fear_greed_result = results[0]
1660        if isinstance(fear_greed_result, tuple) and fear_greed_result is not None:
1661            fear_greed_score, fear_greed_value, fear_greed_status = fear_greed_result
1662            scores.append(fear_greed_score)
1663            explanations.append(f"{fear_greed_status} ({fear_greed_value})")
1664            if verbose:
1665                print(f"    Fear & Greed: {fear_greed_status} ({fear_greed_value}) → score {fear_greed_score:+.2f}", file=sys.stderr)
1666        elif verbose and isinstance(fear_greed_result, Exception):
1667            print(f"    Fear & Greed: Failed ({fear_greed_result})", file=sys.stderr)
1668 
1669        # Process Short Interest
1670        short_interest_result = results[1]
1671        if isinstance(short_interest_result, tuple) and short_interest_result is not None:
1672            short_interest_score, short_interest_pct, days_to_cover = short_interest_result
1673            scores.append(short_interest_score)
1674            if days_to_cover:
1675                explanations.append(f"Short interest {short_interest_pct:.1f}% (days to cover: {days_to_cover:.1f})")
1676            else:
1677                explanations.append(f"Short interest {short_interest_pct:.1f}%")
1678            warnings.append("Short interest data typically ~2 weeks old (FINRA lag)")
1679            if verbose:
1680                print(f"    Short Interest: {short_interest_pct:.1f}% → score {short_interest_score:+.2f}", file=sys.stderr)
1681        elif verbose and isinstance(short_interest_result, Exception):
1682            print(f"    Short Interest: Failed ({short_interest_result})", file=sys.stderr)
1683 
1684        # Process VIX Term Structure
1685        vix_result = results[2]
1686        if isinstance(vix_result, tuple) and vix_result is not None:
1687            vix_structure_score, vix_structure, vix_slope = vix_result
1688            scores.append(vix_structure_score)
1689            explanations.append(f"VIX {vix_structure}")
1690            if verbose:
1691                print(f"    VIX Structure: {vix_structure} (slope {vix_slope:.1f}%) → score {vix_structure_score:+.2f}", file=sys.stderr)
1692        elif verbose and isinstance(vix_result, Exception):
1693            print(f"    VIX Structure: Failed ({vix_result})", file=sys.stderr)
1694 
1695        # Process Insider Activity
1696        insider_result = results[3]
1697        if isinstance(insider_result, tuple) and insider_result is not None:
1698            insider_activity_score, insider_net_shares, insider_net_value = insider_result
1699            scores.append(insider_activity_score)
1700            if insider_net_value:
1701                explanations.append(f"Insider net: ${insider_net_value:.1f}M")
1702            warnings.append("Insider trades may lag filing by 2-3 days")
1703            if verbose:
1704                print(f"    Insider Activity: Net ${insider_net_value:.1f}M → score {insider_activity_score:+.2f}", file=sys.stderr)
1705        elif verbose and isinstance(insider_result, Exception):
1706            print(f"    Insider Activity: Failed ({insider_result})", file=sys.stderr)
1707 
1708        # Process Put/Call Ratio
1709        put_call_result = results[4]
1710        if isinstance(put_call_result, tuple) and put_call_result is not None:
1711            put_call_score, put_call_ratio, put_volume, call_volume = put_call_result
1712            scores.append(put_call_score)
1713            explanations.append(f"Put/call ratio {put_call_ratio:.2f}")
1714            if verbose:
1715                print(f"    Put/Call Ratio: {put_call_ratio:.2f} → score {put_call_score:+.2f}", file=sys.stderr)
1716        elif verbose and isinstance(put_call_result, Exception):
1717            print(f"    Put/Call Ratio: Failed ({put_call_result})", file=sys.stderr)
1718 
1719    except Exception as e:
1720        if verbose:
1721            print(f"    Sentiment analysis error: {e}", file=sys.stderr)
1722        return None
1723 
1724    # Require at least 2 of 5 indicators for valid sentiment
1725    indicators_available = len(scores)
1726    if indicators_available < 2:
1727        if verbose:
1728            print(f"    Sentiment: Insufficient data ({indicators_available}/5 indicators)", file=sys.stderr)
1729        return None
1730 
1731    # Calculate overall score as simple average
1732    overall_score = sum(scores) / len(scores)
1733    explanation = "; ".join(explanations)
1734 
1735    return SentimentAnalysis(
1736        score=overall_score,
1737        explanation=explanation,
1738        fear_greed_score=fear_greed_score,
1739        short_interest_score=short_interest_score,
1740        vix_structure_score=vix_structure_score,
1741        insider_activity_score=insider_activity_score,
1742        put_call_score=put_call_score,
1743        fear_greed_value=fear_greed_value,
1744        fear_greed_status=fear_greed_status,
1745        short_interest_pct=short_interest_pct,
1746        days_to_cover=days_to_cover,
1747        vix_structure=vix_structure,
1748        vix_slope=vix_slope,
1749        insider_net_shares=insider_net_shares,
1750        insider_net_value=insider_net_value,
1751        put_call_ratio=put_call_ratio,
1752        put_volume=put_volume,
1753        call_volume=call_volume,
1754        indicators_available=indicators_available,
1755        data_freshness_warnings=warnings if warnings else None,
1756    )
1757 
1758 
1759def synthesize_signal(
1760    ticker: str,
1761    company_name: str,
1762    earnings: EarningsSurprise | None,
1763    fundamentals: Fundamentals | None,
1764    analysts: AnalystSentiment | None,
1765    historical: HistoricalPatterns | None,
1766    market_context: MarketContext | None,
1767    sector: SectorComparison | None,
1768    earnings_timing: EarningsTiming | None,
1769    momentum: MomentumAnalysis | None,
1770    sentiment: SentimentAnalysis | None,
1771    breaking_news: list[str] | None = None,  # NEW v4.0.0
1772    geopolitical_risk_warning: str | None = None,  # NEW v4.0.0
1773    geopolitical_risk_penalty: float = 0.0,  # NEW v4.0.0
1774) -> Signal:
1775    """Synthesize all components into a final signal."""
1776 
1777    # Collect available components with weights
1778    components = []
1779    weights = []
1780 
1781    if earnings:
1782        components.append(("earnings", earnings.score))
1783        weights.append(0.30)  # reduced from 0.35
1784 
1785    if fundamentals:
1786        components.append(("fundamentals", fundamentals.score))
1787        weights.append(0.20)  # reduced from 0.25
1788 
1789    if analysts and analysts.score is not None:
1790        components.append(("analysts", analysts.score))
1791        weights.append(0.20)  # reduced from 0.25
1792 
1793    if historical:
1794        components.append(("historical", historical.score))
1795        weights.append(0.10)  # reduced from 0.15
1796 
1797    # NEW COMPONENTS
1798    if market_context:
1799        components.append(("market", market_context.score))
1800        weights.append(0.10)
1801 
1802    if sector:
1803        components.append(("sector", sector.score))
1804        weights.append(0.15)
1805 
1806    if momentum:
1807        components.append(("momentum", momentum.score))
1808        weights.append(0.15)
1809 
1810    if sentiment:
1811        components.append(("sentiment", sentiment.score))
1812        weights.append(0.10)
1813 
1814    # Require at least 2 components
1815    if len(components) < 2:
1816        return Signal(
1817            ticker=ticker,
1818            company_name=company_name,
1819            recommendation="HOLD",
1820            confidence=0.0,
1821            final_score=0.0,
1822            supporting_points=["Insufficient data for analysis"],
1823            caveats=["Limited data available"],
1824            timestamp=datetime.now().isoformat(),
1825            components={},
1826        )
1827 
1828    # Normalize weights
1829    total_weight = sum(weights)
1830    normalized_weights = [w / total_weight for w in weights]
1831 
1832    # Calculate weighted score
1833    final_score = sum(score * weight for (_, score), weight in zip(components, normalized_weights))
1834 
1835    # Determine recommendation
1836    if final_score > 0.33:
1837        recommendation = "BUY"
1838    elif final_score < -0.33:
1839        recommendation = "SELL"
1840    else:
1841        recommendation = "HOLD"
1842 
1843    confidence = abs(final_score)
1844 
1845    # Apply earnings timing adjustments and overrides
1846    if earnings_timing:
1847        confidence *= (1.0 + earnings_timing.confidence_adjustment)
1848 
1849        # Override recommendation if needed
1850        if earnings_timing.timing_flag == "pre_earnings":
1851            if recommendation == "BUY":
1852                recommendation = "HOLD"
1853 
1854        elif earnings_timing.timing_flag == "post_earnings":
1855            if earnings_timing.price_change_5d and earnings_timing.price_change_5d > 15:
1856                if recommendation == "BUY":
1857                    recommendation = "HOLD"
1858 
1859    # Check overbought + near 52w high
1860    if momentum and momentum.rsi_14d and momentum.rsi_14d > 70 and momentum.near_52w_high:
1861        if recommendation == "BUY":
1862            recommendation = "HOLD"
1863            confidence *= 0.7
1864 
1865    # NEW v4.0.0: Risk-off confidence penalty
1866    if market_context and market_context.risk_off_detected:
1867        if recommendation == "BUY":
1868            confidence *= 0.7  # Reduce BUY confidence by 30%
1869 
1870    # NEW v4.0.0: Geopolitical sector risk penalty
1871    if geopolitical_risk_penalty > 0:
1872        if recommendation == "BUY":
1873            confidence *= (1.0 - geopolitical_risk_penalty)  # Apply penalty
1874 
1875    # Generate supporting points
1876    supporting_points = []
1877 
1878    if earnings and earnings.actual_eps is not None:
1879        supporting_points.append(
1880            f"{earnings.explanation} - EPS ${earnings.actual_eps:.2f} vs ${earnings.expected_eps:.2f} expected"
1881        )
1882 
1883    if fundamentals and fundamentals.explanation:
1884        supporting_points.append(fundamentals.explanation)
1885 
1886    if analysts and analysts.summary:
1887        supporting_points.append(f"Analyst consensus: {analysts.summary}")
1888 
1889    if historical and historical.pattern_desc:
1890        supporting_points.append(f"Historical pattern: {historical.pattern_desc}")
1891 
1892    if market_context and market_context.explanation:
1893        supporting_points.append(f"Market: {market_context.explanation}")
1894 
1895    if sector and sector.explanation:
1896        supporting_points.append(f"Sector: {sector.explanation}")
1897 
1898    if momentum and momentum.explanation:
1899        supporting_points.append(f"Momentum: {momentum.explanation}")
1900 
1901    if sentiment and sentiment.explanation:
1902        supporting_points.append(f"Sentiment: {sentiment.explanation}")
1903 
1904    # Generate caveats
1905    caveats = []
1906 
1907    # Add earnings timing caveats first (most important)
1908    if earnings_timing and earnings_timing.caveats:
1909        caveats.extend(earnings_timing.caveats)
1910 
1911    # Add sentiment warnings
1912    if sentiment and sentiment.data_freshness_warnings:
1913        caveats.extend(sentiment.data_freshness_warnings)
1914 
1915    # Add momentum warnings
1916    if momentum and momentum.rsi_14d:
1917        if momentum.rsi_14d > 70 and momentum.near_52w_high:
1918            caveats.append("Overbought conditions - high risk entry")
1919 
1920    # Add sector warnings
1921    if sector and sector.score < -0.2:
1922        caveats.append(f"Sector {sector.sector_name} is weak despite stock fundamentals")
1923 
1924    # Add market warnings
1925    if market_context and market_context.vix_status == "fear":
1926        caveats.append(f"High market volatility (VIX {market_context.vix_level:.0f})")
1927 
1928    # NEW v4.0.0: Risk-off warnings
1929    if market_context and market_context.risk_off_detected:
1930        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}%)")
1931 
1932    # NEW v4.0.0: Breaking news alerts
1933    if breaking_news:
1934        for alert in breaking_news[:2]:  # Limit to 2 alerts to avoid overwhelming
1935            caveats.append(f"⚠️ BREAKING NEWS: {alert}")
1936 
1937    # NEW v4.0.0: Geopolitical sector risk warnings
1938    if geopolitical_risk_warning:
1939        caveats.append(geopolitical_risk_warning)
1940 
1941    # Original caveats
1942    if not analysts or analysts.score is None:
1943        caveats.append("Limited or no analyst coverage")
1944 
1945    if not earnings:
1946        caveats.append("No recent earnings data available")
1947 
1948    if len(components) < 4:
1949        caveats.append("Analysis based on limited data components")
1950 
1951    if not caveats:
1952        caveats.append("Market conditions can change rapidly")
1953 
1954    # Limit to 5 caveats
1955    caveats = caveats[:5]
1956 
1957    # Build components dict for output
1958    components_dict = {}
1959    if earnings:
1960        components_dict["earnings_surprise"] = {
1961            "score": earnings.score,
1962            "actual_eps": earnings.actual_eps,
1963            "expected_eps": earnings.expected_eps,
1964            "surprise_pct": earnings.surprise_pct,
1965            "explanation": earnings.explanation,
1966        }
1967 
1968    if fundamentals:
1969        components_dict["fundamentals"] = {
1970            "score": fundamentals.score,
1971            **fundamentals.key_metrics,
1972        }
1973 
1974    if analysts:
1975        components_dict["analyst_sentiment"] = {
1976            "score": analysts.score,
1977            "consensus_rating": analysts.consensus_rating,
1978            "price_target": analysts.price_target,
1979            "current_price": analysts.current_price,
1980            "upside_pct": analysts.upside_pct,
1981            "num_analysts": analysts.num_analysts,
1982        }
1983 
1984    if historical:
1985        components_dict["historical_patterns"] = {
1986            "score": historical.score,
1987            "beats_last_4q": historical.beats_last_4q,
1988            "avg_reaction_pct": historical.avg_reaction_pct,
1989        }
1990 
1991    if market_context:
1992        components_dict["market_context"] = {
1993            "score": market_context.score,
1994            "vix_level": market_context.vix_level,
1995            "vix_status": market_context.vix_status,
1996            "spy_trend_10d": market_context.spy_trend_10d,
1997            "qqq_trend_10d": market_context.qqq_trend_10d,
1998            "market_regime": market_context.market_regime,
1999            "gld_change_5d": market_context.gld_change_5d,
2000            "tlt_change_5d": market_context.tlt_change_5d,
2001            "uup_change_5d": market_context.uup_change_5d,
2002            "risk_off_detected": market_context.risk_off_detected,
2003        }
2004 
2005    if sector:
2006        components_dict["sector_performance"] = {
2007            "score": sector.score,
2008            "sector_name": sector.sector_name,
2009            "stock_return_1m": sector.stock_return_1m,
2010            "sector_return_1m": sector.sector_return_1m,
2011            "relative_strength": sector.relative_strength,
2012            "sector_trend": sector.sector_trend,
2013        }
2014 
2015    if earnings_timing:
2016        components_dict["earnings_timing"] = {
2017            "days_until_earnings": earnings_timing.days_until_earnings,
2018            "days_since_earnings": earnings_timing.days_since_earnings,
2019            "timing_flag": earnings_timing.timing_flag,
2020            "price_change_5d": earnings_timing.price_change_5d,
2021            "confidence_adjustment": earnings_timing.confidence_adjustment,
2022        }
2023 
2024    if momentum:
2025        components_dict["momentum"] = {
2026            "score": momentum.score,
2027            "rsi_14d": momentum.rsi_14d,
2028            "rsi_status": momentum.rsi_status,
2029            "near_52w_high": momentum.near_52w_high,
2030            "near_52w_low": momentum.near_52w_low,
2031            "volume_ratio": momentum.volume_ratio,
2032        }
2033 
2034    if sentiment:
2035        components_dict["sentiment_analysis"] = {
2036            "score": sentiment.score,
2037            "indicators_available": sentiment.indicators_available,
2038            "fear_greed_value": sentiment.fear_greed_value,
2039            "fear_greed_status": sentiment.fear_greed_status,
2040            "short_interest_pct": sentiment.short_interest_pct,
2041            "days_to_cover": sentiment.days_to_cover,
2042            "vix_structure": sentiment.vix_structure,
2043            "vix_slope": sentiment.vix_slope,
2044            "insider_net_value": sentiment.insider_net_value,
2045            "put_call_ratio": sentiment.put_call_ratio,
2046            "data_freshness_warnings": sentiment.data_freshness_warnings,
2047        }
2048 
2049    return Signal(
2050        ticker=ticker,
2051        company_name=company_name,
2052        recommendation=recommendation,
2053        confidence=confidence,
2054        final_score=final_score,
2055        supporting_points=supporting_points[:5],  # Limit to 5
2056        caveats=caveats,  # Already limited to 5 earlier
2057        timestamp=datetime.now().isoformat(),
2058        components=components_dict,
2059    )
2060 
2061 
2062def format_output_text(signal: Signal) -> str:
2063    """Format signal as text output."""
2064    lines = [
2065        "=" * 77,
2066        f"STOCK ANALYSIS: {signal.ticker} ({signal.company_name})",
2067        f"Generated: {signal.timestamp}",
2068        "=" * 77,
2069        "",
2070        f"RECOMMENDATION: {signal.recommendation} (Confidence: {signal.confidence*100:.0f}%)",
2071        "",
2072        "SUPPORTING POINTS:",
2073    ]
2074 
2075    for point in signal.supporting_points:
2076        lines.append(f"• {point}")
2077 
2078    lines.extend([
2079        "",
2080        "CAVEATS:",
2081    ])
2082 
2083    for caveat in signal.caveats:
2084        lines.append(f"• {caveat}")
2085 
2086    lines.extend([
2087        "",
2088        "=" * 77,
2089        "DISCLAIMER: This analysis is for informational purposes only and does NOT",
2090        "constitute financial advice. Consult a licensed financial advisor before",
2091        "making investment decisions. Data provided by Yahoo Finance.",
2092        "=" * 77,
2093    ])
2094 
2095    return "\n".join(lines)
2096 
2097 
2098def format_output_json(signal: Signal) -> str:
2099    """Format signal as JSON output."""
2100    output = {
2101        **asdict(signal),
2102        "disclaimer": "NOT FINANCIAL ADVICE. For informational purposes only.",
2103    }
2104    return json.dumps(output, indent=2)
2105 
2106 
2107def main():
2108    parser = argparse.ArgumentParser(
2109        description="Analyze stocks using Yahoo Finance data"
2110    )
2111    parser.add_argument(
2112        "tickers",
2113        nargs="*",
2114        help="Stock/crypto ticker(s) to analyze"
2115    )
2116    parser.add_argument(
2117        "--output",
2118        choices=["text", "json"],
2119        default="text",
2120        help="Output format (default: text)"
2121    )
2122    parser.add_argument(
2123        "--verbose",
2124        action="store_true",
2125        help="Verbose output to stderr"
2126    )
2127    parser.add_argument(
2128        "--portfolio", "-p",
2129        type=str,
2130        help="Analyze all assets in a portfolio"
2131    )
2132    parser.add_argument(
2133        "--period",
2134        choices=["daily", "weekly", "monthly", "quarterly", "yearly"],
2135        help="Period for portfolio performance analysis"
2136    )
2137 
2138    args = parser.parse_args()
2139 
2140    # Handle portfolio mode
2141    portfolio_assets = []
2142    portfolio_name = None
2143    if args.portfolio:
2144        try:
2145            from portfolio import PortfolioStore
2146            store = PortfolioStore()
2147            portfolio = store.get_portfolio(args.portfolio)
2148            if not portfolio:
2149                # Try to find default portfolio if name not found
2150                default_name = store.get_default_portfolio_name()
2151                if default_name and args.portfolio.lower() == "default":
2152                    portfolio = store.get_portfolio(default_name)
2153                    portfolio_name = default_name
2154                else:
2155                    print(f"Error: Portfolio '{args.portfolio}' not found", file=sys.stderr)
2156                    sys.exit(1)
2157            else:
2158                portfolio_name = portfolio.name
2159 
2160            if not portfolio.assets:
2161                print(f"Portfolio '{portfolio_name}' has no assets", file=sys.stderr)
2162                sys.exit(1)
2163 
2164            portfolio_assets = [(a.ticker, a.quantity, a.cost_basis, a.type) for a in portfolio.assets]
2165            args.tickers = [a.ticker for a in portfolio.assets]
2166 
2167            if args.verbose:
2168                print(f"Analyzing portfolio: {portfolio_name} ({len(portfolio_assets)} assets)", file=sys.stderr)
2169 
2170        except ImportError:
2171            print("Error: portfolio.py not found", file=sys.stderr)
2172            sys.exit(1)
2173        except Exception as e:
2174            print(f"Error loading portfolio: {e}", file=sys.stderr)
2175            sys.exit(1)
2176 
2177    if not args.tickers:
2178        parser.print_help()
2179        sys.exit(1)
2180 
2181    # NEW v4.0.0: Check for breaking news (market-wide, check once before analyzing tickers)
2182    if args.verbose:
2183        print(f"Checking breaking news (last 24h)...", file=sys.stderr)
2184    breaking_news = check_breaking_news(verbose=args.verbose)
2185    if breaking_news and args.verbose:
2186        print(f"  Found {len(breaking_news)} breaking news alert(s)\n", file=sys.stderr)
2187 
2188    results = []
2189 
2190    for ticker in args.tickers:
2191        ticker = ticker.upper()
2192 
2193        if args.verbose:
2194            print(f"\n=== Analyzing {ticker} ===\n", file=sys.stderr)
2195 
2196        # Fetch data
2197        data = fetch_stock_data(ticker, verbose=args.verbose)
2198 
2199        if data is None:
2200            print(f"Error: Invalid ticker '{ticker}' or data unavailable", file=sys.stderr)
2201            sys.exit(2)
2202 
2203        # Get company name
2204        company_name = data.info.get("longName") or data.info.get("shortName") or ticker
2205 
2206        # Detect asset type (crypto vs stock)
2207        is_crypto = data.asset_type == "crypto"
2208 
2209        if args.verbose and is_crypto:
2210            print(f"  Asset type: CRYPTO (using crypto-specific analysis)", file=sys.stderr)
2211 
2212        # Analyze components (different for crypto vs stock)
2213        if is_crypto:
2214            # Crypto: Skip stock-specific analyses
2215            earnings = None
2216            fundamentals = None
2217            analysts = None
2218            historical = None
2219            earnings_timing = None
2220            sector = None
2221 
2222            # Crypto fundamentals (market cap, category, BTC correlation)
2223            if args.verbose:
2224                print(f"Analyzing crypto fundamentals...", file=sys.stderr)
2225            crypto_fundamentals = analyze_crypto_fundamentals(data, verbose=args.verbose)
2226 
2227            # Convert crypto fundamentals to regular Fundamentals for synthesize_signal
2228            if crypto_fundamentals:
2229                fundamentals = Fundamentals(
2230                    score=crypto_fundamentals.score,
2231                    key_metrics={
2232                        "market_cap": crypto_fundamentals.market_cap,
2233                        "market_cap_rank": crypto_fundamentals.market_cap_rank,
2234                        "category": crypto_fundamentals.category,
2235                        "btc_correlation": crypto_fundamentals.btc_correlation,
2236                    },
2237                    explanation=crypto_fundamentals.explanation,
2238                )
2239        else:
2240            # Stock: Full analysis
2241            earnings = analyze_earnings_surprise(data)
2242            fundamentals = analyze_fundamentals(data)
2243            analysts = analyze_analyst_sentiment(data)
2244            historical = analyze_historical_patterns(data)
2245 
2246            # Analyze earnings timing (stocks only)
2247            if args.verbose:
2248                print(f"Checking earnings timing...", file=sys.stderr)
2249            earnings_timing = analyze_earnings_timing(data)
2250 
2251            # Analyze sector performance (stocks only)
2252            if args.verbose:
2253                print(f"Analyzing sector performance...", file=sys.stderr)
2254            sector = analyze_sector_performance(data, verbose=args.verbose)
2255 
2256        # Market context (both crypto and stock)
2257        if args.verbose:
2258            print(f"Analyzing market context...", file=sys.stderr)
2259        market_context = analyze_market_context(verbose=args.verbose)
2260 
2261        # Momentum (both crypto and stock)
2262        if args.verbose:
2263            print(f"Analyzing momentum...", file=sys.stderr)
2264        momentum = analyze_momentum(data)
2265 
2266        # Sentiment (stocks get full sentiment, crypto gets limited)
2267        if args.verbose:
2268            print(f"Analyzing market sentiment...", file=sys.stderr)
2269        if is_crypto:
2270            # Skip insider trading and put/call for crypto
2271            sentiment = None
2272        else:
2273            sentiment = asyncio.run(analyze_sentiment(data, verbose=args.verbose))
2274 
2275        # Geopolitical risks (stocks only)
2276        if is_crypto:
2277            geopolitical_risk_warning = None
2278            geopolitical_risk_penalty = 0.0
2279        else:
2280            sector_name = data.info.get("sector")
2281            geopolitical_risk_warning, geopolitical_risk_penalty = check_sector_geopolitical_risk(
2282                ticker=ticker,
2283                sector=sector_name,
2284                breaking_news=breaking_news,
2285                verbose=args.verbose
2286            )
2287 
2288        if args.verbose:
2289            print(f"Components analyzed:", file=sys.stderr)
2290            if is_crypto:
2291                print(f"  Crypto Fundamentals: {'✓' if fundamentals else '✗'}", file=sys.stderr)
2292                print(f"  Market Context: {'✓' if market_context else '✗'}", file=sys.stderr)
2293                print(f"  Momentum: {'✓' if momentum else '✗'}", file=sys.stderr)
2294                print(f"  (Earnings, Sector, Sentiment: N/A for crypto)\n", file=sys.stderr)
2295            else:
2296                print(f"  Earnings: {'✓' if earnings else '✗'}", file=sys.stderr)
2297                print(f"  Fundamentals: {'✓' if fundamentals else '✗'}", file=sys.stderr)
2298                print(f"  Analysts: {'✓' if analysts and analysts.score else '✗'}", file=sys.stderr)
2299                print(f"  Historical: {'✓' if historical else '✗'}", file=sys.stderr)
2300                print(f"  Market Context: {'✓' if market_context else '✗'}", file=sys.stderr)
2301                print(f"  Sector: {'✓' if sector else '✗'}", file=sys.stderr)
2302                print(f"  Earnings Timing: {'✓' if earnings_timing else '✗'}", file=sys.stderr)
2303                print(f"  Momentum: {'✓' if momentum else '✗'}", file=sys.stderr)
2304                print(f"  Sentiment: {'✓' if sentiment else '✗'}\n", file=sys.stderr)
2305 
2306        # Synthesize signal
2307        signal = synthesize_signal(
2308            ticker=ticker,
2309            company_name=company_name,
2310            earnings=earnings,
2311            fundamentals=fundamentals,
2312            analysts=analysts,
2313            historical=historical,
2314            market_context=market_context,  # NEW
2315            sector=sector,  # NEW
2316            earnings_timing=earnings_timing,  # NEW
2317            momentum=momentum,  # NEW
2318            sentiment=sentiment,  # NEW
2319            breaking_news=breaking_news,  # NEW v4.0.0
2320            geopolitical_risk_warning=geopolitical_risk_warning,  # NEW v4.0.0
2321            geopolitical_risk_penalty=geopolitical_risk_penalty,  # NEW v4.0.0
2322        )
2323 
2324        results.append(signal)
2325 
2326    # Output results
2327    if args.output == "json":
2328        if len(results) == 1:
2329            print(format_output_json(results[0]))
2330        else:
2331            output_data = [asdict(r) for r in results]
2332            # Add portfolio summary if in portfolio mode
2333            if portfolio_assets:
2334                portfolio_summary = generate_portfolio_summary(
2335                    results, portfolio_assets, portfolio_name, args.period
2336                )
2337                output_data = {
2338                    "portfolio": portfolio_name,
2339                    "assets": output_data,
2340                    "summary": portfolio_summary,
2341                }
2342            print(json.dumps(output_data, indent=2))
2343    else:
2344        for i, signal in enumerate(results):
2345            if i > 0:
2346                print("\n")
2347            print(format_output_text(signal))
2348 
2349        # Print portfolio summary if in portfolio mode
2350        if portfolio_assets:
2351            print_portfolio_summary(results, portfolio_assets, portfolio_name, args.period)
2352 
2353 
2354def generate_portfolio_summary(
2355    results: list,
2356    portfolio_assets: list[tuple[str, float, float, str]],
2357    portfolio_name: str,
2358    period: str | None = None,
2359) -> dict:
2360    """Generate portfolio summary data."""
2361    # Map results by ticker
2362    result_map = {r.ticker: r for r in results}
2363 
2364    # Calculate portfolio metrics
2365    total_cost = 0.0
2366    total_value = 0.0
2367    asset_values = []
2368 
2369    for ticker, quantity, cost_basis, asset_type in portfolio_assets:
2370        cost_total = quantity * cost_basis
2371        total_cost += cost_total
2372 
2373        # Get current price from yfinance
2374        try:
2375            stock = yf.Ticker(ticker)
2376            current_price = stock.info.get("regularMarketPrice", 0) or 0
2377            current_value = quantity * current_price
2378            total_value += current_value
2379            asset_values.append((ticker, current_value, cost_total, asset_type))
2380        except Exception:
2381            asset_values.append((ticker, 0, cost_total, asset_type))
2382 
2383    # Calculate period returns if requested
2384    period_return = None
2385    if period and total_value > 0:
2386        period_days = {
2387            "daily": 1,
2388            "weekly": 7,
2389            "monthly": 30,
2390            "quarterly": 90,
2391            "yearly": 365,
2392        }.get(period, 30)
2393 
2394        period_return = calculate_portfolio_period_return(portfolio_assets, period_days)
2395 
2396    # Concentration analysis
2397    concentrations = []
2398    if total_value > 0:
2399        for ticker, value, _, asset_type in asset_values:
2400            if value > 0:
2401                pct = value / total_value * 100
2402                if pct > 30:
2403                    concentrations.append(f"{ticker}: {pct:.1f}%")
2404 
2405    # Build summary
2406    total_pnl = total_value - total_cost
2407    total_pnl_pct = (total_pnl / total_cost * 100) if total_cost > 0 else 0
2408 
2409    summary = {
2410        "portfolio_name": portfolio_name,
2411        "total_cost": total_cost,
2412        "total_value": total_value,
2413        "total_pnl": total_pnl,
2414        "total_pnl_pct": total_pnl_pct,
2415        "asset_count": len(portfolio_assets),
2416        "concentration_warnings": concentrations if concentrations else None,
2417    }
2418 
2419    if period_return is not None:
2420        summary["period"] = period
2421        summary["period_return_pct"] = period_return
2422 
2423    return summary
2424 
2425 
2426def calculate_portfolio_period_return(
2427    portfolio_assets: list[tuple[str, float, float, str]],
2428    period_days: int,
2429) -> float | None:
2430    """Calculate portfolio return over a period using historical prices."""
2431    try:
2432        total_start_value = 0.0
2433        total_current_value = 0.0
2434 
2435        for ticker, quantity, _, _ in portfolio_assets:
2436            stock = yf.Ticker(ticker)
2437            hist = stock.history(period=f"{period_days + 5}d")
2438 
2439            if hist.empty or len(hist) < 2:
2440                continue
2441 
2442            # Get price at period start and now
2443            current_price = hist["Close"].iloc[-1]
2444            start_price = hist["Close"].iloc[0]
2445 
2446            total_current_value += quantity * current_price
2447            total_start_value += quantity * start_price
2448 
2449        if total_start_value > 0:
2450            return (total_current_value - total_start_value) / total_start_value * 100
2451 
2452    except Exception:
2453        pass
2454 
2455    return None
2456 
2457 
2458def print_portfolio_summary(
2459    results: list,
2460    portfolio_assets: list[tuple[str, float, float, str]],
2461    portfolio_name: str,
2462    period: str | None = None,
2463) -> None:
2464    """Print portfolio summary in text format."""
2465    summary = generate_portfolio_summary(results, portfolio_assets, portfolio_name, period)
2466 
2467    print("\n" + "=" * 77)
2468    print(f"PORTFOLIO SUMMARY: {portfolio_name}")
2469    print("=" * 77)
2470 
2471    # Value overview
2472    total_cost = summary["total_cost"]
2473    total_value = summary["total_value"]
2474    total_pnl = summary["total_pnl"]
2475    total_pnl_pct = summary["total_pnl_pct"]
2476 
2477    print(f"\nTotal Cost:    ${total_cost:,.2f}")
2478    print(f"Current Value: ${total_value:,.2f}")
2479    pnl_sign = "+" if total_pnl >= 0 else ""
2480    print(f"Total P&L:     {pnl_sign}${total_pnl:,.2f} ({pnl_sign}{total_pnl_pct:.1f}%)")
2481 
2482    # Period return
2483    if "period_return_pct" in summary:
2484        period_return = summary["period_return_pct"]
2485        period_sign = "+" if period_return >= 0 else ""
2486        print(f"{summary['period'].capitalize()} Return: {period_sign}{period_return:.1f}%")
2487 
2488    # Concentration warnings
2489    if summary.get("concentration_warnings"):
2490        print("\n⚠️ CONCENTRATION WARNINGS:")
2491        for warning in summary["concentration_warnings"]:
2492            print(f"   • {warning} (>30% of portfolio)")
2493 
2494    # Recommendation summary
2495    recommendations = {"BUY": 0, "HOLD": 0, "SELL": 0}
2496    for r in results:
2497        recommendations[r.recommendation] = recommendations.get(r.recommendation, 0) + 1
2498 
2499    print(f"\nRECOMMENDATIONS: {recommendations['BUY']} BUY | {recommendations['HOLD']} HOLD | {recommendations['SELL']} SELL")
2500    print("=" * 77)
2501 
2502 
2503if __name__ == "__main__":
2504    main()
2505