buda_api 1.0.0 → 1.0.1

data/examples/ai/risk_management_example.rb

@@ -0,0 +1,300 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Advanced Risk Management with AI
+# This example demonstrates comprehensive risk management using AI-powered analysis
+
+require 'bundler/setup'
+require_relative '../../lib/buda_api'
+
+# Configuration
+API_KEY = ENV['BUDA_API_KEY'] || 'your_api_key_here'
+API_SECRET = ENV['BUDA_API_SECRET'] || 'your_api_secret_here'
+
+def main
+  puts "⚠️ Advanced AI Risk Management Example"
+  puts "=" * 50
+  
+  unless BudaApi.ai_available?
+    puts "❌ AI features not available. Install ruby_llm gem first."
+    return
+  end
+  
+  # Initialize client and risk manager
+  client = BudaApi::AuthenticatedClient.new(
+    api_key: API_KEY,
+    api_secret: API_SECRET,
+    sandbox: true
+  )
+  
+  risk_manager = BudaApi::AI::RiskManager.new(client, llm_provider: :openai)
+  
+  # Example 1: Comprehensive Portfolio Risk Analysis
+  puts "\n📊 Portfolio Risk Analysis"
+  puts "-" * 30
+  
+  portfolio_risk = risk_manager.analyze_portfolio_risk(
+    include_ai_insights: true,
+    focus_factors: ["concentration_risk", "volatility_risk"]
+  )
+  
+  if portfolio_risk[:type] == :portfolio_risk_analysis
+    puts "Portfolio Overview:"
+    puts "  Total Value: #{portfolio_risk[:portfolio_value].round(2)} CLP"
+    puts "  Risk Level: #{portfolio_risk[:overall_risk][:color]} #{portfolio_risk[:overall_risk][:level]}"
+    puts "  Risk Score: #{portfolio_risk[:overall_risk][:score].round(1)}/5.0"
+    puts "  Holdings: #{portfolio_risk[:currency_count]} different currencies"
+    
+    puts "\nRisk Breakdown:"
+    risk_components = portfolio_risk[:overall_risk][:components]
+    puts "  Concentration Risk: #{risk_components[:concentration].round(1)}/5.0"
+    puts "  Volatility Risk: #{risk_components[:volatility].round(1)}/5.0"
+    puts "  Diversification Risk: #{risk_components[:diversification].round(1)}/5.0"
+    puts "  Correlation Risk: #{risk_components[:correlation].round(1)}/5.0"
+    
+    puts "\nTop Holdings:"
+    portfolio_risk[:holdings].first(3).each do |holding|
+      percentage = (holding[:amount] / portfolio_risk[:portfolio_value]) * 100
+      puts "  #{holding[:currency]}: #{holding[:amount].round(4)} (#{percentage.round(1)}%)"
+    end
+    
+    if portfolio_risk[:recommendations].any?
+      puts "\nRecommendations:"
+      portfolio_risk[:recommendations].each do |rec|
+        puts "  #{rec[:type].upcase}: #{rec[:message]}"
+      end
+    end
+    
+    if portfolio_risk[:ai_insights]
+      puts "\nAI Risk Insights:"
+      puts portfolio_risk[:ai_insights][:analysis]
+    end
+  else
+    puts "Portfolio Risk: #{portfolio_risk[:message]}"
+  end
+  
+  # Example 2: Pre-Trade Risk Evaluation
+  puts "\n🎯 Pre-Trade Risk Evaluation"
+  puts "-" * 30
+  
+  # Evaluate risk for a potential BTC purchase
+  trade_risk = risk_manager.evaluate_trade_risk(
+    "BTC-CLP",
+    "buy",
+    0.001,  # 0.001 BTC
+    nil     # Market price
+  )
+  
+  if trade_risk[:type] == :trade_risk_evaluation
+    puts "Trade Risk Assessment:"
+    puts "  Market: #{trade_risk[:market_id]}"
+    puts "  Side: #{trade_risk[:side]} #{trade_risk[:amount]} BTC"
+    puts "  Risk Level: #{RISK_LEVELS[trade_risk[:risk_level]][:color]} #{RISK_LEVELS[trade_risk[:risk_level]][:description]}"
+    puts "  Risk Score: #{trade_risk[:risk_score].round(1)}/5.0"
+    puts "  Should Proceed: #{trade_risk[:should_proceed] ? '✅ Yes' : '❌ No'}"
+    
+    puts "\nRisk Factors:"
+    puts "  Position Impact: #{trade_risk[:position_risk][:portfolio_percentage].round(1)}% of portfolio"
+    puts "  Market Impact: #{trade_risk[:market_impact_risk][:impact_score].round(1)}/5.0"
+    puts "  Trade Value: #{trade_risk[:trade_impact][:estimated_cost].round(2)} CLP"
+    
+    puts "\nRecommendations:"
+    trade_risk[:recommendations].each do |recommendation|
+      puts "  • #{recommendation}"
+    end
+  end
+  
+  # Example 3: Risk Monitoring with Alerts
+  puts "\n🚨 Risk Threshold Monitoring"
+  puts "-" * 30
+  
+  # Set custom risk thresholds
+  thresholds = {
+    max_position_percentage: 25.0,    # Max 25% in single asset
+    max_daily_loss: 3.0,             # Max 3% daily loss
+    min_diversification_score: 0.7,   # Min diversification
+    max_volatility_score: 3.5         # Max volatility tolerance
+  }
+  
+  monitoring_result = risk_manager.monitor_risk_thresholds(thresholds)
+  
+  puts "Risk Monitoring Results:"
+  puts "  Alerts Detected: #{monitoring_result[:alerts_count]}"
+  puts "  Portfolio Safe: #{monitoring_result[:safe] ? '✅ Yes' : '❌ No'}"
+  
+  if monitoring_result[:alerts].any?
+    puts "\nActive Alerts:"
+    monitoring_result[:alerts].each do |alert|
+      level_emoji = case alert[:level]
+        when :high then "🚨"
+        when :medium then "⚠️"
+        else "ℹ️"
+      end
+      puts "  #{level_emoji} #{alert[:message]}"
+    end
+  end
+  
+  puts "\nCurrent Thresholds:"
+  monitoring_result[:thresholds].each do |name, value|
+    puts "  #{name}: #{value}"
+  end
+  
+  # Example 4: Stop-Loss Recommendations
+  puts "\n🛡️ Stop-Loss Recommendations"
+  puts "-" * 30
+  
+  # Assume we have a BTC position to protect
+  position_size = 0.005  # 0.005 BTC
+  
+  stop_loss_rec = risk_manager.recommend_stop_loss("BTC-CLP", position_size)
+  
+  if stop_loss_rec[:type] == :stop_loss_recommendations
+    puts "Stop-Loss Analysis for #{stop_loss_rec[:position_size]} BTC:"
+    puts "Current Price: #{stop_loss_rec[:current_price]} CLP"
+    puts "Position Value: #{stop_loss_rec[:position_value].round(2)} CLP"
+    
+    puts "\nStop-Loss Options:"
+    stop_loss_rec[:recommendations].each do |name, option|
+      puts "  #{name.capitalize}:"
+      puts "    Price: #{option[:price].round(2)} CLP"
+      puts "    Max Loss: #{option[:max_loss].round(2)} CLP (#{option[:percentage]}%)"
+      puts "    Description: #{option[:description]}"
+      puts
+    end
+    
+    recommended = stop_loss_rec[:recommendation]
+    puts "💡 Recommended: #{recommended} stop-loss based on current market conditions"
+  end
+  
+  # Example 5: Risk-Adjusted Position Sizing
+  puts "\n📏 Risk-Adjusted Position Sizing"
+  puts "-" * 30
+  
+  # Calculate optimal position size based on risk tolerance
+  def calculate_optimal_position_size(portfolio_value, risk_per_trade_percent, stop_loss_percent)
+    risk_amount = portfolio_value * (risk_per_trade_percent / 100.0)
+    position_size_clp = risk_amount / (stop_loss_percent / 100.0)
+    position_size_clp
+  end
+  
+  portfolio_value = portfolio_risk[:portfolio_value] || 1000000  # 1M CLP default
+  risk_per_trade = 2.0  # Risk 2% per trade
+  stop_loss_distance = 5.0  # 5% stop loss
+  
+  optimal_position_clp = calculate_optimal_position_size(
+    portfolio_value, 
+    risk_per_trade, 
+    stop_loss_distance
+  )
+  
+  puts "Position Sizing Calculation:"
+  puts "  Portfolio Value: #{portfolio_value.round(2)} CLP"
+  puts "  Risk Per Trade: #{risk_per_trade}%"
+  puts "  Stop Loss Distance: #{stop_loss_distance}%"
+  puts "  Optimal Position Size: #{optimal_position_clp.round(2)} CLP"
+  puts "  Max Risk Amount: #{(portfolio_value * risk_per_trade / 100.0).round(2)} CLP"
+  
+  # Example 6: Correlation Analysis
+  puts "\n🔗 Asset Correlation Analysis"
+  puts "-" * 30
+  
+  # Simplified correlation analysis using current price changes
+  def analyze_correlations(client, markets)
+    correlations = {}
+    
+    markets.each do |market1|
+      markets.each do |market2|
+        next if market1 == market2
+        
+        begin
+          ticker1 = client.ticker(market1)
+          ticker2 = client.ticker(market2)
+          
+          # Simple correlation based on 24h changes (in real implementation, use historical data)
+          change1 = ticker1.price_variation_24h
+          change2 = ticker2.price_variation_24h
+          
+          # Simplified correlation indicator
+          correlation = case
+            when (change1 > 0 && change2 > 0) || (change1 < 0 && change2 < 0)
+              (change1 * change2).abs / ([change1.abs, change2.abs].max + 0.01)
+            else
+              -(change1 * change2).abs / ([change1.abs, change2.abs].max + 0.01)
+          end
+          
+          correlations["#{market1}-#{market2}"] = correlation.round(2)
+        rescue
+          # Skip if unable to get data
+        end
+      end
+    end
+    
+    correlations
+  end
+  
+  major_markets = ["BTC-CLP", "ETH-CLP"]
+  correlations = analyze_correlations(client, major_markets)
+  
+  puts "Asset Correlation Analysis:"
+  correlations.each do |pair, correlation|
+    correlation_level = case correlation.abs
+      when 0.8..1.0 then "Very High"
+      when 0.6..0.8 then "High" 
+      when 0.4..0.6 then "Medium"
+      when 0.2..0.4 then "Low"
+      else "Very Low"
+    end
+    
+    direction = correlation > 0 ? "Positive" : "Negative"
+    puts "  #{pair}: #{correlation} (#{direction} #{correlation_level})"
+  end
+  
+  # Example 7: Risk Dashboard Summary
+  puts "\n📋 Risk Dashboard Summary"
+  puts "=" * 50
+  
+  dashboard = {
+    portfolio_health: portfolio_risk[:overall_risk][:level],
+    active_alerts: monitoring_result[:alerts_count],
+    risk_score: portfolio_risk[:overall_risk][:score].round(1),
+    recommendations_count: portfolio_risk[:recommendations]&.length || 0,
+    last_updated: Time.now.strftime("%Y-%m-%d %H:%M:%S")
+  }
+  
+  puts "Risk Dashboard:"
+  puts "  Portfolio Health: #{RISK_LEVELS[dashboard[:portfolio_health].to_sym][:color]} #{dashboard[:portfolio_health]}"
+  puts "  Risk Score: #{dashboard[:risk_score]}/5.0"
+  puts "  Active Alerts: #{dashboard[:active_alerts]}"
+  puts "  Pending Recommendations: #{dashboard[:recommendations_count]}"
+  puts "  Last Updated: #{dashboard[:last_updated]}"
+  
+  # Health status
+  overall_status = if dashboard[:risk_score] < 2.5 && dashboard[:active_alerts] == 0
+    "🟢 HEALTHY"
+  elsif dashboard[:risk_score] < 4.0 && dashboard[:active_alerts] < 3
+    "🟡 CAUTION"
+  else
+    "🔴 HIGH RISK"
+  end
+  
+  puts "  Overall Status: #{overall_status}"
+
+rescue BudaApi::ApiError => e
+  puts "❌ API Error: #{e.message}"
+rescue => e
+  puts "❌ Error: #{e.message}"
+  puts e.backtrace.first(3).join("\n") if ENV['DEBUG']
+end
+
+# Define risk levels constant for display
+RISK_LEVELS = {
+  very_low: { color: "🟢", description: "Very Low Risk" },
+  low: { color: "🟡", description: "Low Risk" },
+  medium: { color: "🟠", description: "Medium Risk" },
+  high: { color: "🔴", description: "High Risk" },
+  very_high: { color: "🚫", description: "Very High Risk" }
+}
+
+if __FILE__ == $0
+  main
+end

