# 🤖 Hermes Stock Bot — Documentation

**Autonomous AI-powered stock trading bot** — paper trade, analyze, then go live.

---

## Quick Start

### 1. Extract the package

```bash
tar xzf hermes-stock-bot-v1.0.0.tar.gz
cd hermes-stock-bot-v1.0.0
```

### 2. Set up credentials

```bash
cp .env.example .env
# Edit .env with your Robinhood and API credentials
nano .env
```

### 3. Install dependencies

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 4. Start paper trading

```bash
python3 run_paper.py
```

That's it! The bot starts analyzing stocks immediately and paper trades with live market data.

---

## Features

| Feature | Description |
|---------|-------------|
| 📈 **500+ Stock Scan** | Automatically screens the market for momentum and growth opportunities |
| 🧠 **AI Analysis** | LLM-powered buy/sell decisions with explainable reasoning |
| 💰 **Paper Trading** | Virtual portfolio — trade live markets with fake money |
| ⚡ **Live Trading** | Connect your real Robinhood account when you're ready |
| 🛡️ **Risk Management** | Position sizing, drawdown limits, volatility targeting, circuit breakers |
| 📊 **Dashboard** | Flask web dashboard showing portfolio, P&L, recent trades |
| 🔄 **Multiple Strategies** | Momentum breakout, event-driven, earnings plays, and simple strategy |
| 📝 **Daily Reports** | Automatic performance summaries with P&L and trade logs |

---

## Commands

### Paper Trading (start here)

```bash
# Full paper trading with live data
python3 run_paper.py

# Or use the shell wrapper
bash daily_paper.sh
```

### View Status

```bash
python3 view_monitor_status.py
```

### Performance Summary

```bash
python3 performance_summary.py
```

### Run Tests

```bash
python3 run_test.py              # Quick analyzer + signal test
python3 test_install.py          # Verify dependencies
python3 test_llm_analyst.py      # Test AI analysis pipeline
```

### 24/7 Monitor (advanced)

The bot can run as a background service that continuously monitors the market:

```bash
# Launch the 24/7 monitor
bash launch_monitor.sh

# Launch the dashboard
bash launch_dashboard.sh
```

---

## Configuration

All configuration is done through **environment variables** in `.env`:

| Variable | Required | Description |
|----------|----------|-------------|
| `ROBINHOOD_USERNAME` | Yes | Your Robinhood login email |
| `ROBINHOOD_PASSWORD` | Yes | Your Robinhood password |
| `ROBINHOOD_MFA_SECRET` | No | TOTP secret for 2FA. Leave blank to use SMS |
| `DEEPSEEK_API_KEY` | Yes | API key for AI-powered stock analysis |
| `FINNHUB_API_KEY` | No | Free API key for live price streaming |
| `DISCORD_WEBHOOK_URL` | No | Discord webhook for daily trading reports |

### Trading Strategies

Four built-in strategies are available, configurable in `config/`:

- **Momentum Breakout** — Catches stocks breaking out of resistance
- **Event-Driven** — Trades around news and catalyst events
- **Earnings Play** — Pre/post earnings momentum
- **Simple Strategy** — Basic trend following with risk controls

---

## Architecture

```
hermes-stock-bot/
├── monitor.py                  # Main 24/7 autonomous trading brain
├── run_paper.py                # Paper trading runner
├── run_test.py                 # Quick signal test
├── core/
│   ├── trader.py               # Robinhood API wrapper
│   ├── paper_portfolio.py      # Virtual portfolio engine (+P&L)
│   ├── position_sizer.py       # Risk-based position sizing
│   ├── session_memory.py       # Trading decision memory
│   └── trade_learner.py        # Pattern learning from trades
├── analysis/
│   ├── market_analyzer.py      # Technical + sentiment analysis
│   ├── llm_analyst.py          # AI-powered decision making
│   ├── growth_screener.py      # 500+ stock screener
│   ├── risk_monitor.py         # Circuit breakers + risk rules
│   └── bot_drive.py            # Autonomous drive logic
├── strategies/
│   ├── momentum_breakout.py    # Momentum strategy
│   ├── event_driven.py         # Event-driven strategy
│   ├── earnings_play.py        # Earnings plays
│   └── simple_strategy.py      # Simple trend following
├── backtesting/
│   └── simple_backtester.py    # Historical strategy replay
├── dashboard/
│   └── app.py                  # Flask web dashboard
├── scripts/
│   ├── cooldown_guard.py       # Trading cooldown enforcement
│   └── ...
├── config/
│   └── monitor_config.json     # Bot configuration
├── .env.example                # Environment template
├── setup.sh                    # One-command setup
└── requirements.txt            # Python dependencies
```

---

## Going Live

⚠️ **Paper trade for at least 2 weeks before considering live trading.**

When you're ready:

1. Make sure your paper portfolio is consistently profitable
2. Review your trade logs and AI decision quality
3. Enable live trading in `config/monitor_config.json`
4. Start with a small amount you can afford to lose
5. Monitor daily for the first week

### Risk Warnings

- **Never trade money you can't afford to lose**
- Start with paper trading only
- The bot uses AI that can make mistakes
- Market conditions can change rapidly
- Past performance does not guarantee future results

---

## Project Structure

File count: **26+ files**
Languages: **Python 3.10+**
Dependencies: robin-stocks, yfinance, pandas, numpy, openai, flask
License: **Personal use — not for redistribution**