quantwise 1.2.0 → 1.2.2

package/.claude/skills/theme-detector/scripts/calculators/lifecycle_calculator.py

@@ -0,0 +1,172 @@
+"""
+Lifecycle Maturity Calculator (0-100)
+
+Maturity = duration * 0.25
+         + extremity * 0.25
+         + price_extreme * 0.25
+         + valuation * 0.15
+         + etf_proliferation * 0.10
+
+All sub-scores are direction-aware.
+"""
+
+import statistics
+from typing import List, Dict, Optional
+
+
+LIFECYCLE_WEIGHTS = {
+    "duration": 0.25,
+    "extremity": 0.25,
+    "price_extreme": 0.25,
+    "valuation": 0.15,
+    "etf_proliferation": 0.10,
+}
+
+
+def estimate_duration_score(perf_1m: Optional[float],
+                            perf_3m: Optional[float],
+                            perf_6m: Optional[float],
+                            perf_1y: Optional[float],
+                            is_bearish: bool) -> float:
+    """Count horizons where trend is active. Each active = 25 points.
+
+    Bullish: perf > 2%
+    Bearish: perf < -2%
+    None values treated as inactive.
+    """
+    horizons = [perf_1m, perf_3m, perf_6m, perf_1y]
+    count = 0
+    for p in horizons:
+        if p is None:
+            continue
+        if is_bearish and p < -2.0:
+            count += 1
+        elif not is_bearish and p > 2.0:
+            count += 1
+    return float(count * 25)
+
+
+def extremity_clustering_score(stock_metrics: List[Dict],
+                               is_bearish: bool) -> float:
+    """Proportion of stocks at RSI extremes.
+
+    Bullish: count RSI > 70
+    Bearish: count RSI < 30
+    Formula: min(100, pct * 200)
+    Returns 50.0 if empty.
+    """
+    if not stock_metrics:
+        return 50.0
+
+    valid = [s for s in stock_metrics if s.get("rsi") is not None]
+    if not valid:
+        return 50.0
+
+    if is_bearish:
+        extreme_count = sum(1 for s in valid if s["rsi"] < 30)
+    else:
+        extreme_count = sum(1 for s in valid if s["rsi"] > 70)
+
+    pct = extreme_count / len(valid)
+    return min(100.0, pct * 200.0)
+
+
+def price_extreme_saturation_score(stock_metrics: List[Dict],
+                                   is_bearish: bool) -> float:
+    """Proportion of stocks near 52-week extremes.
+
+    Bullish: dist_from_52w_high <= 0.05
+    Bearish: dist_from_52w_low <= 0.05
+    Formula: min(100, pct * 200)
+    Returns 50.0 if empty.
+    """
+    if not stock_metrics:
+        return 50.0
+
+    key = "dist_from_52w_low" if is_bearish else "dist_from_52w_high"
+    valid = [s for s in stock_metrics if s.get(key) is not None]
+    if not valid:
+        return 50.0
+
+    near_count = sum(1 for s in valid if s[key] <= 0.05)
+    pct = near_count / len(valid)
+    return min(100.0, pct * 200.0)
+
+
+def valuation_premium_score(stock_metrics: List[Dict]) -> float:
+    """Score based on median P/E relative to market average (22).
+
+    premium_ratio = median_PE / 22.0
+    Score: min(100, max(0, (premium_ratio - 0.5) * 32))
+    Needs 3+ valid P/E values, else returns 50.0.
+    """
+    valid_pe = [s["pe_ratio"] for s in stock_metrics
+                if s.get("pe_ratio") is not None and s["pe_ratio"] > 0]
+
+    if len(valid_pe) < 3:
+        return 50.0
+
+    median_pe = statistics.median(valid_pe)
+    premium_ratio = median_pe / 22.0
+    return min(100.0, max(0.0, (premium_ratio - 0.5) * 32.0))
+
+
+def etf_proliferation_score(etf_count: int) -> float:
+    """Score based on number of theme-related ETFs.
+
+    0 => 0, 1 => 20, <=3 => 40, <=6 => 60, <=10 => 80, >10 => 100
+    """
+    if etf_count == 0:
+        return 0.0
+    elif etf_count == 1:
+        return 20.0
+    elif etf_count <= 3:
+        return 40.0
+    elif etf_count <= 6:
+        return 60.0
+    elif etf_count <= 10:
+        return 80.0
+    else:
+        return 100.0
+
+
+def classify_stage(maturity: float) -> str:
+    """Classify lifecycle stage from maturity score.
+
+    0-20: Emerging, 20-40: Accelerating, 40-60: Trending,
+    60-80: Mature, 80-100: Exhausting
+    """
+    if maturity < 20:
+        return "Emerging"
+    elif maturity < 40:
+        return "Accelerating"
+    elif maturity < 60:
+        return "Trending"
+    elif maturity < 80:
+        return "Mature"
+    else:
+        return "Exhausting"
+
+
+def calculate_lifecycle_maturity(duration: Optional[float],
+                                 extremity: Optional[float],
+                                 price_extreme: Optional[float],
+                                 valuation: Optional[float],
+                                 etf_prolif: Optional[float]) -> float:
+    """Weighted sum of lifecycle sub-scores, clamped 0-100.
+
+    Any None input defaults to 50.0.
+    """
+    d = duration if duration is not None else 50.0
+    e = extremity if extremity is not None else 50.0
+    p = price_extreme if price_extreme is not None else 50.0
+    v = valuation if valuation is not None else 50.0
+    et = etf_prolif if etf_prolif is not None else 50.0
+
+    raw = (d * LIFECYCLE_WEIGHTS["duration"]
+           + e * LIFECYCLE_WEIGHTS["extremity"]
+           + p * LIFECYCLE_WEIGHTS["price_extreme"]
+           + v * LIFECYCLE_WEIGHTS["valuation"]
+           + et * LIFECYCLE_WEIGHTS["etf_proliferation"])
+
+    return float(min(100.0, max(0.0, raw)))

