Sentiment Analysis

#!/usr/bin/env python3
"""Keyword-based sentiment analyzer for crypto social media text.

Scores text using curated bullish/bearish word lists without any ML model
or external dependencies. Includes a demo mode with 20 synthetic crypto
social media posts showing sentiment analysis in action.

Usage:
    python scripts/keyword_sentiment.py                # Demo with 20 synthetic posts
    python scripts/keyword_sentiment.py --demo         # Same as above (explicit)
    python scripts/keyword_sentiment.py --text "SOL is going to moon, super bullish"

Dependencies:
    None (stdlib only)
"""

import argparse
import math
import re
import sys
import time
from collections import Counter
from dataclasses import dataclass, field
from typing import Optional


# ── Keyword Dictionaries ───────────────────────────────────────────

BULLISH_KEYWORDS: dict[str, int] = {
    # Strong bullish (weight 3)
    "moonshot": 3, "parabolic": 3, "generational": 3,
    # Moderate bullish (weight 2)
    "moon": 2, "bullish": 2, "breakout": 2, "accumulate": 2,
    "undervalued": 2, "rally": 2, "surge": 2, "soar": 2,
    "adoption": 2, "partnership": 2, "institutional": 2,
    "recovery": 2, "reversal": 2, "pumping": 2,
    # Mild bullish (weight 1)
    "buy": 1, "long": 1, "gem": 1, "rocket": 1, "ath": 1,
    "hodl": 1, "alpha": 1, "dip": 1, "support": 1,
    "bottom": 1, "green": 1, "gains": 1, "profit": 1,
    "lambo": 1, "diamond": 1, "strong": 1, "growth": 1,
    "upgrade": 1, "launch": 1, "listing": 1, "explosive": 1,
    "promising": 1, "opportunity": 1, "underrated": 1,
}

BEARISH_KEYWORDS: dict[str, int] = {
    # Strong bearish (weight 3)
    "scam": 3, "rug": 3, "fraud": 3, "ponzi": 3, "worthless": 3,
    "hack": 3, "exploit": 3, "insolvent": 3, "bankrupt": 3,
    # Moderate bearish (weight 2)
    "dump": 2, "bearish": 2, "crash": 2, "collapse": 2,
    "liquidation": 2, "capitulation": 2, "bagholding": 2,
    "bubble": 2, "warning": 2, "overvalued": 2, "rugpull": 2,
    "dumping": 2,
    # Mild bearish (weight 1)
    "sell": 1, "short": 1, "dead": 1, "rekt": 1, "exit": 1,
    "resistance": 1, "top": 1, "overbought": 1, "red": 1,
    "loss": 1, "falling": 1, "decline": 1, "weak": 1,
    "fear": 1, "risk": 1, "delay": 1, "concern": 1,
}

# Negation words that flip the sentiment of the next keyword
NEGATION_WORDS: set[str] = {
    "not", "no", "never", "dont", "doesn't", "isn't", "wasn't",
    "won't", "can't", "couldn't", "shouldn't", "wouldn't", "neither",
    "hardly", "barely", "without",
}


# ── Data Classes ────────────────────────────────────────────────────


@dataclass
class PostScore:
    """Sentiment score for a single post."""

    text: str
    score: float  # -1.0 to +1.0
    label: str  # "bullish", "bearish", "neutral"
    bullish_words: list[str]
    bearish_words: list[str]
    confidence: float  # 0.0 to 1.0 based on keyword density


@dataclass
class AggregateResult:
    """Aggregated sentiment across multiple posts."""

    total_posts: int
    bullish_count: int
    bearish_count: int
    neutral_count: int
    average_score: float
    median_score: float
    score_std: float
    top_bullish_words: list[tuple[str, int]]
    top_bearish_words: list[tuple[str, int]]
    sentiment_distribution: dict[str, float]


# ── Scoring Functions ───────────────────────────────────────────────


def tokenize(text: str) -> list[str]:
    """Tokenize text into lowercase words, removing punctuation.

    Args:
        text: Raw input text.

    Returns:
        List of lowercase word tokens.
    """
    cleaned = re.sub(r"[^\w\s$#@]", " ", text.lower())
    # Handle cashtags: $SOL -> sol
    cleaned = cleaned.replace("$", "")
    return cleaned.split()


