buda_api 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a433f2896be92c5a860e32dd6d2ee0dcfe1de74cf5f6f49a9da3d60c9c63750
-  data.tar.gz: 2ac6836267f19130e6c130e96475cff7b98a6ea84d611ec3fdfd5a3b1c7aeba5
+  metadata.gz: e1106716da601c58bf56e37ff6308dbb2bd269ff5827c9d99e710b402fabfe88
+  data.tar.gz: 672bda6f820e1c816a29145e25f2c78ddc4f7a9ca645a435f3848ae3da15e02d
 SHA512:
-  metadata.gz: 898d29f2186c0072b78062e4e0c61bd37587cd3e666f4aab8b7182169f5a260e2218daab6e892fc51369d58f1c05f2cf3e9a8ea9aaa81271ec9ec5cefcea87c0
-  data.tar.gz: '05972086e7ce2168148375c016e8e937fcf42ad1c79426c5cd0c15dfd76c2dff074556c10bdf7bd2463341a3ea675a775b09e4314c521a4ce33dcd13ca7cdf64'
+  metadata.gz: 0be69e4ed08718e1b9377bf1f6a447c049567b0eedf9ce0200b29a6c4ee8d99c3e285db9ccdf74fe7cc92a4f1635de9382f91770784b3c8e385649eca9ac93cd
+  data.tar.gz: 053b5fc3d4d904d75dca3d0cdd2360ddba1ea6bafe974b81c284e69763badbaf0b290677637a2dbf10b075f6b3dbcc7053ac66b85cc7fa5e861277e252bd0e1a

data/README.md

