Finance Bro Bot

A sophisticated Discord bot powered by a fine-tuned Qwen2.5-14B language model, specializing in financial analysis, stock recommendations, and market insights. The bot combines real-time market data from Yahoo Finance and SEC EDGAR filings with a custom-trained LLM to provide comprehensive stock analysis with a distinctive "finance bro" personality.

Project Overview

Finance Bro Bot is a complete end-to-end solution that includes:

• Discord Bot Interface: Responds to mentions and DMs with financial analysis
• LLM: Qwen2.5-14B model with RAG (previously fine-tuned with QLoRA, now uses retrieval-augmented generation)
• Real-time Data Integration: Yahoo Finance quotes, news, and SEC EDGAR filings
• Technical Analysis: RSI, MACD, Bollinger Bands, SMA/EMA, and more
• Document RAG: PDF document search for reference materials
• Containerized Deployment: Docker Compose setup with llama.cpp server

Key Features

Feature	Description
Stock Quotes	Real-time prices via Yahoo Finance with fallback APIs
Extended Hours Prices	Pre-market and after-hours quotes via Yahoo Finance
Technical Indicators	RSI, MACD, SMA, EMA, Bollinger Bands, Stochastic
News Sentiment	3-model ensemble (FinBERT + Twitter-RoBERTa + keywords) with LLM materiality layer
SEC Filings	Pulls financial statements from SEC EDGAR XBRL API
Recommendations	Buy/Hold/Sell recommendations with timeframe options
Macro Alerts	Real-time economic release detection (NFP, CPI, PPI, FOMC, GDP)
Macro-Weighted Recs	Macro signals weight 50%/25%/13% in short/medium/long recommendations
Watchlist System	Per-user watchlists with price tracking and alerts
Hourly Summaries	Automated price updates at the top of each hour
Conversation Memory	Per-user conversation history for context
PDF Knowledge Base	Reference document search and retrieval

---

Table of Contents

1. Quick Start
2. Project Structure
3. Configuration
4. Running the Bot
5. Training Pipeline
6. Documentation

---

Quick Start

Prerequisites

• Docker and Docker Compose
• NVIDIA GPU with 16GB+ VRAM (for llama.cpp inference)
• Discord Bot Token (create one here)

Installation

# Clone the repository
git clone <repo-url>
cd finance-bro-bot

# Copy environment template
cp .env.template .env

# Edit .env and add your Discord bot token
nano .env

# Start the services
docker compose up -d

# Check logs
docker compose logs -f discord-bot

---

Project Structure

