Skip to content
BranchesTags

Repository files navigation

Stock Analysis Agent

Quantitative stock analysis with 5 engines, regime detection, adaptive learning, and paper trading

Python 3.9+ Streamlit License: MIT Cost


83 market packages • 3,800+ symbols • 6 global regions • runs 100% local


This is NOT financial advice. Educational and research purposes only. No guarantees of returns.


Highlights

5 Analysis Engines Momentum, Fundamental, Technical, Sector Rotation, and Mean Reversion — each regime-aware with adaptive weighting that learns from outcomes.

Market Regime Detection Classifies markets as Trending Up/Down, Range-Bound, or High Volatility using SPY, VIX, breadth, and 4 lead indicators for early warnings.

Paper Trading + Kelly Sizing Prove your edge with virtual money before risking capital. Half-Kelly position sizing, automatic stop losses, staged profit taking.

Self-Improving System Every analysis feeds a learning database. After 30 days, adaptive weights automatically boost engines that perform and reduce those that don't.

Quick Start

git clone https://github.com/sreedeepkesav/aggressive-stock-agent.git
cd aggressive-stock-agent

python3 -m venv venv
source venv/bin/activate          # Linux / macOS
# venv\Scripts\activate           # Windows

pip install -r requirements.txt
cp .env.example .env              # works out of the box (LLM_MODE=off, $0 cost)

streamlit run app.py              # launch dashboard at localhost:8501

No API keys needed. Zero cost by default.

Important: Every command below assumes you're inside the project folder with the venv active. If you see ModuleNotFoundError or command not found, run source venv/bin/activate first.


Table of Contents



Dashboard

cd aggressive-stock-agent
source venv/bin/activate       # always activate venv first

streamlit run app.py

Opens at http://localhost:8501. Dark theme with regime-colored banners, Altair charts, and gradient metric cards.

Page What it does
Dashboard Regime status, engine accuracy chart, confidence calibration curve, regime change log
Analyze Deep-dive a single ticker across all 5 engines. Insider activity panel, risk assessment
Scan Scan any of the 83 watchlist packages. Filter by confidence, agreement, actionability
Paper Trade Virtual trading with equity curve, run cycles, full trade log, engine attribution
Portfolio Live positions, trade history, exit signals with urgency levels
Backtest Walk-forward backtesting — fast mode (instant) or full mode (real combiner + costs)
Discover Reddit trending tickers + RSS financial news
Settings LLM mode, risk params, API keys, alert config (email / webhook)


CLI Usage

Make sure venv is active before running any command: source venv/bin/activate

# Is the market safe right now?
python stock_agent.py ticker SPY

# Should I buy NVDA?
python stock_agent.py ticker NVDA

# What's the best semiconductor stock today?
python stock_agent.py scan 10 --package sector_semiconductors

# Show me top AI stocks
python stock_agent.py scan 5 --package theme_ai

# List all 83 available packages
python stock_agent.py packages

# Would this strategy have worked historically?
python stock_agent.py backtest 6 --package us_mega_cap --fast

# Full backtest with real costs
python stock_agent.py backtest 12 --package mega_cap_tech

# What are people buzzing about on Reddit?
python stock_agent.py discovery

# View portfolio + exit signals
python stock_agent.py portfolio show
python stock_agent.py portfolio stats

# Configure settings interactively
python stock_agent.py settings


Paper Trading

Prove the system works with real market data and virtual money before putting capital at risk.

Make sure venv is active: source venv/bin/activate

# Paper trade specific stocks
python -m portfolio.paper_trader --symbols NVDA AAPL MSFT TSLA AMD

# Paper trade an entire package
python -m portfolio.paper_trader --package mega_cap_tech

# Paper trade your active watchlist
python -m portfolio.paper_trader

# Check how your paper portfolio is doing
python -m portfolio.paper_trader --summary

Position sizing uses half-Kelly criterion (clamped to 25% max per position). Falls back to 1% risk when fewer than 10 trades in history.

Exit rules: trailing stop (ATR-based), staged profit taking at 2R/3R/5R, time exit at 30 days.

Automate with cron (recommended)

Run paper trading + learning seeder every weekday at 6 PM EST:

crontab -e
# Seed learning system (builds data for adaptive weights)
0 18 * * 1-5 cd /path/to/aggressive-stock-agent && venv/bin/python seed_learning.py >> logs/seed.log 2>&1

# Paper trading cycle
30 18 * * 1-5 cd /path/to/aggressive-stock-agent && venv/bin/python -m portfolio.paper_trader >> logs/paper_trade.log 2>&1

After 30+ days, the adaptive weight system kicks in automatically.



API Keys (Optional)

Set in .env. None required for basic operation.

Key Purpose Cost
ALPHA_VANTAGE_API_KEY Auto-fallback when Yahoo Finance fails Free (25/day)
ANTHROPIC_API_KEY AI-powered analysis summaries ~$0.01/run
SEC_API_KEY Enhanced SEC filing data Free
REDDIT_CLIENT_ID / SECRET Reddit ticker discovery Free
Where to get each key

To enable AI summaries:

LLM_MODE=haiku    # cheap summaries (~$0.0003/run)
LLM_MODE=sonnet   # deep analysis (~$0.01/run)


Regime Change Alerts

Get notified when the market regime shifts (e.g., TRENDING_UP -> HIGH_VOLATILITY).

Configure in Settings > Alerts or in .env:

# Email
ALERT_EMAIL_TO=you@example.com
ALERT_SMTP_HOST=smtp.gmail.com
ALERT_SMTP_PORT=587
ALERT_SMTP_USER=you@gmail.com
ALERT_SMTP_PASS=your-app-password