package/.claude/skills/theme-detector/scripts/calculators/theme_classifier.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Theme Classifier - Detect cross-sector and vertical themes from ranked industries.
+
+Cross-sector themes match industries against keyword templates (min 2 matches).
+Vertical themes detect sector concentration (min 3 same-sector industries in top/bottom).
+
+themes_config format:
+{
+    "cross_sector": [
+        {
+            "theme_name": str,
+            "matching_keywords": [str, ...],
+            "proxy_etfs": [str, ...],
+            "static_stocks": [str, ...],
+        },
+        ...
+    ],
+    "vertical_min_industries": int,   # default 3
+    "cross_sector_min_matches": int,  # default 2
+}
+"""
+
+from collections import Counter
+from typing import Dict, List, Set
+
+
+def classify_themes(
+    ranked_industries: List[Dict],
+    themes_config: Dict,
+    top_n: int = 30,
+) -> List[Dict]:
+    """
+    Match ranked industries to cross-sector and vertical themes.
+
+    Only the top N and bottom N industries (by momentum rank) are considered
+    for theme matching. This prevents themes from always matching when using
+    the full ~145 industry universe.
+
+    Args:
+        ranked_industries: Output of rank_industries (sorted by momentum_score desc).
+        themes_config: Theme definitions with cross_sector templates and thresholds.
+        top_n: Number of top/bottom industries to consider (default 30).
+
+    Returns:
+        List of theme result dicts, each with:
+            theme_name, direction, matching_industries, sector_weights,
+            proxy_etfs, static_stocks
+    """
+    if not ranked_industries:
+        return []
+
+    cross_sector_min = themes_config.get("cross_sector_min_matches", 2)
+    vertical_min = themes_config.get("vertical_min_industries", 3)
+    cross_sector_defs = themes_config.get("cross_sector", [])
+
+    # Build active set from top N + bottom N (deduplicated)
+    top = ranked_industries[:top_n]
+    bottom = ranked_industries[-top_n:] if len(ranked_industries) > top_n else []
+    active_set: Dict[str, Dict] = {ind["name"]: ind for ind in top}
+    for ind in bottom:
+        if ind["name"] not in active_set:
+            active_set[ind["name"]] = ind
+
+    themes = []
+
+    # 1. Cross-sector theme matching (active set only)
+    for theme_def in cross_sector_defs:
+        keywords = theme_def.get("matching_keywords", [])
+        matches = [kw for kw in keywords if kw in active_set]
+
+        if len(matches) >= cross_sector_min:
+            matching_inds = [active_set[m] for m in matches]
+            direction = _majority_direction(matching_inds)
+            sector_weights = get_theme_sector_weights(
+                {"matching_industries": matching_inds}
+            )
+
+            themes.append({
+                "theme_name": theme_def["theme_name"],
+                "direction": direction,
+                "matching_industries": matching_inds,
+                "sector_weights": sector_weights,
+                "proxy_etfs": theme_def.get("proxy_etfs", []),
+                "static_stocks": theme_def.get("static_stocks", []),
+                "theme_origin": "seed",
+                "name_confidence": "high",
+            })
+
+    # 2. Vertical (single-sector) theme detection
+    # Count industries per sector in top N and bottom N separately
+    top_set = set(ind["name"] for ind in top)
+
+    # Top N sector groups
+    top_sector_groups: Dict[str, List[Dict]] = {}
+    for ind in top:
+        sector = ind.get("sector")
+        if sector is None:
+            continue
+        top_sector_groups.setdefault(sector, []).append(ind)
+
+    for sector, inds in top_sector_groups.items():
+        if len(inds) >= vertical_min:
+            direction = _majority_direction(inds)
+            sector_weights = get_theme_sector_weights(
+                {"matching_industries": inds}
+            )
+            themes.append({
+                "theme_name": f"{sector} Sector Concentration",
+                "direction": direction,
+                "matching_industries": inds,
+                "sector_weights": sector_weights,
+                "proxy_etfs": [],
+                "static_stocks": [],
+                "theme_origin": "vertical",
+                "name_confidence": "high",
+            })
+
+    # Bottom N sector groups (excluding industries already in top N)
+    bottom_sector_groups: Dict[str, List[Dict]] = {}
+    for ind in bottom:
+        if ind["name"] in top_set:
+            continue
+        sector = ind.get("sector")
+        if sector is None:
+            continue
+        bottom_sector_groups.setdefault(sector, []).append(ind)
+
+    for sector, inds in bottom_sector_groups.items():
+        if len(inds) >= vertical_min:
+            direction = _majority_direction(inds)
+            sector_weights = get_theme_sector_weights(
+                {"matching_industries": inds}
+            )
+            themes.append({
+                "theme_name": f"{sector} Sector Concentration",
+                "direction": direction,
+                "matching_industries": inds,
+                "sector_weights": sector_weights,
+                "proxy_etfs": [],
+                "static_stocks": [],
+                "theme_origin": "vertical",
+                "name_confidence": "high",
+            })
+
+    return themes
+
+
+def get_matched_industry_names(themes: List[Dict]) -> Set[str]:
+    """Return the set of all matched industry names across classified themes.
+
+    Args:
+        themes: Output of classify_themes().
+
+    Returns:
+        Set of industry name strings.
+    """
+    names: Set[str] = set()
+    for theme in themes:
+        for ind in theme.get("matching_industries", []):
+            name = ind.get("name", "")
+            if name:
+                names.add(name)
+    return names
+
+
+def get_theme_sector_weights(theme: Dict) -> Dict[str, float]:
+    """
+    Calculate sector weight distribution for a theme's matching industries.
+
+    Args:
+        theme: Dict with "matching_industries" key containing industry dicts
+               (each may have a "sector" field).
+
+    Returns:
+        Dict mapping sector name to its proportion (0.0-1.0).
+        Industries without a sector field are excluded.
+    """
+    matching = theme.get("matching_industries", [])
+    sectors = [ind["sector"] for ind in matching if "sector" in ind]
+
+    if not sectors:
+        return {}
+
+    counts = Counter(sectors)
+    total = sum(counts.values())
+
+    return {sector: count / total for sector, count in counts.items()}
+
+
+def _majority_direction(industries: List[Dict]) -> str:
+    """Determine majority direction from a list of industries."""
+    bullish = sum(1 for ind in industries if ind.get("direction") == "bullish")
+    bearish = len(industries) - bullish
+    return "bullish" if bullish > bearish else "bearish"

package/.claude/skills/theme-detector/scripts/calculators/theme_discoverer.py

@@ -0,0 +1,280 @@
+"""Theme Discoverer - Automatic theme detection from unmatched industries.
+
+Finds clusters of unmatched industries with similar performance patterns
+and generates new theme entries compatible with classify_themes() output.
+
+Algorithm:
+1. Extract top_n and bottom_n from ranked_industries, exclude matched names.
+2. Separate into bullish (top) and bearish (bottom) groups.
+3. Sort each group by weighted_return.
+4. Cluster adjacent industries that satisfy BOTH:
+   a. weighted_return gap <= gap_threshold
+   b. perf vector distance <= vector_threshold (normalized Euclidean)
+5. Filter clusters by min_cluster_size.
+6. Exclude clusters that overlap significantly with existing themes.
+7. Auto-name clusters from industry name tokens.
+"""
+
+import math
+from collections import Counter
+from typing import Dict, List, Set, Tuple
+
+from calculators.theme_classifier import get_theme_sector_weights
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_GAP_THRESHOLD_PCT = 3.0
+_VECTOR_THRESHOLD = 0.5
+_MIN_CLUSTER_SIZE = 2
+_OVERLAP_THRESHOLD = 0.5
+
+_STOP_WORDS = {
+    "Services", "Products", "Equipment", "Materials", "General",
+    "Other", "Specialty", "Diversified", "Regulated", "Independent",
+    "&", "-", "and",
+}
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def discover_themes(
+    ranked_industries: List[Dict],
+    matched_names: Set[str],
+    existing_themes: List[Dict],
+    top_n: int = 30,
+    gap_threshold: float = _GAP_THRESHOLD_PCT,
+    vector_threshold: float = _VECTOR_THRESHOLD,
+    min_cluster_size: int = _MIN_CLUSTER_SIZE,
+) -> List[Dict]:
+    """Discover new themes from unmatched industries.
+
+    Args:
+        ranked_industries: Full ranked list (sorted by momentum_score desc).
+        matched_names: Set of industry names already matched by seed/vertical.
+        existing_themes: List of existing theme dicts (for overlap detection).
+        top_n: Number of top/bottom industries to consider.
+        gap_threshold: Max weighted_return gap between adjacent industries.
+        vector_threshold: Max normalized Euclidean distance for perf vectors.
+        min_cluster_size: Minimum industries to form a cluster.
+
+    Returns:
+        List of theme dicts compatible with classify_themes() output,
+        each with theme_origin="discovered" and name_confidence="medium".
+    """
+    bullish, bearish = _get_unmatched_industries(ranked_industries, matched_names, top_n)
+
+    discovered = []
+    for group, direction in [(bullish, "bullish"), (bearish, "bearish")]:
+        clusters = _cluster_by_proximity(group, gap_threshold, vector_threshold)
+        for cluster in clusters:
+            if len(cluster) < min_cluster_size:
+                continue
+            if _is_duplicate_of_existing(cluster, direction, existing_themes):
+                continue
+            name = _auto_name_cluster(cluster)
+            theme = _build_theme_dict(name, cluster)
+            discovered.append(theme)
+
+    return discovered
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+def _get_unmatched_industries(
+    ranked: List[Dict],
+    matched_names: Set[str],
+    top_n: int,
+) -> Tuple[List[Dict], List[Dict]]:
+    """Extract unmatched industries from top N and bottom N.
+
+    Returns:
+        (bullish_unmatched, bearish_unmatched)
+    """
+    top = ranked[:top_n]
+    bottom = ranked[-top_n:] if len(ranked) > top_n else []
+
+    # Deduplicate: industries in both top and bottom only appear in top
+    top_names = {ind["name"] for ind in top}
+
+    bullish = [
+        ind for ind in top
+        if ind["name"] not in matched_names and ind.get("direction") == "bullish"
+    ]
+    bearish = [
+        ind for ind in bottom
+        if ind["name"] not in matched_names
+        and ind["name"] not in top_names
+        and ind.get("direction") == "bearish"
+    ]
+
+    return bullish, bearish
+
+
+def _cluster_by_proximity(
+    industries: List[Dict],
+    gap_threshold: float,
+    vector_threshold: float,
+) -> List[List[Dict]]:
+    """Cluster industries by weighted_return proximity and perf vector distance.
+
+    Industries are sorted by weighted_return. Adjacent pairs are joined into
+    the same cluster if BOTH conditions are met:
+    1. abs(weighted_return difference) <= gap_threshold
+    2. perf_vector_distance <= vector_threshold
+
+    Returns:
+        List of clusters (each cluster is a list of industry dicts).
+        Only clusters with >= 2 members are returned.
+    """
+    if not industries:
+        return []
+
+    sorted_inds = sorted(industries, key=lambda x: x.get("weighted_return", 0), reverse=True)
+    ranges = _compute_ranges(sorted_inds)
+
+    clusters: List[List[Dict]] = [[sorted_inds[0]]]
+
+    for i in range(1, len(sorted_inds)):
+        prev = sorted_inds[i - 1]
+        curr = sorted_inds[i]
+
+        gap = abs(prev.get("weighted_return", 0) - curr.get("weighted_return", 0))
+        vec_dist = _perf_vector_distance(prev, curr, ranges)
+
+        if gap <= gap_threshold and vec_dist <= vector_threshold:
+            clusters[-1].append(curr)
+        else:
+            clusters.append([curr])
+
+    # Filter to min size 2
+    return [c for c in clusters if len(c) >= 2]
+
+
+def _perf_vector_distance(a: Dict, b: Dict, ranges: Dict) -> float:
+    """Normalized Euclidean distance between perf vectors (1W, 1M, 3M).
+
+    Each timeframe difference is normalized by the range (max - min) across
+    all industries in the group. If range is 0, that dimension is ignored.
+
+    Returns:
+        0.0 (identical) to ~1.7 (maximally different across all 3 dimensions).
+    """
+    keys = ["perf_1w", "perf_1m", "perf_3m"]
+    total = 0.0
+
+    for key in keys:
+        r = ranges.get(key, 0)
+        if r == 0:
+            continue
+        diff = (a.get(key, 0) - b.get(key, 0)) / r
+        total += diff * diff
+
+    return math.sqrt(total)
+
+
+def _compute_ranges(industries: List[Dict]) -> Dict[str, float]:
+    """Compute value ranges for perf normalization."""
+    keys = ["perf_1w", "perf_1m", "perf_3m"]
+    ranges = {}
+    for key in keys:
+        vals = [ind.get(key, 0) for ind in industries]
+        if vals:
+            ranges[key] = max(vals) - min(vals)
+        else:
+            ranges[key] = 0
+    return ranges
+
+
+def _auto_name_cluster(industries: List[Dict]) -> str:
+    """Generate a descriptive name for a cluster from industry name tokens.
+
+    Tokenizes all industry names, removes stop words, picks the top 2
+    most frequent tokens and joins them.
+    """
+    tokens: List[str] = []
+    for ind in industries:
+        name = ind.get("name", "")
+        for token in name.split():
+            cleaned = token.strip("(),")
+            if cleaned and cleaned not in _STOP_WORDS:
+                tokens.append(cleaned)
+
+    if not tokens:
+        return "Unknown Cluster"
+
+    counts = Counter(tokens)
+    top = counts.most_common(3)
+
+    if len(top) >= 2:
+        return f"{top[0][0]} & {top[1][0]} Related"
+    elif len(top) == 1:
+        return f"{top[0][0]} Related"
+    return "Unknown Cluster"
+
+
+def _is_duplicate_of_existing(
+    cluster_industries: List[Dict],
+    cluster_direction: str,
+    existing_themes: List[Dict],
+    overlap_threshold: float = _OVERLAP_THRESHOLD,
+) -> bool:
+    """Check if a discovered cluster duplicates an existing theme.
+
+    A cluster is considered duplicate if:
+    1. Direction matches an existing theme, AND
+    2. Jaccard similarity >= threshold OR overlap coefficient >= threshold.
+
+    The overlap coefficient (intersection / min(|A|, |B|)) catches cases
+    where a small cluster is a subset of a large existing theme, which
+    Jaccard alone would miss because the union denominator dilutes the ratio.
+    """
+    cluster_names = {ind.get("name", "") for ind in cluster_industries}
+    if not cluster_names:
+        return False
+
+    for theme in existing_themes:
+        if theme.get("direction") != cluster_direction:
+            continue
+        theme_names = {ind.get("name", "") for ind in theme.get("matching_industries", [])}
+        if not theme_names:
+            continue
+        intersection = cluster_names & theme_names
+        union = cluster_names | theme_names
+        jaccard = len(intersection) / len(union) if union else 0
+        min_size = min(len(cluster_names), len(theme_names))
+        overlap_coeff = len(intersection) / min_size if min_size else 0
+        if jaccard >= overlap_threshold or overlap_coeff >= overlap_threshold:
+            return True
+
+    return False
+
+
+def _build_theme_dict(name: str, industries: List[Dict]) -> Dict:
+    """Build a theme dict compatible with classify_themes() output.
+
+    Discovered themes have proxy_etfs=[], static_stocks=[],
+    theme_origin="discovered", name_confidence="medium".
+    """
+    # Determine direction from majority
+    bullish = sum(1 for ind in industries if ind.get("direction") == "bullish")
+    bearish = len(industries) - bullish
+    direction = "bullish" if bullish > bearish else "bearish"
+
+    sector_weights = get_theme_sector_weights({"matching_industries": industries})
+
+    return {
+        "theme_name": name,
+        "direction": direction,
+        "matching_industries": industries,
+        "sector_weights": sector_weights,
+        "proxy_etfs": [],
+        "static_stocks": [],
+        "theme_origin": "discovered",
+        "name_confidence": "medium",
+    }