quantwise 1.2.0 → 1.2.2

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

@@ -0,0 +1,142 @@
+"""Theme configuration loader with YAML support and inline fallback.
+
+Loads cross-sector theme definitions from:
+1. User-specified YAML file (--themes-config)
+2. Bundled themes.yaml (same directory as this module)
+3. Inline DEFAULT_THEMES_CONFIG (fallback when YAML is unavailable)
+
+Error handling:
+- Explicit yaml_path: fail-fast on any error (FileNotFoundError, yaml.YAMLError)
+- No yaml_path: bundled YAML -> inline fallback (safe degradation)
+"""
+
+import copy
+import os
+import sys
+from typing import Dict, Optional, Tuple
+
+# Build tuple of catchable YAML errors (yaml may not be installed)
+_YAML_ERRORS: tuple = ()
+try:
+    import yaml
+    _YAML_ERRORS = (yaml.YAMLError,)
+except ImportError:
+    pass
+
+
+def load_themes_config(
+    yaml_path: Optional[str] = None,
+) -> Tuple[Dict, Dict[str, int]]:
+    """Load themes config and ETF catalog.
+
+    Args:
+        yaml_path: Path to custom themes YAML. If None, tries bundled then inline.
+
+    Returns:
+        (themes_config, etf_catalog) where themes_config has etf_count stripped.
+
+    Raises:
+        FileNotFoundError: If explicit yaml_path doesn't exist.
+        yaml.YAMLError: If explicit yaml_path contains invalid YAML.
+        ValueError: If config fails validation.
+    """
+    if yaml_path is not None:
+        # Explicit path -> fail-fast
+        raw = _load_yaml(yaml_path)
+        _validate_config(raw)
+        catalog = _extract_etf_catalog(raw)
+        config = _strip_etf_count(raw)
+        return config, catalog
+
+    # No path specified -> try bundled YAML, then inline fallback
+    try:
+        bundled = _get_bundled_yaml_path()
+        raw = _load_yaml(bundled)
+        _validate_config(raw)
+        catalog = _extract_etf_catalog(raw)
+        config = _strip_etf_count(raw)
+        return config, catalog
+    except (FileNotFoundError, ValueError, RuntimeError, ImportError, *_YAML_ERRORS) as exc:
+        print(f"WARNING: YAML load failed ({exc}), using inline config",
+              file=sys.stderr)
+        from default_theme_config import DEFAULT_THEMES_CONFIG, ETF_CATALOG
+        return copy.deepcopy(DEFAULT_THEMES_CONFIG), dict(ETF_CATALOG)
+
+
+def _load_yaml(path: str) -> Dict:
+    """Load and parse a YAML file.
+
+    Raises:
+        FileNotFoundError: If file doesn't exist.
+        RuntimeError: If PyYAML is not installed.
+        yaml.YAMLError: If YAML is malformed.
+    """
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"YAML config not found: {path}")
+
+    try:
+        import yaml
+    except ImportError:
+        raise RuntimeError(
+            "PyYAML is required but not installed. "
+            "Install with: pip install pyyaml>=6.0"
+        )
+
+    with open(path) as f:
+        return yaml.safe_load(f)
+
+
+def _validate_config(config: Dict) -> None:
+    """Validate required keys in themes config.
+
+    Raises:
+        ValueError: If required keys are missing.
+    """
+    if not isinstance(config, dict):
+        raise ValueError("Config must be a dict")
+
+    if "cross_sector" not in config:
+        raise ValueError("Config missing required key: cross_sector")
+
+    for i, theme in enumerate(config["cross_sector"]):
+        if "theme_name" not in theme:
+            raise ValueError(
+                f"Theme at index {i} missing required key: theme_name"
+            )
+        if "matching_keywords" not in theme:
+            raise ValueError(
+                f"Theme '{theme.get('theme_name', i)}' missing required key: "
+                f"matching_keywords"
+            )
+
+
+def _extract_etf_catalog(config: Dict) -> Dict[str, int]:
+    """Extract ETF counts from config into a catalog dict.
+
+    Each theme may have an `etf_count` field. Missing etf_count defaults to 0.
+
+    Returns:
+        {theme_name: etf_count}
+    """
+    catalog = {}
+    for theme in config.get("cross_sector", []):
+        name = theme.get("theme_name", "")
+        catalog[name] = theme.get("etf_count", 0)
+    return catalog
+
+
+def _strip_etf_count(config: Dict) -> Dict:
+    """Return a copy of config with etf_count removed from each theme.
+
+    The etf_count is only used for ETF catalog extraction and should not
+    be passed to classify_themes().
+    """
+    result = copy.deepcopy(config)
+    for theme in result.get("cross_sector", []):
+        theme.pop("etf_count", None)
+    return result
+
+
+def _get_bundled_yaml_path() -> str:
+    """Return the absolute path to the bundled themes.yaml."""
+    return os.path.join(os.path.dirname(os.path.abspath(__file__)), "themes.yaml")

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

