Theme Detector

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 (Emerging/Accelerating/Trending/Mature/Exhausting), 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 (Emerging / Accelerating / Trending / Mature / Exhausting) based on duration, extremity clustering, valuation, and ETF proliferation 3. Confidence (Low / Medium / High): Reliability of the detection, combining quantitative breadth with narrative confirmation. Script output is capped at Medium; Claude's WebSearch narrative confirmation step can elevate to High.

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)

---

Prerequisites

Required:

• Python 3.10+ with core dependencies. The scripts use modern type-hint syntax such as dict | None, so Python 3.9 and older can fail at import time even when dependencies are installed.

  pip install requests beautifulsoup4 lxml pandas numpy yfinance

Cron / mixed-Python fallback: If the active python3 is older than 3.10, or a newer Hermes venv lacks the data-science dependencies, run the detector through uv with an explicit modern interpreter and temporary dependencies instead of editing the environment mid-cron:

uv run --python 3.12 \
  --with requests --with beautifulsoup4 --with lxml \
  --with pandas --with numpy --with yfinance \
  --with finvizfinance --with PyYAML \
  python skills/theme-detector/scripts/theme_detector.py \
  --finviz-api-key "$FINVIZ_API_KEY" \
  --fmp-api-key "$FMP_API_KEY" \
  --output-dir reports/

Use this as a setup workaround, not as evidence that the detector is broken; still report FINVIZ/FMP/API-data caveats separately.

Optional API Keys:

FINVIZ Elite (recommended for full industry coverage and speed):

export FINVIZ_API_KEY=your_finviz_elite_api_key_here

FMP API (optional, for P/E ratio valuation data):

export FMP_API_KEY=your_fmp_api_key_here

Optional Python packages:

• finvizfinance - Required for FINVIZ Elite mode
• PyYAML - Required for --themes-config custom themes

Without FINVIZ Elite, the skill uses public FINVIZ scraping (limited to ~20 stocks per industry, slower rate limits).

---

Workflow

Step 1: Verify Environment

Check that API keys are configured (see Prerequisites):

# Verify FINVIZ Elite API key (optional but recommended)
echo $FINVIZ_API_KEY

# Verify FMP API key (optional)
echo $FMP_API_KEY

Step 2: Execute Theme Detection Script

Run the main detection script:

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

Script Options:

# 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 10 \
  --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

Read the JSON output to understand quantitative results:

# Find the latest report
ls -lt reports/theme_detector_*.json | head -1

# Read the JSON output
cat reports/theme_detector_YYYY-MM-DD_HHMMSS.json

Step 4: Perform Narrative Confirmation via WebSearch

For the top 5 themes (by Theme Heat score), execute WebSearch queries to confirm narrative strength:

Search Pattern:

"[theme name] stocks market [current month] [current year]"
"[theme name] sector momentum [current month] [current year]"

Evaluate narrative signals:

• Strong narrative: Multiple major outlets covering the theme, analyst upgrades, policy catalysts
• Moderate narrative: Some coverage, mixed sentiment, no clear catalyst
• Weak narrative: Little coverage, or predominantly contrarian/skeptical tone

Update Confidence levels based on findings:

• Quantitative High + Narrative Strong = High confidence
• Quantitative High + Narrative Weak = Medium confidence (possible momentum divergence)
• Quantitative Low + Narrative Strong = Medium confidence (narrative may lead price)
• Quantitative Low + Narrative Weak = Low confidence

Step 5: Analyze Results and Provide Recommendations

Cross-reference detection results with knowledge bases:

Reference Documents to Consult: 1. references/cross_sector_themes.md - Theme definitions and constituent industries 2. references/thematic_etf_catalog.md - ETF exposure options by theme 3. references/theme_detection_methodology.md - Scoring model details 4. references/finviz_industry_codes.md - Industry classification reference

Analysis Framework:

For Hot Bullish Themes (Heat >= 70, Direction = Bullish):

• Identify lifecycle stage (Emerging = opportunity, Mature/Exhausting = caution)
• List top-performing industries within the theme
• Recommend proxy ETFs for exposure
• Flag if ETF proliferation is high (crowded trade warning)

For Hot Bearish Themes (Heat >= 70, Direction = Bearish):

• Identify industries under pressure
• Assess if bearish momentum is accelerating or decelerating
• Recommend hedging strategies or sectors to avoid
• Note potential mean-reversion opportunities if lifecycle is Mature/Exhausting

For Emerging Themes (Heat 40-69, Lifecycle = Emerging):

• These may represent early rotation signals
• Recommend monitoring with watchlist
• Identify catalyst events that could accelerate the theme

For Exhausted Themes (Heat >= 60, Lifecycle = Exhausting):

• Warn about crowded trade risk
• High ETF count confirms excessive retail participation
• Consider contrarian positioning or reducing exposure

Step 6: Generate Final Report

Present the final report to the user using the report template structure:

# Theme Detection Report
**Date:** YYYY-MM-DD
**Mode:** FINVIZ Elite / Public
**Themes Analyzed:** N
**Data Quality:** [note any limitations]

## Theme Dashboard
[Top themes table with Heat, Direction, Lifecycle, Confidence]

## Bullish Themes Detail
[Detailed analysis of bullish themes sorted by Heat]

## Bearish Themes Detail
[Detailed analysis of bearish themes sorted by Heat]

