Opportunity Scout

Industrial Decarbonisation Opportunity Scout — LangGraph multi-agent pipeline for identifying thermal energy storage deployment opportunities.

Built as a demonstration of architecture PM&A team would use to automate market opportunity analysis.

---

What it does

Given a grid region (e.g. ERCOT West) and industrial sector (e.g. cement), the agent:

1. Fetches real electricity market data (LMP prices, curtailment) from GridStatus.io
2. Finds industrial facilities via EPA ECHO
3. Assesses solar resource via NREL
4. Researches policy incentives via Federal Register
5. Scores 5 dimensions deterministically (no LLM arithmetic)
6. Detects conflicting signals and assesses data confidence
7. Routes to: auto-approve → briefing | fetch more data | human review | disqualify
8. Generates a structured PM&A-style opportunity briefing

---

Setup

git clone <repo>
cd opportunity-scout
pip install -e .
cp .env.example .env
# Fill in your API keys in .env

Get free API keys (5 mins)

Key	Where
GOOGLE_API_KEY	aistudio.google.com
GROQ_API_KEY	console.groq.com
EIA_API_KEY	api.eia.gov/api/registration.php
NREL_API_KEY	developer.nrel.gov/signup
TAVILY_API_KEY	tavily.com

GridStatus.io and EPA ECHO require no API key for basic usage.

---

Run

# Development (uses Ollama — install from ollama.ai first)
ollama pull llama3.1
make dev

# Production (uses Gemini + Groq)
ENV=prod make run

# Tests
make test

# Eval suite
make eval

---

Architecture

mcp_servers/    — data connectors (GridStatus, EIA, NREL, EPA, Policy)
graph/          — LangGraph nodes, state schema, routing conditions
scoring/        — deterministic scoring functions + domain weights (the SOP)
prompts/        — LLM prompts as plain text files (version controlled)
models/         — model factory (dev=Ollama, prod=Gemini+Groq)
evals/          — eval cases + runner (run on every commit)
app/            — Streamlit frontend with human-review UI
docs/           — architecture, SOP, and ADRs

See docs/architecture.md for the full design and docs/sop.md for the domain logic.

---

⚠️ items remaining

To complete:

• graph/graph.py — full edge wiring and conditional routing
• graph/routing/conditions.py — route_after_scoring() decision matrix
• scoring/dimensions.py — arithmetic for all dimension scorers
• scoring/composite.py — weighted composite calculation

All files have # OP markers with specific instructions.