robinhood/docs/AI_FEATURES.md

AI Features & Integration

Complete guide to AI-powered features in the Gold Trading Simulator

---

🎯 Overview

The platform integrates professional-grade AI analysis powered by OpenRouter (Claude 3.5 Sonnet, GPT-4, and other models) to provide gold-specific market analysis, trading recommendations, and daily trading plans.

---

🚀 Core AI Features

1. AI Scenario Analysis

Purpose: Real-time market analysis with BUY/SELL/HOLD recommendations

Endpoint: POST /api/ai/analyze

Capabilities:

• Gold market structure analysis (trend vs consolidation)
• Technical indicator interpretation (RSI, MACD, EMAs, etc.)
• Support/resistance level identification
• Risk assessment (LOW/MEDIUM/HIGH)
• Confidence scoring (0-100%)
• Actionable trade recommendations

Gold-Specific Context:

• ✅ Typical volatility range ($20-40 daily)
• ✅ Price levels to nearest $0.50
• ✅ USD inverse correlation
• ✅ Safe-haven demand factors
• ✅ Session timing (London/NY overlap optimal)

Response Format:

{
  "recommendation": "BUY",
  "confidence": 78,
  "reasoning": "Gold showing bullish momentum above key support...",
  "support_levels": [2045.50, 2038.00, 2030.50],
  "resistance_levels": [2067.50, 2075.00, 2082.50],
  "risk_level": "MEDIUM",
  "entry_price": 2050.00,
  "target_price": 2070.00,
  "stop_loss": 2043.00
}

---

2. Daily Trading Plan Generation

Purpose: Comprehensive daily trading strategy with specific levels and rules

Endpoint: POST /api/ai/daily-plan

Capabilities:

• Market bias assessment (BULLISH/BEARISH/NEUTRAL)
• Entry zone identification
• Multiple target levels
• Stop loss placement
• Support/resistance mapping
• Max trade recommendations
• Risk/reward calculations
• Contingency planning

Trader Profile Integration:

• Capital size
• Risk tolerance (conservative/moderate/aggressive)
• Trading style (scalping/day trading/swing)
• Preferred session times

Output Structure:

{
  "date": "2025-11-23",
  "market_bias": "BULLISH",
  "confidence": 75,
  "key_levels": {
    "support": [2045.50, 2038.00, 2030.50],
    "resistance": [2067.50, 2075.00, 2082.50]
  },
  "trade_setups": [
    {
      "direction": "LONG",
      "entry_zone": [2048.00, 2051.00],
      "targets": [2060.00, 2070.00, 2080.00],
      "stop_loss": 2043.00,
      "risk_reward": 2.5
    }
  ],
  "max_trades": 3,
  "risk_per_trade": "1-2% of capital",
  "notes": "Focus on London/NY overlap. Watch USD movements..."
}

---

3. AI Trading Coach

Component: AITradingCoach.tsx

Features:

• Interactive chat interface
• Real-time market Q&A
• Strategy refinement
• Trade review assistance
• Educational guidance

Use Cases:

• "Should I enter this trade?"
• "How do I manage this position?"
• "What's happening with gold prices?"
• "Explain this indicator pattern"

---

4. News Summarization

Endpoint: POST /api/ai/summarize-news

Capabilities:

• Multi-article summarization
• Sentiment analysis
• Key takeaways extraction
• Market impact assessment

---

⚙️ Configuration

Required Environment Variables

# OpenRouter API Key (Required)
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx

# Model Selection (Optional, defaults to claude-3.5-sonnet)
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

# Alternative models available:
# - anthropic/claude-3.5-sonnet (recommended for trading)
# - openai/gpt-4-turbo
# - google/gemini-pro
# - meta-llama/llama-3.1-70b

Model Settings

Default Configuration:

• Model: Claude 3.5 Sonnet
• Temperature: 0.7 (balanced creativity/consistency)
• Max Tokens: 1500-3000
• Timeout: 60 seconds

Cost Optimization:

• Analysis: ~$0.01-0.03 per request
• Daily Plan: ~$0.03-0.05 per generation
• News Summary: ~$0.01-0.02 per batch

Recommended: Start with $5 OpenRouter credit (~200-500 analyses)

---

📋 Prompt Templates

Available Templates

Located in backend/app/services/prompts.py:

