.env.example

# API Keys
ALPACA_API_KEY=your_alpaca_api_key_here
ALPACA_SECRET_KEY=your_alpaca_secret_key_here
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional: OpenAI-compatible LLM gateway (e.g., Tetrate Agent Router)
# When set, these override the base URL and API key used by OpenAI/OpenRouter SDK clients.
# Example base URL: https://api.router.tetrate.ai/v1
LLM_GATEWAY_BASE_URL=
LLM_GATEWAY_API_KEY=
# Alias supported by the codebase (equivalent to LLM_GATEWAY_API_KEY)
TETRATE_API_KEY=

RAG_WEBHOOK_TOKEN=
RAG_WEBHOOK_URL=
SENTRY_DSN=
SENTRY_AUTH_TOKEN=

# Optional: enable DeepSeek via OpenRouter (adds deepseek/deepseek-r1 to LLM council)
OPENROUTER_ENABLE_DEEPSEEK=true
# OPENROUTER_DEEPSEEK_MODEL=deepseek/deepseek-r1

# Optional: enable Kimi K2 via OpenRouter for budget optimization (Dec 2025)
# Kimi K2 is 7.5x cheaper than Sonnet with comparable agentic performance
# Available models:
#   moonshotai/kimi-k2-0905  - Latest (256K context, $0.39/$1.90 per M tokens)
#   moonshotai/kimi-k2       - Standard (131K context)
#   moonshotai/kimi-k2:free  - Free tier (rate limited)
#   moonshotai/kimi-k2-thinking - Reasoning model (like o1/DeepSeek-R1)
OPENROUTER_ENABLE_KIMI_K2=true
OPENROUTER_KIMI_K2_MODEL=moonshotai/kimi-k2-0905

ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key_here

# FRED API (Federal Reserve Economic Data)
# Get free API key: https://fred.stlouisfed.org/docs/api/api_key.html
# Used by TreasuryLadderStrategy for real-time Treasury yields
FRED_API_KEY=your_fred_api_key_here

# LLM Observability - OpenRouter private Input & Output Logging
# Enable "Input & Output Logging" in OpenRouter Observability settings.
# This repo cannot verify the remote dashboard toggle directly, so declare the
# intended state here for health checks and CI reporting.
# IMPORTANT:
# - Only direct requests sent to openrouter.ai appear in OpenRouter private logs.
# - If LLM_GATEWAY_BASE_URL points at a gateway (for example TARS), OpenRouter
#   private logs only cover direct fallback requests, not primary gateway traffic.
OPENROUTER_INPUT_OUTPUT_LOGGING_ENABLED=false

# Configuration
PAPER_TRADING=true
# DAILY_INVESTMENT is auto-scaled by _apply_dynamic_daily_budget():
# 1% of equity, min $10, max $1000. Manual override possible.
DAILY_INVESTMENT=10.0
TIER1_ALLOCATION=0.60
TIER2_ALLOCATION=0.20
TIER3_ALLOCATION=0.10
TIER4_ALLOCATION=0.10

# Risk Management
MAX_DAILY_LOSS_PCT=2.0
MAX_POSITION_SIZE_PCT=10.0
MAX_DRAWDOWN_PCT=10.0
STOP_LOSS_PCT=5.0

# ============================================================
# OPTIONS THETA AUTOMATION
# ============================================================
# Enable automatic theta harvest execution (poor man's covered calls, iron condors)
# Requires: Account equity >= $5k for poor man's covered calls
#           Account equity >= $10k for iron condors
# IV Percentile must be >= 50% for premium selling
ENABLE_THETA_AUTOMATION=true

# Theta strategy equity thresholds (in USD)
THETA_STAGE_1_EQUITY=5000   # Poor man's covered calls
THETA_STAGE_2_EQUITY=10000  # Iron condors
THETA_STAGE_3_EQUITY=25000  # Full options suite

# Minimum IV percentile for premium selling strategies
IV_PERCENTILE_THRESHOLD=50

# Order Execution
USE_LIMIT_ORDERS=true
LIMIT_ORDER_BUFFER_PCT=0.1
LIMIT_ORDER_TIMEOUT_SECONDS=60

# Market Data Provider Configuration
# yfinance settings (primary source)
YFINANCE_LOOKBACK_BUFFER_DAYS=35
YFINANCE_SECONDARY_LOOKBACK_DAYS=150
YFINANCE_MAX_RETRIES=3
YFINANCE_INITIAL_BACKOFF_SECONDS=1.0

# Alpaca settings (preferred fallback)
ALPACA_MAX_RETRIES=3
ALPACA_INITIAL_BACKOFF_SECONDS=2.0

# Alpha Vantage settings (last resort live source)
ALPHAVANTAGE_MIN_INTERVAL_SECONDS=15
ALPHAVANTAGE_BACKOFF_SECONDS=60
ALPHAVANTAGE_MAX_RETRIES=4

# Cache settings
MARKET_DATA_CACHE_DIR=data/cache/alpha_vantage
CACHE_TTL_SECONDS=21600
CACHE_MAX_AGE_DAYS=7

# Alerting Configuration
# Telegram Bot (recommended - free, instant, reliable)
# Setup: https://core.telegram.org/bots#3-how-do-i-create-a-bot
# 1. Open Telegram and search for @BotFather
# 2. Send /newbot and follow instructions
# 3. Copy bot token below
# 4. Send a message to your bot
# 5. Visit: https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates
# 6. Find your chat ID in JSON response and paste below
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=

# Alternative/Additional Alerting (optional)
ALERT_EMAIL=
ALERT_WEBHOOK_URL=

