📈 Market Regime Agent (v1)
A deterministic, offline market context agent that classifies the current market regime using transparent signals and persistent memory.
Observe → Reason → Act → Remember
This agent is designed to provide context, not predictions — and to integrate cleanly with other trading and analysis agents.
🧠 What This Agent Does
MarketRegimeAgent answers one core question:
“What type of market environment am I operating in right now?”
It classifies the market using explicit, rule-based signals:
Trend (moving averages)
Volatility (realized volatility)
Breadth (participation across assets)
Risk-On / Risk-Off (relative asset performance)
Example Output { "regime": "Risk-Off / Low Vol / Downtrend / Healthy Breadth", "confidence": 0.75, "drivers": [ "SPY below long-term trend", "Volatility below stress threshold", "Majority of assets above MA50", "SPY underperforming TLT" ], "implications": [ "Reduce exposure", "Avoid chasing breakouts", "Favor defensive positioning" ] }
❌ What This Agent Does NOT Do
This is intentional.
MarketRegimeAgent does not:
Predict prices
Generate trade signals
Optimize returns
Backtest strategies
Fetch live market data
Call OpenAI or any LLM
Make any external API requests
Require API keys
It provides context, not alpha.
🧩 Design Philosophy
Market regimes are not a language problem — they are a signal aggregation problem.
For that reason, this agent is:
✅ Deterministic
✅ Offline
✅ Explainable
✅ Testable
✅ Reproducible
All logic is explicit. No hidden heuristics. No model hallucination.
LLMs, if used later, are limited to optional narration, never classification.
🔁 Agent Loop
This agent implements a full agent lifecycle:
Observe
Ingests price history (CSV)
Validates structure
Reason
Computes signals
Classifies regime
Assigns confidence
Generates drivers & implications
Act
Detects regime changes
Applies alert cooldown logic
Remember
Persists last regime
Stores history
Prevents duplicate alerts
State is stored as JSON — simple, portable, and GitHub-safe.
📂 Input Requirements (Important)
This agent only accepts price history CSVs in wide format.
✅ Valid Input Example date,SPY,QQQ,IWM,TLT,GLD 2024-01-02,470,410,190,93,180 2024-01-03,472,412,191,92.8,181 ...
Required
date column
At least one market index (e.g. SPY)
Recommended
Risk-off proxy (TLT)
Multiple assets for breadth
❌ Invalid Inputs
Do not upload:
Trade logs (trades.example.csv)
Execution history
Journals
Order data
Those belong to other agents (e.g. Trade Journal, Execution Discipline).
Uploading non-price CSVs may cause unrelated errors if other agents exist in the same project.
📏 Data Length & NaN Behavior
This agent uses rolling windows:
MA50 / MA200
20-day realized volatility
Breadth across assets
If your dataset has insufficient rows (typically < 200):
Some signals will be NaN
Confidence will be reduced
Regime classification will be conservative
No alerts will be fired
This is expected behavior.
The agent does not fabricate missing data.
🚦 Confidence Score
Confidence reflects signal completeness, not correctness.
1.00 → all signals available
0.75 → most signals available
0.25 → insufficient data
Low confidence means:
“Use this as rough context, not a strong regime call.”
🗂 Memory & State
State is stored in:
state/memory.json
It tracks:
Last regime
Last alert date
Regime history
This enables:
Change detection
Alert deduplication
Longitudinal analysis
No databases required.
🖥 Running the App Install pip install -r requirements.txt
Run streamlit run app.py
Upload a valid price CSV or load the included sample file.
🧪 Testing Strategy (Recommended)
Run with ≥ 1 year of daily data
Confirm regime stability across days
Introduce a synthetic drawdown to test regime change
Verify alerts fire once per transition
Confirm memory persists across runs
This agent is tested for stability and interpretability, not prediction accuracy.
🔌 Integration with Other Agents
MarketRegimeAgent is designed to be upstream context for:
Portfolio risk analysis
Sentiment interpretation
Trade journal diagnostics
Execution discipline enforcement
It improves downstream decisions without modifying them.
🔮 Future Extensions (Optional)
Optional LLM explanation layer
Live data adapters (yfinance, FRED, etc.)
Regime persistence (N-day confirmation)
Cross-asset confirmation
Multi-regime labeling
These are enhancements — not requirements.
🎯 Summary
MarketRegimeAgent is a real agent, not a demo.
It is:
Offline
Deterministic
Transparent
Stateful
Integration-ready
If you are looking for predictions or automated trading, this is not the right tool.
If you want clear market context to support human decision-making, this agent is built for exactly that.