data/examples/ai/trading_assistant_example.rb

@@ -0,0 +1,295 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: AI-Enhanced Trading Assistant
+# This example demonstrates how to use BudaApi with AI features for comprehensive trading analysis
+
+require 'bundler/setup'
+require_relative '../lib/buda_api'
+
+# Configuration
+API_KEY = ENV['BUDA_API_KEY'] || 'your_api_key_here'
+API_SECRET = ENV['BUDA_API_SECRET'] || 'your_api_secret_here'
+LLM_PROVIDER = :openai  # or :anthropic, :ollama
+
+def main
+  puts "🤖 BudaApi AI Trading Assistant Example"
+  puts "=" * 50
+  
+  # Check if AI features are available
+  unless BudaApi.ai_available?
+    puts "❌ AI features are not available. Please install ruby_llm gem:"
+    puts "   gem install ruby_llm"
+    return
+  end
+  
+  puts "✅ AI features available"
+  
+  # Initialize authenticated client
+  client = BudaApi::AuthenticatedClient.new(
+    api_key: API_KEY,
+    api_secret: API_SECRET,
+    sandbox: true  # Use sandbox for testing
+  )
+  
+  # Initialize AI trading assistant
+  assistant = BudaApi.trading_assistant(client, llm_provider: LLM_PROVIDER)
+  
+  # Example 1: Market Analysis with AI
+  puts "\n📊 Market Analysis"
+  puts "-" * 30
+  
+  market_analysis = assistant.analyze_market("BTC-CLP")
+  puts "Market: #{market_analysis[:market_id]}"
+  puts "Current Price: #{market_analysis[:current_price]} CLP"
+  puts "Trend: #{market_analysis[:trend]}"
+  puts "AI Recommendation: #{market_analysis[:ai_recommendation][:action]}"
+  puts "Confidence: #{market_analysis[:ai_recommendation][:confidence]}%"
+  
+  # Example 2: Trading Strategy Suggestions
+  puts "\n🎯 Trading Strategy"
+  puts "-" * 30
+  
+  strategy = assistant.suggest_trading_strategy(
+    market_id: "BTC-CLP",
+    risk_tolerance: "medium",
+    investment_horizon: "short_term"
+  )
+  
+  puts "Strategy: #{strategy[:strategy_name]}"
+  puts "Entry Range: #{strategy[:entry_signals][:price_range][:min]} - #{strategy[:entry_signals][:price_range][:max]} CLP"
+  puts "Target: #{strategy[:profit_targets].first[:price]} CLP (#{strategy[:profit_targets].first[:percentage]}%)"
+  puts "Stop Loss: #{strategy[:risk_management][:stop_loss][:price]} CLP"
+  
+  # Example 3: Entry/Exit Signals
+  puts "\n🚦 Entry/Exit Signals"
+  puts "-" * 30
+  
+  signals = assistant.get_entry_exit_signals(["BTC-CLP", "ETH-CLP"])
+  
+  signals[:signals].each do |signal|
+    puts "#{signal[:market_id]}:"
+    puts "  Signal: #{signal[:signal]} (#{signal[:strength]})"
+    puts "  Price: #{signal[:current_price]} CLP"
+    puts "  Recommendation: #{signal[:recommendation]}"
+    puts
+  end
+  
+  # Example 4: Natural Language Trading
+  puts "\n💬 Natural Language Trading"
+  puts "-" * 30
+  
+  nl_trader = BudaApi.natural_language_trader(client, llm_provider: LLM_PROVIDER)
+  
+  # Execute natural language commands
+  commands = [
+    "Check my BTC balance",
+    "What's the current price of Ethereum?",
+    "Show me the order book for BTC-CLP"
+  ]
+  
+  commands.each do |command|
+    puts "Query: #{command}"
+    result = nl_trader.execute_command(command, confirm_trades: false)
+    puts "Response: #{result[:content] || result[:message]}"
+    puts
+  end
+  
+  # Example 5: Risk Management
+  puts "\n⚠️ Risk Management"
+  puts "-" * 30
+  
+  risk_manager = BudaApi::AI::RiskManager.new(client, llm_provider: LLM_PROVIDER)
+  
+  portfolio_risk = risk_manager.analyze_portfolio_risk(include_ai_insights: true)
+  
+  if portfolio_risk[:type] == :portfolio_risk_analysis
+    puts "Portfolio Value: #{portfolio_risk[:portfolio_value].round(2)} CLP"
+    puts "Risk Level: #{portfolio_risk[:overall_risk][:color]} #{portfolio_risk[:overall_risk][:level]}"
+    puts "Risk Score: #{portfolio_risk[:overall_risk][:score].round(1)}/5.0"
+    
+    if portfolio_risk[:ai_insights]
+      puts "\nAI Risk Insights:"
+      puts portfolio_risk[:ai_insights][:analysis]
+    end
+  else
+    puts "Portfolio analysis: #{portfolio_risk[:message]}"
+  end
+  
+  # Example 6: Anomaly Detection
+  puts "\n🔍 Anomaly Detection"
+  puts "-" * 30
+  
+  detector = BudaApi::AI::AnomalyDetector.new(client, llm_provider: LLM_PROVIDER)
+  
+  anomalies = detector.detect_market_anomalies(
+    markets: ["BTC-CLP", "ETH-CLP"],
+    include_ai_analysis: true
+  )
+  
+  puts "Markets Analyzed: #{anomalies[:markets_analyzed]}"
+  puts "Anomalies Detected: #{anomalies[:anomalies_detected]}"
+  
+  if anomalies[:anomalies_detected] > 0
+    puts "\nTop Anomalies:"
+    anomalies[:anomalies].first(3).each do |anomaly|
+      puts "  #{anomaly[:type]}: #{anomaly[:description]} (#{anomaly[:severity]})"
+    end
+    
+    if anomalies[:ai_analysis]
+      puts "\nAI Analysis:"
+      puts anomalies[:ai_analysis][:analysis]
+    end
+  else
+    puts "✅ No significant anomalies detected"
+  end
+  
+  # Example 7: Report Generation
+  puts "\n📋 Report Generation"
+  puts "-" * 30
+  
+  reporter = BudaApi::AI::ReportGenerator.new(client, llm_provider: LLM_PROVIDER)
+  
+  portfolio_report = reporter.generate_portfolio_summary(
+    format: "markdown",
+    include_ai: true
+  )
+  
+  if portfolio_report[:type] == :portfolio_summary_report
+    puts "Report generated successfully!"
+    puts "Format: #{portfolio_report[:format]}"
+    
+    # Save report to file
+    filename = "portfolio_report_#{Time.now.strftime('%Y%m%d_%H%M%S')}.md"
+    File.write(filename, portfolio_report[:formatted_content])
+    puts "Report saved to: #{filename}"
+  else
+    puts "Report generation: #{portfolio_report[:message] || portfolio_report[:error]}"
+  end
+  
+  # Example 8: Custom AI Analysis
+  puts "\n🧠 Custom AI Analysis"
+  puts "-" * 30
+  
+  custom_prompt = "Analyze the Chilean cryptocurrency market trends and provide investment recommendations for the next week"
+  
+  custom_report = reporter.generate_custom_report(
+    custom_prompt,
+    [:portfolio, :market],
+    format: "text"
+  )
+  
+  if custom_report[:ai_analysis]
+    puts "Custom Analysis:"
+    puts custom_report[:ai_analysis][:content]
+  else
+    puts "Custom analysis not available"
+  end
+  
+rescue BudaApi::AuthenticationError
+  puts "❌ Authentication failed. Please check your API credentials."
+rescue BudaApi::ApiError => e
+  puts "❌ API Error: #{e.message}"
+rescue => e
+  puts "❌ Unexpected error: #{e.message}"
+  puts e.backtrace.first(5).join("\n") if ENV['DEBUG']
+end
+
+# Interactive mode
+def interactive_mode
+  puts "\n🎮 Interactive AI Trading Mode"
+  puts "Type 'help' for commands, 'exit' to quit"
+  puts "-" * 40
+  
+  client = BudaApi::AuthenticatedClient.new(
+    api_key: API_KEY,
+    api_secret: API_SECRET,
+    sandbox: true
+  )
+  
+  nl_trader = BudaApi.natural_language_trader(client, llm_provider: LLM_PROVIDER)
+  
+  loop do
+    print "\n💬 Ask me anything about trading: "
+    input = gets.chomp
+    
+    case input.downcase
+    when 'exit', 'quit'
+      puts "👋 Goodbye!"
+      break
+    when 'help'
+      show_help
+    when 'clear'
+      nl_trader.clear_history
+      puts "🧹 Conversation history cleared"
+    else
+      if input.strip.empty?
+        puts "Please enter a command or question"
+        next
+      end
+      
+      puts "🤔 Processing..."
+      result = nl_trader.execute_command(input, confirm_trades: true)
+      
+      case result[:type]
+      when :text_response
+        puts "🤖 #{result[:content]}"
+      when :confirmation_required
+        puts "⚠️ #{result[:message]}"
+        print "Confirm? (y/n): "
+        confirm = gets.chomp.downcase
+        if confirm == 'y' || confirm == 'yes'
+          # Would execute the confirmed action
+          puts "✅ Action confirmed (demo mode - not actually executed)"
+        else
+          puts "❌ Action cancelled"
+        end
+      when :order_placed
+        puts "✅ #{result[:message]}"
+      when :balance_info
+        puts "💰 #{result[:message]}"
+      when :market_data
+        puts "📊 #{result[:message]}"
+      when :error
+        puts "❌ #{result[:error]}"
+      else
+        puts "📋 #{result[:message] || 'Action completed'}"
+      end
+    end
+  end
+end
+
+def show_help
+  puts """
+Available commands:
+  - Check my [currency] balance
+  - What's the price of [crypto]?
+  - Buy/sell [amount] [crypto]
+  - Show order book for [market]
+  - Get market analysis for [market]
+  - What are the best trading opportunities?
+  - Analyze my portfolio risk
+  - Generate a trading report
+  
+Special commands:
+  - help: Show this help
+  - clear: Clear conversation history  
+  - exit: Quit interactive mode
+"""
+end
+
+if __FILE__ == $0
+  puts "Choose mode:"
+  puts "1. Run examples (default)"
+  puts "2. Interactive mode"
+  print "Selection (1-2): "
+  
+  choice = gets.chomp
+  
+  case choice
+  when '2'
+    interactive_mode if BudaApi.ai_available?
+  else
+    main
+  end
+end