def score_text(
    text: str,
    bullish: Optional[dict[str, int]] = None,
    bearish: Optional[dict[str, int]] = None,
    use_negation: bool = True,
) -> PostScore:
    """Score a text string for crypto sentiment.

    Uses keyword matching with optional negation detection.
    Negation flips the sentiment of the next keyword found.

    Args:
        text: The text to analyze.
        bullish: Bullish keyword dict (word -> weight). Defaults to built-in.
        bearish: Bearish keyword dict (word -> weight). Defaults to built-in.
        use_negation: Whether to apply negation detection.

    Returns:
        PostScore with score, label, matched words, and confidence.
    """
    bull_dict = bullish or BULLISH_KEYWORDS
    bear_dict = bearish or BEARISH_KEYWORDS

    words = tokenize(text)
    bull_score = 0
    bear_score = 0
    bull_words: list[str] = []
    bear_words: list[str] = []

    negated = False
    for word in words:
        if use_negation and word in NEGATION_WORDS:
            negated = True
            continue

        is_bull = word in bull_dict
        is_bear = word in bear_dict

        if is_bull:
            weight = bull_dict[word]
            if negated:
                bear_score += weight
                bear_words.append(f"~{word}")  # ~ prefix = negated
            else:
                bull_score += weight
                bull_words.append(word)
            negated = False
        elif is_bear:
            weight = bear_dict[word]
            if negated:
                bull_score += weight
                bull_words.append(f"~{word}")
            else:
                bear_score += weight
                bear_words.append(word)
            negated = False
        else:
            # Non-keyword resets negation after 1 intervening word
            # (e.g., "not very bullish" should still negate)
            pass

    total_weight = bull_score + bear_score
    if total_weight == 0:
        score = 0.0
        label = "neutral"
        confidence = 0.0
    else:
        score = (bull_score - bear_score) / total_weight
        keyword_density = len(bull_words + bear_words) / max(len(words), 1)
        confidence = min(1.0, keyword_density * 5)  # 20% density = full confidence

        if score > 0.1:
            label = "bullish"
        elif score < -0.1:
            label = "bearish"
        else:
            label = "neutral"

    return PostScore(
        text=text,
        score=round(score, 3),
        label=label,
        bullish_words=bull_words,
        bearish_words=bear_words,
        confidence=round(confidence, 3),
    )


