Upload alpha_factory/personas/crowd_scout.py with huggingface_hub

alpha_factory/personas/crowd_scout.py

@@ -0,0 +1,99 @@
+"""
+Crowd Scout — Persona 4 (Mediumfish)
+Checks novelty: correlation to library + thematic dedup.
+"""
+from ..infra.llm_client import LLMClient
+from ..schemas import CrowdScoutResult, Verdict
+
+
+SYSTEM_PROMPT = """You are a portfolio manager evaluating whether a new alpha is sufficiently 
+different from the existing library to justify inclusion.
+
+You must assess TWO dimensions:
+1. NUMERICAL: Is the alpha's correlation to existing alphas below 0.65?
+2. THEMATIC: Even if correlation is low, does this alpha exploit the SAME anomaly as existing ones?
+
+An alpha is a THEMATIC DUPLICATE if it:
+- Exploits the same underlying behavioral bias (e.g., two momentum alphas = duplicate even if corr=0.3)
+- Uses the same field family with minor operator changes
+- Is a linear combination of existing alphas
+
+You MUST label the alpha's underlying anomaly from this list:
+PEAD, value, momentum, reversal, low_vol, quality, liquidity, sentiment, analyst, 
+option_surface, social, fundamental, technical, event, other
+
+RULES:
+- If the library already has 3+ alphas with the same anomaly_tag → this alpha is SATURATED → kill
+- If correlation > 0.85 → DUPLICATE → kill
+- If correlation 0.65-0.85 AND same anomaly_tag → DEMOTE (allow with reduced weight)
+- If correlation < 0.65 AND different anomaly_tag → PROMOTE
+"""
+
+
+async def scout_novelty(
+    llm: LLMClient,
+    expression: str,
+    theme: str,
+    anomaly_tag: str,
+    existing_anomaly_tags: list[str],
+    max_corr_to_library: float,
+    model: str | None = None,
+) -> CrowdScoutResult:
+    """
+    Assess whether an alpha is novel enough to include in the library.
+    
+    Combines numerical (correlation) check with LLM thematic assessment.
+    """
+    # Determine saturation
+    tag_count = existing_anomaly_tags.count(anomaly_tag)
+    is_saturated = tag_count >= 3
+
+    # Quick deterministic checks
+    if max_corr_to_library > 0.85:
+        return CrowdScoutResult(
+            max_corr_to_library=max_corr_to_library,
+            is_thematic_duplicate=True,
+            anomaly_already_saturated=is_saturated,
+            verdict=Verdict.KILL,
+            reason=f"Correlation {max_corr_to_library:.2f} > 0.85 threshold — duplicate",
+        )
+
+    if is_saturated and max_corr_to_library > 0.5:
+        return CrowdScoutResult(
+            max_corr_to_library=max_corr_to_library,
+            is_thematic_duplicate=True,
+            anomaly_already_saturated=True,
+            verdict=Verdict.KILL,
+            reason=f"Anomaly '{anomaly_tag}' already has {tag_count} alphas AND corr={max_corr_to_library:.2f}",
+        )
+
+    # For borderline cases (corr 0.4-0.65), use LLM for thematic assessment
+    if max_corr_to_library > 0.4:
+        user_prompt = f"""Assess this alpha's thematic novelty:
+
+Expression: {expression[:200]}...
+Theme: {theme}
+Anomaly tag: {anomaly_tag}
+Max correlation to existing library: {max_corr_to_library:.3f}
+Existing anomaly distribution: {dict(zip(set(existing_anomaly_tags), [existing_anomaly_tags.count(t) for t in set(existing_anomaly_tags)]))}
+
+Is this a THEMATIC DUPLICATE of something already in the library?
+Consider: does it exploit the same behavioral bias, even if numerically different?"""
+
+        result = await llm.generate_json(
+            prompt=user_prompt,
+            schema=CrowdScoutResult,
+            model=model or llm.config.mediumfish_model,
+            temperature=0.3,
+            system_prompt=SYSTEM_PROMPT,
+        )
+        return result
+
+    # Low correlation + not saturated → promote
+    return CrowdScoutResult(
+        max_corr_to_library=max_corr_to_library,
+        is_thematic_duplicate=False,
+        anomaly_already_saturated=is_saturated,
+        verdict=Verdict.PROMOTE,
+        reason=f"Novel: corr={max_corr_to_library:.2f} < 0.65, anomaly '{anomaly_tag}' has {tag_count} existing",
+    )