██╗ ███████╗██╗ ██╗██╗ ██║ ██╔════╝██║ ██║██║ ██║ █████╗ ██║ ██║██║ ██║ ██╔══╝ ╚██╗ ██╔╝██║ ███████╗███████╗ ╚████╔╝ ██║ ╚══════╝╚══════╝ ╚═══╝ ╚═╝

AI options intelligence — paper trading only

LEVI

LEVI gathers evidence, applies deterministic risk rules, requires unanimous AI agreement from three independent specialist agents, and only then becomes eligible to place a paper trade.

No live execution. No exceptions in this release.

Risk is decided before intelligence. Models never control risk — they only provide evidence.

---

Install

Requirements: Python 3.11+, Node 18+ (for the dashboard), Docker (optional)

git clone https://github.com/tradersurfer/LEVI
cd LEVI

python -m venv .venv
source .venv/bin/activate   # Windows PowerShell: .\.venv\Scripts\Activate.ps1

python -m pip install -r requirements.txt
cp .env.example .env       # Windows PowerShell: Copy-Item .env.example .env

python scripts/validate_env.py
python -m uvicorn bot.status_api:app --reload

Windows users can instead run powershell -ExecutionPolicy Bypass -File scripts/install.ps1 from the repository root. The installer creates and uses this repository's .venv.

Or with Docker:

docker compose up --build

Paper trading is on by default: TASTYTRADE_PAPER=true, LEVI_DEFAULT_EXECUTION_MODE=paper_trading, AUTO_EXECUTE=false, and RUN_BOT=false. Live execution is not available in this release.

Evidence encryption requires a deployment-specific LEVI_EVIDENCE_ENCRYPTION_KEY. Authentication and persistence are opt-in through LEVI_AUTH_ENABLED=false and LEVI_PERSISTENCE_ENABLED=false defaults. See .env.example for the complete configuration contract.

Full setup, dashboard install, and paper-broker configuration: docs/GETTING_STARTED.md

---

What LEVI does

Philosophy

Deterministic policy
        ↓
Risk controls
        ↓
Evidence and specialist research
        ↓
3-of-3 consensus
        ↓
Paper-order eligibility

Models provide bounded analysis from supplied evidence. Python owns validation, risk vetoes, tenant isolation, and execution policy. Missing or weak evidence produces no trade.

Architecture

User profile + mode policy
            │
            ▼
Encrypted, user-scoped evidence ──► What You Need gate
            │
            ▼
SCOUT + ATLAS + LENS specialists
            │
            ▼
Unanimous consensus (3 / 3)
            │
            ▼
GUARDIAN deterministic risk veto
            │
            ▼
Paper-only LIMIT-order gateway

The FastAPI entrypoint is bot/status_api.py. Broker, market-data, evidence-storage, and model providers sit behind explicit interfaces. The dashboard is read-only and user-scoped; authentication and durable persistence are opt-in.

Specialist agents and consensus

Agent	Responsibility
SCOUT	Supplied sentiment, flow, news, and crowd-positioning evidence
ATLAS	Supplied macro, rates, volatility, regime, and catalyst evidence
LENS	Ticker-matched chart structure and validated quotes
VOLT	Deterministic Black–Scholes and liquidity diagnostics
GUARDIAN	Non-model risk checks and final veto authority
SCRIBE	Narrative summary without a vote

SCOUT, ATLAS, and LENS must return the same bullish or bearish verdict at or above LEVI_CONSENSUS_MIN_CONFIDENCE=0.70. Neutral, blocked, insufficient, malformed, low-confidence, ownership-mismatched, or 2-to-1 outcomes do not approve. GUARDIAN can veto any unanimous result.

Risk engine

These rules are deterministic and cannot be overridden by a model:

Rule	Enforcement
Execution mode	Paper trading required
Order type	LIMIT only; market orders prohibited
Minimum DTE	Four days by default
Averaging down	Prohibited
Loss and position limits	Enforced from the validated user profile
Quote freshness	Three seconds for options; fifteen seconds for stocks
Buying power and approval	Required before eligibility

Documentation

• Getting Started
• Architecture
• API Reference
• Security
• Troubleshooting
• Contributing
• FAQ

License

Apache License 2.0 — see LICENSE and NOTICE.

---

Paper trade first. Not financial advice.