finance-bro-bot/
├── config/                  # Configuration files
│   ├── settings.py          # Application settings (env vars)
│   ├── init_prompt.txt      # Bot personality configuration
│   └── ignored_words.txt    # Words to ignore in ticker detection
├── src/                     # Source code
│   ├── bot/                 # Discord bot implementation
│   │   ├── discord_client.py    # Main bot client
│   │   └── commands.py          # Slash commands
│   ├── data/                # Data persistence
│   │   └── watchlist_db.py      # SQLite watchlist database
│   ├── finance/             # Financial data services
│   │   ├── stock_data.py        # Alpaca, Yahoo Finance, SEC EDGAR integration
│   │   └── recommendation.py    # Hybrid recommendation engine (8 signal sources)
│   ├── macro/               # Macro economic signals (see src/macro/macro_readme.md)
│   │   ├── data_sources.py      # yfinance overnight snapshot + FRED API
│   │   ├── cross_asset.py       # 7-9 signal cross-asset scorer
│   │   ├── release_monitor.py   # FRED releases + BLS API + FRED series + Fed RSS + alert formatting
│   │   └── macro_readme.md      # Full macro system documentation
│   ├── performance/         # Model performance analysis (see src/SRC_README.md)
│   │   ├── data_access.py       # SQL queries + TTL caching against performance/predictions schemas
│   │   ├── model_report.py      # Per-model health scoring + trend detection
│   │   ├── charts.py            # matplotlib chart generation (dark theme) → BytesIO
│   │   ├── llm_context.py       # LLM integration: query parsing, screeners, agreement analysis
│   │   ├── signal_context.py    # Per-stock signal quality lookup
│   │   ├── stock_surfacing.py   # Ranked signal surfacing from predictions tables
│   │   ├── weight_adjuster.py   # Informational weight analysis (does NOT change FBB)
│   │   └── test_webhook.py      # Posts charts + tables to #stonk-performance webhook
│   ├── alerting/            # Day trader alert system
│   │   └── __init__.py          # Price history, SMA alerts
│   ├── llm/                 # LLM client
│   │   └── client.py            # OpenAI-compatible API client
│   └── documents/           # Document processing
│       └── pdf_loader.py        # PDF loading and search
├── rl_agent/                # RL Trading Agent (separate project)
│   ├── src/                 # Agent source code
│   ├── config/              # Agent configuration (portfolios.yaml)
│   ├── docs/                # Guides (multi_portfolio_guide.md)
│   ├── models/              # Trained model checkpoints (not in git)
│   ├── logs/                # Training logs (not in git)
│   ├── tensorboard/         # TensorBoard logs (not in git)
│   ├── tests/               # Agent tests
│   └── README_RL_AGENT.md   # RL Agent documentation
├── db/                      # Database files
│   ├── watchlist.db             # SQLite database
│   └── WATCHLIST_README.md      # Watchlist documentation
├── training/                # Model fine-tuning pipeline (for LLM)
│   ├── prepare_data.py      # Convert PDFs to training data
│   ├── finetune.py          # Single-GPU fine-tuning script
│   ├── finetune_multigpu.py # Multi-GPU fine-tuning with early stopping
│   ├── merge_lora.py        # Merge LoRA weights with base model
│   ├── convert_hf_to_gguf.py    # Convert to GGUF format
│   └── data/                # Training data (generated)
├── models/                  # GGUF model files
├── data/                    # PDF reference documents
├── logs/                    # Application logs
├── docker-compose.yml       # Container orchestration
├── requirements.txt         # Python dependencies
├── .env                     # Environment variables (not in git)
└── .env.template            # Environment variable template

---

Root Directory Files

docker-compose.yml

Orchestrates the two-container setup:

• llama-server: llama.cpp server running the fine-tuned GGUF model with CUDA acceleration
• discord-bot: Python Discord bot that connects to the LLM server

requirements.txt

Python dependencies for the Discord bot:

• discord.py - Discord API wrapper
• aiohttp - Async HTTP client for LLM API
• yfinance - Yahoo Finance data
• pymupdf - PDF text extraction

.env.template

Template for required environment variables:

DISCORD_BOT_TOKEN=your_token_here
LLM_API_BASE=http://llama-server:8000
LLM_MODEL_NAME=finance-bro-v2-q4_k_m
fred_key=your_fred_api_key          # Free at https://fred.stlouisfed.org/docs/api/api_key.html
BLS_API_KEY=your_bls_api_key        # Free at https://data.bls.gov/registrationEngine/

---

Configuration

See config/CONFIG_README.md for detailed configuration documentation.

Key configuration files:

• config/settings.py - Environment-based settings (tokens, API URLs, model params)
• config/init_prompt.txt - Bot personality and behavior instructions
• config/ignored_words.txt - Words to exclude from ticker detection

---

Running the Bot

With Docker (Recommended)

# Start all services
docker compose up -d

# View logs
docker compose logs -f discord-bot

# Restart after code changes
docker compose restart discord-bot

# Stop everything
docker compose down

Locally (Development)

# Install dependencies
pip install -r requirements.txt

# Run the bot (requires llama-server running separately)
python -m src.bot.discord_client

---

Training Pipeline

See training/TRAINING_README.md for detailed training documentation.

Overview

The training pipeline fine-tunes Qwen2.5-14B on financial documents using QLoRA:

1. Data Preparation: prepare_data.py converts PDFs to chat-format training data
2. Fine-tuning: finetune_multigpu.py trains LoRA adapters with early stopping
3. Merging: merge_lora.py combines LoRA weights with the base model
4. Conversion: convert_hf_to_gguf.py creates GGUF files for llama.cpp

Quick Training

# Prepare training data from PDFs
python training/prepare_data.py

# Fine-tune (on GPU)
CUDA_VISIBLE_DEVICES=1 python training/finetune_multigpu.py

