rcrewai 0.1.0

data/docs/tutorials/getting-started.md

@@ -0,0 +1,341 @@
+---
+layout: tutorial
+title: Getting Started with RCrewAI
+description: Learn how to install and use RCrewAI to build your first AI crew
+---
+
+# Getting Started with RCrewAI
+
+This tutorial will walk you through installing RCrewAI and creating your first AI crew.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+- Ruby 3.0 or higher installed
+- Bundler gem installed (`gem install bundler`) 
+- An API key from one of the supported providers:
+  - **OpenAI** (recommended for beginners): Get from [platform.openai.com](https://platform.openai.com)
+  - **Anthropic (Claude)**: Get from [console.anthropic.com](https://console.anthropic.com)
+  - **Google (Gemini)**: Get from [ai.google.dev](https://ai.google.dev)
+  - **Azure OpenAI**: Set up through Azure portal
+
+## Installation
+
+### Method 1: Add to your Gemfile
+
+Add RCrewAI to your application's Gemfile:
+
+```ruby
+gem 'rcrewai'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Method 2: Direct Installation
+
+Install the gem directly:
+
+```bash
+gem install rcrewai
+```
+
+## Configuration
+
+RCrewAI supports multiple LLM providers. Choose the one that works best for you:
+
+### OpenAI (Recommended for beginners)
+
+Set your API key as an environment variable:
+```bash
+export OPENAI_API_KEY="your-openai-key-here"
+```
+
+Configure RCrewAI:
+```ruby
+RCrewAI.configure do |config|
+  config.llm_provider = :openai
+  config.openai_model = 'gpt-4'  # or 'gpt-3.5-turbo' for lower cost
+end
+```
+
+### Anthropic (Claude)
+
+```bash
+export ANTHROPIC_API_KEY="your-anthropic-key-here"
+```
+
+```ruby
+RCrewAI.configure do |config|
+  config.llm_provider = :anthropic
+  config.anthropic_model = 'claude-3-sonnet-20240229'
+end
+```
+
+### Google (Gemini)
+
+```bash
+export GOOGLE_API_KEY="your-google-key-here"
+```
+
+```ruby
+RCrewAI.configure do |config|
+  config.llm_provider = :google
+  config.google_model = 'gemini-pro'
+end
+```
+
+### Azure OpenAI
+
+```bash
+export AZURE_OPENAI_API_KEY="your-azure-key"
+export AZURE_API_VERSION="2023-05-15"
+export AZURE_DEPLOYMENT_NAME="your-deployment"
+```
+
+```ruby
+RCrewAI.configure do |config|
+  config.llm_provider = :azure
+  config.base_url = "https://your-resource.openai.azure.com/"
+  config.azure_model = 'gpt-4'
+end
+```
+
+For more configuration options, see the [Configuration Documentation]({{ site.baseurl }}/api/configuration).
+
+## Creating Your First Crew
+
+Let's create an intelligent research crew that can actually search the web, analyze information, and write reports.
+
+### Step 1: Create the Crew and Configure
+
+```ruby
+require 'rcrewai'
+
+# Configure RCrewAI with your chosen provider
+RCrewAI.configure do |config|
+  config.llm_provider = :openai  # or :anthropic, :google, :azure
+  # API keys are loaded from environment variables automatically
+end
+
+# Create a new crew
+crew = RCrewAI::Crew.new("ai_research_crew")
+```
+
+### Step 2: Create Intelligent Agents with Tools
+
+Create specialized agents with actual capabilities:
+
+```ruby
+# Research Agent with web search capabilities
+researcher = RCrewAI::Agent.new(
+  name: "alex_researcher",
+  role: "Senior Research Analyst", 
+  goal: "Uncover cutting-edge developments in AI and data science",
+  backstory: "You are a seasoned researcher with a knack for uncovering the latest trends and technologies in AI and data science. You excel at finding reliable sources and extracting key insights.",
+  tools: [RCrewAI::Tools::WebSearch.new],  # Can search the web!
+  verbose: true,  # Shows reasoning process
+  max_iterations: 5  # Limit reasoning loops
+)
+
+# Writer Agent with file writing capabilities  
+writer = RCrewAI::Agent.new(
+  name: "emma_writer",
+  role: "Tech Content Strategist",
+  goal: "Craft compelling content on tech advancements", 
+  backstory: "You are a renowned Content Strategist, known for your insightful and engaging articles on technology and innovation. You transform complex research into compelling narratives.",
+  tools: [
+    RCrewAI::Tools::FileWriter.new,  # Can write files!
+    RCrewAI::Tools::FileReader.new   # Can read reference materials
+  ],
+  verbose: true,
+  allow_delegation: false
+)
+
+# Add agents to the crew
+crew.add_agent(researcher)
+crew.add_agent(writer)
+```
+
+### Step 3: Create Advanced Tasks with Dependencies
+
+Define tasks with specific outputs and dependencies:
+
+```ruby
+# Research Task - Agent will actually search the web!
+research_task = RCrewAI::Task.new(
+  name: "research_ai_trends_2024",
+  description: "Research the latest AI developments and breakthroughs in 2024. Focus on identifying key trends, major companies involved, and potential impacts on different industries.",
+  agent: researcher,
+  expected_output: "A comprehensive research report covering: 1) Top 5 AI trends in 2024, 2) Key companies and their innovations, 3) Industry impact analysis, 4) Future predictions",
+  max_retries: 2  # Retry if web search fails
+)
+
+# Writing Task - Agent will use research results and save to file!
+writing_task = RCrewAI::Task.new(
+  name: "write_ai_trends_article", 
+  description: "Write a compelling, informative article about AI trends based on the research. Make it engaging for a tech-savvy audience. Save the final article to a file named 'ai_trends_2024.md'.",
+  agent: writer,
+  expected_output: "A well-structured 1000-1500 word article covering the research findings, saved to ai_trends_2024.md file",
+  context: [research_task],  # Uses research results as input
+  callback: ->(task, result) { puts "Article completed: #{result.length} characters written!" }
+)
+
+# Add tasks to the crew
+crew.add_task(research_task)
+crew.add_task(writing_task)
+```
+
+### Step 4: Execute and Monitor
+
+Run the crew and monitor the intelligent agents at work:
+
+```ruby
+puts "🚀 Starting AI Research Crew..."
+puts "The agents will now research and write about AI trends!"
+
+# Execute the crew - this will:
+# 1. Research agent searches web for AI trends
+# 2. Research agent analyzes and summarizes findings  
+# 3. Writer agent receives research context
+# 4. Writer agent creates article and saves to file
+result = crew.execute
+
+# Check results and status
+puts "\n" + "="*50
+puts "📊 EXECUTION SUMMARY"
+puts "="*50
+
+puts "Research Task Status: #{research_task.status}"
+puts "Research Execution Time: #{research_task.execution_time&.round(2)}s"
+puts "Research Result Preview:"
+puts research_task.result[0..200] + "..." if research_task.result
+
+puts "\nWriting Task Status: #{writing_task.status}" 
+puts "Writing Execution Time: #{writing_task.execution_time&.round(2)}s"
+puts "Article Preview:"
+puts writing_task.result[0..200] + "..." if writing_task.result
+
+# Check if file was actually created
+if File.exist?('ai_trends_2024.md')
+  puts "\n✅ Article successfully saved to ai_trends_2024.md"
+  puts "File size: #{File.size('ai_trends_2024.md')} bytes"
+else
+  puts "\n❌ Article file not found"
+end
+
+# Check agent memory stats
+puts "\n🧠 Agent Memory Stats:"
+puts "Researcher memory: #{researcher.memory.stats}"
+puts "Writer memory: #{writer.memory.stats}"
+```
+
+### What Just Happened?
+
+When you run this code with a valid API key, here's what actually happens:
+
+1. **Researcher Agent**:
+   - Uses reasoning loops to plan the research approach
+   - Executes web searches using DuckDuckGo  
+   - Analyzes search results to identify key trends
+   - Synthesizes findings into a comprehensive report
+   - Stores successful strategies in memory
+
+2. **Writer Agent**:
+   - Receives research findings as context
+   - Plans article structure and key points
+   - Creates engaging, well-structured content
+   - Saves the final article to a markdown file
+   - Learns from successful writing patterns
+
+3. **System Features**:
+   - Automatic retry if web search fails
+   - Security controls on file operations
+   - Memory persistence between executions  
+   - Comprehensive logging and monitoring
+
+## Using the CLI
+
+RCrewAI also provides a command-line interface for managing crews:
+
+### Create a New Crew
+
+```bash
+$ rcrewai new research_team
+Creating new crew: research_team
+Crew 'research_team' created successfully!
+```
+
+### List Available Crews
+
+```bash
+$ rcrewai list
+Available crews:
+  - research_team
+  - marketing_crew
+  - development_crew
+```
+
+### Run a Crew
+
+```bash
+$ rcrewai run --crew research_team
+Running crew: research_team
+Executing tasks...
+```
+
+## Working with Tools
+
+Agents can be equipped with tools to enhance their capabilities:
+
+```ruby
+# Create a web search tool
+search_tool = RCrewAI::Tools::WebSearch.new
+
+# Create an agent with tools
+analyst = RCrewAI::Agent.new(
+  name: "data_analyst",
+  role: "Data Analyst",
+  goal: "Analyze data and provide insights",
+  tools: [search_tool]
+)
+```
+
+## Best Practices
+
+1. **Define Clear Roles**: Give each agent a specific, well-defined role
+2. **Set Specific Goals**: Make agent goals measurable and achievable
+3. **Create Detailed Tasks**: Provide clear descriptions and expected outputs
+4. **Use Task Dependencies**: Link related tasks using the context parameter
+5. **Leverage Tools**: Equip agents with appropriate tools for their tasks
+
+## Next Steps
+
+Now that you've created your first crew, explore these topics:
+
+- [Advanced Agent Configuration]({{ site.baseurl }}/tutorials/advanced-agents)
+- [Custom Tools Development]({{ site.baseurl }}/tutorials/custom-tools)
+- [Working with Multiple Crews]({{ site.baseurl }}/tutorials/multiple-crews)
+- [Production Deployment]({{ site.baseurl }}/tutorials/deployment)
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: "No API key configured"
+**Solution**: Ensure your API key is set in the environment variables or configuration file.
+
+**Issue**: "Agent not found"
+**Solution**: Make sure the agent is added to the crew before creating tasks that reference it.
+
+**Issue**: "Task execution failed"
+**Solution**: Check that all task dependencies are properly defined and agents have necessary tools.
+
+## Get Help
+
+- [GitHub Issues](https://github.com/gkosmo/rcrewAI/issues)
+- [API Documentation]({{ site.baseurl }}/api/)
+- [Examples]({{ site.baseurl }}/examples/)

data/examples/async_execution_example.rb

@@ -0,0 +1,294 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/rcrewai'
+require 'benchmark'
+
+puts "⚡ Async Execution Example"
+puts "=" * 50
+
+# Configure RCrewAI
+RCrewAI.configure do |config|
+  config.llm_provider = :openai  # Change as needed
+  config.temperature = 0.1
+end
+
+puts "🔧 Setting up crew for async vs sync performance comparison..."
+
+# Create a crew with multiple tasks that can benefit from parallelization
+crew = RCrewAI::Crew.new("data_processing_crew")
+
+# Create specialized agents
+data_collector = RCrewAI::Agent.new(
+  name: "data_collector",
+  role: "Data Collection Specialist",
+  goal: "Gather data from various sources efficiently",
+  backstory: "You specialize in collecting and organizing data from multiple sources.",
+  tools: [RCrewAI::Tools::WebSearch.new],
+  verbose: true,
+  max_iterations: 3
+)
+
+data_analyst = RCrewAI::Agent.new(
+  name: "data_analyst",
+  role: "Data Analyst", 
+  goal: "Analyze collected data and extract insights",
+  backstory: "You excel at finding patterns and insights in datasets.",
+  tools: [RCrewAI::Tools::FileWriter.new],
+  verbose: true,
+  max_iterations: 4
+)
+
+report_writer = RCrewAI::Agent.new(
+  name: "report_writer",
+  role: "Technical Writer",
+  goal: "Create comprehensive reports from analysis",
+  backstory: "You transform complex analysis into clear, actionable reports.",
+  tools: [RCrewAI::Tools::FileWriter.new, RCrewAI::Tools::FileReader.new],
+  verbose: true,
+  max_iterations: 3
+)
+
+code_reviewer = RCrewAI::Agent.new(
+  name: "code_reviewer",
+  role: "Code Quality Specialist", 
+  goal: "Review and analyze code quality",
+  backstory: "You ensure code meets quality standards and best practices.",
+  tools: [RCrewAI::Tools::CodeExecutor.new, RCrewAI::Tools::FileReader.new],
+  verbose: true,
+  max_iterations: 4
+)
+
+# Add agents to crew
+crew.add_agent(data_collector)
+crew.add_agent(data_analyst) 
+crew.add_agent(report_writer)
+crew.add_agent(code_reviewer)
+
+puts "👥 Created crew with #{crew.agents.length} specialized agents"
+
+# Create tasks that can run independently (parallel execution potential)
+data_collection_task1 = RCrewAI::Task.new(
+  name: "collect_market_data",
+  description: "Research current market trends in AI and machine learning for 2024",
+  agent: data_collector,
+  expected_output: "Market research summary with key trends and statistics",
+  async: true
+)
+
+data_collection_task2 = RCrewAI::Task.new(
+  name: "collect_tech_data", 
+  description: "Research emerging technologies in software development",
+  agent: data_collector,
+  expected_output: "Technology research summary with key developments",
+  async: true
+)
+
+# Analysis tasks that depend on data collection
+analysis_task1 = RCrewAI::Task.new(
+  name: "analyze_market_trends",
+  description: "Analyze the collected market data to identify opportunities and threats",
+  agent: data_analyst,
+  expected_output: "Market analysis report with actionable insights saved to market_analysis.md",
+  context: [data_collection_task1],
+  async: true
+)
+
+analysis_task2 = RCrewAI::Task.new(
+  name: "analyze_tech_trends",
+  description: "Analyze emerging technology data to predict future developments",
+  agent: data_analyst, 
+  expected_output: "Technology trend analysis saved to tech_analysis.md",
+  context: [data_collection_task2],
+  async: true
+)
+
+# Code review task (independent)
+code_review_task = RCrewAI::Task.new(
+  name: "review_sample_code",
+  description: "Review this Python code for best practices: 'def calculate(x, y): return x + y if x > 0 else 0'",
+  agent: code_reviewer,
+  expected_output: "Code review with suggestions for improvement",
+  async: true
+)
+
+# Final report task (depends on all analysis)
+final_report_task = RCrewAI::Task.new(
+  name: "create_comprehensive_report",
+  description: "Combine all analysis into a comprehensive business report with recommendations",
+  agent: report_writer,
+  expected_output: "Executive business report combining all insights saved to executive_report.md",
+  context: [analysis_task1, analysis_task2, code_review_task],
+  async: true
+)
+
+# Add all tasks to crew
+crew.add_task(data_collection_task1)
+crew.add_task(data_collection_task2) 
+crew.add_task(analysis_task1)
+crew.add_task(analysis_task2)
+crew.add_task(code_review_task)
+crew.add_task(final_report_task)
+
+puts "📋 Created #{crew.tasks.length} tasks with dependency chains"
+
+# Demonstrate both sync and async execution
+puts "\n🔄 Comparing Synchronous vs Asynchronous Execution"
+puts "-" * 60
+
+# First: Synchronous execution
+puts "\n1️⃣ SYNCHRONOUS EXECUTION"
+puts "Tasks will execute sequentially, one at a time..."
+
+sync_time = Benchmark.measure do
+  sync_results = crew.execute
+  
+  puts "\n📊 Synchronous Results:"
+  puts "  Process: #{sync_results[:process]}"
+  puts "  Success Rate: #{sync_results[:success_rate]}%"
+  puts "  Completed: #{sync_results[:completed_tasks]}/#{sync_results[:total_tasks]}"
+  puts "  Failed: #{sync_results[:failed_tasks]}"
+end
+
+puts "⏱️  Synchronous execution time: #{sync_time.real.round(2)} seconds"
+
+# Clear any previous results
+crew.tasks.each do |task|
+  task.instance_variable_set(:@result, nil)
+  task.instance_variable_set(:@status, :pending)
+end
+
+puts "\n2️⃣ ASYNCHRONOUS EXECUTION" 
+puts "Tasks will execute in parallel where possible..."
+
+async_time = Benchmark.measure do
+  async_results = crew.execute(
+    async: true,
+    max_concurrency: 4,  # Allow up to 4 concurrent tasks
+    timeout: 300,        # 5 minute timeout
+    verbose: true        # Show detailed async logs
+  )
+  
+  puts "\n📊 Asynchronous Results:"
+  puts "  Process: #{async_results[:process]}"
+  puts "  Execution Mode: #{async_results[:execution_mode]}"
+  puts "  Max Concurrency: #{async_results[:max_concurrency]}"
+  puts "  Success Rate: #{async_results[:success_rate]}%"
+  puts "  Completed: #{async_results[:completed_tasks]}/#{async_results[:total_tasks]}"
+  puts "  Failed: #{async_results[:failed_tasks]}"
+  puts "  Timeouts: #{async_results[:timed_out_tasks]}"
+  
+  if async_results[:thread_pool_stats]
+    puts "  Thread Pool Stats:"
+    puts "    Max Threads: #{async_results[:thread_pool_stats][:max_threads]}"
+    puts "    Peak Usage: #{async_results[:thread_pool_stats][:largest_length]} threads"
+  end
+end
+
+puts "⚡ Asynchronous execution time: #{async_time.real.round(2)} seconds"
+
+# Performance comparison
+puts "\n🏆 PERFORMANCE COMPARISON"
+puts "=" * 40
+speedup = sync_time.real / async_time.real
+puts "Speedup: #{speedup.round(2)}x faster with async execution"
+puts "Time saved: #{(sync_time.real - async_time.real).round(2)} seconds"
+
+if speedup > 1.5
+  puts "🚀 Significant performance improvement with async execution!"
+elsif speedup > 1.2
+  puts "✅ Good performance improvement with async execution"
+else
+  puts "ℹ️  Minimal performance difference (tasks may be I/O bound or have dependencies)"
+end
+
+# Show task execution patterns
+puts "\n📈 TASK EXECUTION ANALYSIS"
+puts "-" * 30
+
+# Demonstrate hierarchical async execution
+puts "\n3️⃣ HIERARCHICAL ASYNC EXECUTION"
+puts "Manager will coordinate parallel task delegation..."
+
+# Create a new crew with manager for hierarchical async
+hierarchical_crew = RCrewAI::Crew.new("async_hierarchical_crew", process: :hierarchical)
+
+# Add a manager
+project_manager = RCrewAI::Agent.new(
+  name: "project_manager",
+  role: "Project Coordinator",
+  goal: "Coordinate team efforts efficiently",
+  backstory: "You excel at managing parallel workstreams and ensuring optimal resource utilization.",
+  manager: true,
+  allow_delegation: true,
+  verbose: true
+)
+
+hierarchical_crew.add_agent(project_manager)
+hierarchical_crew.add_agent(data_collector)
+hierarchical_crew.add_agent(data_analyst)
+hierarchical_crew.add_agent(code_reviewer)
+
+# Create simpler tasks for hierarchical demo
+quick_tasks = [
+  RCrewAI::Task.new(
+    name: "quick_research",
+    description: "Quick research on Ruby vs Python performance",
+    expected_output: "Brief comparison summary"
+  ),
+  RCrewAI::Task.new(
+    name: "quick_analysis", 
+    description: "Analyze a simple dataset: [1,2,3,4,5]",
+    expected_output: "Basic statistical analysis"
+  ),
+  RCrewAI::Task.new(
+    name: "quick_code_check",
+    description: "Review this Ruby code: 'arr.map(&:to_i).sum'",
+    expected_output: "Code quality assessment"
+  )
+]
+
+quick_tasks.each { |task| hierarchical_crew.add_task(task) }
+
+hierarchical_time = Benchmark.measure do
+  hierarchical_results = hierarchical_crew.execute(
+    async: true,
+    max_concurrency: 3,
+    verbose: true
+  )
+  
+  puts "\n📊 Hierarchical Async Results:"
+  puts "  Manager: #{hierarchical_results[:manager]}"
+  puts "  Process: #{hierarchical_results[:process]}" 
+  puts "  Success Rate: #{hierarchical_results[:success_rate]}%"
+  puts "  Tasks Completed: #{hierarchical_results[:completed_tasks]}/#{hierarchical_results[:total_tasks]}"
+end
+
+puts "🏗️  Hierarchical async execution time: #{hierarchical_time.real.round(2)} seconds"
+
+# Check generated files
+puts "\n📄 GENERATED FILES"
+output_files = [
+  'market_analysis.md',
+  'tech_analysis.md', 
+  'executive_report.md'
+]
+
+output_files.each do |file|
+  if File.exist?(file)
+    puts "  ✅ #{file} (#{File.size(file)} bytes)"
+  else
+    puts "  ❌ #{file} (not generated)"
+  end
+end
+
+puts "\n🎯 ASYNC EXECUTION BENEFITS DEMONSTRATED:"
+puts "  • Parallel task processing where dependencies allow"
+puts "  • Efficient resource utilization with thread pooling"
+puts "  • Manager coordination in hierarchical async mode"
+puts "  • Automatic dependency resolution across phases"
+puts "  • Timeout and error handling for robust execution"
+puts "  • Detailed performance metrics and monitoring"
+
+puts "\n" + "=" * 50
+puts "⚡ Async Execution Demo Complete!"
+puts "=" * 50