# ============================================================
# AGENT INTEGRATIONS (ALL ENABLED BY DEFAULT)
# ============================================================

# ============================================================
# GATE 2 & 3: RL/LLM FILTERS (RE-ENABLED Dec 11, 2025)
# These gates provide ACTUAL EDGE - don't run without them!
# ============================================================

# Gate 2: RL Filter - Reinforcement Learning signal filtering
# Provides edge by learning which momentum signals actually profit
RL_FILTER_ENABLED=true

# Gate 3: LLM Sentiment - Multi-source sentiment analysis
# Filters false signals using news/social sentiment
LLM_SENTIMENT_ENABLED=true

# Sentiment thresholds (only apply when Gate 3 enabled)
LLM_NEGATIVE_SENTIMENT_THRESHOLD=-0.2

# DeepAgents - Planning-based trading agent with sub-agent delegation
DEEPAGENTS_ENABLED=true

# LLM Council - Multi-model consensus for trading decisions
LLM_COUNCIL_ENABLED=true

# Go ADK Integration (requires Go service running)
ENABLE_ADK_AGENTS=true

# RL Systems
ENABLE_RL_RETRAIN=true
RL_USE_TRANSFORMER=1
USE_MEDALLION_ARCHITECTURE=true

# DiscoRL-Inspired DQN (Dec 2025 - DeepMind Nature paper integration)
# Enables categorical value distribution + EMA normalization for Gate 2
# Dec 12, 2025: CEO directive - RL capped at 10% total influence (90% momentum)
# Within the 10% RL budget: heuristic 40%, transformer 45%, disco 15%
RL_USE_DISCO_DQN=true
RL_TOTAL_WEIGHT=0.10
RL_HEURISTIC_WEIGHT=0.40
RL_TRANSFORMER_WEIGHT=0.45
RL_DISCO_WEIGHT=0.15
DISCO_DQN_BINS=51
DISCO_DQN_GAMMA=0.997
DISCO_DQN_LR=0.0003
DISCO_DQN_MODEL_PATH=models/ml/disco_dqn.pt

# Ensemble Voting (Agent Weighting)
ENSEMBLE_WEIGHT_MCP=0.35
ENSEMBLE_WEIGHT_LANGCHAIN=0.15
ENSEMBLE_WEIGHT_GEMINI=0.15
ENSEMBLE_WEIGHT_ML=0.25
ENSEMBLE_WEIGHT_ENSEMBLE_RL=0.25
ENSEMBLE_WEIGHT_GROK=0.10

# Ensemble Consensus Thresholds
ENSEMBLE_BUY_THRESHOLD=0.15
ENSEMBLE_SELL_THRESHOLD=-0.15

# Ensemble Execution Sizing Scale
ENSEMBLE_SIZE_SCALE_MIN=0.5
ENSEMBLE_SIZE_SCALE_MAX=1.0

# Reddit API (for retail sentiment analysis via PRAW)
# OPTIONAL: Get credentials for higher rate limits: https://www.reddit.com/prefs/apps
# 1. Log into Reddit and go to https://www.reddit.com/prefs/apps
# 2. Scroll down and click "create another app..."
# 3. Select "script" as app type
# 4. Fill in: name (e.g., "TradingBot"), description, redirect uri (http://localhost:8080)
# 5. Copy client_id (under app name) and secret
# NOTE: If not set, will use public JSON API with lower rate limits (no auth required)
REDDIT_CLIENT_ID=
REDDIT_CLIENT_SECRET=
REDDIT_USERNAME=
REDDIT_PASSWORD=

# TikTok API (Research API for sentiment analysis)
# Get credentials: https://developers.tiktok.com/
# 1. Create TikTok Developer account
# 2. Create new app in TikTok Developer Portal
# 3. Request access to Research API (requires approval)
# 4. Copy Client Key and Client Secret below
TIKTOK_CLIENT_KEY=your_tiktok_client_key_here
TIKTOK_CLIENT_SECRET=your_tiktok_client_secret_here

# LinkedIn API (for professional sentiment analysis)
# Setup: https://www.linkedin.com/developers/apps
# 1. Create a LinkedIn app
# 2. Request access to Marketing Developer Platform or Posts API
# 3. Add OAuth2 redirect URI for authentication
# 4. Copy Client ID and Client Secret below
# 5. (Optional) Generate access token and paste below
LINKEDIN_CLIENT_ID=
LINKEDIN_CLIENT_SECRET=
LINKEDIN_ACCESS_TOKEN=

# Value Cost Averaging (VCA) Configuration
USE_VCA=true
VCA_TARGET_GROWTH_RATE=0.10
VCA_MAX_ADJUSTMENT=2.0
VCA_MIN_ADJUSTMENT=0.3

# ========================================
# Error Monitoring & Alerts (Sentry + Slack)
# ========================================

# Sentry Error Tracking
# Get DSN: https://sentry.io -> Projects -> Your Project -> Settings -> Client Keys (DSN)
# 1. Create account at https://sentry.io (free tier: 5K events/month)
# 2. Create Python project
# 3. Copy DSN from project settings
SENTRY_DSN=
ENVIRONMENT=production

# Slack Alerts (for Sentry notifications)
# Option 1: Configure in Sentry Dashboard (recommended)
#   - Go to Sentry -> Settings -> Integrations -> Slack
#   - Install Slack integration and select workspace
#   - Configure alert rules to send to specific channels
#
# Option 2: Direct webhook (for custom alerts)
#   - Go to Slack -> Apps -> Incoming Webhooks -> Add New Webhook
#   - Copy webhook URL below
SLACK_WEBHOOK_URL=
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_CHANNEL=#trading-alerts