This project automates the detection of significant stock market "breakouts" before they become widely known, targeting traders and investors seeking actionable insights without constant market monitoring. It delivers curated, AI-analyzed stock alerts and market briefings directly to Discord or email, providing a competitive edge by highlighting stocks making decisive moves.

How It Works

The system automates stock breakout detection through a multi-stage pipeline. It leverages TradingView's screener API for real-time identification of stocks exhibiting significant price moves, high volume, and specific price/market cap criteria. Candidates then pass through an Alpaca-powered historical quality filter, discarding stocks with weak long-term performance to avoid noise. Finally, AI models (Gemini, GPT, or local Ollama) generate concise analyses of the breakout drivers, aggregate relevant news, and provide actionable insights. This layered approach ensures alerts are based on both immediate technical signals and underlying fundamental strength, enhanced by AI-driven context.

Quick Start & Requirements

• Primary Install: Clone the repository, install dependencies (pip install -r requirements.txt), and install browser automation tools (playwright install chromium).
• Run Command: python src/tradealerts.py.
• Core Requirements: Free Alpaca account with API keys, a Google Gemini API key (or alternative LLM setup), and a Discord webhook URL for notifications.
• Optional Enhancements: TradingView account for chart screenshots, Gmail OAuth for email alerts, and an Alpaca premium plan for enhanced data accuracy.
• Configuration: Primarily managed via config/config.json or environment variables.
• Setup Guide: Detailed steps are available in SETUP.md.

Highlighted Details

• Automated detection of stock breakouts using configurable filters for price, volume, and relative volume.
• AI-driven analysis (Gemini, GPT, Ollama) providing plain-English summaries of stock movements, news aggregation, and risk assessment.
• Comprehensive notification system delivering individual stock alerts, daily market briefings, and afternoon recaps via Discord and email.
• Multi-stage filtering process combining real-time technical indicators with historical performance validation.

Maintenance & Community

The provided README does not detail specific contributors, sponsorships, or community channels (e.g., Discord/Slack). It does include CONTRIBUTING.md and DISCLAIMER.md files.

Licensing & Compatibility

The project is released under the MIT License, permitting free use, modification, and distribution. No explicit restrictions for commercial use or closed-source linking are mentioned, aligning with the permissive nature of the MIT license.

Limitations & Caveats

The tool is strictly for informational and educational purposes, not financial advice, and past performance is not indicative of future results. Alert quality and data accuracy are dependent on the chosen Alpaca data feed (free IEX vs. paid SIP). Functionality is modular; omitting integrations like LLMs or TradingView will reduce the richness of alerts.