quantwise 1.2.0 → 1.2.2

package/.claude/skills/theme-detector/scripts/scorer.py

@@ -0,0 +1,87 @@
+"""
+Theme Detector - Scoring, Labeling & Confidence
+
+Combines theme heat and lifecycle maturity into a final theme score dict.
+Follows the pattern from macro-regime-detector/scripts/scorer.py.
+"""
+
+from typing import Dict
+
+
+HEAT_LABELS = {
+    80: "Hot",
+    60: "Warm",
+    40: "Neutral",
+    20: "Cool",
+    0: "Cold",
+}
+
+
+def get_heat_label(heat_score: float) -> str:
+    """Map heat score to label: Hot/Warm/Neutral/Cool/Cold."""
+    if heat_score >= 80:
+        return "Hot"
+    elif heat_score >= 60:
+        return "Warm"
+    elif heat_score >= 40:
+        return "Neutral"
+    elif heat_score >= 20:
+        return "Cool"
+    else:
+        return "Cold"
+
+
+def calculate_confidence(quant_confirmed: bool,
+                         breadth_confirmed: bool,
+                         narrative_confirmed: bool,
+                         stale_data_penalty: bool) -> str:
+    """Determine confidence level from confirmation layers.
+
+    3 layers confirmed => High
+    2 layers confirmed => Medium
+    1 or 0 layers     => Low
+    stale_data_penalty downgrades by 1 level (High->Medium, Medium->Low).
+    """
+    confirmed_count = sum([quant_confirmed, breadth_confirmed, narrative_confirmed])
+
+    if confirmed_count >= 3:
+        level = "High"
+    elif confirmed_count >= 2:
+        level = "Medium"
+    else:
+        level = "Low"
+
+    if stale_data_penalty and level != "Low":
+        level = "Medium" if level == "High" else "Low"
+
+    return level
+
+
+def determine_data_mode(fmp_available: bool, finviz_elite: bool) -> str:
+    """Describe available data sources."""
+    if fmp_available and finviz_elite:
+        return "FINVIZ-Elite+FMP"
+    elif fmp_available and not finviz_elite:
+        return "FMP-only"
+    elif not fmp_available and finviz_elite:
+        return "FINVIZ-Elite"
+    else:
+        return "FINVIZ-Public"
+
+
+def score_theme(theme_heat: float,
+                lifecycle_maturity: float,
+                lifecycle_stage: str,
+                direction: str,
+                confidence: str,
+                data_mode: str) -> Dict:
+    """Combine all dimensions into final theme score dict."""
+    return {
+        "theme_heat": theme_heat,
+        "heat_label": get_heat_label(theme_heat),
+        "lifecycle_maturity": lifecycle_maturity,
+        "lifecycle_stage": lifecycle_stage,
+        "direction": direction,
+        "confidence": confidence,
+        "data_mode": data_mode,
+    }

package/.claude/skills/theme-detector/scripts/tests/README.md

@@ -0,0 +1,21 @@
+# Theme Detector Tests
+
+## Unit Tests (Phase 1)
+- test_industry_ranker.py
+- test_theme_classifier.py
+- test_heat_calculator.py
+- test_lifecycle_calculator.py
+- test_scorer.py
+- test_report_generator.py
+- test_uptrend_client.py
+
+## Unit Tests (Phase 2)
+- test_representative_stock_selector.py (dynamic stock selection, FINVIZ/FMP fallback, circuit breaker)
+
+## Integration Tests
+- test_theme_detector_e2e.py (full pipeline, mocked I/O, no network required)
+
+## Network Integration Tests (Phase 2 TODO)
+- test_finviz_performance_client.py (requires network)
+- test_etf_scanner.py (requires network)
+- test_uptrend_client_integration.py (requires network)

package/.claude/skills/theme-detector/scripts/tests/conftest.py

@@ -0,0 +1,9 @@
+"""Shared fixtures for Theme Detector tests"""
+
+import os
+import sys
+
+# Add scripts directory to path so modules can be imported
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+# Add tests directory to path so helpers can be imported
+sys.path.insert(0, os.path.dirname(__file__))

