# alphadesk — Complete User Guide

![alphadesk logo](./alphadesk-logo.png)

> **AI Hedge Fund · The Alpha Loop** — Five agents argue, one decision.

📺 **Watch the full demo:** [alphadesk — AI Hedge Fund in Action (YouTube)](https://youtu.be/1p6U7xmYE4Y)

---

## Table of Contents

1. [What is The Alpha Loop?](#what-is-the-alpha-loop)
2. [The Simulated Portfolio](#the-simulated-portfolio)
3. [Step-by-Step Workflow](#step-by-step-workflow)
4. [Understanding Each Layer](#understanding-each-layer)
5. [Modes: Operational vs Strategic](#modes-operational-vs-strategic)
6. [Common Questions & Troubleshooting](#common-questions--troubleshooting)

---

## What is The Alpha Loop?

**alphadesk** is an AI-powered trading analysis system built on a **5-layer pipeline** simulating a real hedge fund. It automates the entire investment decision-making process — from raw data to a final trade proposal — in under 15 seconds.

The term **"alpha"** in finance means returns above the market benchmark. The Alpha Loop is the cycle that hunts for, validates, and risk-checks those excess-return opportunities before presenting a conviction verdict.

### The Five Layers

```
  1  ALPHA GENERATORS      → 4 agents scan for trading signals
         ↓
  2  BACKTEST ENGINE        → validates the signal through history
         ↓
  3  EXECUTION DESK         → entry, stop-loss, and profit target
         ↓
  4  RISK OVERSIGHT         → 8 hard safety gates (any fail = reject)
         ↓
  5  PERFORMANCE & ATTRIBUTION → final conviction thesis + P&L report
```

Each layer only runs if the previous one passes. If any gate fails, the pipeline stops and tells you exactly why.

### The Conviction Scale

Every trade gets a conviction score based on historical win rates at that signal strength. This is your confidence meter:

| Conviction Level | Historical Win Rate | What It Means | Action |
|---|---|---|---|
| **NO EDGE** | ~50% | Coin flip | Do not trade |
| **WEAK SIGNAL** | ~55% | Barely better than random | Paper-trade only |
| **MODERATE CONVICTION** | ~58% | Small position acceptable | Small position |
| **HIGH CONVICTION** | ~65% | Good odds | Standard position |
| **STRONG CONVICTION** | 70%+ | Excellent odds | Full position |

Higher conviction = better odds. The system blocks trades below **MODERATE CONVICTION** automatically.

---

## The Simulated Portfolio

### What It Is

A **paper-trading account** that starts with $100,000 cash and tracks all approved positions as if they were real. No real money. No broker connection. Every approved trade fills automatically.

### Why You Need It

The portfolio is not cosmetic — the **Risk Officer** reads it in real time:

- After your first trade fills, subsequent analyses see the existing position
- If you're already 40% in Tech, a new NVDA trade will be sized down automatically
- Your drawdown, VaR, and sector exposure all update after each fill

This means each cycle gets a **personalized** risk assessment, not a generic one.

### Portfolio Metrics Explained

| Metric | What It Means |
|--------|---------------|
| **NAV** | Net Asset Value = cash + all positions at today's price |
| **Cash** | Uninvested dollars remaining |
| **Exposure** | % of portfolio deployed into positions |
| **VaR (95%)** | Maximum expected 1-day loss at 95% confidence |
| **Drawdown** | Current loss from the portfolio's all-time peak (%) |

### Resetting the Portfolio

Click **RESET** in the Simulated Portfolio panel to clear all positions and return to $100,000 cash. Use this when you want to start a fresh scenario.

---

## Step-by-Step Workflow

### Step 1 — Pick a Ticker

Type any ticker symbol into the input field at the top of the page, or click one of the quick-select buttons:

```
TRY:   NVDA   AAPL   TSLA   MSFT   GOOGL   META   AMZN   SPY   BTC-USD
```

**Free tickers** (no license required): `SPY`, `BTC-USD`

**Paid tickers** (require Tier 2 activation): all others

Valid formats: `AAPL`, `BTC-USD`, `QQQ`, `MSFT`, `TSLA`, etc.

---

### Step 2 — Check the Macro Filter

Before clicking Analyze, the banner at the top shows current macro conditions:

```
MACRO FILTER    VIX 18.4  CALM    10Y YIELD 4.41%  OK
Macro conditions acceptable for trading
```

**VIX Thresholds:**
- **VIX < 20** → Green · CALM — normal volatility, proceed
- **VIX 20–30** → Yellow · ELEVATED — caution, wider stops
- **VIX > 30** → Red · STRESSED — extreme volatility, risk of rejection

The system will still run under elevated VIX, but Risk Oversight may block or size down the trade.

---

### Step 3 — Select Your Mode

When you click **ANALYZE →** on a paid ticker, the subscription modal appears:

**OPERATIONAL (Tier 1 — $19/mo)**
- Technical indicators + backtesting
- Entry / stop / profit target
- Basic risk checks
- Up to 25 reports per day
- Fast (~5 seconds)

**STRATEGIC (Tier 2 — $49/mo)**
- Everything in Operational, plus:
- Real AI debate (bull vs bear arguments with evidence)
- 3-personality risk review (Aggressive, Balanced, Conservative)
- Full conviction thesis with historical win rate
- Unlimited PDF exports
- Deeper (~10–15 seconds)

**Already have a key?** Paste it into the license field at the bottom of the modal and click **ACTIVATE**.

---

### Step 4 — Watch the Pipeline Run

After you click Analyze, the **Alpha Loop** panel shows each stage lighting up in sequence:

```
●──────○──────○──────○──────○
ALPHA   BACKTEST  EXECUTION  RISK   ATTRIBUTION
```

Each dot fills as that layer completes. If the cycle stops early, Risk Oversight rejected the trade — expand that layer card to see exactly which gate failed.

---

### Step 5 — Read the Verdict

Once all 5 layers complete, the **decision banner** shows:

```
┌─────────────────────────────────────────────────┐
│  Final · Performance & Attribution · Layer 5    │
│                                                 │
│  MODERATE CONVICTION  ·  BULL                  │
│                                                 │
│  ENTRY       $737.62                            │
│  STOP LOSS   $720.62   (−1.85%)                 │
│  TARGET      $771.62   (+4.61%)                 │
│  RISK/REWARD  1 : 2.5                           │
└─────────────────────────────────────────────────┘
```

**Conviction levels and what they mean:**

| Level | Historical Win Rate | Action |
|-------|--------------------|----|
| NO EDGE | ~50% | Do not trade |
| WEAK SIGNAL | ~55% | Paper-trade only |
| MODERATE CONVICTION | ~58% | Small position |
| HIGH CONVICTION | ~65% | Standard position |
| STRONG CONVICTION | 70%+ | Full position |

---

### Step 6 — Check the Live Data Sources

Below the verdict, a panel shows every data source used:

```
Live data sources                          8 OK · 0 ERR

Prices        OK    $737.62   ·TWELVEDATA    asof 12s ago
Fundamentals  OK    P/E 27.7  ·YFINANCE      asof 3m ago
OHLCV         OK    260 bars  ·TWELVEDATA    asof 3m ago
SEC EDGAR     OK    10 filings             asof 3m ago
Reddit        OK    23 posts               asof 3m ago
News          OK    10 headlines·YFINANCE   asof 3m ago
VIX (^VIX)    OK    18.4 CALM ·YFINANCE    asof 12s ago
10Y Treasury  OK    4.41%     ·YFINANCE     asof 3m ago
```

**Green OK** = data fetched successfully and is fresh.
**Timestamp** = how long ago this source was last pulled.
**Provider badge** = TWELVEDATA (real-time) or YFINANCE (15-min delayed).

---

### Step 7 — Export the PDF Report

Click **PDF REPORT** to download a full 3-page report containing:
- Executive Summary (verdict, conviction, entry mechanics)
- Full layer reasoning (analyst scores, risk check results)
- Data sources and freshness
- Historical backtest statistics

---

## Understanding Each Layer

### Layer 1 — Alpha Generators

Four specialized agents independently score the ticker from 0.0 (strong bear) to 1.0 (strong bull):

| Agent | Signals Used | Edge |
|-------|-------------|------|
| **Technical** | RSI, MACD, Bollinger Bands, EMA, ADX, Stochastic, VWAP, Donchian | Trend + momentum |
| **Fundamental** | P/E, P/S, EPS growth, margins, debt | Valuation quality |
| **News & Sentiment** | Headlines, Reddit posts, sentiment polarity | Market narrative |
| **SEC Filings** | Insider buying/selling, recent 8-Ks, earnings guidance | Institutional moves |

Scores are combined into a single **long_score**. A score above 0.63 is required to proceed.

---

### Layer 2 — Backtest Engine

The signal from Layer 1 is replayed through the past 6–12 months of historical daily data.

**Key outputs:**
- **Win rate** — % of times this signal produced a positive 20-day return
- **Sharpe ratio** — return per unit of risk
- **Max drawdown** — worst losing streak during the backtest period

A win rate below 52% downgrades conviction. Below 50% and the trade is flagged as NO EDGE.

---

### Layer 3 — Execution Desk

If the signal passes Layers 1 and 2, the Execution Desk calculates mechanics using the **ATR Stop Protocol**:

```
ATR (14-day Average True Range) = $8.50

Entry:         Current price            = $737.62
Stop Loss:     Entry − (2 × ATR)        = $720.62  (−1.85%)
Profit Target: Entry + (4 × ATR)        = $771.62  (+4.61%)
Risk/Reward:   4 / 2 = 2.0              (favorable — rule: must be ≥ 1.5)
```

**Why ATR?** ATR scales the stop to the stock's actual volatility. A high-volatility stock like NVDA needs a wider stop than a low-volatility bond ETF. ATR-based stops prevent premature shake-outs.

---

### Layer 4 — Risk Oversight

Eight hard gates are checked. **Any single failure rejects the trade.**

| Gate | Rule | Example Failure |
|------|------|----------------|
| **Earnings Calendar** | Block trades <24h pre-earnings | NVDA reports tomorrow → BLOCKED |
| **VIX Spike** | Block if VIX > 30 | Crisis day VIX = 35 → BLOCKED |
| **Portfolio Capacity** | Max 5% VaR per cycle | VaR would exceed limit → BLOCKED |
| **Sector Concentration** | Max 35% per sector | Tech already at 40% → SIZE DOWN |
| **Position Size** | Max 25% per single position | 30% proposed → capped at 25% |
| **Liquidity** | Avg daily volume > 100M | Microcap → SIZE DOWN |
| **Drawdown Limit** | Max 10% portfolio drawdown | Drawdown at 9.5% → BLOCKED |
| **Liquidity Score** | Can exit all positions in 1 day | Illiquid holdings → WARN |

**SIZE DOWN** means the trade is approved but at a smaller size (e.g., 50% of proposed).
**BLOCKED** means the trade is fully rejected.

---

### Layer 5 — Performance & Attribution

The final layer writes the complete verdict:

- **Bull thesis**: Which agents are bullish and why (with data citations)
- **Bear thesis**: Counter-arguments and risks
- **Conviction level**: Tied to historical win rate at this signal strength
- **Expected P&L**: Dollar gain if target hit vs. dollar loss if stop hit
- **Attribution**: Which data sources drove the decision

---

## Modes: Operational vs Strategic

| Feature | Operational (Tier 1) | Strategic (Tier 2) |
|---------|---------------------|-------------------|
| All technical indicators | ✓ | ✓ |
| Backtesting | ✓ | ✓ |
| Entry / stop / target | ✓ | ✓ |
| 8 risk gates | ✓ | ✓ |
| PDF export (basic) | ✓ | ✓ |
| **AI bull/bear debate** | ✗ | ✓ |
| **3-personality risk team** | ✗ | ✓ |
| **Evidence-cited arguments** | ✗ | ✓ |
| **Historical win rate display** | ✗ | ✓ |
| **Full conviction thesis** | ✗ | ✓ |
| Speed | ~5s | ~10–15s |

**When to use Operational**: Fast daily screening across many tickers.
**When to use Strategic**: Before placing an actual trade you want high confidence in.

---

## Common Questions & Troubleshooting

**Q: The spinner keeps going and never finishes.**
A: The server may be overloaded or a data source timed out. Refresh the page and try again. If it persists, check that your local server is running (`python -m uvicorn main:app`).

**Q: "Earnings <24h — position blocked" — why can't I override it?**
A: Post-earnings moves are 2–3× normal volatility and unpredictable in direction. This is a hard circuit breaker with no override. Wait for earnings to pass, then re-run.

**Q: My trade was "sized down to 50%" — what does that mean?**
A: Risk Oversight approved the trade but found a constraint (sector overweight, elevated VIX, recent drawdown). The system cut position size in half to keep risk within policy. You can accept the smaller trade or reset the portfolio.

**Q: The data shows "3m ago" — is it stale?**
A: 3 minutes is normal for most sources. yfinance updates every 15 minutes during market hours. Only worry if a source shows ERR or the timestamp is over 30 minutes.

**Q: Can I connect this to my real broker?**
A: Not yet. alphadesk is a research and analysis tool. Copy the Entry, Stop, and Target values into your broker's order screen manually.

**Q: What does "No fundamentals data found for SPY" mean?**
A: ETFs don't have earnings or P/E ratios. The system skips fundamental analysis for ETFs automatically. All other layers still run normally.

**Q: How do I reset the simulated portfolio?**
A: Click the **RESET** button in the Simulated Portfolio panel (top right of the panel). This returns cash to $100,000 and clears all positions.

**Q: What's a good Risk/Reward ratio?**
A: The system requires a minimum of **1.5 : 1** (target is 1.5× the stop distance). A ratio of 2 : 1 or higher is ideal — it means you only need to be right 40% of the time to break even.

---

*alphadesk v2 · The Alpha Loop · AI Hedge Fund · alphadesk.finance*