Mrjie7205/serenity-bottleneck-hunter

What it solves

It automates a specific investment research methodology designed to find "bottleneck" stocks—overlooked upstream companies that are critical to a specific investment theme (e.g., AI data center power). Instead of chasing popular stocks, it helps users identify the essential suppliers that the rest of the industry depends on before the broader market notices them.

How it works

The project functions as a "skill" for AI agents (like OpenAI Codex or Claude Code) by providing a structured workflow and a suite of engineering tools to prevent common LLM errors:

1. Reverse Supply-Chain Mapping: It breaks down a theme into a five-layer dependency map to find critical nodes.
2. Bottleneck Archetypes: It applies nine specific patterns to identify which companies are true "chokepoints."
3. Data Validation: To prevent hallucinations, it uses dedicated scripts for ticker verification, ETF holdings audits, and mandatory price fetching via APIs (EODHD/yfinance) rather than allowing the LLM to guess prices.
4. Accountability Framework: It forces a "Red Team" analysis for every candidate, requiring a falsification condition (how to prove the thesis wrong) and tracking these picks in a CSV for future out-of-sample validation.
5. Reporting: It generates a self-contained HTML report featuring a visual supply chain map and a "water level" scale for timing and valuation.

Who it’s for

• Investment researchers and traders looking for a systematic way to find upstream alpha.
• Users of AI agents (Codex, Claude) who want to turn an LLM into a disciplined financial analyst.

Highlights

• Hallucination Guardrails: Implements a multi-layer defense (ticker truth libraries and pre-commit hooks) to ensure company data is accurate.
• Anti-Bias Logic: Uses ETF audits to counter the "popularity bias" of LLMs.
• Quantitative Accountability: Tracks Alpha relative to theme ETFs and compares "picked" vs "excluded" baskets to measure actual skill.
• Visual Reporting: Automatically renders SVG supply-chain maps and valuation trajectories in HTML reports.