charieswei
/
TradingAgents
mirror of https://github.com/TauricResearch/TradingAgents.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
TradingAgents/CHANGELOG_EMBEDDING.md

7.1 KiB
Raw Blame History

Changelog - Embedding Provider Separation

[2.0.0] - 2025-01-XX

Added

Separate Embedding Configuration

  • New Config Parameters: Added 4 new configuration options for independent embedding setup
    • embedding_provider: Choose between "openai", "ollama", or "none"
    • embedding_backend_url: Separate API endpoint for embeddings
    • embedding_model: Specific model to use for embeddings
    • enable_memory: Boolean flag to enable/disable memory system

Multi-Provider Support

  • OpenAI Embeddings: Production-grade embeddings with text-embedding-3-small (default)
  • Ollama Embeddings: Local embedding support with nomic-embed-text
  • Disabled Memory: Option to run without memory/embeddings for testing or cost optimization

CLI Enhancements

  • Step 7: Embedding Provider Selection: New interactive step in CLI workflow
  • User-friendly provider selection with clear descriptions
  • Automatic configuration based on provider choice

Graceful Fallback System

  • Memory operations return empty results instead of crashing
  • Comprehensive error logging for debugging
  • Agents continue functioning when embeddings are unavailable
  • Safe defaults throughout the memory system

Documentation

  • docs/EMBEDDING_CONFIGURATION.md: Complete configuration guide with examples
  • docs/EMBEDDING_MIGRATION.md: Implementation details and migration guide
  • API reference and troubleshooting sections

Changed

Core Components

  • TradingAgentsGraph: Now initializes embeddings separately from chat models

    • Added _configure_embeddings() method for smart defaults
    • Logs memory status on initialization
    • reflect_and_remember() respects memory settings

  • FinancialSituationMemory: Complete refactor with robust error handling

    • All methods return Optional types with None fallbacks
    • Added is_enabled() method to check memory status
    • Provider-specific model selection logic
    • Comprehensive logging at INFO, WARNING, and ERROR levels

  • cli/main.py: Updated to support embedding configuration

    • Added embedding provider selection to user workflow
    • Passes embedding config to graph initialization
    • Improved code formatting and consistency

  • cli/utils.py: New selection function for embeddings

    • select_embedding_provider() returns (provider, url, model) tuple
    • Interactive questionnaire with helpful descriptions
    • Code style improvements

Fixed

Critical Issues

  • OpenRouter Compatibility: Resolved crash when using OpenRouter for chat

    • Previous: Used same backend URL for embeddings, causing HTML response errors
    • Now: Embeddings use separate, configurable endpoint

  • Provider Flexibility: Fixed inability to mix providers

    • Previous: Chat and embedding providers were coupled
    • Now: Use any combination (e.g., OpenRouter chat + OpenAI embeddings)

  • Embedding Failures: System no longer crashes on embedding errors

    • Previous: AttributeError: 'str' object has no attribute 'data'
    • Now: Graceful fallback with logging, system continues

Backward Compatibility

✅ Fully Backward Compatible - No breaking changes

  • Existing configurations work without modification
  • Smart defaults applied when embedding settings are omitted
  • Default: Uses OpenAI for both chat and embeddings (previous behavior)

Example Migration

Before (Still Works)

config = {
    "llm_provider": "openai",
    "backend_url": "https://api.openai.com/v1",
}

After (New Capabilities)

config = {
    # Chat with OpenRouter
    "llm_provider": "openrouter",
    "backend_url": "https://openrouter.ai/api/v1",
    "deep_think_llm": "deepseek/deepseek-chat-v3-0324:free",
    "quick_think_llm": "meta-llama/llama-3.3-8b-instruct:free",
    
    # Embeddings with OpenAI
    "embedding_provider": "openai",
    "embedding_backend_url": "https://api.openai.com/v1",
    "embedding_model": "text-embedding-3-small",
    "enable_memory": True,
}

Usage Examples

Scenario 1: OpenRouter + OpenAI (Recommended)

config = {
    "llm_provider": "openrouter",
    "embedding_provider": "openai",  # Separate provider
}

Scenario 2: All Local with Ollama

config = {
    "llm_provider": "ollama",
    "embedding_provider": "ollama",
    "embedding_model": "nomic-embed-text",
}

Scenario 3: No Memory/Embeddings

config = {
    "llm_provider": "anthropic",
    "enable_memory": False,  # Disable embeddings
}

Environment Variables

New API key requirements based on configuration:

# For OpenAI embeddings
export OPENAI_API_KEY="sk-..."

# For OpenRouter chat
export OPENROUTER_API_KEY="sk-or-..."

# For Anthropic chat
export ANTHROPIC_API_KEY="sk-ant-..."

Technical Details

Files Modified

  • tradingagents/default_config.py - Added embedding config parameters
  • tradingagents/agents/utils/memory.py - Complete refactor with error handling
  • tradingagents/graph/trading_graph.py - Separated embedding initialization
  • cli/main.py - Added embedding provider selection step
  • cli/utils.py - New select_embedding_provider() function

Files Added

  • docs/EMBEDDING_CONFIGURATION.md - Comprehensive guide
  • docs/EMBEDDING_MIGRATION.md - Implementation summary
  • CHANGELOG_EMBEDDING.md - This file

Dependencies

No new dependencies required. Uses existing:

  • openai - For OpenAI API clients
  • chromadb - For vector storage

Performance Impact

  • Initialization: Negligible overhead (~50ms for embedding client setup)
  • Runtime: No impact when memory disabled
  • Cost: Potential savings by using local embeddings or disabling memory

Security Notes

  • Use separate API keys for different providers (least privilege)
  • Embedding data is sent to configured provider endpoint
  • Ensure compliance with data governance policies

Known Limitations

  • Embedding providers limited to OpenAI, Ollama, or disabled
  • No caching of embeddings (future enhancement)
  • ChromaDB storage is local only

Future Roadmap

Potential enhancements for next versions:

  • Additional embedding providers (HuggingFace, Cohere, Azure)
  • Embedding caching to reduce API calls
  • Custom fine-tuned embedding model support
  • Async/batch embedding operations
  • Embedding quality metrics and monitoring

Upgrade Instructions

  1. Update to latest version on feature/separate-embedding-client branch
  2. Review your current configuration
  3. (Optional) Add explicit embedding configuration for clarity
  4. Set appropriate API keys in .env
  5. Test with your configuration
  6. Monitor logs for any warnings

No code changes required for existing deployments!

Support

For issues or questions:

  • Review docs/EMBEDDING_CONFIGURATION.md for detailed guide
  • Check logs for specific error messages
  • Open GitHub issue with configuration and logs

Contributors

This feature addresses the embedding/chat provider separation issue discussed in the community and implements the solution with backward compatibility and robust error handling.

Branch: feature/separate-embedding-client
Status: ✅ Ready for merge
Breaking Changes: None
Migration Required: No (optional enhancements available)