# Merge LoRA and convert to GGUF
python training/merge_lora.py
python training/convert_hf_to_gguf.py --outfile models/new-model.gguf

---

Documentation

Document	Description
config/CONFIG_README.md	Configuration files and settings
src/SRC_README.md	Source code architecture and modules (includes performance analysis module)
db/WATCHLIST_README.md	Watchlist system, price tracking, and news sentiment
training/TRAINING_README.md	Fine-tuning pipeline and scripts
rl_agent/README_RL_AGENT.md	RL Trading Agent documentation
rl_agent/docs/multi_portfolio_guide.md	Adding a new portfolio — step-by-step guide for multi-portfolio setup
src/macro/macro_readme.md	Macro system architecture — cross-asset scoring, FRED/BLS/Fed RSS release detection, FOMC same-day capture, impact scoring, recommendation integration
recommendation_analysis/recommendation_analysis.md	Recommendation methodology — all 8 signals, scoring formulas, timeframe weights, risk assessment guide, backtest analysis (76K predictions, factor research, cross-sectional normalization)
rl_agent/tests/startup_validation_readme.md	RL Agent startup validation checks + pytest test suite documentation

---

RL Trading Agent (V2.5)

The RL Trading Agent is a separate project within this repository that uses reinforcement learning to make autonomous trading decisions on Alpaca paper trading.

Overview

• Algorithm: DQN (off-policy, reuses replay buffer for sample efficiency)
• State Space: 67 features (20 Rules Engine + 6 FBB + 30 macro + 11 portfolio)
• Action Space: 39 discrete actions (24 long + 15 short/cover — HOLD, market/limit orders, stop-loss, trailing stop, short sell, cover)
• Multi-Portfolio: Multiple Alpaca accounts share one DQN brain. Per-portfolio constraints via action masking. See multi-portfolio guide.
• Reward: Position-based mark-to-market P&L + alpha vs SPY + risk/profit-taking pressure + signal alignment
• Data Sources: Rules Engine signals, FBB hybrid recommendations, Alpaca portfolio state, 6 macro instruments × 5 timeframes

Key Features

Feature	Description
Live Paper Trading	Executes real orders on Alpaca paper account
Dual Signal Sources	Rules Engine (BUY signals) + Finance Bro Bot (confirmation + SELL signals)
Alpha Tracking	Rewards beating SPY at portfolio and position level
Portfolio-Weighted Rewards	Position size relative to portfolio scales all reward components
Early Episode Termination	Episodes end on full position exit — prevents sell-then-rebuy churn
Exit Mode Lock	After first sell, only SELL/HOLD allowed for remainder of episode
Hard Stop-Loss	Positions at -25% (bearish FBB) or -35% force-sold, bypassing DQN
Hourly Discord Diagnostics	Reward breakdown, rejection rate, action distribution, KL divergence
Risk Management	Quadratic drawdown escalation, holding cost, cash reserve, PDT checks
Discord Alerts	Trade notifications, portfolio status, reward summaries

Episode Parameters

Parameter	Value	Rationale
steps_per_ticker	30	5 min of price action at 10s intervals. Sell episodes terminate early (~1 min).
step_interval_seconds	10	Enough for liquid stocks to tick between steps.
tickers_per_episode	20	Covers more portfolio per batch cycle.
buffer_size	100K	Clean data dominates in 2-3 days, not weeks.
Review losers (DQN)	10	Top 10 worst positions get DQN episodes per review cycle.
Review winners (DQN)	5	Less urgent than losers.
Hard stop-loss	Instant	Positions past -25% (bearish FBB) or -35% force-sold immediately, no episode needed.
Review interval	15 min	Portfolio review fires between episodes, not between batches.

Quick Start

# Start the RL agent container
docker compose up -d rl-agent

# View training logs
docker compose logs -f rl-agent

# Rebuild after pip dependency changes
docker compose build rl-agent && docker compose up -d rl-agent

# Note: rl_agent/ is volume-mounted, code changes are live (restart only)
docker compose restart rl-agent

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Rules Engine   │────▶│   RL Agent      │────▶│  Alpaca API     │
│  + FBB Signals  │     │  (DQN)          │     │  (Paper Trading)│
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  Discord/DB     │
                        │  - Trade alerts │
                        │  - Reward diag  │
                        │  - PostgreSQL   │
                        └─────────────────┘