@@ -16,6 +16,7 @@ A comprehensive Ruby SDK for [Buda.com](https://buda.com) cryptocurrency exchang
 - ⚡ **Automatic Retries** - Built-in retry logic for transient failures
 - 📖 **Extensive Documentation** - Complete API reference and examples
 - 🧪 **Comprehensive Examples** - Real-world usage examples including a trading bot
+- 🤖 **AI-Powered Trading** - Advanced AI features with RubyLLM integration
 
 ## Installation
 
@@ -37,6 +38,12 @@ Or install it yourself as:
 $ gem install buda_api
 ```
 
+For AI features, also install:
+
+```bash
+$ gem install ruby_llm
+```
+
 ## Quick Start
 
 ### Public API (No Authentication Required)
@@ -373,6 +380,14 @@ The SDK includes comprehensive examples in the `examples/` directory:
 
 - [`trading_bot_example.rb`](examples/trading_bot_example.rb) - Simple trading bot with price monitoring
 
+### AI-Enhanced Examples
+
+- [`ai/trading_assistant_example.rb`](examples/ai/trading_assistant_example.rb) - Comprehensive AI trading assistant
+- [`ai/natural_language_trading.rb`](examples/ai/natural_language_trading.rb) - Conversational trading interface
+- [`ai/risk_management_example.rb`](examples/ai/risk_management_example.rb) - AI-powered risk analysis
+- [`ai/anomaly_detection_example.rb`](examples/ai/anomaly_detection_example.rb) - Market anomaly detection
+- [`ai/report_generation_example.rb`](examples/ai/report_generation_example.rb) - Automated trading reports
+
 ### Running Examples
 
 1. Copy the environment file:
@@ -391,6 +406,9 @@ BUDA_API_SECRET=your_api_secret_here
 # Public API example (no credentials needed)
 ruby examples/public_api_example.rb
 
+# AI-enhanced trading assistant
+ruby examples/ai/trading_assistant_example.rb
+
 # Authenticated API example (requires credentials)
 ruby examples/authenticated_api_example.rb
 
@@ -462,9 +480,88 @@ The SDK automatically handles HMAC-SHA384 signature generation:
 2. Creates signature using HTTP method, path, body, and nonce
 3. Includes proper headers: `X-SBTC-APIKEY`, `X-SBTC-NONCE`, `X-SBTC-SIGNATURE`
 
+## AI Features
+
+The BudaApi Ruby SDK includes powerful AI enhancements through RubyLLM integration:
+
+### Trading Assistant
+```ruby
+# Initialize AI trading assistant
+assistant = BudaApi.trading_assistant(client)
+
+# Get AI market analysis
+analysis = assistant.analyze_market("BTC-CLP")
+puts analysis[:ai_recommendation][:action]  # "buy", "sell", or "hold"
+puts analysis[:ai_recommendation][:confidence]  # Confidence percentage
+
+# Get trading strategy recommendations
+strategy = assistant.suggest_trading_strategy(
+  market_id: "BTC-CLP",
+  risk_tolerance: "medium",
+  investment_horizon: "short_term"
+)
+```
+
+### Natural Language Trading
+```ruby
+# Create conversational trading interface
+nl_trader = BudaApi.natural_language_trader(client)
+
+# Execute commands in natural language
+result = nl_trader.execute_command("Check my Bitcoin balance")
+result = nl_trader.execute_command("What's the current price of Ethereum?")
+result = nl_trader.execute_command("Buy 0.001 BTC at market price")
+```
+
+### Risk Management
+```ruby
+# Initialize AI risk manager
+risk_manager = BudaApi::AI::RiskManager.new(client)
+
+# Analyze portfolio risk with AI insights
+portfolio_risk = risk_manager.analyze_portfolio_risk(
+  include_ai_insights: true
+)
+
+# Evaluate individual trade risk
+trade_risk = risk_manager.evaluate_trade_risk(
+  "BTC-CLP", "buy", 0.001
+)
+```
+
+### Anomaly Detection
+```ruby
+# Create market anomaly detector
+detector = BudaApi::AI::AnomalyDetector.new(client)
+
+# Detect market anomalies with AI analysis
+anomalies = detector.detect_market_anomalies(
+  markets: ["BTC-CLP", "ETH-CLP"],
+  include_ai_analysis: true
+)
+```
+
+### Report Generation
+```ruby
+# Generate AI-powered reports
+reporter = BudaApi::AI::ReportGenerator.new(client)
+
+# Portfolio summary with AI insights
+report = reporter.generate_portfolio_summary(
+  format: "markdown",
+  include_ai: true
+)
+
+# Custom AI analysis
+custom_report = reporter.generate_custom_report(
+  "Analyze market trends and provide investment recommendations",
+  [:portfolio, :market]
+)
+```
+
 ## Contributing
 
-1. Fork it (https://github.com/yourusername/buda-api-ruby/fork)
+1. Fork it (https://github.com/PabloB07/buda-api-ruby/fork)
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
@@ -473,7 +570,7 @@ The SDK automatically handles HMAC-SHA384 signature generation:
 ### Development Setup
 
 ```bash
-git clone https://github.com/yourusername/buda-api-ruby.git
+git clone https://github.com/PabloB07/buda-api-ruby.git
 cd buda-api-ruby
 bundle install
 bundle exec rspec
@@ -517,8 +614,8 @@ The authors and contributors are not responsible for any financial losses incurr
 ## Support
 
 - 📖 [API Documentation](https://api.buda.com)  
-- 🐛 [Issue Tracker](https://github.com/yourusername/buda-api-ruby/issues)
-- 💬 [Discussions](https://github.com/yourusername/buda-api-ruby/discussions)
+- 🐛 [Issue Tracker](https://github.com/PabloB07/buda-api-ruby/issues)
+- 💬 [Discussions](https://github.com/PabloB07/buda-api-ruby/discussions)
 
 ## Related Projects
 

data/buda_api.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "buda_api"
-  spec.version       = "1.0.0"
+  spec.version       = "1.0.1"
   spec.authors       = ["Buda API Ruby SDK"]
   spec.email         = ["pablob0798@gmail.com"]
 
@@ -29,6 +29,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency "logger", "~> 1.5"
   spec.add_dependency "json", "~> 2.6"
 
+  # Optional AI dependencies
+  spec.add_dependency "ruby_llm", "~> 0.5", ">= 0.5.0"
+
   # Development dependencies
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "webmock", "~> 3.0"

data/examples/ai/README.md

@@ -0,0 +1,314 @@
+# AI-Enhanced Ruby SDK Examples
+
+This directory contains comprehensive examples demonstrating the AI-powered features of the BudaApi Ruby SDK.
+
+## Examples Overview
+
+### 1. Trading Assistant (`trading_assistant_example.rb`)
+**Main AI-Enhanced Trading Example**
+
+Comprehensive demonstration of AI trading capabilities including:
+- **Market Analysis**: AI-powered technical and fundamental analysis
+- **Trading Strategies**: Intelligent strategy recommendations
+- **Entry/Exit Signals**: Automated signal generation
+- **Natural Language Trading**: Conversational trading interface
+- **Risk Management**: Portfolio risk assessment
+- **Anomaly Detection**: Market irregularity detection
+- **Report Generation**: AI-generated trading reports
+- **Interactive Mode**: Real-time AI trading assistant
+
+```bash
+# Run the main example
+ruby examples/ai/trading_assistant_example.rb
+
+# Run in interactive mode
+ruby examples/ai/trading_assistant_example.rb
+# Select option 2 for interactive mode
+```
+
+### 2. Advanced Risk Management (`risk_management_example.rb`)
+**Comprehensive Risk Analysis System**
+
+Features:
+- **Portfolio Risk Analysis**: Diversification and concentration analysis
+- **Pre-Trade Risk Evaluation**: Risk assessment before placing orders
+- **Risk Monitoring**: Real-time threshold monitoring with alerts
+- **Stop-Loss Recommendations**: AI-calculated stop-loss levels
+- **Position Sizing**: Risk-adjusted position calculations
+- **Correlation Analysis**: Asset correlation detection
+- **Risk Dashboard**: Comprehensive risk overview
+
+```bash
+ruby examples/ai/risk_management_example.rb
+```
+
+### 3. Natural Language Trading (`natural_language_trading.rb`)
+**Conversational Trading Interface**
+
+Chat-based trading with AI:
+- **Natural Language Queries**: Ask questions in plain English
+- **Balance Inquiries**: "Check my BTC balance"
+- **Market Data**: "What's the current price of Ethereum?"
+- **Trading Commands**: "Buy 0.001 BTC at market price"
+- **Safety Features**: Demo mode and confirmations
+- **Context Awareness**: Maintains conversation history
+
+```bash
+ruby examples/ai/natural_language_trading.rb
+```
+
+### 4. Anomaly Detection (`anomaly_detection_example.rb`)
+**AI-Powered Market Monitoring**
+
+Automated market surveillance:
+- **Real-Time Scanning**: Continuous market anomaly detection
+- **Multiple Detection Types**: Price spikes, volume anomalies, whale activity
+- **Severity Classification**: Critical, high, medium, low alerts
+- **Historical Analysis**: Pattern detection in historical data
+- **AI Analysis**: Intelligent anomaly interpretation
+- **Monitoring Modes**: One-time, continuous, or single-market analysis
+
+```bash
+# One-time scan
+ruby examples/ai/anomaly_detection_example.rb
+
+# Demo mode (simulated data)
+ruby examples/ai/anomaly_detection_example.rb --demo
+```
+
+### 5. Report Generation (`report_generation_example.rb`)
+**Automated AI Report System**
+
+Professional trading reports:
+- **Portfolio Reports**: Comprehensive portfolio analysis
+- **Trading Performance**: Trading statistics and insights
+- **Market Analysis**: Market trend analysis
+- **Custom Reports**: AI-generated custom analysis
+- **Multiple Formats**: Markdown, HTML, JSON, CSV export
+- **Report Dashboard**: Interactive report generation interface
+
+```bash
+# Interactive dashboard
+ruby examples/ai/report_generation_example.rb
+
+# Generate demo reports
+ruby examples/ai/report_generation_example.rb --demo
+```
+
+## Prerequisites
+
+### Required Gems
+```bash
+# Install the AI dependency
+gem install ruby_llm
+
+# Or add to your Gemfile
+gem 'ruby_llm', '~> 0.5'
+```
+
+### API Configuration
+Set your Buda API credentials:
+
+```bash
+export BUDA_API_KEY="your_api_key_here"
+export BUDA_API_SECRET="your_api_secret_here"
+```
+
+### LLM Provider Setup
+Configure your preferred AI provider:
+
+**OpenAI (Recommended)**
+```bash
+export OPENAI_API_KEY="your_openai_key"
+```
+
+**Anthropic Claude**
+```bash
+export ANTHROPIC_API_KEY="your_anthropic_key"
+```
+
+## Usage Patterns
+
+### Basic AI Trading Assistant
+```ruby
+require_relative '../lib/buda_api'
+
+client = BudaApi::AuthenticatedClient.new(
+  api_key: ENV['BUDA_API_KEY'],
+  api_secret: ENV['BUDA_API_SECRET']
+)
+
+# Initialize AI assistant
+assistant = BudaApi.trading_assistant(client)
+
+# Get market analysis
+analysis = assistant.analyze_market("BTC-CLP")
+puts "Trend: #{analysis[:trend]}"
+puts "AI Recommendation: #{analysis[:ai_recommendation][:action]}"
+```
+
+### Natural Language Trading
+```ruby
+# Create natural language trader
+nl_trader = BudaApi.natural_language_trader(client)
+
+# Execute commands in natural language
+result = nl_trader.execute_command("Check my Bitcoin balance")
+result = nl_trader.execute_command("What's the current ETH price?")
+result = nl_trader.execute_command("Buy 0.001 BTC at market price")
+```
+
+### Risk Management
+```ruby
+# Initialize risk manager
+risk_manager = BudaApi::AI::RiskManager.new(client)
+
+# Analyze portfolio risk
+portfolio_risk = risk_manager.analyze_portfolio_risk(
+  include_ai_insights: true
+)
+
+# Evaluate trade risk
+trade_risk = risk_manager.evaluate_trade_risk(
+  "BTC-CLP", "buy", 0.001
+)
+
+puts "Trade Risk: #{trade_risk[:risk_level]}"
+puts "Should Proceed: #{trade_risk[:should_proceed]}"
+```
+
+### Anomaly Detection
+```ruby
+# Create anomaly detector
+detector = BudaApi::AI::AnomalyDetector.new(client)
+
+# Detect market anomalies
+anomalies = detector.detect_market_anomalies(
+  markets: ["BTC-CLP", "ETH-CLP"],
+  include_ai_analysis: true
+)
+
+puts "Anomalies Detected: #{anomalies[:anomalies_detected]}"
+```
+
+### Report Generation
+```ruby
+# Initialize report generator
+reporter = BudaApi::AI::ReportGenerator.new(client)
+
+# Generate portfolio report
+report = reporter.generate_portfolio_summary(
+  format: "markdown",
+  include_ai: true
+)
+
+# Export to file
+reporter.export_report(report, "portfolio_report.md")
+```
+
+## AI Features Overview
+
+### Market Analysis Capabilities
+- **Technical Analysis**: Price patterns, trends, support/resistance
+- **Fundamental Analysis**: Market sentiment, news impact assessment
+- **Risk Assessment**: Volatility analysis, correlation detection
+- **Strategy Recommendations**: Entry/exit points, position sizing
+
+### Natural Language Processing
+- **Command Interpretation**: Understands trading intentions in natural language
+- **Context Awareness**: Maintains conversation history and context
+- **Error Handling**: Provides helpful suggestions for unclear commands
+- **Safety Features**: Confirms potentially risky operations
+
+### Risk Management AI
+- **Portfolio Analysis**: Diversification scoring, concentration risk
+- **Pre-Trade Evaluation**: Impact assessment before order placement
+- **Dynamic Monitoring**: Real-time risk threshold monitoring
+- **Predictive Modeling**: Risk-adjusted return optimization
+
+### Anomaly Detection AI
+- **Pattern Recognition**: Identifies unusual market behaviors
+- **Multi-Factor Analysis**: Price, volume, spread, and correlation anomalies
+- **Severity Scoring**: Intelligent risk prioritization
+- **Real-Time Monitoring**: Continuous market surveillance
+
+### Report Generation AI
+- **Intelligent Summarization**: Key insights extraction
+- **Trend Analysis**: Pattern identification and explanation
+- **Actionable Recommendations**: Specific improvement suggestions
+- **Multi-Format Export**: Professional report formatting
+
+## Safety Features
+
+### Demo Mode
+All examples default to demo/sandbox mode for safety:
+- No real trades are executed without explicit confirmation
+- Clear indicators when in demo vs. live mode
+- Sandbox API endpoints used by default
+
+### Confirmation Systems
+- **Trade Confirmations**: All trading operations require explicit confirmation
+- **Risk Warnings**: High-risk operations trigger warnings
+- **Clear Feedback**: Detailed success/error messages
+
+### Error Handling
+- **Graceful Degradation**: Functions work even if AI features unavailable
+- **Helpful Error Messages**: Clear guidance when issues occur
+- **Fallback Options**: Alternative approaches when AI fails
+
+## Performance Notes
+
+### API Rate Limits
+- Examples include appropriate delays between API calls
+- Batch operations optimize API usage
+- Rate limit error handling and retry logic
+
+### AI Provider Costs
+- Most examples use moderate token limits to control costs
+- Optional AI features can be disabled to reduce usage
+- Clear documentation of approximate token consumption
+
+## Troubleshooting
+
+### Common Issues
+
+**AI Features Not Available**
+```
+❌ AI features are not available. Please install ruby_llm gem:
+   gem install ruby_llm
+```
+
+**Authentication Errors**
+```
+❌ Authentication failed. Please check your API credentials.
+```
+Set proper environment variables:
+```bash
+export BUDA_API_KEY="your_key"
+export BUDA_API_SECRET="your_secret"
+```
+
+**LLM API Errors**
+- Verify your LLM provider API key is set
+- Check your API quota/billing status
+- Try a different LLM provider
+
+### Debug Mode
+Enable debug output:
+```bash
+DEBUG=1 ruby examples/ai/trading_assistant_example.rb
+```
+
+## Contributing
+
+When adding new AI examples:
+
+1. **Follow Safety Patterns**: Always default to demo mode
+2. **Include Error Handling**: Graceful degradation when AI unavailable
+3. **Add Documentation**: Clear comments and usage instructions
+4. **Test Thoroughly**: Verify both AI and non-AI code paths
+5. **Optimize Costs**: Be mindful of LLM API usage
+
+## License
+
+These examples are part of the BudaApi Ruby SDK and are subject to the same license terms.