theme-detector

Files (40)

• SKILL.md
• report_template.md · assets/
• manifest.json
• cross_sector_themes.md · references/
• finviz_industry_codes.md · references/
• thematic_etf_catalog.md · references/
• theme_detection_methodology.md · references/
• __init__.py · scripts/calculators/
• heat_calculator.py · scripts/calculators/
• industry_ranker.py · scripts/calculators/
• lifecycle_calculator.py · scripts/calculators/
• theme_classifier.py · scripts/calculators/
• theme_discoverer.py · scripts/calculators/
• config_loader.py · scripts/
• default_theme_config.py · scripts/
• etf_scanner.py · scripts/
• finviz_performance_client.py · scripts/
• get_data.py · scripts/
• report_generator.py · scripts/
• representative_stock_selector.py · scripts/
• scorer.py · scripts/
• README.md · scripts/tests/
• conftest.py · scripts/tests/
• test_config_loader.py · scripts/tests/
• test_detect_divergence.py · scripts/tests/
• test_etf_scanner.py · scripts/tests/
• test_finviz_performance_client.py · scripts/tests/
• test_heat_calculator.py · scripts/tests/
• test_industry_ranker.py · scripts/tests/
• test_lifecycle_calculator.py · scripts/tests/
• test_report_generator.py · scripts/tests/
• test_representative_stock_selector.py · scripts/tests/
• test_scorer.py · scripts/tests/
• test_theme_classifier.py · scripts/tests/
• test_theme_detector_e2e.py · scripts/tests/
• test_theme_discoverer.py · scripts/tests/
• test_uptrend_client.py · scripts/tests/
• theme_detector.py · scripts/
• themes.yaml · scripts/
• uptrend_client.py · scripts/

SKILL.md (first lines)

# Theme Detector

## Overview

This skill detects and ranks trending market themes by analyzing cross-sector momentum, volume, and breadth signals. It identifies both bullish (upward momentum) and bearish (downward pressure) themes, assesses lifecycle maturity (early/mid/late/exhaustion), and provides a confidence score combining quantitative data with narrative analysis.

**3-Dimensional Scoring Model:**
1. **Theme Heat** (0-100): Direction-neutral strength of the theme (momentum, volume, uptrend ratio, breadth)
2. **Lifecycle Maturity**: Stage classification (Early / Mid / Late / Exhaustion) based on duration, extremity clustering, valuation, and ETF proliferation
3. **Confidence** (Low / Medium / High): Reliability of the detection, combining quantitative breadth with narrative confirmation

**Key Features:**
- Cross-sector theme detection using FINVIZ industry data
- Direction-aware scoring (bullish and bearish themes)
- Lifecycle maturity assessment to identify crowded vs. emerging trades
- ETF proliferation scoring (more ETFs = more mature/crowded theme)
- Integration with uptrend-dashboard for 3-point evaluation
- Dual-mode operation: FINVIZ Elite (fast) or public scraping (slower, limited)
- WebSearch-based narrative confirmation for top themes

---

## When to Use This Skill

**Explicit Triggers:**
- "What market themes are trending right now?"
- "Which sectors are hot/cold?"
- "Detect current market themes"
- "What are the strongest bullish/bearish narratives?"
- "Is AI/clean energy/defense still a strong theme?"
- "Where is sector rotation heading?"
- "Show me thematic investing opportunities"

**Implicit Triggers:**
- User wants to understand broad market narrative shifts
- User is looking for thematic ETF or sector allocation ideas
- User asks about crowded trades or late-cycle themes
- User wants to know which themes are emerging vs. exhausted

**When NOT to Use:**
- Individual stock analysis (use us-stock-analysis instead)
- Specific sector deep-dive with chart reading (use sector-analyst instead)
- Portfolio rebalancing (use portfolio-manager instead)
- Dividend/income investing (use value-dividend-screener instead)

---

## Workflow

### Step 1: Verify Requirements

Check for required API keys and dependencies:

```bash
# Check for FINVIZ Elite API key (optional but recommended)
echo $FINVIZ_API_KEY

# Check for FMP API key (optional, used for valuation metrics)
echo $FMP_API_KEY
```

**Requirements:**
- **Python 3.7+** with `requests`, `beautifulsoup4`, `lxml`
- **FINVIZ Elite API key** (recommended for full industry coverage and speed)
- **FMP API key** (optional, for P/E ratio valuation data)
- Without FINVIZ Elite, the skill uses public FINVIZ scraping (limited to ~20 stocks per industry, slower rate limits)

**Installation:**
```bash
pip install requests beautifulsoup4 lxml
```

### Step 2: Execute Theme Detection Script

Run the main detection script:

```bash
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/
```

**Script Options:**
```bash
# Full run (public FINVIZ mode, no API key required)
python3 skills/theme-detector/scripts/theme_detector.py \
  --output-dir reports/

# With FINVIZ Elite API key
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key $FINVIZ_API_KEY \
  --output-dir reports/

# With FMP API key for enhanced stock data
python3 skills/theme-detector/scripts/theme_detector.py \
  --fmp-api-key $FMP_API_KEY \
  --output-dir reports/

# Custom limits
python3 skills/theme-detector/scripts/theme_detector.py \
  --max-themes 5 \
  --max-stocks-per-theme 5 \
  --output-dir reports/

# Explicit FINVIZ mode
python3 skills/theme-detector/scripts/theme_detector.py \
  --finviz-mode public \
  --output-dir reports/
```

**Expected Execution Time:**
- FINVIZ Elite mode: ~2-3 minutes (14+ themes)
- Public FINVIZ mode: ~5-8 minutes (rate-limited scraping)

### Step 3: Read and Parse Detection Results

The script generates two output files:
- `theme_detector_YYYY-MM-DD_HHMMSS.json` - Structured data for programmatic use
- `theme_detector_YYYY-MM-DD_HHMMSS.md` - Human-readable report

From johncui9392/Aeolus, MIT.

More from johncui9392/Aeolus