## All Themes Summary
[Complete theme ranking table]

## Industry Rankings
[Top performing and worst performing industries]

## Sector Uptrend Ratios
[Sector-level aggregation if uptrend data available]

## Methodology Notes
[Brief explanation of scoring model]

Save the report to reports/ directory.

---

Output

The skill generates two output files in the reports/ directory:

JSON Output (theme_detector_YYYY-MM-DD_HHMMSS.json):

{
  "report_type": "theme_detector",
  "generated_at": "2026-04-18 10:30:00",
  "metadata": {
    "generated_at": "2026-04-18 10:30:00",
    "data_mode": "full",
    "finviz_mode": "elite",
    "fmp_available": true,
    "max_themes": 14,
    "max_stocks_per_theme": 5,
    "data_sources": {
      "finviz_industries": 152,
      "yfinance_stocks": 68,
      "etf_volume": 24
    }
  },
  "summary": {
    "total_themes": 14,
    "bullish_count": 8,
    "bearish_count": 6,
    "top_bullish": "AI & Machine Learning",
    "top_bearish": "Regional Banks"
  },
  "themes": {
    "all": [
      {
        "name": "AI & Machine Learning",
        "direction": "bullish",
        "heat": 85.3,
        "maturity": 42.1,
        "stage": "Accelerating",
        "confidence": "Medium",
        "heat_label": "Hot",
        "industries": ["Software - Infrastructure", "Semiconductors"],
        "representative_stocks": [{"symbol": "NVDA"}, {"symbol": "MSFT"}],
        "proxy_etfs": ["BOTZ", "ROBO"],
        "theme_origin": "seed"
      }
    ],
    "bullish": [...],
    "bearish": [...]
  },
  "industry_rankings": {
    "top": [...],
    "bottom": [...]
  },
  "sector_uptrend": {...},
  "data_quality": {...}
}

Markdown Report (theme_detector_YYYY-MM-DD_HHMMSS.md):

• Theme Dashboard with sortable rankings
• Bullish/Bearish theme detail sections
• Industry performance rankings
• Sector uptrend ratio summary
• Methodology notes

Key Output Fields (per theme):

---

Resources

Scripts Directory (scripts/)

Main Scripts:

• theme_detector.py - Main orchestrator script
• Coordinates industry data collection, theme classification, and scoring
• Generates JSON + Markdown output
• Usage: python3 theme_detector.py [options]

• theme_classifier.py - Maps industries to cross-sector themes
• Reads theme definitions from cross_sector_themes.md
• Calculates theme-level aggregated scores
• Determines direction (bullish/bearish) from constituent industries
• Display mapping: "bullish" → "LEAD", "bearish" → "LAG" (see report_generator.py::_direction_label())

• finviz_industry_scanner.py - FINVIZ industry data collection
• Elite mode: CSV export with full stock data per industry
• Public mode: Web scraping with rate limiting
• Extracts: performance, volume, change%, avg volume, market cap

• calculators/lifecycle_calculator.py - Lifecycle maturity assessment
• Duration scoring, extremity clustering, valuation analysis
• ETF proliferation scoring from thematic_etf_catalog.md
• Stage classification: Emerging / Accelerating / Trending / Mature / Exhausting

• report_generator.py - Report output generation
• Markdown report from template
• JSON structured output
• Theme dashboard formatting

References Directory (references/)

Knowledge Bases:

• cross_sector_themes.md - Theme definitions with industries, ETFs, stocks, and matching criteria
• thematic_etf_catalog.md - Comprehensive thematic ETF catalog with counts per theme
• finviz_industry_codes.md - Complete FINVIZ industry-to-filter-code mapping
• theme_detection_methodology.md - Technical documentation of the 3D scoring model

Assets Directory (assets/)

• report_template.md - Markdown template for report generation with placeholder format

---

Important Notes

FINVIZ Mode Differences

Direction Detection Logic

Theme direction is determined by majority vote of constituent industries' relative rank:

1. Industry ranking: All ~145 industries are ranked by multi-timeframe momentum score 2. Rank-based direction: Industries in the top half of the ranked list are classified as "bullish"; bottom half as "bearish" 3. Theme majority vote: _majority_direction() counts bullish vs. bearish industries within each theme; the majority wins

Display mapping: "bullish" → LEAD, "bearish" → LAG (see report_generator.py::_direction_label())

A LEAD theme indicates relative outperformance of its constituent industries. A LAG theme may still have positive absolute returns — it indicates relative underperformance, not a short signal.

Known Limitations

1. Survivorship bias: Only analyzes currently listed stocks and ETFs 2. Lag: FINVIZ data may lag intraday moves by 15 minutes (public mode) 3. Theme boundaries: Some stocks fit multiple themes; classification uses primary industry 4. ETF proliferation: Catalog is static and may not capture very new ETFs 5. Narrative scoring: WebSearch-based and inherently subjective 6. Public mode limitation: ~20 stocks per industry may miss small-cap signals

Disclaimer

This analysis is for educational and informational purposes only.

• Not investment advice
• Past thematic trends do not guarantee future performance
• Theme detection identifies momentum, not fundamental value
• Conduct your own research before making investment decisions

---

Version: 1.0 Last Updated: 2026-02-16 API Requirements: FINVIZ Elite (recommended) or public mode (free); FMP API optional Execution Time: ~2-8 minutes depending on mode Output Formats: JSON + Markdown Themes Covered: 14+ cross-sector themes