package/.claude/skills/theme-detector/scripts/tests/test_config_loader.py

@@ -0,0 +1,239 @@
+"""Tests for config_loader module.
+
+Covers YAML loading, validation, ETF catalog extraction, and fallback behavior.
+"""
+
+import os
+import tempfile
+
+import pytest
+
+from config_loader import (
+    load_themes_config,
+    _load_yaml,
+    _validate_config,
+    _extract_etf_catalog,
+    _strip_etf_count,
+    _get_bundled_yaml_path,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _write_yaml(tmpdir, content):
+    path = os.path.join(tmpdir, "themes.yaml")
+    with open(path, "w") as f:
+        f.write(content)
+    return path
+
+
+VALID_YAML = """\
+cross_sector_min_matches: 2
+vertical_min_industries: 3
+cross_sector:
+  - theme_name: "Test Theme"
+    matching_keywords:
+      - Semiconductors
+      - Software - Application
+    proxy_etfs: [SMH, SOXX]
+    static_stocks: [NVDA, AMD]
+    etf_count: 4
+"""
+
+VALID_YAML_NO_ETF_COUNT = """\
+cross_sector_min_matches: 2
+vertical_min_industries: 3
+cross_sector:
+  - theme_name: "No ETF Count"
+    matching_keywords:
+      - Gold
+    proxy_etfs: [GDX]
+    static_stocks: [NEM]
+"""
+
+
+# ---------------------------------------------------------------------------
+# TestLoadYaml
+# ---------------------------------------------------------------------------
+
+class TestLoadYaml:
+
+    def test_loads_valid_yaml(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = _write_yaml(tmpdir, VALID_YAML)
+            config = _load_yaml(path)
+            assert config["cross_sector_min_matches"] == 2
+            assert len(config["cross_sector"]) == 1
+
+    def test_missing_file_raises(self):
+        with pytest.raises(FileNotFoundError):
+            _load_yaml("/nonexistent/path/themes.yaml")
+
+    def test_invalid_yaml_raises(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = _write_yaml(tmpdir, "cross_sector: [{{invalid")
+            with pytest.raises(Exception):
+                _load_yaml(path)
+
+
+# ---------------------------------------------------------------------------
+# TestValidateConfig
+# ---------------------------------------------------------------------------
+
+class TestValidateConfig:
+
+    def test_valid_config_passes(self):
+        config = {
+            "cross_sector_min_matches": 2,
+            "vertical_min_industries": 3,
+            "cross_sector": [
+                {
+                    "theme_name": "Test",
+                    "matching_keywords": ["A"],
+                    "proxy_etfs": [],
+                    "static_stocks": [],
+                },
+            ],
+        }
+        _validate_config(config)  # should not raise
+
+    def test_missing_cross_sector_raises(self):
+        config = {"cross_sector_min_matches": 2}
+        with pytest.raises(ValueError, match="cross_sector"):
+            _validate_config(config)
+
+    def test_missing_theme_name_raises(self):
+        config = {
+            "cross_sector": [
+                {"matching_keywords": ["A"]},
+            ],
+        }
+        with pytest.raises(ValueError, match="theme_name"):
+            _validate_config(config)
+
+    def test_missing_matching_keywords_raises(self):
+        config = {
+            "cross_sector": [
+                {"theme_name": "Test"},
+            ],
+        }
+        with pytest.raises(ValueError, match="matching_keywords"):
+            _validate_config(config)
+
+
+# ---------------------------------------------------------------------------
+# TestExtractEtfCatalog
+# ---------------------------------------------------------------------------
+
+class TestExtractEtfCatalog:
+
+    def test_extracts_etf_counts(self):
+        config = {
+            "cross_sector": [
+                {"theme_name": "A", "etf_count": 5},
+                {"theme_name": "B", "etf_count": 3},
+            ],
+        }
+        catalog = _extract_etf_catalog(config)
+        assert catalog == {"A": 5, "B": 3}
+
+    def test_missing_etf_count_defaults_to_zero(self):
+        config = {
+            "cross_sector": [
+                {"theme_name": "A"},
+            ],
+        }
+        catalog = _extract_etf_catalog(config)
+        assert catalog == {"A": 0}
+
+    def test_empty_config_returns_empty(self):
+        config = {"cross_sector": []}
+        catalog = _extract_etf_catalog(config)
+        assert catalog == {}
+
+
+# ---------------------------------------------------------------------------
+# TestStripEtfCount
+# ---------------------------------------------------------------------------
+
+class TestStripEtfCount:
+
+    def test_removes_etf_count_from_themes(self):
+        config = {
+            "cross_sector": [
+                {"theme_name": "A", "etf_count": 5, "matching_keywords": ["X"]},
+            ],
+        }
+        stripped = _strip_etf_count(config)
+        assert "etf_count" not in stripped["cross_sector"][0]
+        assert stripped["cross_sector"][0]["theme_name"] == "A"
+
+    def test_preserves_other_keys(self):
+        config = {
+            "cross_sector_min_matches": 2,
+            "vertical_min_industries": 3,
+            "cross_sector": [
+                {"theme_name": "A", "etf_count": 5, "matching_keywords": ["X"]},
+            ],
+        }
+        stripped = _strip_etf_count(config)
+        assert stripped["cross_sector_min_matches"] == 2
+        assert stripped["vertical_min_industries"] == 3
+
+
+# ---------------------------------------------------------------------------
+# TestLoadThemesConfig (integration)
+# ---------------------------------------------------------------------------
+
+class TestLoadThemesConfig:
+
+    def test_bundled_yaml_loads_successfully(self):
+        """Default (no path) loads the bundled themes.yaml."""
+        config, catalog = load_themes_config()
+        assert "cross_sector" in config
+        assert len(config["cross_sector"]) == 15
+        assert "AI & Semiconductors" in catalog
+        assert catalog["AI & Semiconductors"] == 8
+
+    def test_custom_yaml_path(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = _write_yaml(tmpdir, VALID_YAML)
+            config, catalog = load_themes_config(yaml_path=path)
+            assert len(config["cross_sector"]) == 1
+            assert config["cross_sector"][0]["theme_name"] == "Test Theme"
+            assert catalog == {"Test Theme": 4}
+
+    def test_explicit_path_missing_raises_error(self):
+        """Explicit path that doesn't exist -> fail-fast (not fallback)."""
+        with pytest.raises(FileNotFoundError):
+            load_themes_config(yaml_path="/nonexistent/themes.yaml")
+
+    def test_explicit_path_invalid_yaml_raises_error(self):
+        """Explicit path with invalid YAML -> fail-fast."""
+        with tempfile.TemporaryDirectory() as tmpdir:
+            path = _write_yaml(tmpdir, "cross_sector: [{{invalid")
+            with pytest.raises(Exception):
+                load_themes_config(yaml_path=path)
+
+    def test_bundled_yaml_fallback_to_inline(self, monkeypatch):
+        """When bundled YAML is broken, falls back to inline config."""
+        def fake_get_path():
+            return "/nonexistent/bundled/themes.yaml"
+        monkeypatch.setattr("config_loader._get_bundled_yaml_path", fake_get_path)
+        config, catalog = load_themes_config()
+        # Should fall back to DEFAULT_THEMES_CONFIG from default_theme_config.py
+        assert "cross_sector" in config
+        assert len(config["cross_sector"]) == 15
+
+    def test_config_has_no_etf_count_after_loading(self):
+        """etf_count should be stripped from the returned config."""
+        config, catalog = load_themes_config()
+        for theme in config["cross_sector"]:
+            assert "etf_count" not in theme
+
+    def test_get_bundled_yaml_path_exists(self):
+        path = _get_bundled_yaml_path()
+        assert os.path.exists(path)
+        assert path.endswith("themes.yaml")