@@ -0,0 +1,254 @@
+"""Default inline theme configuration (fallback when YAML is unavailable).
+
+This module holds DEFAULT_THEMES_CONFIG and ETF_CATALOG constants extracted
+from theme_detector.py to avoid circular imports between theme_detector.py
+and config_loader.py.
+"""
+
+from typing import Dict
+
+DEFAULT_THEMES_CONFIG: Dict = {
+    "cross_sector_min_matches": 2,
+    "vertical_min_industries": 3,
+    "cross_sector": [
+        {
+            "theme_name": "AI & Semiconductors",
+            "matching_keywords": [
+                "Semiconductors",
+                "Semiconductor Equipment & Materials",
+                "Software - Application",
+                "Software - Infrastructure",
+                "Information Technology Services",
+                "Computer Hardware",
+                "Electronic Components",
+            ],
+            "proxy_etfs": ["SMH", "SOXX", "AIQ", "BOTZ"],
+            "static_stocks": [
+                "NVDA", "AVGO", "AMD", "INTC", "QCOM",
+                "MRVL", "AMAT", "LRCX", "KLAC", "TSM",
+            ],
+        },
+        {
+            "theme_name": "Clean Energy & EV",
+            "matching_keywords": [
+                "Solar",
+                "Utilities - Renewable",
+                "Auto Manufacturers",
+                "Electrical Equipment & Parts",
+                "Specialty Chemicals",
+            ],
+            "proxy_etfs": ["ICLN", "QCLN", "TAN", "LIT"],
+            "static_stocks": [
+                "ENPH", "SEDG", "FSLR", "RUN", "TSLA",
+                "RIVN", "ALB", "PLUG", "BE", "NEE",
+            ],
+        },
+        {
+            "theme_name": "Cybersecurity",
+            "matching_keywords": [
+                "Software - Infrastructure",
+                "Software - Application",
+                "Information Technology Services",
+            ],
+            "proxy_etfs": ["CIBR", "HACK", "BUG"],
+            "static_stocks": [
+                "CRWD", "PANW", "FTNT", "ZS", "S",
+                "OKTA", "NET", "CYBR", "QLYS", "RPD",
+            ],
+        },
+        {
+            "theme_name": "Cloud Computing & SaaS",
+            "matching_keywords": [
+                "Software - Application",
+                "Software - Infrastructure",
+                "Information Technology Services",
+            ],
+            "proxy_etfs": ["SKYY", "WCLD", "CLOU"],
+            "static_stocks": [
+                "CRM", "NOW", "SNOW", "DDOG", "MDB",
+                "NET", "ZS", "HUBS", "WDAY", "TEAM",
+            ],
+        },
+        {
+            "theme_name": "Biotech & Genomics",
+            "matching_keywords": [
+                "Biotechnology",
+                "Drug Manufacturers - General",
+                "Drug Manufacturers - Specialty & Generic",
+                "Diagnostics & Research",
+            ],
+            "proxy_etfs": ["XBI", "IBB", "ARKG"],
+            "static_stocks": [
+                "AMGN", "GILD", "VRTX", "REGN", "MRNA",
+                "BIIB", "ILMN", "SGEN", "ALNY", "BMRN",
+            ],
+        },
+        {
+            "theme_name": "Infrastructure & Construction",
+            "matching_keywords": [
+                "Engineering & Construction",
+                "Building Products & Equipment",
+                "Building Materials",
+                "Specialty Industrial Machinery",
+                "Farm & Heavy Construction Machinery",
+                "Infrastructure Operations",
+            ],
+            "proxy_etfs": ["PAVE", "IFRA"],
+            "static_stocks": [
+                "CAT", "DE", "VMC", "MLM", "URI",
+                "PWR", "EME", "J", "ACM", "FAST",
+            ],
+        },
+        {
+            "theme_name": "Gold & Precious Metals",
+            "matching_keywords": [
+                "Gold",
+                "Silver",
+                "Other Precious Metals & Mining",
+            ],
+            "proxy_etfs": ["GDX", "GDXJ", "SLV", "GLD"],
+            "static_stocks": [
+                "NEM", "GOLD", "AEM", "FNV", "WPM",
+                "RGLD", "KGC", "AGI", "HL", "PAAS",
+            ],
+        },
+        {
+            "theme_name": "Oil & Gas (Energy)",
+            "matching_keywords": [
+                "Oil & Gas E&P",
+                "Oil & Gas Equipment & Services",
+                "Oil & Gas Integrated",
+                "Oil & Gas Midstream",
+                "Oil & Gas Refining & Marketing",
+                "Oil & Gas Drilling",
+            ],
+            "proxy_etfs": ["XLE", "XOP", "OIH"],
+            "static_stocks": [
+                "XOM", "CVX", "COP", "EOG", "SLB",
+                "PXD", "MPC", "PSX", "OXY", "DVN",
+            ],
+        },
+        {
+            "theme_name": "Financial Services & Banks",
+            "matching_keywords": [
+                "Banks - Diversified",
+                "Banks - Regional",
+                "Capital Markets",
+                "Insurance - Diversified",
+                "Financial Data & Stock Exchanges",
+                "Asset Management",
+            ],
+            "proxy_etfs": ["XLF", "KBE", "KRE"],
+            "static_stocks": [
+                "JPM", "BAC", "GS", "MS", "WFC",
+                "C", "BLK", "SCHW", "ICE", "CME",
+            ],
+        },
+        {
+            "theme_name": "Healthcare & Pharma",
+            "matching_keywords": [
+                "Drug Manufacturers - General",
+                "Medical Devices",
+                "Medical Instruments & Supplies",
+                "Healthcare Plans",
+                "Medical Care Facilities",
+            ],
+            "proxy_etfs": ["XLV", "IHI", "XBI"],
+            "static_stocks": [
+                "UNH", "JNJ", "LLY", "PFE", "ABT",
+                "TMO", "DHR", "SYK", "ISRG", "MDT",
+            ],
+        },
+        {
+            "theme_name": "Defense & Aerospace",
+            "matching_keywords": [
+                "Aerospace & Defense",
+                "Communication Equipment",
+                "Scientific & Technical Instruments",
+            ],
+            "proxy_etfs": ["ITA", "PPA", "XAR"],
+            "static_stocks": [
+                "LMT", "RTX", "NOC", "GD", "BA",
+                "LHX", "HII", "TDG", "HWM", "AXON",
+            ],
+        },
+        {
+            "theme_name": "Real Estate & REITs",
+            "matching_keywords": [
+                "REIT - Diversified",
+                "REIT - Industrial",
+                "REIT - Residential",
+                "REIT - Retail",
+                "REIT - Specialty",
+                "REIT - Office",
+                "Real Estate - Development",
+                "Real Estate Services",
+            ],
+            "proxy_etfs": ["VNQ", "IYR", "XLRE"],
+            "static_stocks": [
+                "PLD", "AMT", "EQIX", "CCI", "SPG",
+                "O", "WELL", "DLR", "PSA", "AVB",
+            ],
+        },
+        {
+            "theme_name": "Retail & Consumer",
+            "matching_keywords": [
+                "Internet Retail",
+                "Specialty Retail",
+                "Apparel Retail",
+                "Discount Stores",
+                "Home Improvement Retail",
+                "Department Stores",
+            ],
+            "proxy_etfs": ["XRT", "XLY"],
+            "static_stocks": [
+                "AMZN", "HD", "LOW", "TJX", "COST",
+                "WMT", "TGT", "ROST", "BURL", "LULU",
+            ],
+        },
+        {
+            "theme_name": "Crypto & Blockchain",
+            "matching_keywords": [
+                "Capital Markets",
+                "Software - Infrastructure",
+                "Financial Data & Stock Exchanges",
+            ],
+            "proxy_etfs": ["BITO", "BLOK", "BITQ"],
+            "static_stocks": [
+                "COIN", "MSTR", "MARA", "RIOT", "CLSK",
+                "HUT", "BITF", "HIVE", "SQ", "PYPL",
+            ],
+        },
+        {
+            "theme_name": "Nuclear & Uranium",
+            "matching_keywords": [
+                "Uranium",
+                "Utilities - Independent Power Producers",
+                "Utilities - Regulated Electric",
+            ],
+            "proxy_etfs": ["URA", "URNM", "NLR"],
+            "static_stocks": [
+                "CCJ", "UEC", "NXE", "DNN", "LEU",
+                "SMR", "UUUU", "URG", "OKLO", "VST",
+            ],
+        },
+    ],
+}
+
+ETF_CATALOG: Dict[str, int] = {
+    "AI & Semiconductors": 8,
+    "Clean Energy & EV": 7,
+    "Cybersecurity": 4,
+    "Cloud Computing & SaaS": 4,
+    "Biotech & Genomics": 5,
+    "Infrastructure & Construction": 3,
+    "Gold & Precious Metals": 4,
+    "Oil & Gas (Energy)": 5,
+    "Financial Services & Banks": 5,
+    "Healthcare & Pharma": 5,
+    "Defense & Aerospace": 5,
+    "Real Estate & REITs": 4,
+    "Retail & Consumer": 3,
+    "Crypto & Blockchain": 4,
+    "Nuclear & Uranium": 3,
+}