def aggregate_scores(posts: list[PostScore]) -> AggregateResult:
    """Aggregate sentiment scores across multiple posts.

    Args:
        posts: List of PostScore objects.

    Returns:
        AggregateResult with counts, averages, and word frequencies.
    """
    if not posts:
        return AggregateResult(
            total_posts=0, bullish_count=0, bearish_count=0, neutral_count=0,
            average_score=0.0, median_score=0.0, score_std=0.0,
            top_bullish_words=[], top_bearish_words=[],
            sentiment_distribution={},
        )

    scores = [p.score for p in posts]
    bullish_count = sum(1 for p in posts if p.label == "bullish")
    bearish_count = sum(1 for p in posts if p.label == "bearish")
    neutral_count = sum(1 for p in posts if p.label == "neutral")

    avg = sum(scores) / len(scores)
    sorted_scores = sorted(scores)
    n = len(sorted_scores)
    median = (
        sorted_scores[n // 2]
        if n % 2 == 1
        else (sorted_scores[n // 2 - 1] + sorted_scores[n // 2]) / 2.0
    )
    variance = sum((s - avg) ** 2 for s in scores) / len(scores)
    std = math.sqrt(variance)

    # Word frequency
    all_bull: Counter[str] = Counter()
    all_bear: Counter[str] = Counter()
    for p in posts:
        for w in p.bullish_words:
            all_bull[w.lstrip("~")] += 1
        for w in p.bearish_words:
            all_bear[w.lstrip("~")] += 1

    total = len(posts)
    distribution = {
        "bullish": round(bullish_count / total * 100, 1),
        "neutral": round(neutral_count / total * 100, 1),
        "bearish": round(bearish_count / total * 100, 1),
    }

    return AggregateResult(
        total_posts=total,
        bullish_count=bullish_count,
        bearish_count=bearish_count,
        neutral_count=neutral_count,
        average_score=round(avg, 3),
        median_score=round(median, 3),
        score_std=round(std, 3),
        top_bullish_words=all_bull.most_common(10),
        top_bearish_words=all_bear.most_common(10),
        sentiment_distribution=distribution,
    )


# ── Display ─────────────────────────────────────────────────────────


def display_post_score(post: PostScore, index: int) -> None:
    """Display a single post's sentiment analysis.

    Args:
        post: The scored post.
        index: Post number for display.
    """
    indicator = {
        "bullish": "[+]",
        "bearish": "[-]",
        "neutral": "[=]",
    }.get(post.label, "[?]")

    # Truncate text for display
    display_text = post.text if len(post.text) <= 80 else post.text[:77] + "..."

    print(f"\n  {indicator} Post {index}: {display_text}")
    print(f"      Score: {post.score:>+.3f}  |  Label: {post.label}  |  Confidence: {post.confidence:.1%}")
    if post.bullish_words:
        print(f"      Bullish words: {', '.join(post.bullish_words)}")
    if post.bearish_words:
        print(f"      Bearish words: {', '.join(post.bearish_words)}")


def display_aggregate(agg: AggregateResult) -> None:
    """Display aggregated sentiment results.

    Args:
        agg: AggregateResult to display.
    """
    print("\n" + "=" * 60)
    print("  AGGREGATE SENTIMENT ANALYSIS")
    print("=" * 60)

    print(f"\n  Total Posts Analyzed: {agg.total_posts}")
    print(f"\n  --- Distribution ---")

    # Visual bar chart
    bar_width = 40
    for label in ["bullish", "neutral", "bearish"]:
        pct = agg.sentiment_distribution.get(label, 0)
        bar_len = int(pct / 100 * bar_width)
        bar = "#" * bar_len + "." * (bar_width - bar_len)
        count = {"bullish": agg.bullish_count, "neutral": agg.neutral_count,
                 "bearish": agg.bearish_count}[label]
        print(f"  {label:>8}: [{bar}] {pct:5.1f}% ({count})")

    print(f"\n  --- Score Statistics ---")
    print(f"  Average Score:  {agg.average_score:>+.3f}")
    print(f"  Median Score:   {agg.median_score:>+.3f}")
    print(f"  Std Deviation:  {agg.score_std:>.3f}")

    # Overall label
    if agg.average_score > 0.1:
        overall = "BULLISH"
    elif agg.average_score < -0.1:
        overall = "BEARISH"
    else:
        overall = "NEUTRAL"
    print(f"  Overall:        {overall}")

    print(f"\n  --- Top Bullish Words ---")
    if agg.top_bullish_words:
        for word, count in agg.top_bullish_words[:7]:
            print(f"    {word:<20} x{count}")
    else:
        print("    (none)")

    print(f"\n  --- Top Bearish Words ---")
    if agg.top_bearish_words:
        for word, count in agg.top_bearish_words[:7]:
            print(f"    {word:<20} x{count}")
    else:
        print("    (none)")

    print("\n" + "=" * 60)
    print("  NOTE: This is analytical information only, not financial advice.")
    print("=" * 60 + "\n")


# ── Demo Mode ───────────────────────────────────────────────────────

DEMO_POSTS: list[str] = [
    # Bullish posts
    "SOL is going parabolic! This breakout is massive, accumulate before the moon!",
    "$SOL partnership with Visa is bullish af, institutional adoption incoming",
    "Just bought the dip on Solana. This gem is so undervalued right now. Diamond hands hodl!",
    "SOL rally looking strong, support held perfectly. Green candles everywhere",
    "Solana TPS hitting new ATH, this is bullish for the ecosystem growth",
    "Massive gains on my SOL long position, this pump is just getting started",
    "New DeFi launch on Solana looks promising, real opportunity here",
    # Bearish posts
    "Another Solana outage? This chain is dead, total scam. Selling everything.",
    "$SOL is dumping hard, this crash could get worse. Overvalued garbage",
    "Warning: SOL looks like a classic bubble, bearish divergence on the 4h chart",
    "Rugpull on another Solana memecoin, this ecosystem is full of fraud and exploits",
    "Liquidation cascade incoming for SOL longs. Overbought and at resistance.",
    "SOL is weak, declining volume, capitulation hasnt even started yet",
    # Neutral / mixed posts
    "Solana TVL is at 4.2B, interesting to see how it compares to Ethereum",
    "Just deployed my first smart contract on Solana. The developer experience is smooth.",
    "SOL trading at $150, volume is average. Waiting for a clear direction.",
    "Not bullish on SOL short term but long term the technology is solid",
    "Comparing Solana vs Avalanche transaction costs for my research paper",
    "The new Solana phone looks cool but not sure how it affects the token price",
    "Attending Solana Breakpoint conference next week, should be informative",
]


def run_demo() -> None:
    """Run demo mode with 20 synthetic crypto social media posts."""
    print("\n" + "=" * 60)
    print("  KEYWORD SENTIMENT ANALYZER — DEMO MODE")
    print("  Analyzing 20 synthetic crypto social media posts")
    print("=" * 60)

    scored_posts: list[PostScore] = []
    for i, text in enumerate(DEMO_POSTS, 1):
        post_score = score_text(text)
        scored_posts.append(post_score)
        display_post_score(post_score, i)

    agg = aggregate_scores(scored_posts)
    display_aggregate(agg)


# ── Single Text Mode ───────────────────────────────────────────────


def analyze_single(text: str) -> None:
    """Analyze a single text input.

    Args:
        text: The text to analyze.
    """
    print("\n" + "=" * 60)
    print("  KEYWORD SENTIMENT ANALYZER — SINGLE TEXT")
    print("=" * 60)

    result = score_text(text)
    display_post_score(result, 1)

    print("\n" + "=" * 60)
    print("  NOTE: This is analytical information only, not financial advice.")
    print("=" * 60 + "\n")


# ── Main ────────────────────────────────────────────────────────────


def main() -> None:
    """Entry point: parse arguments and run analyzer."""
    parser = argparse.ArgumentParser(
        description="Keyword-based crypto sentiment analyzer"
    )
    parser.add_argument(
        "--text",
        type=str,
        default=None,
        help="Single text to analyze",
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run demo mode with 20 synthetic posts (default if no --text)",
    )
    args = parser.parse_args()

    if args.text:
        analyze_single(args.text)
    else:
        run_demo()


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""Sentiment scanner that fetches live data from free APIs and computes composite scores.

Pulls data from:
- Alternative.me Fear & Greed Index (no auth required)
- CoinGecko community data (no auth required, rate limited)
- Binance funding rates and long/short ratios (no auth required)

Computes a composite sentiment score from -100 (extreme fear) to +100 (extreme greed)
and flags contrarian opportunities.

Usage:
    python scripts/sentiment_scanner.py                     # Live scan for SOL
    python scripts/sentiment_scanner.py --symbol ETH        # Live scan for ETH
    python scripts/sentiment_scanner.py --demo              # Demo with synthetic data

Dependencies:
    uv pip install httpx
"""

import argparse
import math
import sys
import time
from dataclasses import dataclass, field
from typing import Optional

try:
    import httpx
except ImportError:
    print("Missing dependency. Install with: uv pip install httpx")
    sys.exit(1)


# ── Configuration ───────────────────────────────────────────────────

COINGECKO_BASE = "https://api.coingecko.com/api/v3"
FEAR_GREED_URL = "https://api.alternative.me/fng/"
BINANCE_FUTURES_BASE = "https://fapi.binance.com"

# CoinGecko ID mapping for common tokens
COINGECKO_IDS: dict[str, str] = {
    "SOL": "solana",
    "BTC": "bitcoin",
    "ETH": "ethereum",
    "AVAX": "avalanche-2",
    "MATIC": "matic-network",
    "ARB": "arbitrum",
    "OP": "optimism",
    "LINK": "chainlink",
    "DOT": "polkadot",
    "ADA": "cardano",
}

# Binance futures symbol mapping
BINANCE_SYMBOLS: dict[str, str] = {
    "SOL": "SOLUSDT",
    "BTC": "BTCUSDT",
    "ETH": "ETHUSDT",
    "AVAX": "AVAXUSDT",
    "MATIC": "MATICUSDT",
    "ARB": "ARBUSDT",
    "OP": "OPUSDT",
    "LINK": "LINKUSDT",
    "DOT": "DOTUSDT",
    "ADA": "ADAUSDT",
}

DEFAULT_WEIGHTS: dict[str, float] = {
    "social": 0.30,
    "velocity": 0.15,
    "fear_greed": 0.30,
    "funding": 0.25,
}

REQUEST_TIMEOUT = 15.0


# ── Data Classes ────────────────────────────────────────────────────


@dataclass
class FearGreedData:
    """Fear & Greed Index reading."""

    value: int
    classification: str
    timestamp: int


@dataclass
class CommunityData:
    """CoinGecko community statistics."""

    twitter_followers: int = 0
    reddit_subscribers: int = 0
    reddit_active_48h: int = 0
    telegram_members: int = 0
    sentiment_up_pct: float = 50.0
    sentiment_down_pct: float = 50.0
    developer_commits_4w: int = 0


@dataclass
class FundingData:
    """Binance futures funding rate and long/short ratio."""

    funding_rate: float = 0.0
    funding_time: int = 0
    long_short_ratio: float = 1.0
    long_account_pct: float = 0.5
    short_account_pct: float = 0.5


@dataclass
class SentimentResult:
    """Complete sentiment analysis result."""

    symbol: str
    fear_greed: Optional[FearGreedData] = None
    community: Optional[CommunityData] = None
    funding: Optional[FundingData] = None
    social_polarity: float = 0.0
    mention_velocity: float = 1.0
    composite_score: float = 0.0
    contrarian_signals: list[str] = field(default_factory=list)
    errors: list[str] = field(default_factory=list)


# ── API Fetchers ────────────────────────────────────────────────────


def fetch_fear_greed(client: httpx.Client, limit: int = 7) -> Optional[FearGreedData]:
    """Fetch the crypto Fear & Greed Index from alternative.me.

    Args:
        client: HTTP client instance.
        limit: Number of historical days to fetch.

    Returns:
        Most recent FearGreedData or None on failure.
    """
    try:
        resp = client.get(FEAR_GREED_URL, params={"limit": limit})
        resp.raise_for_status()
        data = resp.json()
        latest = data["data"][0]
        return FearGreedData(
            value=int(latest["value"]),
            classification=latest["value_classification"],
            timestamp=int(latest["timestamp"]),
        )
    except (httpx.HTTPError, KeyError, IndexError, ValueError) as exc:
        print(f"  [WARN] Fear & Greed fetch failed: {exc}")
        return None


def fetch_community_data(
    client: httpx.Client, coingecko_id: str
) -> Optional[CommunityData]:
    """Fetch community statistics from CoinGecko.

    Args:
        client: HTTP client instance.
        coingecko_id: CoinGecko coin identifier (e.g., 'solana').

    Returns:
        CommunityData or None on failure.
    """
    try:
        resp = client.get(
            f"{COINGECKO_BASE}/coins/{coingecko_id}",
            params={
                "localization": "false",
                "tickers": "false",
                "market_data": "false",
                "community_data": "true",
                "developer_data": "true",
            },
        )
        resp.raise_for_status()
        data = resp.json()
        cd = data.get("community_data", {})
        dd = data.get("developer_data", {})
        return CommunityData(
            twitter_followers=cd.get("twitter_followers") or 0,
            reddit_subscribers=cd.get("reddit_subscribers") or 0,
            reddit_active_48h=cd.get("reddit_accounts_active_48h") or 0,
            telegram_members=cd.get("telegram_channel_user_count") or 0,
            sentiment_up_pct=data.get("sentiment_votes_up_percentage") or 50.0,
            sentiment_down_pct=data.get("sentiment_votes_down_percentage") or 50.0,
            developer_commits_4w=dd.get("commit_count_4_weeks") or 0,
        )
    except (httpx.HTTPError, KeyError, ValueError) as exc:
        print(f"  [WARN] CoinGecko community fetch failed: {exc}")
        return None


def fetch_funding_data(
    client: httpx.Client, binance_symbol: str
) -> Optional[FundingData]:
    """Fetch funding rate and long/short ratio from Binance Futures.

    Args:
        client: HTTP client instance.
        binance_symbol: Binance futures symbol (e.g., 'SOLUSDT').

    Returns:
        FundingData or None on failure.
    """
    funding_rate = 0.0
    funding_time = 0
    ls_ratio = 1.0
    long_pct = 0.5
    short_pct = 0.5

    # Fetch funding rate
    try:
        resp = client.get(
            f"{BINANCE_FUTURES_BASE}/fapi/v1/fundingRate",
            params={"symbol": binance_symbol, "limit": 1},
        )
        resp.raise_for_status()
        data = resp.json()
        if data:
            funding_rate = float(data[-1]["fundingRate"])
            funding_time = int(data[-1]["fundingTime"])
    except (httpx.HTTPError, KeyError, IndexError, ValueError) as exc:
        print(f"  [WARN] Funding rate fetch failed: {exc}")

    # Fetch long/short ratio
    try:
        resp = client.get(
            f"{BINANCE_FUTURES_BASE}/futures/data/globalLongShortAccountRatio",
            params={"symbol": binance_symbol, "period": "1h", "limit": 1},
        )
        resp.raise_for_status()
        data = resp.json()
        if data:
            ls_ratio = float(data[-1]["longShortRatio"])
            long_pct = float(data[-1]["longAccount"])
            short_pct = float(data[-1]["shortAccount"])
    except (httpx.HTTPError, KeyError, IndexError, ValueError) as exc:
        print(f"  [WARN] Long/short ratio fetch failed: {exc}")

    return FundingData(
        funding_rate=funding_rate,
        funding_time=funding_time,
        long_short_ratio=ls_ratio,
        long_account_pct=long_pct,
        short_account_pct=short_pct,
    )


# ── Scoring Functions ───────────────────────────────────────────────


def compute_social_polarity(community: Optional[CommunityData]) -> float:
    """Derive social polarity from CoinGecko sentiment votes.

    Args:
        community: CommunityData with sentiment percentages.

    Returns:
        Polarity from -1.0 (bearish) to +1.0 (bullish).
    """
    if community is None:
        return 0.0
    up = community.sentiment_up_pct
    down = community.sentiment_down_pct
    total = up + down
    if total == 0:
        return 0.0
    return (up - down) / total


def estimate_mention_velocity(community: Optional[CommunityData]) -> float:
    """Estimate mention velocity from Reddit active users.

    Uses reddit_active_48h relative to subscriber count as a proxy.
    Normal engagement is ~0.5-2% of subscribers active.

    Args:
        community: CommunityData with Reddit stats.

    Returns:
        Velocity estimate (1.0 = normal, >3.0 = elevated).
    """
    if community is None or community.reddit_subscribers == 0:
        return 1.0
    active_ratio = community.reddit_active_48h / community.reddit_subscribers
    # Baseline: 1% of subscribers active in 48h is normal
    baseline_ratio = 0.01
    if baseline_ratio <= 0:
        return 1.0
    return active_ratio / baseline_ratio


def compute_composite_score(
    social_polarity: float,
    mention_velocity: float,
    fear_greed_value: int,
    funding_rate: float,
    weights: Optional[dict[str, float]] = None,
) -> float:
    """Compute weighted composite sentiment score.

    Args:
        social_polarity: Social sentiment from -1.0 to +1.0.
        mention_velocity: Mention rate vs baseline (1.0 = normal).
        fear_greed_value: Fear & Greed Index (0-100).
        funding_rate: Perpetual futures funding rate.
        weights: Custom component weights.

    Returns:
        Composite score from -100.0 (extreme fear) to +100.0 (extreme greed).
    """
    w = weights or DEFAULT_WEIGHTS

    s_social = max(-1.0, min(1.0, social_polarity))
    s_velocity = min(mention_velocity / 10.0, 1.0)
    s_fg = (fear_greed_value - 50) / 50.0
    s_funding = max(-1.0, min(1.0, -10.0 * funding_rate))

    raw = (
        w["social"] * s_social
        + w["velocity"] * s_velocity
        + w["fear_greed"] * s_fg
        + w["funding"] * s_funding
    )
    return round(raw * 100, 1)


def detect_contrarian_signals(result: SentimentResult) -> list[str]:
    """Identify contrarian trading signals from sentiment data.

    Args:
        result: SentimentResult with all computed metrics.

    Returns:
        List of contrarian signal descriptions.
    """
    signals: list[str] = []

    # Extreme composite scores
    if result.composite_score <= -70:
        signals.append(
            f"EXTREME FEAR (composite={result.composite_score:.1f}): "
            "Historically a potential accumulation zone"
        )
    elif result.composite_score >= 70:
        signals.append(
            f"EXTREME GREED (composite={result.composite_score:.1f}): "
            "Historically a potential distribution zone"
        )

    # Funding rate extremes
    if result.funding and result.funding.funding_rate > 0.0005:
        signals.append(
            f"HIGH FUNDING ({result.funding.funding_rate:.4%}): "
            "Longs paying significant premium — crowded long risk"
        )
    elif result.funding and result.funding.funding_rate < -0.0005:
        signals.append(
            f"NEGATIVE FUNDING ({result.funding.funding_rate:.4%}): "
            "Shorts paying premium — potential short squeeze"
        )

    # Long/short ratio extremes
    if result.funding and result.funding.long_short_ratio > 2.0:
        signals.append(
            f"CROWDED LONG (L/S ratio={result.funding.long_short_ratio:.2f}): "
            "Liquidation cascade risk if price drops"
        )
    elif result.funding and result.funding.long_short_ratio < 0.5:
        signals.append(
            f"CROWDED SHORT (L/S ratio={result.funding.long_short_ratio:.2f}): "
            "Short squeeze risk if price rises"
        )

    # High velocity + extreme polarity
    if result.mention_velocity > 5.0 and result.social_polarity > 0.6:
        signals.append(
            f"EUPHORIC SPIKE (velocity={result.mention_velocity:.1f}x, "
            f"polarity={result.social_polarity:.2f}): Potential fade opportunity"
        )
    elif result.mention_velocity > 5.0 and result.social_polarity < -0.6:
        signals.append(
            f"PANIC SPIKE (velocity={result.mention_velocity:.1f}x, "
            f"polarity={result.social_polarity:.2f}): Potential bounce opportunity"
        )

    # Fear & Greed extremes
    if result.fear_greed and result.fear_greed.value <= 10:
        signals.append(
            f"EXTREME FEAR INDEX ({result.fear_greed.value}): "
            "Rare reading — bottom formation historically likely"
        )
    elif result.fear_greed and result.fear_greed.value >= 90:
        signals.append(
            f"EXTREME GREED INDEX ({result.fear_greed.value}): "
            "Rare reading — top formation historically likely"
        )

    return signals


# ── Display ─────────────────────────────────────────────────────────


def classify_score(score: float) -> str:
    """Classify a composite score into a human-readable label.

    Args:
        score: Composite score from -100 to +100.

    Returns:
        Classification string.
    """
    if score <= -70:
        return "Extreme Fear"
    elif score <= -30:
        return "Fear"
    elif score <= 30:
        return "Neutral"
    elif score <= 70:
        return "Greed"
    else:
        return "Extreme Greed"


def display_result(result: SentimentResult) -> None:
    """Print a formatted sentiment analysis report.

    Args:
        result: Complete SentimentResult.
    """
    print("\n" + "=" * 60)
    print(f"  SENTIMENT ANALYSIS: {result.symbol}")
    print("=" * 60)

    # Fear & Greed
    print("\n--- Market Fear & Greed Index ---")
    if result.fear_greed:
        bar_len = result.fear_greed.value // 2
        bar = "#" * bar_len + "." * (50 - bar_len)
        print(f"  Value: {result.fear_greed.value}/100 ({result.fear_greed.classification})")
        print(f"  [{bar}]")
    else:
        print("  Not available")

    # Community Data
    print("\n--- Social / Community Data ---")
    if result.community:
        print(f"  Twitter Followers:   {result.community.twitter_followers:>12,}")
        print(f"  Reddit Subscribers:  {result.community.reddit_subscribers:>12,}")
        print(f"  Reddit Active (48h): {result.community.reddit_active_48h:>12,}")
        print(f"  Telegram Members:    {result.community.telegram_members:>12,}")
        print(f"  Sentiment Up:        {result.community.sentiment_up_pct:>11.1f}%")
        print(f"  Sentiment Down:      {result.community.sentiment_down_pct:>11.1f}%")
        print(f"  Dev Commits (4w):    {result.community.developer_commits_4w:>12,}")
    else:
        print("  Not available")

    # Funding & Positioning
    print("\n--- On-Chain Positioning ---")
    if result.funding:
        print(f"  Funding Rate:      {result.funding.funding_rate:>12.4%}")
        print(f"  Long/Short Ratio:  {result.funding.long_short_ratio:>12.2f}")
        print(f"  Long Accounts:     {result.funding.long_account_pct:>11.1%}")
        print(f"  Short Accounts:    {result.funding.short_account_pct:>11.1%}")
    else:
        print("  Not available")

    # Derived Metrics
    print("\n--- Derived Metrics ---")
    print(f"  Social Polarity:     {result.social_polarity:>+.3f}  (-1 to +1)")
    print(f"  Mention Velocity:    {result.mention_velocity:>.2f}x  (1.0 = normal)")

    # Composite Score
    label = classify_score(result.composite_score)
    print("\n--- Composite Sentiment Score ---")
    score_bar_pos = int((result.composite_score + 100) / 4)
    score_bar_pos = max(0, min(50, score_bar_pos))
    bar = "." * score_bar_pos + "|" + "." * (50 - score_bar_pos)
    print(f"  Score: {result.composite_score:>+6.1f}  ({label})")
    print(f"  -100 [{bar}] +100")

    # Contrarian Signals
    print("\n--- Contrarian Signals ---")
    if result.contrarian_signals:
        for sig in result.contrarian_signals:
            print(f"  >> {sig}")
    else:
        print("  No contrarian signals detected (sentiment in normal range)")

    # Errors
    if result.errors:
        print("\n--- Warnings ---")
        for err in result.errors:
            print(f"  [!] {err}")

    print("\n" + "=" * 60)
    print("  NOTE: This is analytical information only, not financial advice.")
    print("=" * 60 + "\n")


# ── Demo Mode ───────────────────────────────────────────────────────


def run_demo() -> None:
    """Run demo mode with synthetic sentiment data showing a fear/greed cycle.

    Generates 5 synthetic scenarios to illustrate different sentiment regimes.
    """
    print("\n" + "=" * 60)
    print("  SENTIMENT SCANNER — DEMO MODE")
    print("  Synthetic data showing different sentiment regimes")
    print("=" * 60)

    scenarios: list[dict] = [
        {
            "name": "Extreme Fear (Capitulation)",
            "symbol": "SOL",
            "fear_greed": FearGreedData(value=8, classification="Extreme Fear", timestamp=0),
            "community": CommunityData(
                twitter_followers=2_500_000, reddit_subscribers=300_000,
                reddit_active_48h=45_000, telegram_members=100_000,
                sentiment_up_pct=20.0, sentiment_down_pct=80.0,
                developer_commits_4w=150,
            ),
            "funding": FundingData(
                funding_rate=-0.0008, funding_time=0,
                long_short_ratio=0.4, long_account_pct=0.286, short_account_pct=0.714,
            ),
        },
        {
            "name": "Fear (Declining Market)",
            "symbol": "SOL",
            "fear_greed": FearGreedData(value=30, classification="Fear", timestamp=0),
            "community": CommunityData(
                twitter_followers=2_500_000, reddit_subscribers=300_000,
                reddit_active_48h=6_000, telegram_members=100_000,
                sentiment_up_pct=35.0, sentiment_down_pct=65.0,
                developer_commits_4w=160,
            ),
            "funding": FundingData(
                funding_rate=-0.0002, funding_time=0,
                long_short_ratio=0.8, long_account_pct=0.444, short_account_pct=0.556,
            ),
        },
        {
            "name": "Neutral (Consolidation)",
            "symbol": "SOL",
            "fear_greed": FearGreedData(value=50, classification="Neutral", timestamp=0),
            "community": CommunityData(
                twitter_followers=2_500_000, reddit_subscribers=300_000,
                reddit_active_48h=3_000, telegram_members=100_000,
                sentiment_up_pct=52.0, sentiment_down_pct=48.0,
                developer_commits_4w=180,
            ),
            "funding": FundingData(
                funding_rate=0.0001, funding_time=0,
                long_short_ratio=1.1, long_account_pct=0.524, short_account_pct=0.476,
            ),
        },
        {
            "name": "Greed (Bull Market)",
            "symbol": "SOL",
            "fear_greed": FearGreedData(value=72, classification="Greed", timestamp=0),
            "community": CommunityData(
                twitter_followers=2_500_000, reddit_subscribers=300_000,
                reddit_active_48h=15_000, telegram_members=100_000,
                sentiment_up_pct=78.0, sentiment_down_pct=22.0,
                developer_commits_4w=200,
            ),
            "funding": FundingData(
                funding_rate=0.0004, funding_time=0,
                long_short_ratio=1.8, long_account_pct=0.643, short_account_pct=0.357,
            ),
        },
        {
            "name": "Extreme Greed (Euphoria)",
            "symbol": "SOL",
            "fear_greed": FearGreedData(value=92, classification="Extreme Greed", timestamp=0),
            "community": CommunityData(
                twitter_followers=2_500_000, reddit_subscribers=300_000,
                reddit_active_48h=60_000, telegram_members=100_000,
                sentiment_up_pct=92.0, sentiment_down_pct=8.0,
                developer_commits_4w=120,
            ),
            "funding": FundingData(
                funding_rate=0.0012, funding_time=0,
                long_short_ratio=3.5, long_account_pct=0.778, short_account_pct=0.222,
            ),
        },
    ]

    for i, scenario in enumerate(scenarios, 1):
        print(f"\n{'~' * 60}")
        print(f"  Scenario {i}/5: {scenario['name']}")
        print(f"{'~' * 60}")

        result = SentimentResult(symbol=scenario["symbol"])
        result.fear_greed = scenario["fear_greed"]
        result.community = scenario["community"]
        result.funding = scenario["funding"]

        result.social_polarity = compute_social_polarity(result.community)
        result.mention_velocity = estimate_mention_velocity(result.community)

        fg_value = result.fear_greed.value if result.fear_greed else 50
        fr_value = result.funding.funding_rate if result.funding else 0.0

        result.composite_score = compute_composite_score(
            social_polarity=result.social_polarity,
            mention_velocity=result.mention_velocity,
            fear_greed_value=fg_value,
            funding_rate=fr_value,
        )
        result.contrarian_signals = detect_contrarian_signals(result)

        display_result(result)


# ── Live Scanner ────────────────────────────────────────────────────


def run_live_scan(symbol: str) -> SentimentResult:
    """Run a live sentiment scan for the given symbol.

    Fetches data from all free API sources, computes derived metrics,
    and identifies contrarian signals.

    Args:
        symbol: Token symbol (e.g., 'SOL', 'BTC', 'ETH').

    Returns:
        Complete SentimentResult.
    """
    symbol = symbol.upper()
    result = SentimentResult(symbol=symbol)

    coingecko_id = COINGECKO_IDS.get(symbol)
    binance_symbol = BINANCE_SYMBOLS.get(symbol)

    if not coingecko_id:
        result.errors.append(
            f"No CoinGecko mapping for {symbol}. "
            f"Supported: {', '.join(sorted(COINGECKO_IDS.keys()))}"
        )
    if not binance_symbol:
        result.errors.append(
            f"No Binance mapping for {symbol}. "
            f"Supported: {', '.join(sorted(BINANCE_SYMBOLS.keys()))}"
        )

    print(f"\nScanning sentiment for {symbol}...")

    with httpx.Client(timeout=REQUEST_TIMEOUT) as client:
        # Fetch Fear & Greed (market-wide)
        print("  Fetching Fear & Greed Index...")
        result.fear_greed = fetch_fear_greed(client)

        # Fetch community data (token-specific)
        if coingecko_id:
            print(f"  Fetching CoinGecko community data for {coingecko_id}...")
            result.community = fetch_community_data(client, coingecko_id)

        # Fetch funding data (token-specific)
        if binance_symbol:
            print(f"  Fetching Binance futures data for {binance_symbol}...")
            result.funding = fetch_funding_data(client, binance_symbol)

    # Compute derived metrics
    result.social_polarity = compute_social_polarity(result.community)
    result.mention_velocity = estimate_mention_velocity(result.community)

    fg_value = result.fear_greed.value if result.fear_greed else 50
    fr_value = result.funding.funding_rate if result.funding else 0.0

    result.composite_score = compute_composite_score(
        social_polarity=result.social_polarity,
        mention_velocity=result.mention_velocity,
        fear_greed_value=fg_value,
        funding_rate=fr_value,
    )

    result.contrarian_signals = detect_contrarian_signals(result)

    return result


# ── Main ────────────────────────────────────────────────────────────


def main() -> None:
    """Entry point: parse arguments and run scanner."""
    parser = argparse.ArgumentParser(
        description="Crypto sentiment scanner using free APIs"
    )
    parser.add_argument(
        "--symbol",
        type=str,
        default="SOL",
        help="Token symbol to scan (default: SOL)",
    )
    parser.add_argument(
        "--demo",
        action="store_true",
        help="Run demo mode with synthetic data",
    )
    args = parser.parse_args()

    if args.demo:
        run_demo()
    else:
        result = run_live_scan(args.symbol)
        display_result(result)


if __name__ == "__main__":
    main()