1. analysis_default

   • General gold market analysis
   • Technical and fundamental factors
   • Risk-aware recommendations

2. risk_control_default

   • Position sizing guidance
   • Stop loss recommendations
   • Risk management rules

3. daily_plan_template

   • Comprehensive daily strategy
   • Multiple scenarios
   • Time-based execution

4. technical_analysis_focused

   • Deep dive on indicators
   • Chart pattern recognition
   • Momentum analysis

5. market_sentiment_analysis

   • News impact assessment
   • Sentiment scoring
   • Fundamental drivers

Customizing Prompts

Edit System Prompts:

# backend/app/services/openrouter.py
SYSTEM_MESSAGE = """
You are an expert gold (XAU/USD) trading analyst...
[Customize persona and expertise here]
"""

Edit Analysis Prompt:

# backend/app/services/openrouter.py - analyze_scenario()
analysis_prompt = f"""
Analyze the current gold market...
[Customize analysis framework here]
"""

Edit Plan Prompt:

# backend/app/services/ai_plan_service.py - generate_plan()
plan_prompt = f"""
Generate a comprehensive daily trading plan...
[Customize plan structure here]
"""

---

🧪 Testing

Basic Connectivity Test

cd backend
python test_openrouter.py

Expected Output:

✅ SUCCESS! OpenRouter API is working
Model: anthropic/claude-3.5-sonnet
Response: [AI-generated text about gold trading]

Comprehensive Prompt Test

cd backend
python test_improved_prompts.py

Tests:

• ✅ AI scenario analysis
• ✅ Daily plan generation
• ✅ Response formatting
• ✅ Error handling

---

💡 Best Practices

For Optimal AI Performance

1. Provide Quality Data

   • Include 20-50 recent candles
   • Send current technical indicators
   • Update price data frequently

2. Set Proper Context

   • Specify user's capital and risk tolerance
   • Include current positions
   • Mention trading style preferences

3. Use at Optimal Times

   • Before market open (for daily plans)
   • During London/NY overlap (for real-time analysis)
   • After major news events

4. Combine Multiple Features

   • Start with Daily Plan
   • Use Scenario Analysis for specific setups
   • Consult Trading Coach for questions
   • Review with News Summarization

---

🔧 Implementation Details

Service Architecture

Frontend (React)
    ↓
API Layer (FastAPI)
    ↓
AI Services
    ├── openrouter.py (Scenario Analysis)
    ├── ai_plan_service.py (Daily Plans)
    └── prompts.py (Template Library)
    ↓
OpenRouter API
    └── Claude 3.5 Sonnet / GPT-4

Key Files

Backend Services:

• backend/app/services/openrouter.py - Core AI analysis service
• backend/app/services/ai_plan_service.py - Daily plan generator
• backend/app/services/prompts.py - Prompt template library
• backend/app/api/ai.py - AI API endpoints
• backend/app/api/ai_coach.py - Trading coach endpoint

Frontend Components:

• frontend/src/components/AIAnalysisPanel.tsx - AI analysis UI
• frontend/src/components/DailyTradingPlan.tsx - Daily plan UI
• frontend/src/components/AITradingCoach.tsx - Interactive coach
• frontend/src/services/api.ts - API client

Database Models:

• TradingPlan - Stores generated plans
• DecisionLog - Tracks AI recommendations vs actions
• IndicatorPreference - User's preferred indicators for AI

---

📊 Response Quality Examples

Scenario Analysis Response

Before Enhancement:

Generic recommendation with basic reasoning.
No specific levels or risk assessment.

After Enhancement:

RECOMMENDATION: BUY
CONFIDENCE: 78%

REASONING:
Gold is showing bullish momentum above the key $2,045 support level.
The 20-EMA has crossed above the 50-EMA (golden cross), indicating
strengthening uptrend. RSI at 58 shows room to run before overbought.
MACD histogram turning positive supports the bullish case.

ENTRY: $2,050.00 (on pullback to 20-EMA)
TARGETS: $2,060 (R1), $2,070 (previous high), $2,082 (R2)
STOP LOSS: $2,043 (below recent swing low + $4 buffer)

RISK LEVEL: MEDIUM
- USD showing weakness supporting gold
- Safe-haven demand elevated
- Watch for reversal at $2,070 resistance