# Webhook (Slack, Discord, Telegram)
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/...


Risk Parameters

All tunable via .env or the Settings page. Defaults are conservative:

Parameter Default What it controls
MAX_POSITION_PCT 10% Max allocation per position
MAX_PORTFOLIO_HEAT 8% Max total portfolio at risk
DRAWDOWN_CIRCUIT_BREAKER -10% Halts all trading at this drawdown
MAX_SIMULTANEOUS_POSITIONS 5 Position count limit
MAX_SECTOR_CONCENTRATION 40% Max in one sector
CASH_RESERVE_PCT 20% Minimum cash reserve
MAX_POSITION_CORRELATION 0.75 Reject correlated positions


Architecture

stock_agent.py              Entry point
app.py                      Streamlit dashboard (8 pages, dark theme)
seed_learning.py            Daily learning seeder (cron-ready)

engines/
  signal_combiner.py        Regime-weighted combination of 5 engines
  momentum.py               RSI divergence, MACD, OBV, stochastic
  technical.py              Market structure, VWAP, Keltner, Bollinger
  fundamental.py            Dynamic sector P/E, ROIC, earnings quality
  sector.py                 Sector rotation, relative strength
  mean_reversion.py         Regime-gated oversold/overbought detection
  regime.py                 VIX, breadth, credit stress, yield curve
  timeframe.py              Weekly confirmation filter

portfolio/
  paper_trader.py           Paper trading + Kelly criterion sizing
  backtest.py               Walk-forward backtester (lookahead-free)
  risk.py                   Position limits, correlation, drawdown breaker
  memory.py                 Adaptive learning: predictions -> outcomes -> weights
  calibration.py            Confidence calibration (predicted vs actual)
  attribution.py            Per-engine contribution analysis
  tracker.py                Sharpe, win rate, vs SPY benchmarking
  state.py                  SQLite persistence layer
  exits.py                  Trailing stops, staged profit taking, time exits

data/
  market_data.py            yfinance + Alpha Vantage fallback
  alpha_vantage.py          Secondary data source (25 free calls/day)
  insider_signal.py         SEC EDGAR Form 4 insider analysis
  indicators.py             RSI, SMA, EMA, MACD, ATR, BB, OBV, ADX
  sector_cache.py           Dynamic sector median P/E from ETFs
  sec_edgar.py              SEC filing search
  earnings.py               Earnings calendar + blackout windows
  news.py                   RSS financial news
  reddit.py                 Reddit ticker mentions

alerts/
  regime_alerts.py          Regime change detection + email/webhook dispatch

config/
  settings.py               All configuration (env vars)
  watchlists.py             83 packages, 3800+ symbols
Signal flow 
detect_regime()              SPY/VIX/breadth + 4 lead indicators
       |                     -> TRENDING_UP | TRENDING_DOWN | RANGE_BOUND | HIGH_VOLATILITY
       v
engine.analyze()             Each of 5 engines -> signal + confidence + reasons
       |
       v
SignalCombiner.analyze()     Regime-adjusted weights + adaptive weights + earnings blackout
       |
       v
apply_timeframe_filter()     Weekly trend confirms or demotes daily signal
       |
       v
memory.save_analysis()       Save to SQLite for learning
       |
       v
memory.check_outcomes()      Fill actual returns after 5+ days
       |
       v
get_adaptive_weights()       Engines that work get more weight, those that don't get less
Market regime weights
Regime Momentum Fundamental Technical Sector Mean Rev
Trending Up 30% 20% 25% 15% 10%
Trending Down 10% 30% 15% 15% 30%
Range Bound 15% 25% 20% 10% 30%
High Volatility 10% 30% 10% 20% 30%
Global market coverage
Region Packages Symbols Examples
US 29 ~2,900 S&P 500, NASDAQ 100, 18 sector packages, Dividend Aristocrats
Europe 11 ~625 FTSE, DAX, CAC 40, SMI, Nordic
Asia-Pacific 12 ~975 Nikkei, KOSPI, NIFTY, Taiwan, ASX
Americas 5 ~270 TSX, Ibovespa, IPC
Middle East & Africa 2 ~75 Saudi, UAE, South Africa JSE
Thematic 22 ~700 AI/ML, Cybersecurity, Space, Quantum, Cannabis


Troubleshooting

ModuleNotFoundError: No module named 'yfinance'

You're not in the venv. Run source venv/bin/activate first.

streamlit: command not found

Same thing — activate the venv, or run venv/bin/streamlit run app.py directly.

Yahoo Finance returns empty data

Yahoo rate-limits aggressive usage. Set ALPHA_VANTAGE_API_KEY in .env for automatic fallback. Or wait a few minutes and retry.

portfolio.db is locked

Another process is using it. Kill any running streamlit or python processes.

Dashboard has import errors

Make sure you're on the latest commit:

source venv/bin/activate
git pull && pip install -r requirements.txt --upgrade


Development Phases

Phase Focus Key Changes
Phase 1 Fix The Foundation Backtester lookahead fix, monolith removal, correlation risk checks, dynamic sector P/E
Phase 2 Build The Trust Layer Dashboard UI overhaul, Alpha Vantage fallback, confidence calibration, regime alerting, learning seeder
Phase 3 Develop Real Edge Paper trading with Kelly criterion, SEC insider signals, performance attribution, engine agreement analysis


The system is designed to prove itself before you put money in.

Run paper trading for 30+ days. Watch the dashboard. Let the data tell you if it works.


This software is for educational and research purposes only. Not financial advice. Trading involves risk of loss. Always consult a licensed financial advisor.

About

AI-powered aggressive stock advisory agent with 8 institutional-grade analysis engines

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages