Upload alpha_factory/deterministic/theme_sampler.py with huggingface_hub

alpha_factory/deterministic/theme_sampler.py

@@ -0,0 +1,111 @@
+"""
+Theme Sampler — deterministic gap analysis.
+Picks under-explored themes from the factor store.
+"""
+import math
+from collections import Counter
+from typing import Optional
+from ..schemas import AnomalyTag
+
+
+# Theme definitions mapped to BRAIN field families
+THEME_FIELDS = {
+    "value_quality": ["book_to_price", "earnings_yield", "roe", "roa", "debt_to_equity", "current_ratio"],
+    "momentum": ["close", "returns", "volume", "ts_returns", "high", "low"],
+    "reversal": ["close", "returns", "volume", "bid_ask_spread"],
+    "volatility": ["volatility", "ivol", "beta", "hv", "atr"],
+    "analyst": ["analyst_rating", "estimate_revision", "target_price", "recommendation"],
+    "sentiment_social": ["sentiment", "social_volume", "social_score", "news_sentiment"],
+    "option_surface": ["iv30", "iv60", "iv90", "iv180", "pcr", "skew", "term_structure"],
+    "earnings_event": ["earnings_surprise", "post_earnings_drift", "guidance"],
+    "liquidity_micro": ["bid_ask_spread", "volume", "turnover", "amihud_illiquidity"],
+    "growth": ["revenue_growth", "earnings_growth", "asset_growth", "sales_growth"],
+    "intraday": ["open", "high", "low", "close", "vwap", "intraday_range"],
+    "fundamental_yield": ["dividend_yield", "buyback_yield", "shareholder_yield", "fcf_yield"],
+}
+
+# Known archetypes from the existing 18-alpha library
+PROVEN_ARCHETYPES = [
+    "value_quality_blend",
+    "intraday_mr_decay",
+    "vol_scaled_shock",
+    "pead_revisions",
+    "skew_term",
+    "social_momentum",
+    "multi_horizon_mr",
+    "fundamental_yield_composite",
+]
+
+
+def compute_gap_scores(
+    existing_themes: list[str],
+    existing_anomaly_tags: list[str],
+    dead_themes: Optional[list[str]] = None,
+) -> list[tuple[str, float]]:
+    """
+    Rank themes by how under-explored they are.
+
+    gap_score = log(field_count) - 2 * log(1 + alphas_in_theme) - dead_penalty
+
+    Higher score = bigger opportunity.
+    """
+    theme_counts = Counter(existing_themes)
+    anomaly_counts = Counter(existing_anomaly_tags)
+    dead_set = set(dead_themes or [])
+
+    scores = []
+    for theme, fields in THEME_FIELDS.items():
+        if theme in dead_set:
+            continue  # Skip dead themes (§11.5)
+
+        field_count = len(fields)
+        alpha_count = theme_counts.get(theme, 0)
+
+        gap = math.log(field_count + 1) - 2 * math.log(1 + alpha_count)
+
+        # Bonus if the anomaly tag is under-represented
+        tag = _theme_to_tag(theme)
+        tag_count = anomaly_counts.get(tag, 0)
+        if tag_count < 2:
+            gap += 0.5  # novelty bonus
+
+        scores.append((theme, gap))
+
+    # Sort descending
+    scores.sort(key=lambda x: -x[1])
+    return scores
+
+
+def pick_theme(
+    existing_themes: list[str],
+    existing_anomaly_tags: list[str],
+    dead_themes: Optional[list[str]] = None,
+    top_k: int = 3,
+) -> str:
+    """Pick the best theme to explore next (highest gap score)."""
+    import random
+    scores = compute_gap_scores(existing_themes, existing_anomaly_tags, dead_themes)
+    # Sample from top-k for diversity
+    top = scores[:top_k]
+    if not top:
+        return random.choice(list(THEME_FIELDS.keys()))
+    return random.choice(top)[0]
+
+
+def _theme_to_tag(theme: str) -> str:
+    """Map theme name to AnomalyTag value."""
+    mapping = {
+        "value_quality": "value",
+        "momentum": "momentum",
+        "reversal": "reversal",
+        "volatility": "low_vol",
+        "analyst": "analyst",
+        "sentiment_social": "sentiment",
+        "option_surface": "option_surface",
+        "earnings_event": "pead",
+        "liquidity_micro": "liquidity",
+        "growth": "fundamental",
+        "intraday": "technical",
+        "fundamental_yield": "fundamental",
+    }
+    return mapping.get(theme, "other")