# Automated Trading System

Production-grade automated stock trading bot with FinBERT sentiment analysis, technical indicators, risk management, and a live Rich terminal dashboard.

## Overview

This project is a fully automated, algorithmic trading bot designed to trade U.S. equities via the Alpaca API. It utilizes a hybrid approach, combining technical analysis (RSI, MACD, Bollinger Bands, VWAP) with AI-driven sentiment analysis (FinBERT + VADER) to generate trading signals. The system features a strict, 8-layer risk management pipeline to ensure capital preservation.

---

## 🚀 Quick Start Guide

Follow these steps to download, configure, and run the project locally.

### 1. Download the Project
If you are downloading this from Hugging Face or GitHub, you can clone the repository or download the ZIP file and extract it.

`ash
git clone <your-repository-url>
cd trading_system
`

### 2. Set Up a Virtual Environment (Recommended)
It is highly recommended to run this bot inside a Python virtual environment to avoid dependency conflicts.

**On Windows:**
`ash
python -m venv .venv
.venv\Scriptsctivate
`

**On macOS/Linux:**
`ash
python3 -m venv .venv
source .venv/bin/activate
`

### 3. Install Requirements
Install all required Python packages using the provided 
equirements.txt file.

`ash
pip install -r requirements.txt
`

*(Optional)* For CUDA GPU support (highly recommended for faster FinBERT sentiment analysis):
`ash
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu128
`

### 4. Configure Your Environment
The bot requires an Alpaca account (Paper or Live) and a NewsAPI key to function.

1. Copy the example configuration file to create your active .env file:
   `ash
   # On Windows (Command Prompt/PowerShell)
   copy .env.example .env
   
   # On macOS/Linux
   cp .env.example .env
   `
2. Open the .env file in a text editor and fill in your API keys:
   - ALPACA_API_KEY & ALPACA_SECRET_KEY: Get these from your [Alpaca Dashboard](https://app.alpaca.markets). (Live keys start with AK, Paper keys start with PK).
   - ALPACA_BASE_URL: Use https://paper-api.alpaca.markets for paper trading, or https://api.alpaca.markets for live trading.
   - TRADING_MODE: Set to paper or live.
   - NEWS_API_KEY: Get this from [NewsAPI](https://newsapi.org).
   - *(Optional)* TELEGRAM_BOT_TOKEN & TELEGRAM_CHAT_ID: For mobile alerts.

### 5. Run the Bot
Once your .env file is configured, you can start the bot!

`ash
python main.py
`
*Note: The bot will automatically check if the market is open. If the market is closed, it will sleep until the next trading session.*

---

## 📊 Backtesting

Before running the bot with real money, you should backtest the strategy against historical data.

`ash
# Run a backtest on specific symbols over a date range
python -m backtester.engine --symbol AAPL --start 2023-01-01 --end 2024-12-31
`
The backtester includes a realistic cost model (slippage, commissions) and utilizes a vectorized engine for fast execution.

---

## 🛡️ Risk Management Pipeline

The bot will **never** place a trade without passing the strict 8-check risk pipeline:
1. **Safe Mode** — Auto-triggered on 3 consecutive broker API errors.
2. **Daily Loss** — Blocks all trades if the daily loss limit (e.g., ) is hit.
3. **Equity Drop** — Blocks trading if the account equity drops >5% from the start of the day.
4. **Consecutive Losses** — Halts trading for 30 minutes and halves position size after 3 consecutive losses.
5. **Profit Lock** — (Optional) Stops trading for the day after a specific profit target is hit to protect gains.
6. **Max Positions** — Hard cap on simultaneous open positions.
7. **PDT Compliance** — Prevents Pattern Day Trader flags on accounts under ,000.
8. **Overnight Protection** — Refuses new entries after 15:45 ET and force-closes positions before the bell.

---

## 📁 Architecture Overview

`	ext
trading_system/
├── .env                 # Secret API keys and configuration
├── main.py              # Main orchestrator / Entry point
├── config.py            # Environment variable loader & validator
├── contracts.py         # Cross-module typed interfaces (Pydantic)
├── data/                # SQLite storage & Alpaca market data fetchers
├── signals/             # Technical indicators (RSI, MACD, VWAP) & Sentiment (FinBERT)
├── strategy/            # Trend-following, Mean Reversion, & Regime detection
├── execution/           # Alpaca API wrapper, Risk limits, Order routing, Portfolio state
├── monitoring/          # Rich terminal dashboard, Telegram alerts, & JSON logging
├── backtester/          # Vectorized backtest engine & CSV reporting
└── tests/               # pytest test suite
`

## 🧪 Running Tests
To ensure everything is working correctly, you can run the test suite:
`ash
pytest tests/ -v
`

## Disclaimer
*This software is for educational and research purposes only. Do not risk money which you are afraid to lose. USE THE SOFTWARE AT YOUR OWN RISK. The authors and all affiliates assume no responsibility for your trading results.*