Performance Bottleneck & Scaling Roadmap

The primary bottleneck is wall-clock time, not compute. Each 10-second step is ~98% idle (sleeping + waiting on API responses). The GPU (Tesla P40) does a single DQN forward pass in <1ms per step — massively underutilized.

Alpaca API rate limit: 200 req/min per account (hard limit, no self-service increase). Each episode uses ~35 API calls over 5.5 min (~6 req/min). This constrains practical parallelism to ~30 concurrent episodes before throttling.

Phase	Speedup	Complexity	Status
Per-episode portfolio review	Hard stop-loss latency: 7h → 5.5 min	Low	Done
Parallel episodes (4-6 threads)	4-6x throughput (~25 min batches)	Moderate	Planned
Alpaca WebSocket streaming	Eliminates ~33 REST calls/episode, enables 30+ parallel episodes	High	Future

Parallel episodes would require synchronization around the replay buffer (not thread-safe), trade executor (shared portfolio state), and reward calculator (per-episode state). The Alpaca WebSocket streaming API (wss://stream.data.alpaca.markets for quotes, wss://api.alpaca.markets/stream for trade updates) would replace REST polling, reducing API usage from ~35 calls/episode to ~2 (order submissions only).

See rl_agent/README_RL_AGENT.md for full documentation.

---

Macro Alert System

The bot monitors economic releases in real-time and posts alerts to #stockstuff, adjusting a macro score that feeds into all stock recommendations. For full architecture details, see src/macro/macro_readme.md.

Data Sources

Source	Purpose	API Key Required
FRED Releases API	Economic calendar (15 tracked releases)	Yes (fred_key)
BLS Public Data API	Real-time NFP, CPI, unemployment data	Optional but recommended (BLS_API_KEY)
yfinance	Overnight cross-asset signals (Nikkei, DAX, VIX, DXY, etc.)	No

Tracked Releases (FRED)

Employment Situation (NFP), Consumer Price Index, Producer Price Index, FOMC Press Release, Advance Retail Sales, GDP, Unemployment Insurance Claims, ADP Employment, ISM Manufacturing, ISM Services, Housing Starts, Employment Cost Index, Durable Goods Orders, Personal Income and Outlays, Housing Vacancies.

Tracked BLS Series

Series	ID	Description
Nonfarm Payrolls	CES0000000001	Total employment (thousands)
Unemployment Rate	LNS14000000	U-3 rate (%)
CPI All Items	CUUR0000SA0	Consumer price index

Alert Flow

1. 6 AM ET: Morning brief with cross-asset signal + today's FRED release schedule
2. 7:30 AM - 4 PM ET (every 3 min): FRED detects new releases, BLS API detects new data values
3. On release: Discord embed with actual, previous, change, market impact score
4. Macro score (-2.0 to +2.0) adjusts and feeds into all recommendation weights

Recommendation Weights

The macro score is weighted by timeframe (macro events dominate short-term price action):

Component	Short	Medium	Long
Macro	50%	25%	13%
Technical	15%	22%	22%
LLM	13%	19%	14%
News (hybrid)	10%	12%	8%
Analyst	5%	10%	8%
Options	5%	6%	4%
Earnings	2%	6%	9%
SEC Statements	0%	0%	22%

---

Performance Analysis System

The bot includes a performance analysis module (src/performance/) that tracks how 6 prediction models perform against realized 5-day forward returns. This system is read-only — it does not modify FBB's recommendation engine.

Models Tracked

Model	What It Predicts	Key Metrics
XGB Classifier	4-class probability (>+10%, <-10%, middle bands)	Calibration error, predicted vs actual rate
CS-MLP Forecast	Continuous return + conformal intervals	Rank correlation, D10-D1 spread, conformal coverage
Rules Engine	Tier (T0-T3) + action (BUY/SELL/HOLD)	Tier alpha spread vs T0 baseline
Macro Gate	Tail risk score, gate threshold	Gated vs ungated forward returns
Finance Bro Bot	Rating (strong_sell → strong_buy) × horizon	Bull-bear spread, rank correlation
Momentum	Short signal quality by tier	Short P&L by tier over time

Discord Integration

Channel: #stonk-performance (via webhook)

Trigger phrases (mention the bot in #stockstuff):

• "rules engine recommendation on AAPL" — per-stock analysis with tier, XGB probs, CS-MLP return + confidence interval
• "top 10 signals" — ranked stocks from all prediction models
• "any stocks with xgb > 70%?" — natural language screener (XGB, CS-MLP, tier filters)
• "do FBB and rules engine agree?" — model agreement/disagreement analysis
• "rules engine help" — show all available query types

Slash commands:

• /performance [model] — model report card + charts (xgb, cs, rules, macro, fbb, momentum, all)
• /signals [count] — top ranked signals from prediction tables

Charts

Chart	Description
Model Health Dashboard	2×3 grid with key metric trend per model
XGB Four-Class	Predicted probability vs actual hit rate for all 4 target classes
XGB Calibration	Scatter plot of predicted vs actual for both tail classes
Tier Alpha	Avg returns by tier + tier spread vs T0 baseline over time
Rating Returns	FBB rating performance by horizon with observation counts
Macro Gate	Tail risk score vs market forward return
Momentum Short	Short P&L by tier over time
Top Signals	Horizontal bar chart of ranked stocks with score breakdown
Intraweek	Day-by-day alpha buildup within the evaluation week

Automated Digests

Posted to #stonk-performance via webhook (see src/performance/test_webhook.py):

• Top signals table with composite ranking
• All chart types
• Weight analysis summary (informational only)

For module details, see src/SRC_README.md.

---

Bot Commands

Slash Commands

Command	Description
/quote SYMBOL	Get real-time stock quote
/news SYMBOL	Get recent news for a stock
/watch SYMBOL	Add a stock to your personal watchlist
/unwatch SYMBOL	Remove a stock from your watchlist
/watchlist	View your current watchlist with prices
/ask QUESTION	Ask the bot a question
/docs	List loaded reference documents
/status	Check bot and LLM server status
/reset	Clear your conversation history
/performance [model]	Model performance report cards + charts
/signals [count]	Top ranked signals from prediction models
/help	Show available commands

Text Commands (via @mention)

You can also use these commands by mentioning the bot:

• @Finance Bro Bot /watch AAPL, TSLA - Add multiple stocks to watchlist
• @Finance Bro Bot /unwatch AAPL - Remove from watchlist

Mentions

Mention the bot in the #stockstuff channel (configurable) to interact:

@Finance Bro Bot what's your recommendation on AAPL?

The bot will ask for your timeframe (short/medium/long-term) before providing analysis.

---

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Discord API   │────▶│  Discord Bot    │────▶│  llama.cpp      │
│                 │◀────│  (Python)       │◀────│  Server (CUDA)  │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  External APIs  │
                        │  - Yahoo Finance│
                        │  - Alpaca       │
                        │  - FRED API     │
                        │  - BLS API      │
                        │  - SEC EDGAR    │
                        └─────────────────┘
                               ▲
                               │
┌─────────────────┐     ┌─────────────────┐
│  Rules Engine   │────▶│  RL Trading     │────▶ Alpaca Paper Trading
│  + FBB Signals  │     │  Agent (DQN)    │────▶ Discord Alerts
└─────────────────┘     └─────────────────┘────▶ PostgreSQL Logging

---

Data Sources

Data Type	Source	Notes
Regular hours prices	Alpaca (batch)	Fast, reliable, 100 symbols/call
Extended hours prices	Yahoo Finance	Pre-market and after-hours via yfinance 1.0
News headlines	Yahoo Finance RSS	Falls back to API if RSS fails
Fundamentals	Finnhub + SEC EDGAR	P/E, EPS, revenue, etc.
Insider transactions	Finnhub	Recent buys/sells
Economic calendar	FRED Releases API	15 tracked high-impact releases
Economic data (NFP, CPI)	BLS Public Data API	Real-time series polling with registered key
Macro series (fed funds, etc.)	FRED Series API	Historical + latest observations
Cross-asset signals	yfinance	Overnight international indices + VIX/DXY/crude/gold

---

Background Tasks

The bot runs several automated tasks:

Task	Schedule	Description
morning_macro_snapshot	6 AM ET daily	Pre-market brief: cross-asset signals + today's FRED release schedule
intraday_calendar_poller	Every 3 min (7:30 AM - 4 PM ET)	Polls FRED releases + BLS API for new economic data, posts alerts, adjusts macro score
hourly_watchlist_summary	Top of each hour (5 AM - 7 PM ET)	Posts price summary for all watchlisted stocks
market_open_summary	9:30 AM ET daily	Posts opening prices for watchlist stocks
watchlist_price_updater	Every 10 min	Updates cached prices for watchlist and alert calculations
news_sentiment_updater	15 min (market) / 2 hr (off)	Fetches news and scores sentiment
health_monitor	Every 15 min	Checks LLM server health
account_position_sync	Every hour	Syncs Alpaca account positions
watchlist_expiry_checker	9 AM ET daily	Checks for expiring watchlist items
performance digest	Via webhook (manual/scheduled)	Posts model charts + top signals to #stonk-performance

---

Regression Testing & Quality Checklist

When making changes to the bot, verify the following functionality:

Critical Output Format Tests

Test a recommendation request (e.g., @Finance Bro Bot short term recommendation on AAPL) and verify:

Check	Expected	File Location
Price displayed correctly	**TICKER - $XX.XX** (+/-X.XX% today) with exact price from Yahoo Finance	discord_client.py:834-848
Technical Analysis section	RSI, SMA 20/50, MACD, Volume all present with values	discord_client.py:850-886
News Sentiment with scores	Each headline shows - "headline" (source) - **+/-X.X** (Label)	discord_client.py:889-955
Overall Sentiment score	**Overall Sentiment: +/-X.XX (Label)** at end of news section	discord_client.py:942-953
Recommendation line	**Recommendation:** [action] - [reason]	discord_client.py:401
Key Risks line	**Key Risks:** [brief risk]	discord_client.py:402
No hallucinated prices	Price matches actual Yahoo Finance data, not made up	Verify against /quote TICKER

Known Issues to Watch For

1. Model ignores format instructions: The V3 fine-tuned model may ignore system prompts. The hybrid approach in _build_recommendation_response() pre-formats data to work around this.

2. Chinese characters in output: The model sometimes outputs Chinese text. Filtered via re.sub(r'[\u4e00-\u9fff]+', '', response) in discord_client.py:392.

3. Price hallucination: If the model makes up prices instead of using provided data, check that market_data_context is being passed correctly in the system prompt.

4. Repetition loops: If the model repeats itself, verify repeat_penalty, frequency_penalty, and presence_penalty in llm/client.py:73-76.

5. News dates from distant past: News is now filtered to prioritize articles from the last 7 days, falling back to 7-30 day old articles only if needed. Articles older than 30 days are excluded. See _filter_news_by_recency() in stock_data.py.

Sentiment Scoring

News sentiment uses a 4-pillar hybrid approach (FinBERT + keywords + LLM sentiment + materiality weighting). See recommendation_analysis/recommendation_analysis.md for full details.

Testing Commands

# Test inside container
docker exec finance-bro-bot python3 -c "
import asyncio
from src.finance.stock_data import StockDataService

async def test():
    quote = await StockDataService.get_quote('AAPL')
    print(f'Price: {quote.get(\"price\")}')
    indicators = await StockDataService.get_technical_indicators('AAPL')
    print(f'RSI: {indicators.get(\"rsi_14\")}')

asyncio.run(test())
"

# Check bot logs
docker compose logs --tail=50 discord-bot

# Restart after changes
docker compose restart discord-bot

Model Configuration

Current model: finance-bro-v3-q4_k_m (configured in docker-compose.yml:78)

LLM parameters in llm/client.py:

• temperature: 0.3 (from settings)
• repeat_penalty: 1.5
• frequency_penalty: 0.7
• presence_penalty: 0.5
• stop: ["---", "signing off", "See ya", "Remember:", "Note:"]

---

License

This project is for educational purposes. Not financial advice.

---

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

For questions or issues, open a GitHub issue.