Theme Detection Report

Date: {{date}} Mode: {{mode}} Themes Analyzed: {{themes_analyzed}} Industries Scanned: {{industries_scanned}} Total Stocks: {{total_stocks}} Uptrend Data: {{uptrend_data_status}} Execution Time: {{execution_time}}

---

1. Theme Dashboard

{{#each top_themes}} | {{rank}} | {{name}} | {{direction_emoji}} {{direction}} | {{heat}}/100 | {{lifecycle}} | {{confidence}} | {{/each}}

Legend: Direction: LEAD/LAG (Dashboard), ^/v (Summary) | Heat: 0-100 scale | Lifecycle: Emerging/Accelerating/Trending/Mature/Exhausting

---

2. Bullish Themes Detail

{{#each bullish_themes}}

{{name}} - Heat: {{heat}}/100

Direction: Bullish ({{direction_strength}}) | Lifecycle: {{lifecycle}} | Confidence: {{confidence}}

Heat Components:

• Momentum: {{momentum}}/100
• Volume: {{volume}}/100
• Uptrend: {{uptrend}}/100
• Breadth: {{breadth}}/100

Lifecycle Factors:

• Duration: {{duration_weeks}} weeks
• Extremity clustering: {{extremity_pct}}%
• Relative P/E: {{relative_pe}}x
• ETF proliferation: {{etf_count}} ETFs (score: {{etf_score}}/100)
• Narrative: {{narrative_assessment}}

Top Industries: {{#each industries}}

• {{name}}: {{change_pct}}% ({{stock_count}} stocks, uptrend {{uptrend_ratio}}%)

{{/each}}

Top Movers: {{#each top_stocks}}

• {{ticker}}: {{change_pct}}% | Vol: {{relative_volume}}x

{{/each}}

Proxy ETFs: {{proxy_etfs}}

Assessment: {{assessment}}

--- {{/each}}

3. Bearish Themes Detail

{{#each bearish_themes}}

{{name}} - Heat: {{heat}}/100

Direction: Bearish ({{direction_strength}}) | Lifecycle: {{lifecycle}} | Confidence: {{confidence}}

Heat Components:

• Momentum: {{momentum}}/100
• Volume: {{volume}}/100
• Downtrend: {{downtrend}}/100
• Breadth: {{breadth}}/100

Top Declining Industries: {{#each industries}}

• {{name}}: {{change_pct}}% ({{stock_count}} stocks, downtrend {{downtrend_ratio}}%)

{{/each}}

Worst Performers: {{#each bottom_stocks}}

• {{ticker}}: {{change_pct}}% | Vol: {{relative_volume}}x

{{/each}}

Assessment: {{assessment}}

--- {{/each}}

4. All Themes Summary

{{#each all_themes}} | {{name}} | {{direction}} | {{heat}} | {{momentum}} | {{volume}} | {{uptrend}} | {{breadth}} | {{lifecycle}} | {{confidence}} | {{/each}}

---

5. Industry Rankings

Top 10 Industries (by performance)

{{#each top_industries}} | {{rank}} | {{name}} | {{sector}} | {{change_pct}}% | {{rel_volume}}x | {{uptrend_ratio}}% | {{theme}} | {{/each}}

Bottom 10 Industries (by performance)

{{#each bottom_industries}} | {{rank}} | {{name}} | {{sector}} | {{change_pct}}% | {{rel_volume}}x | {{downtrend_ratio}}% | {{theme}} | {{/each}}

---

6. Sector Uptrend Ratios

{{#each sectors}} | {{name}} | {{uptrend_ratio}}% | {{avg_change_pct}}% | {{dominant_theme}} | {{direction}} | {{/each}}

---

7. Methodology Notes

Scoring Model: 3-Dimensional (Heat x Lifecycle x Confidence)

• Theme Heat (0-100): Momentum (30%) + Volume (25%) + Uptrend (25%) + Breadth (20%)
• Lifecycle: Duration + Extremity clustering + Valuation + ETF proliferation + Narrative saturation
• Confidence: Quantitative breadth + Cross-sector confirmation + Narrative verification

Data Sources:

• FINVIZ {{mode}} (industry performance, volume, 52-week data)

{{#if uptrend_data}}

• uptrend-dashboard (3-point technical evaluation)

{{/if}} {{#if fmp_data}}

• FMP API (P/E ratios for valuation analysis)

{{/if}}

• WebSearch (narrative confirmation for top themes)

Limitations:

• Theme definitions are static (predefined in cross_sector_themes.md)
• {{mode_limitation}}
• Duration tracking requires historical baseline data
• Narrative assessment is subjective

---

Generated by Theme Detector v1.0 | {{date}} {{time}}

Cross-Sector Theme Definitions

This reference defines market themes by their constituent FINVIZ industries, sectors, proxy ETFs, and representative stocks. The theme_classifier.py script reads these definitions to map industry-level data into theme-level aggregations.

Usage Notes:

• Industry names must exactly match FINVIZ industry names (see finviz_industry_codes.md)
• min_matching_industries: Design-intent minimum for each theme. In practice, theme detection uses the global cross_sector_min_matches setting (default: 2, configurable in themes.yaml) as the threshold. Per-theme values below are informational and not individually enforced in code
• static_stocks: Fallback representative stocks used when industry-level data is insufficient
• proxy_etfs: Used for quick volume/momentum checks and as user-facing exposure recommendations

---

AI & Semiconductors

• Direction bias: Bullish (typically)
• Industries: Semiconductors, Software - Application, Software - Infrastructure, Information Technology Services, Electronic Components, Computer Hardware, Scientific & Technical Instruments
• Sectors: Technology (primary), Communication Services, Industrials
• Proxy ETFs: SMH, SOXX, AIQ, BOTZ, CHAT
• Static stocks: NVDA, AVGO, AMD, INTC, QCOM, MRVL, AMAT, LRCX, KLAC, TSM, MU, ARM, SNPS, CDNS, MCHP
• Min matching industries: 2

---

Clean Energy & EV

• Direction bias: Bullish (typically)
• Industries: Solar, Utilities - Renewable, Auto Manufacturers, Auto Parts, Electrical Equipment & Parts, Specialty Chemicals
• Sectors: Utilities, Consumer Cyclical, Industrials, Basic Materials
• Proxy ETFs: ICLN, QCLN, TAN, DRIV, LIT
• Static stocks: ENPH, SEDG, FSLR, RUN, TSLA, RIVN, LCID, NIO, PLUG, BE, CHPT, ALB, SQM, LAC, LTHM
• Min matching industries: 2

---

Cybersecurity

• Direction bias: Bullish (typically)
• Industries: Software - Infrastructure, Information Technology Services, Software - Application, Communication Equipment
• Sectors: Technology (primary)
• Proxy ETFs: CIBR, HACK, BUG
• Static stocks: CRWD, PANW, FTNT, ZS, NET, S, OKTA, CYBR, QLYS, RPD, TENB, VRNS, SAIL, MNDT, DDOG
• Min matching industries: 2

Note: Cybersecurity overlaps with broader software industries. Theme classification uses proxy ETF volume and static stock performance to differentiate from general software themes.

---

Cloud Computing & SaaS

• Direction bias: Bullish (typically)
• Industries: Software - Application, Software - Infrastructure, Information Technology Services
• Sectors: Technology (primary), Communication Services
• Proxy ETFs: SKYY, WCLD, CLOU
• Static stocks: CRM, NOW, SNOW, DDOG, TEAM, MDB, ESTC, NET, ZS, HUBS, BILL, TTD, PLTR, DOCN, DT
• Min matching industries: 2

Note: Cloud/SaaS overlaps significantly with Cybersecurity and AI themes. When multiple themes share the same industries, proxy ETF performance differentiates them.

---

Biotech & Genomics

• Direction bias: Bullish (typically, but highly volatile)
• Industries: Biotechnology, Drug Manufacturers - Specialty & Generic, Medical Devices, Diagnostics & Research, Drug Manufacturers - General
• Sectors: Healthcare (primary)
• Proxy ETFs: XBI, IBB, ARKG, GNOM
• Static stocks: AMGN, GILD, VRTX, REGN, MRNA, BIIB, ILMN, CRSP, NTLA, BEAM, EDIT, EXAS, TWST, SGEN, BMRN
• Min matching industries: 2

---

Infrastructure & Construction

• Direction bias: Bullish (typically, policy-driven)
• Industries: Engineering & Construction, Building Materials, Industrial Distribution, Farm & Heavy Construction Machinery, Steel, Specialty Industrial Machinery, Railroads, Waste Management
• Sectors: Industrials (primary), Basic Materials
• Proxy ETFs: PAVE, IFRA, SIMS
• Static stocks: CAT, DE, VMC, MLM, URI, PWR, EME, MTZ, GVA, AECOM, STRL, GBX, NUE, CLF, RS
• Min matching industries: 3

---

Gold & Precious Metals

• Direction bias: Bullish (typically in risk-off or inflation)
• Industries: Gold, Silver, Other Precious Metals & Mining
• Sectors: Basic Materials (primary)
• Proxy ETFs: GDX, GDXJ, RING, SIL
• Static stocks: NEM, GOLD, AEM, FNV, WPM, RGLD, KGC, AGI, AU, HMY, PAAS, CDE, HL, MAG, EQX
• Min matching industries: 2

---

Oil & Gas (Energy Sector)

• Direction bias: Varies (cyclical)
• Industries: Oil & Gas E&P, Oil & Gas Equipment & Services, Oil & Gas Midstream, Oil & Gas Refining & Marketing, Oil & Gas Integrated, Oil & Gas Drilling
• Sectors: Energy (primary)
• Proxy ETFs: XLE, XOP, OIH
• Static stocks: XOM, CVX, COP, EOG, SLB, HAL, PXD, DVN, MPC, VLO, PSX, OXY, FANG, HES, WMB
• Min matching industries: 2

---

Financial Services & Banks

• Direction bias: Varies (rate-sensitive)
• Industries: Banks - Diversified, Banks - Regional, Capital Markets, Insurance - Diversified, Insurance - Property & Casualty, Financial Data & Stock Exchanges, Credit Services, Asset Management, Insurance Brokers, Mortgage Finance
• Sectors: Financial Services (primary)
• Proxy ETFs: XLF, KBE, KRE, IAI
• Static stocks: JPM, BAC, WFC, GS, MS, C, SCHW, BLK, AXP, ICE, CME, MCO, SPGI, BX, KKR
• Min matching industries: 3

---

Healthcare & Pharma

• Direction bias: Varies (defensive in downturns)
• Industries: Drug Manufacturers - General, Health Care Plans, Medical Care Facilities, Health Information Services, Medical Distribution, Medical Instruments & Supplies, Pharmaceutical Retailers
• Sectors: Healthcare (primary)
• Proxy ETFs: XLV, IHE, IHI
• Static stocks: UNH, JNJ, LLY, PFE, ABT, TMO, DHR, MDT, ISRG, SYK, BSX, EW, HCA, CVS, CI
• Min matching industries: 3

Note: Healthcare & Pharma is distinct from Biotech & Genomics. Healthcare focuses on established pharma, insurance, and medical devices; Biotech focuses on emerging drug development and genomics.

---

Defense & Aerospace

• Direction bias: Bullish (typically in geopolitical tension)
• Industries: Aerospace & Defense, Airlines, Security & Protection Services
• Sectors: Industrials (primary)
• Proxy ETFs: ITA, PPA, ROKT, ARKX
• Static stocks: LMT, RTX, NOC, BA, GD, LHX, HII, TDG, HWM, AXON, LDOS, BWXT, KTOS, RKLB, SPR
• Min matching industries: 2

---

Real Estate & REITs

• Direction bias: Varies (rate-sensitive)
• Industries: REIT - Residential, REIT - Industrial, REIT - Retail, REIT - Office, REIT - Healthcare Facilities, REIT - Diversified, REIT - Hotel & Motel, REIT - Specialty, Real Estate Services, Real Estate - Diversified, Real Estate - Development
• Sectors: Real Estate (primary)
• Proxy ETFs: VNQ, XLRE, IYR
• Static stocks: PLD, AMT, CCI, EQIX, SPG, O, WELL, DLR, PSA, VICI, EXR, AVB, ARE, MAA, IRM
• Min matching industries: 3

---

Retail & Consumer

• Direction bias: Varies (consumer sentiment driven)
• Industries: Internet Retail, Specialty Retail, Apparel Retail, Home Improvement Retail, Department Stores, Discount Stores, Luxury Goods, Restaurants, Leisure, Resorts & Casinos, Gambling, Apparel Manufacturing, Footwear & Accessories
• Sectors: Consumer Cyclical (primary), Consumer Defensive
• Proxy ETFs: XLY, XRT, XLP, IBUY
• Static stocks: AMZN, HD, LOW, TJX, COST, WMT, TGT, NKE, SBUX, MCD, DPZ, LULU, ROST, BURL, DECK
• Min matching industries: 3

---

Crypto & Blockchain

• Direction bias: Bullish (typically in risk-on)
• Industries: Capital Markets, Software - Application, Financial Data & Stock Exchanges, Information Technology Services
• Sectors: Financial Services, Technology
• Proxy ETFs: BITO, BLOK, BITQ, IBIT, DAPP
• Static stocks: COIN, MSTR, MARA, RIOT, CLSK, HUT, BITF, SQ, PYPL, HOOD, CIFR, IREN, HIVE, CORZ, BTBT
• Min matching industries: 2

Note: Crypto theme uses proxy ETFs and static stocks as primary signals rather than industry classification, since blockchain companies span multiple traditional industries.

---

Nuclear Energy

• Direction bias: Bullish (policy-driven, AI data center demand)
• Industries: Uranium, Utilities - Independent Power Producers, Specialty Industrial Machinery, Electrical Equipment & Parts
• Sectors: Energy, Utilities, Industrials
• Proxy ETFs: URA, URNM, NLR, NUKZ
• Static stocks: CCJ, UEC, NXE, DNN, UUUU, LEU, SMR, OKLO, BWX, GEV, CEG, VST, TLN, NRG, BWXT
• Min matching industries: 2

---

Uranium

• Direction bias: Bullish (supply deficit narrative)
• Industries: Uranium, Other Industrial Metals & Mining
• Sectors: Energy (primary), Basic Materials
• Proxy ETFs: URA, URNM, URNJ
• Static stocks: CCJ, UEC, NXE, DNN, UUUU, LEU, URG, GLATF, EU, PALAF, SRUUF, LTBR, FCUUF, AEC, WSTRF
• Min matching industries: 1

Note: Uranium is a sub-theme of Nuclear Energy but tracked separately due to its distinct commodity-driven dynamics. Requires only 1 matching industry due to narrow sector focus.

---

Obesity & GLP-1

• Direction bias: Bullish (medical innovation)
• Industries: Drug Manufacturers - General, Drug Manufacturers - Specialty & Generic, Medical Devices, Biotechnology
• Sectors: Healthcare (primary)
• Proxy ETFs: SLIM, HRTS
• Static stocks: LLY, NVO, AMGN, VKTX, ALT, GPCR, SMLR, RVMD, PTGX, IVA
• Min matching industries: 2

Note: Obesity/GLP-1 is a narrow theme that overlaps with Healthcare & Pharma. It is differentiated primarily through proxy ETF volume and static stock performance rather than industry classification.

---

Summary Table

Total: 17 themes covering all major market narratives.

---

Theme Overlap Matrix

Some industries contribute to multiple themes. When scoring, each industry's data is used in all applicable themes:

This overlap is intentional - a strong software industry may boost multiple themes simultaneously, reflecting the interconnected nature of market narratives.

FINVIZ Industry Filter Codes

This reference maps all FINVIZ industry names to their corresponding filter codes used in the FINVIZ Screener API and Elite CSV export URLs.

URL Pattern (Elite CSV Export):

https://elite.finviz.com/export.ashx?v=151&f=ind_{code},cap_smallover&auth={API_KEY}

URL Pattern (Public Screener):

https://finviz.com/screener.ashx?v=151&f=ind_{code},cap_smallover

Filter Code Convention: ind_ + lowercase industry name with spaces, hyphens, ampersands, and special characters removed.

---

Aerospace & Defense

Auto & Transport

Basic Materials

Communication Services

Consumer Cyclical

Consumer Defensive

Energy

Financial Services

Healthcare

Industrials

Real Estate

Technology

Utilities

---

Complete Alphabetical Index

This flat list provides all industry filter codes in alphabetical order for quick lookup:

Total: 142 industries

---

Notes

1. Filter code derivation: Remove spaces, hyphens, ampersands (&), and other special characters from the industry name, then lowercase the result. Prefix with ind_.

2. Cross-sector industries: Some industries (e.g., Uranium) appear under multiple FINVIZ sectors (Energy and Basic Materials). The filter code is the same regardless of which sector view you navigate from.

3. Industry changes: FINVIZ occasionally adds, removes, or renames industries. This list was compiled as of February 2026. If a filter code returns no results, verify the industry name on FINVIZ directly.

4. Combining filters: Multiple industry filters can be combined in FINVIZ URLs using comma separation:

   f=ind_semiconductors,ind_softwareapplication,cap_smallover

5. Market cap filter: For theme detection, always combine with cap_smallover (market cap > $300M) to filter out micro-caps that may distort aggregated metrics.

6. Special cases:

• "E&P" becomes "ep" (ampersand removed)
• "REIT - " prefix becomes "reit" (hyphen and spaces removed)
• "Wineries & Distilleries" becomes "wineriesanddistilleries" (ampersand becomes "and" in this case)
• Verify edge cases against FINVIZ directly if results seem incorrect

Thematic ETF Catalog

This catalog maps market themes to their associated ETFs. The ETF count per theme is used for the etf_proliferation_score in lifecycle maturity assessment.

ETF Proliferation Scoring:

Higher ETF proliferation indicates more retail/institutional interest and a potentially more mature (crowded) theme.

---

AI & Semiconductors

ETF Count: 11 | Proliferation Score: 100

---

Clean Energy & EV

ETF Count: 9 | Proliferation Score: 80

---

Cybersecurity

ETF Count: 4 | Proliferation Score: 60

---

Cloud Computing & SaaS

ETF Count: 4 | Proliferation Score: 60

---

Biotech & Genomics

ETF Count: 6 | Proliferation Score: 60

---

Infrastructure & Construction

ETF Count: 3 | Proliferation Score: 40

---

Cannabis

ETF Count: 3 | Proliferation Score: 40

---

Blockchain & Crypto

ETF Count: 5 | Proliferation Score: 60

---

Defense & Aerospace

ETF Count: 5 | Proliferation Score: 60

---

Obesity & GLP-1

ETF Count: 2 | Proliferation Score: 40

---

Nuclear Energy

ETF Count: 3 | Proliferation Score: 40

---

Water Resources

ETF Count: 3 | Proliferation Score: 40

---

Robotics & Automation

ETF Count: 3 | Proliferation Score: 40

---

Lithium & Battery Technology

ETF Count: 2 | Proliferation Score: 40

---

Gold & Precious Metals

ETF Count: 5 | Proliferation Score: 60

---

Uranium

ETF Count: 3 | Proliferation Score: 40

---

Oil & Gas (Energy)

ETF Count: 6 | Proliferation Score: 60

---

Financial Services & Banks

ETF Count: 5 | Proliferation Score: 60

---

Healthcare & Pharma

ETF Count: 5 | Proliferation Score: 60

---

Real Estate & REITs

ETF Count: 4 | Proliferation Score: 60

---

Retail & Consumer

ETF Count: 4 | Proliferation Score: 60

---

Summary Table

Notes:

• Some ETFs appear in multiple themes (e.g., LIT in both Clean Energy and Lithium, IRBO in both AI and Robotics)
• AUM Tier: Large (>$1B), Medium ($100M-$1B), Small (<$100M)
• Leveraged ETFs (LABU, CLDL) included for completeness but not recommended for theme exposure measurement
• Catalog should be updated quarterly to capture new ETF launches and closures

Theme Detection Methodology

Overview

The Theme Detector uses a 3-Dimensional Scoring Model to identify, rank, and assess market themes. Unlike single-score ranking systems, this approach separates the intensity of a theme (heat), its maturity stage (lifecycle), and the reliability of the signal (confidence) into independent dimensions.

---

Dimension 1: Theme Heat (0-100)

Theme Heat measures the direction-neutral strength of a theme. A high heat score means the theme is generating significant market activity, regardless of whether it is bullish or bearish.

Components

1.1 Momentum Strength (weight: 35%)

Measures the direction-neutral momentum strength using a log-sigmoid function on the absolute weighted return.

Formula:

weighted_return = perf_1w * 0.10 + perf_1m * 0.25 + perf_3m * 0.35 + perf_6m * 0.30
momentum_score = 100 / (1 + exp(-2.0 * (ln(1 + |weighted_return|) - ln(16))))

Midpoint at |15%| weighted return. Log transform compresses extreme values for better mid-range separation. Absolute value is used so both strong bullish and strong bearish moves generate high heat.

Data Source: FINVIZ industry performance (1W, 1M, 3M, 6M change %)

Example Scores (continuous, not stepped): | |Weighted Return| | Score | |---------------------|-------| | 0% | ~3 | | 5% | ~27 | | 15% | 50 (midpoint) | | 30% | ~73 | | 50% | ~86 |

1.2 Volume Intensity (weight: 20%)

Measures abnormal volume using sqrt scaling on the 20-day/60-day volume ratio.

Formula:

ratio = vol_20d / vol_60d
volume_score = min(100, sqrt(max(0, ratio - 0.8)) / sqrt(1.2) * 100)

Returns 50.0 if either volume input is None or zero.

Data Source: FINVIZ relative volume (volume / avg volume ratio)

Example Scores:

1.3 Uptrend Signal (weight: 25%)

Continuous score from sector uptrend data with base + bonus structure.

Formula per sector:

base = min(80, ratio * 100)        # continuous 0-80
ma_bonus = 10 if ratio > ma_10     # MA above bonus
slope_bonus = 10 if slope > 0      # positive slope bonus
sector_score = base + ma_bonus + slope_bonus  # 0-100

Final score = weighted average of sector scores. For bearish themes, result is inverted (100 - score).

Data Source: uptrend-dashboard output (ratio, ma_10, slope per sector)

Returns 50.0 if no sector data available.

1.4 Breadth Signal (weight: 20%)

Measures directionally-aligned industry participation using a power curve with industry count bonus.

Formula:

breadth_score = min(100, ratio^2.5 * 80 + count_bonus)
count_bonus = min(20, industry_count * 2)

The ratio is the fraction of matched industries with directionally-aligned weighted returns (positive for LEAD themes, negative for LAG themes). Power curve (exponent 2.5) suppresses low ratios and amplifies high ones.

Data Source: Industry-level weighted returns (not stock-level)

Example Scores (no count bonus):

Returns 50.0 if ratio is None.

Theme Heat Composite

theme_heat = (momentum * 0.35) + (volume * 0.20) + (uptrend * 0.25) + (breadth * 0.20)

Any None sub-score defaults to 50.0. Result clamped to 0-100.

---

Dimension 2: Lifecycle Maturity

Lifecycle assessment classifies a theme into one of five stages: Emerging, Accelerating, Trending, Mature, or Exhausting. This is critical for distinguishing emerging opportunities from crowded trades.

Components

2.1 Duration Score (weight: 25%)

How long the theme has been active (consecutive weeks of elevated heat).

Measurement: Count weeks where theme_heat >= 40.

Limitation: Duration tracking requires historical data. On first run, duration defaults to "Unknown" and lifecycle uses other factors only.

2.2 Extremity Clustering Score (weight: 25%)

Percentage of stocks in the theme near 52-week highs or lows.

Formula:

extremity_pct = count(within_5pct_of_52wk_high_or_low) / count(total_stocks)

Data Source: FINVIZ 52-week high/low data

2.3 Price Extreme Saturation Score (weight: 25%)

Proportion of stocks near 52-week extremes (within 5%).

Formula:

bullish: pct = count(dist_from_52w_high <= 0.05) / total
bearish: pct = count(dist_from_52w_low <= 0.05) / total
score = min(100, pct * 200)

2.4 Valuation Score (weight: 15%)

Average P/E ratio of theme constituents relative to S&P 500 P/E.

Formula:

relative_pe = avg_theme_pe / sp500_pe

Data Source: FMP API for P/E ratios (optional; uses FINVIZ forward P/E as fallback)

2.5 ETF Proliferation Score (weight: 10%)

Number of thematic ETFs tracking the theme. More ETFs indicate greater retail/institutional attention.

Source: thematic_etf_catalog.md (static reference)

Lifecycle Maturity Composite

maturity = (duration * 0.25) + (extremity * 0.25) + (price_extreme * 0.25) + (valuation * 0.15) + (etf_proliferation * 0.10)

Lifecycle Stage Classification

The lifecycle stage is classified from the maturity score:

Note: Media/Narrative Saturation is not included in the automated maturity calculation. Claude's WebSearch narrative confirmation can be used to qualitatively adjust the lifecycle assessment.

---

Dimension 3: Confidence (Low / Medium / High)

Confidence measures how reliable the theme detection is, based on data quality and confirmation signals.

Layers

3.1 Quantitative Layer (base)

Based on data breadth and consistency:

3.2 Breadth Layer (modifier)

Cross-sector participation adds confidence:

3.3 Narrative Layer (modifier, applied in Step 4)

WebSearch confirmation adjusts confidence:

Final Confidence

confidence = apply_modifiers(quantitative_base, breadth_modifier, narrative_modifier)
confidence = clamp(confidence, Low, High)

---

Direction Detection

Theme direction (leading vs. lagging) is determined by relative rank, not absolute price change:

Algorithm

1. Each industry gets a rank_direction based on its position in the momentum-ranked list: top half = "bullish" (leading), bottom half = "bearish" (lagging). 2. Theme direction is the majority vote of its constituent industries' rank_direction.

# Industry-level (industry_ranker.py)
rank_direction = "bullish" if rank <= len(industries) // 2 else "bearish"

# Theme-level (theme_classifier.py)
direction = majority_vote([ind.rank_direction for ind in theme.industries])

Important: Relative, Not Absolute

LEAD/LAG direction is relative. A "lagging" theme may still have positive absolute returns — it simply underperforms relative to other themes. This means:

• LEAD themes: Suitable for overweight / new positions
• LAG themes: Candidates for underweight reduction, not short signals

---

Data Sources

Primary: FINVIZ

Elite Mode (recommended):

• CSV export endpoint: https://elite.finviz.com/export.ashx?v=151&f=ind_{code},cap_smallover,...&auth=KEY
• Provides: ticker, company, sector, industry, market cap, P/E, change%, volume, avg volume, 52wk high/low, RSI, SMA20/50/200
• Rate limit: 0.5s between requests
• Coverage: Full stock universe per industry

Public Mode (fallback):

• HTML scraping: https://finviz.com/screener.ashx?v=151&f=ind_{code},cap_smallover
• Provides: Same fields but limited to page 1 (~20 stocks per industry)
• Rate limit: 2.0s between requests (aggressive scraping may trigger blocks)
• Coverage: Top 20 stocks per industry by market cap

Secondary: FMP API (optional)

• P/E ratios for valuation analysis
• Not required; FINVIZ forward P/E used as fallback
• Useful for more granular valuation metrics

Tertiary: uptrend-dashboard (optional)

• CSV output from the uptrend-dashboard skill
• Provides 3-point technical evaluation per stock
• Significantly improves uptrend ratio accuracy
• If unavailable, FINVIZ price-vs-SMA200 is used as proxy

Quaternary: WebSearch (narrative layer)

• Used for narrative confirmation in Step 4
• Not automated; Claude performs searches during workflow
• Subjective assessment of media coverage and analyst sentiment

---

Integration with uptrend-dashboard

When uptrend-dashboard data is available, the theme detector uses it for enhanced 3-point evaluation:

3-Point Evaluation Criteria: 1. Price > 50-day SMA (short-term trend) 2. 50-day SMA > 200-day SMA (medium-term trend, golden/death cross) 3. 200-day SMA is rising (long-term trend confirmation)

Stocks meeting all 3 points = in confirmed uptrend Stocks meeting 0 points = in confirmed downtrend

This provides more accurate uptrend ratios than simple price-above-SMA200 proxy.

---

Output Schema

JSON Output Structure

{
  "metadata": {
    "date": "2026-02-16",
    "mode": "elite",
    "themes_analyzed": 14,
    "industries_scanned": 145,
    "total_stocks": 5200,
    "uptrend_data_available": true,
    "execution_time_seconds": 150
  },
  "themes": [
    {
      "name": "AI & Semiconductors",
      "direction": "Bullish",
      "direction_strength": "Strong",
      "theme_heat": 82,
      "heat_components": {
        "momentum": 90,
        "volume": 75,
        "uptrend": 85,
        "breadth": 70
      },
      "lifecycle": {
        "stage": "Mature",
        "duration_weeks": 12,
        "extremity_pct": 45,
        "relative_pe": 1.8,
        "etf_proliferation_score": 100,
        "etf_count": 11
      },
      "confidence": "High",
      "confidence_components": {
        "quantitative": "High",
        "breadth_modifier": "+1",
        "narrative_modifier": "pending"
      },
      "industries": [
        {
          "name": "Semiconductors",
          "change_pct": 4.2,
          "avg_relative_volume": 1.8,
          "uptrend_ratio": 0.75,
          "stock_count": 35
        }
      ],
      "top_stocks": [
        {"ticker": "NVDA", "change_pct": 6.5, "relative_volume": 2.1},
        {"ticker": "AVGO", "change_pct": 4.8, "relative_volume": 1.9}
      ],
      "proxy_etfs": ["SMH", "SOXX", "AIQ", "BOTZ"]
    }
  ],
  "industry_rankings": {
    "top_10": [...],
    "bottom_10": [...]
  },
  "sector_summary": {
    "Technology": {"uptrend_ratio": 0.65, "avg_change_pct": 2.1},
    "Energy": {"uptrend_ratio": 0.40, "avg_change_pct": -1.5}
  }
}

---

Known Limitations

1. Static theme definitions: Cross-sector themes are predefined in cross_sector_themes.md. New themes (e.g., a sudden meme-stock theme) are not automatically detected.

2. Industry granularity: FINVIZ industry classification may not perfectly map to investment themes. Some industries span multiple themes.

3. Single-stock dominance: Large-cap stocks (e.g., NVDA in AI) can skew theme-level metrics. Market-cap weighting amplifies this effect.

4. Temporal lag: Weekly performance data does not capture intraday or same-day momentum shifts.

5. ETF catalog staleness: The thematic ETF catalog is manually maintained and may not reflect recent ETF launches or closures.

6. Public mode data limits: Only ~20 stocks per industry are captured, which may underrepresent small/mid-cap participation.

7. Duration tracking: First-run analysis cannot assess theme duration without historical baseline data.

8. Narrative subjectivity: Confidence adjustment from WebSearch is inherently subjective and depends on search result quality.

9. Survivorship bias: Analysis only covers currently listed stocks and active ETFs, missing delisted or closed instruments.

10. FINVIZ data delays: Public FINVIZ data is 15-minute delayed; Elite provides real-time during market hours.