RISK/REWARD: 1:2.8 (Favorable)

Daily Plan Response

Before Enhancement:

Basic market outlook without specific levels or rules.

After Enhancement:

GOLD TRADING PLAN - November 23, 2025

MARKET BIAS: BULLISH (Confidence: 75%)

STRATEGY: Pullback buying on strong uptrend
- Look for dips to 20/50-EMA zone
- Target breakout above yesterday's high
- Respect key support at $2,045

TRADE SETUPS:

Setup #1 (Primary):
  DIRECTION: LONG
  ENTRY ZONE: $2,048-2,051 (pullback to EMA zone)
  TARGETS: T1=$2,060 (25%), T2=$2,070 (50%), T3=$2,082 (25%)
  STOP: $2,043 (below swing low)
  R:R: 2.5:1

Setup #2 (Breakout):
  DIRECTION: LONG
  ENTRY: $2,070 break and retest
  TARGETS: $2,082, $2,095
  STOP: $2,065
  R:R: 2:1

MAX TRADES: 3
RISK PER TRADE: 1-2% of capital
MAX DAILY LOSS: -3% (stop trading if hit)

BEST TIMING: 8:00-11:00 AM EST (London/NY overlap)

KEY LEVELS:
  Resistance: $2,067.50, $2,075, $2,082.50
  Support: $2,045.50, $2,038, $2,030.50

WATCH FOR:
- USD weakness continuation
- 10Y Treasury yields
- Any Fed speaker comments

CONTINGENCY:
If price drops below $2,045: Switch to BEARISH bias,
target $2,038 and $2,030 support levels.

---

🚨 Troubleshooting

Issue: AI responses seem generic

Cause: API key not set or incorrect Fix:

# Check .env file
cat backend/.env | grep OPENROUTER

# Should show:
OPENROUTER_API_KEY=sk-or-v1-xxxxx

Issue: Slow response times

Cause: Large context or complex analysis Fix:

• Reduce price history to 50 candles max
• Use faster model (e.g., GPT-3.5)
• Reduce max_tokens to 1500

Issue: Responses don't include specific levels

Cause: Insufficient price data Fix: Send at least 20 recent candles with OHLC data

Issue: 500 Error on AI analysis

Cause: Empty price_data array (fixed in latest version) Fix: Update to latest openrouter.py with graceful handling

Issue: High API costs

Optimization:

• Cache daily plans (regenerate only on user request)
• Use scenario analysis sparingly
• Consider cheaper models for news summarization
• Set usage limits in OpenRouter dashboard

---

📈 Future Enhancements

Planned Features

• Pattern recognition training
• Backtesting AI recommendations
• Multi-timeframe analysis
• Correlation analysis with other assets
• AI-powered alert generation
• Custom prompt templates per user
• Performance tracking (AI vs manual trades)

---

🔐 Security & Privacy

Data Handling

• ✅ API keys stored in environment variables
• ✅ No sensitive data sent to OpenRouter
• ✅ User trading data stays in local database
• ✅ AI responses cached to minimize API calls

API Key Security

Never commit API keys to git:

# Add to .gitignore
backend/.env

Use environment-specific keys:

• Development: Use test key with low limits
• Production: Use main key with higher limits
• Rotate keys periodically

---

📞 Support

Getting Help

1. Check test scripts:

   python test_openrouter.py
   python test_improved_prompts.py
   

2. Review logs:

   # Backend logs
   tail -f backend/logs/app.log
   

3. OpenRouter Dashboard:

   • Monitor usage: https://openrouter.ai/activity
   • Check credits: https://openrouter.ai/credits
   • View API logs: https://openrouter.ai/logs

Common Questions

Q: Which AI model should I use? A: Claude 3.5 Sonnet for best trading analysis. GPT-4 Turbo for faster responses. GPT-3.5 for cost optimization.

Q: How much does it cost? A: ~$0.01-0.05 per analysis. $5 credit = 200-500 analyses.

Q: Can I use multiple models? A: Yes, switch via OPENROUTER_MODEL env variable.

Q: Does it work offline? A: No, requires internet connection to OpenRouter API.

Q: Can I self-host? A: Yes, modify services to use local LLM (Ollama, LM Studio).

---

Status: ✅ Production Ready Version: 2.0 Last Updated: November 2025 Maintained: Active