Blame for README.md

---
title: SentryTheta AI
emoji: 🛡️
colorFrom: indigo
colorTo: red
sdk: docker
app_port: 7860
pinned: false
---

# 🛡️ SentryTheta AI — Autonomous Options Risk & Strategy Platform

> **Built for the Alpaca AI Trading Agents Hackathon**  
> *An institutional-grade, multi-agent options trading desk with deterministic risk guardrails, real-time news sentiment analysis, and a glassmorphic human-in-the-loop dashboard.*

---

## 🌟 Overview

**SentryTheta AI** bridges the gap between LLM reasoning and mathematical risk controls in financial markets. Rather than allowing generative models to directly submit raw financial transactions, SentryTheta employs a **Multi-Agent Orchestration Layer** supervised by a **Deterministic Risk Engine** (Sentry Risk) and real-time execution via Alpaca's Paper Trading API.

Whether operating in **Copilot Mode** (human-in-the-loop 1-click approvals) or **Autopilot Mode** (100% autonomous execution), SentryTheta enforces strict position limits, drawdown circuit breakers, automated stop-loss, and take-profit harvests.

---

## 🚀 Key Features

- 🧠 **Multi-Agent Decision System (`backend/agent.py`):**
  - **Market Analyst:** Continuously monitors Yahoo Finance RSS feeds and evaluates news sentiment via Google Gemini 1.5/2.0 Flash (with deterministic NLP fallbacks).
  - **Volatility Strategist:** Queries live option chains from Alpaca, identifies near-the-money opportunities, and designs option strategies (*Long Calls, Long Puts, Cash-Secured Puts*).
  - **Sentry Risk Officer:** Deterministically checks capital allocations, margin limits, and daily account drawdowns.
  - **Trade Executor:** Dispatches verified orders directly to Alpaca or stages them in the Copilot queue.

- 🛡️ **Deterministic Risk Management (`backend/risk_engine.py`):**
  - **Position Sizing Caps:** Ensures individual option positions do not exceed customizable percentages of total equity (e.g. 5%).
  - **Max Daily Drawdown:** Protects capital by halting all automated scanning if daily losses breach predefined limits (e.g. 3%).
  - **Automated Exit Triggers:** Constantly monitors active positions to execute automated Stop-Loss (-15%) and Take-Profit (+30%) liquidations.

- 📊 **Real-Time Glassmorphic Dashboard (`frontend/`):**
  - **AI Thought Terminal:** Streams live agent reasoning and system actions with sub-agent color coding.
  - **Copilot Decision Center:** Real-time trade review cards with dynamic sentiment meters and risk clearance reports.
  - **Searchable Tickers Registry:** Dynamic tag-input dropdown with **6,100+ option-eligible assets** cached from Alpaca.
  - **Guided Workflow Stepper:** Step-by-step onboarding checklist and matching visual badges for intuitive navigation.
  - **Full Mobile Responsiveness:** Clean vertical stacking, touch-friendly interactions, and horizontal scroll tables on mobile/tablet screens.

- 💾 **SQLite Persistence Layer (`backend/db_helper.py`):**
  - All system settings, risk limits, portfolio states, and historical terminal logs persist across server reboots via `sentrytheta.db`.

- 🔌 **Model Context Protocol (MCP) Integration (`mcp_server.py`):**
  - Implements an MCP-compliant JSON-RPC server enabling external LLM tools (Claude Desktop, Cursor, Custom Agents) to query portfolio health and trigger option scans.

---

## 🏗️ System Architecture

```mermaid
graph TD
    A[RSS News Feeds] --> B[1. Market Analyst AI]
    C[Alpaca Option Chains] --> D[2. Volatility Strategist]
    B -->|Sentiment Score| D
    D -->|Option Proposal| E[3. Sentry Risk Officer]
    E -->|Check 5% Cap & Drawdowns| F{Risk Passed?}
    F -->|No| G[Log Warning to Terminal]
    F -->|Yes| H{Trading Mode}
    H -->|Copilot Mode| I[Copilot Decision Center]
    H -->|Autopilot Mode| J[Alpaca Paper Trading API]
    I -->|User Approves| J
    J -->|Order Filled| K[Active Option Contracts & SQLite DB]
```

---

## ⚡ Quick Start

### 1. Clone & Install Dependencies
```bash
git clone https://github.com/abdullasibghat/SentryTheta-AI.git
cd SentryTheta-AI
pip install -r requirements.txt
```

### 2. Configure Environment (`.env`)
Copy the template and add your credentials:
```env
# Alpaca Paper Trading Credentials
ALPACA_API_KEY=your_alpaca_key_id
ALPACA_SECRET_KEY=your_alpaca_secret_key
ALPACA_PAPER=true

# Google Gemini API (Free Tier from Google AI Studio)
GEMINI_API_KEY=your_gemini_api_key

# Trading Configuration
TARGET_TICKERS=AAPL,MSFT,NVDA,SPY,QQQ
TRADING_MODE=copilot # copilot or autopilot
SCAN_INTERVAL_SECONDS=60
```

### 3. Launch Dashboard & Server
```bash
python main.py run-server
```
Visit **`http://localhost:8000`** in your browser.

---

## 🧪 CLI Commands

Test and interact with the platform directly from the terminal:

* **Dry-Run API Test:**
  ```bash
  python main.py test-trading --mock
  ```
* **Run Single Agent Scanner Cycle:**
  ```bash
  python main.py run-agent --ticker NVDA
  ```
* **Start Model Context Protocol (MCP) Server:**
  ```bash
  python main.py run-mcp
  ```

---

## 🏆 Hackathon Alignment

| Criteria | SentryTheta Implementation |
| :--- | :--- |
| **Agent Autonomy** | Multi-agent hierarchy analyzing news sentiment, designing option spreads, and self-executing on Autopilot. |
| **Alpaca Integration** | Real-time option contracts lookups, account metrics streaming, and live paper order fills via `alpaca-py`. |
| **Risk Guardrails** | Deterministic mathematical risk engine overriding LLM hallucinations to protect account equity. |
| **User Experience** | Glassmorphic, responsive web interface with real-time WebSockets, live stepper checklists, and 1-click approvals. |
| **Extensibility** | MCP server integration and SQLite persistence for stateful, long-term operation. |

---

## 📄 License
This project is licensed under the MIT License.