TradingAgents/.claude/cache/issue_body.md

Summary

Add OpenRouter as a third LLM provider option alongside OpenAI and Anthropic, leveraging OpenRouter's OpenAI-compatible API to enable access to multiple model providers through a single endpoint.

What Does NOT Work

Pattern: Direct OpenRouter SDK Integration

• OpenRouter does not have a dedicated SDK
• Attempting to create a separate OpenRouter client class fails because OpenRouter is OpenAI-compatible and should reuse the OpenAI SDK
• Using a custom client breaks LangChain integration patterns

Pattern: Hardcoding Model Names

• Hardcoding specific OpenRouter model names in config files fails because OpenRouter's model catalog changes frequently
• Model names should be configurable via environment variables, not hardcoded defaults

Pattern: Separate API Key Validation

• Creating OpenRouter-specific validation logic fails because OpenRouter uses the same OpenAI SDK authentication pattern
• Validation should reuse existing OpenAI patterns with different base URL

Scenarios

Fresh Install

• User runs Spektiv for the first time
• No .env file exists
• System should:
  • Create .env from .env.example with OPENROUTER_API_KEY= template
  • Default to openai provider if OPENROUTER_API_KEY not set
  • Show clear error message if user selects openrouter without API key

Update/Upgrade - Valid Existing Data

• User has existing .env with OPENAI_API_KEY or ANTHROPIC_API_KEY
• System should:
  • Preserve existing configuration
  • Add OPENROUTER_API_KEY= to .env.example (user must manually add to .env)
  • Not overwrite existing llm_provider setting
  • Display info message about new OpenRouter option

Update/Upgrade - User Customizations

• User has custom llm_provider, backend_url, or model settings
• System must:
  • Never overwrite user's custom backend_url
  • Never change user's selected llm_provider
  • Only update .env.example, not .env

Implementation Approach

File 1: spektiv/default_config.py

Add OpenRouter to GENAI_PROVIDERS and genai_config section with llm_provider, backend_url, and model options.

File 2: spektiv/graph/trading_graph.py

Add elif branch for openrouter provider using ChatOpenAI with:

• base_url: https://openrouter.ai/api/v1
• api_key from OPENROUTER_API_KEY env var
• default_headers with HTTP-Referer and X-Title

File 3: .env.example

Add OPENROUTER_API_KEY template and LLM_PROVIDER, LLM_MODEL, BACKEND_URL options.

File 4: main.py

Add OpenRouter configuration example in comments.

File 5: README.md

Update LLM configuration section with all three providers (OpenAI, Anthropic, OpenRouter).

Test Scenarios

1. Fresh Install - No API Keys: Error message requesting API key for selected provider
2. Switch from OpenAI to OpenRouter: System uses OpenRouter, preserves OpenAI key
3. Custom Backend URL: System uses custom URL instead of default OpenRouter URL
4. Invalid OpenRouter Model: Clear error from OpenRouter API with docs link
5. Missing API Key: Immediate error before any API calls
6. Update Preserves Custom Config: .env unchanged, only .env.example updated

Acceptance Criteria

Fresh Install

• .env.example includes OPENROUTER_API_KEY= template
• .env.example includes LLM configuration examples for all three providers
• System defaults to openai if no provider specified
• Error message shown if user selects openrouter without API key

Updates

• Existing .env files are never modified
• Only .env.example is updated with new template
• Existing llm_provider setting is preserved
• Existing backend_url customizations are preserved
• README updated with OpenRouter configuration examples

Functionality

• OpenRouter works with default model
• OpenRouter works with custom LLM_MODEL setting
• OpenRouter works with custom BACKEND_URL setting
• LangChain integration uses ChatOpenAI with custom base_url
• HTTP headers include referer and title for OpenRouter tracking

Validation

• Clear error if OPENROUTER_API_KEY missing
• Clear error if invalid llm_provider specified
• Error messages include documentation links
• Config validation happens before first API call

Security

• API keys never logged or printed
• API keys only read from environment variables
• No hardcoded API keys in any file
• .env file remains in .gitignore

Documentation

• README shows all three provider configurations
• README links to OpenRouter model catalog
• README explains model name format (provider/model-name)
• Comments in code explain OpenRouter OpenAI-compatibility

Environment Requirements

• Python 3.8+
• LangChain 0.1.0+
• OpenAI SDK (already required for OpenAI provider)

Source of Truth

• OpenRouter API documentation: https://openrouter.ai/docs
• Proven implementation pattern from anyclaude
• Verified: 2024-12-25