pedicab 0.3.1 → 0.3.3

data/EXAMPLES.md

@@ -0,0 +1,884 @@
+# Usage Examples and Tutorials
+
+## Table of Contents
+
+1. [Basic Conversations](#basic-conversations)
+2. [Context Management](#context-management)
+3. [Custom Handlers](#custom-handlers)
+4. [Conditional Logic](#conditional-logic)
+5. [State Management](#state-management)
+6. [Performance Monitoring](#performance-monitoring)
+7. [Error Handling](#error-handling)
+8. [Advanced Patterns](#advanced-patterns)
+9. [Real-world Examples](#real-world-examples)
+
+---
+
+## Basic Conversations
+
+### Simple Q&A
+
+```ruby
+require 'pedicab'
+
+# Create a conversation instance
+ai = Pedicab['chatbot']
+
+# Ask a question
+response = ai["What is the capital of France?"]
+puts response.out
+# => "The capital of France is Paris."
+
+# Get timing information
+puts "Response time: #{response.took} seconds"
+```
+
+### Multi-turn Conversations
+
+```ruby
+ai = Pedicab['conversation']
+
+# First exchange
+response1 = ai["Tell me about Ruby programming"]
+puts response1.out
+
+# Continue with context - AI remembers the previous exchange
+response2 = ai << "What are its main features?"
+puts response2.out
+
+# Continue again
+response3 = ai << "How does it compare to Python?"
+puts response3.out
+
+# View conversation history
+puts "Prompts asked: #{ai.last.inspect}"
+puts "Responses received: #{ai.response.inspect}"
+```
+
+---
+
+## Context Management
+
+### Fresh Conversations vs. Continued Context
+
+```ruby
+ai = Pedicab['context_demo']
+
+# Using [] - starts fresh each time
+response1 = ai["What is 2+2?"]
+puts response1.out  # => "2+2 equals 4"
+
+response2 = ai["What about 3+3?"]  # Fresh conversation, no memory of previous
+puts response2.out  # => "3+3 equals 6"
+
+# Using << - continues with context
+ai.reset!
+response3 = ai["What is 2+2?"]
+puts response3.out  # => "2+2 equals 4"
+
+response4 = ai << "What about 3+3?"  # Knows we're doing math
+puts response4.out  # => "Following the math pattern, 3+3 equals 6."
+```
+
+### Context Resetting
+
+```ruby
+ai = Pedicab['reset_demo']
+
+# Build up some context
+ai["I'm learning programming"]
+ai << "Teach me about variables"
+ai << "What about functions?"
+
+# View current context
+puts "Current conversation: #{ai.last.length} exchanges"
+
+# Reset and start fresh
+ai.reset!
+puts "After reset: #{ai.last.length} exchanges"
+
+# Start new topic
+response = ai["What is machine learning?"]
+puts response.out  # Fresh context, no memory of programming discussion
+```
+
+---
+
+## Custom Handlers
+
+### Response Formatting
+
+```ruby
+ai = Pedicab['formatted_bot']
+
+# Set up custom response handler
+ai.handle do |response|
+  puts "=" * 50
+  puts "Question: #{response.prompt}"
+  puts "Answer: #{response.out}"
+  puts "Thinking: #{response.thoughts.last}" if response.thoughts.last
+  puts "Time: #{response.took.round(3)}s"
+  puts "=" * 50
+  response
+end
+
+# Now all responses will be formatted
+ai["What is photosynthesis?"]
+ai << "Why is it important?"]
+```
+
+### Response Transformation
+
+```ruby
+ai = Pedicab['transformer']
+
+# Handler that modifies the response
+ai.handle do |response|
+  # Convert to uppercase and add emphasis
+  modified = response.out.upcase + "!!!"
+  response.out = modified
+  response
+end
+
+response = ai["Hello there"]
+puts response.out
+# => "HELLO THERE!!!"
+```
+
+### Logging Handler
+
+```ruby
+ai = Pedicab['logger']
+
+# Set up logging handler
+ai.handle do |response|
+  # Log to file
+  File.open('conversation.log', 'a') do |f|
+    f.puts "[#{Time.now}] Prompt: #{response.prompt}"
+    f.puts "[#{Time.now}] Response: #{response.out}"
+    f.puts "[#{Time.now}] Time: #{response.took}s"
+    f.puts "---"
+  end
+  
+  # Also print to console
+  puts response.out
+  response
+end
+
+ai["How do you work?"]
+ai << "What can you do?"]
+```
+
+---
+
+## Conditional Logic
+
+### Basic Conditions
+
+```ruby
+ai = Pedicab['conditional']
+
+# Ask a yes/no question
+is_technical = ai.ride.if?("Ruby is a programming language")
+puts is_technical  # => true
+
+# Use condition in logic
+if ai.ride.if?("the user is asking about technology")
+  response = ai["I'd be happy to help with technology questions!"]
+else
+  response = ai["I can help with many topics. What interests you?"]
+end
+```
+
+### Conditional Blocks
+
+```ruby
+ai = Pedicab['smart_bot']
+
+# Use conditional blocks for different responses
+ai.ride.if?("user is asking for help") do
+  ai["I'm here to help! What do you need assistance with?"]
+end
+
+ai.ride.if?("user is greeting") do
+  ai["Hello! How can I assist you today?"]
+end
+
+# Get result without block
+wants_code = ai.ride.if?("user wants programming help")
+if wants_code
+  ai["Let's write some code together!"]
+end
+```
+
+### Multi-Condition Logic
+
+```ruby
+ai = Pedicab['classifier']
+
+# Classify user intent
+prompt = "I want to build a website"
+
+is_web = ai.ride.if?("user wants to build a website")
+is_app = ai.ride.if?("user wants to build a mobile app")
+is_code = ai.ride.if?("user wants programming help")
+
+case
+when is_web
+  ai["Let's discuss web development! HTML, CSS, and JavaScript are great starting points."]
+when is_app  
+  ai["Mobile app development is exciting! Are you thinking iOS or Android?"]
+when is_code
+  ai["Programming is a valuable skill! What language interests you?"]
+else
+  ai["I'd be happy to help! Can you tell me more about what you'd like to create?"]
+end
+```
+
+---
+
+## State Management
+
+### Custom State Variables
+
+```ruby
+ride = Pedicab.ride['stateful']
+
+# Set custom state
+ride[:user_name] = "Alice"
+ride[:user_level] = "beginner"
+ride[:last_topic] = "Ruby basics"
+
+# Use state in prompts
+prompt = "Hi, I'm #{ride[:user_name]} and I'm a #{ride[:user_level]}"
+response = ride.go(prompt)
+
+# Update state based on conversation
+ride[:last_topic] = "introduction"
+```
+
+### Persistent State Across Sessions
+
+```ruby
+class PersistentBot
+  def initialize(id)
+    @ride = Pedicab.ride[id]
+    load_state
+  end
+  
+  def chat(message)
+    # Use stored state
+    response = @ride.go(message)
+    
+    # Save important information
+    if @ride.if?("user introduced themselves")
+      @ride[:user_name] = extract_name(response.out)
+    end
+    
+    save_state
+    response
+  end
+  
+  private
+  
+  def load_state
+    # Load from file or database
+    # Implementation depends on your needs
+  end
+  
+  def save_state
+    # Save to file or database
+  end
+  
+  def extract_name(text)
+    # Extract name from response
+    # Simple regex or more sophisticated NLP
+    text.match(/My name is (\w+)/)&.[](1) || "Unknown"
+  end
+end
+
+# Usage
+bot = PersistentBot['my_bot']
+bot.chat("Hi, my name is John and I want to learn programming")
+```
+
+---
+
+## Performance Monitoring
+
+### Request Timing
+
+```ruby
+ai = Pedicab['monitored']
+
+# Single request timing
+response = ai["Explain quantum computing"]
+puts "Last request: #{response.took} seconds"
+
+# Cumulative timing
+ai["What is machine learning?"]
+ai["How does AI work?"]
+
+puts "Total conversation time: #{ai.life} seconds"
+puts "Average per request: #{ai.life / ai.response.length} seconds"
+
+# Detailed timing breakdown
+ai.time.each_with_index do |time, index|
+  puts "Request #{index + 1}: #{time} seconds"
+end
+```
+
+### Performance Comparison
+
+```ruby
+# Compare different models or prompts
+def benchmark_prompt(prompt, model = nil)
+  old_model = ENV['MODEL']
+  ENV['MODEL'] = model if model
+  
+  ai = Pedicab['benchmark']
+  start_time = Time.now
+  response = ai[prompt]
+  end_time = Time.now
+  
+  ENV['MODEL'] = old_model
+  
+  {
+    model: model || 'default',
+    prompt_length: prompt.length,
+    response_length: response.out.length,
+    time: response.took,
+    total_time: end_time - start_time
+  }
+end
+
+# Run benchmarks
+results = [
+  benchmark_prompt("What is Ruby?", 'qwen'),
+  benchmark_prompt("What is Ruby?", 'llama2'),
+  benchmark_prompt("What is Ruby?", 'mistral')
+]
+
+results.each do |result|
+  puts "#{result[:model]}: #{result[:time]}s"
+end
+```
+
+---
+
+## Error Handling
+
+### Robust Error Handling
+
+```ruby
+class SafeAIBot
+  def initialize(id)
+    @ai = Pedicab[id]
+  end
+  
+  def safe_chat(prompt)
+    begin
+      response = @ai[prompt]
+      
+      # Check for empty or problematic responses
+      if response.out.strip.empty?
+        return "I apologize, but I couldn't generate a response."
+      end
+      
+      # Check for error indicators in response
+      if response.out.include?("Error:") || response.out.include?("I don't know")
+        return "I'm having trouble processing that request. Could you rephrase it?"
+      end
+      
+      response.out
+      
+    rescue Pedicab::Error => e
+      puts "Pedicab error: #{e.message}"
+      "I'm experiencing technical difficulties. Please try again later."
+      
+    rescue => e
+      puts "Unexpected error: #{e.message}"
+      "Something went wrong. Please try again."
+    end
+  end
+end
+
+# Usage
+bot = SafeAIBot['safe_bot']
+puts bot.safe_chat("Tell me about something")
+```
+
+### Retry Logic
+
+```ruby
+class RetryBot
+  def initialize(id, max_retries: 3)
+    @ai = Pedicab[id]
+    @max_retries = max_retries
+  end
+  
+  def chat_with_retry(prompt)
+    attempts = 0
+    
+    while attempts < @max_retries
+      begin
+        response = @ai[prompt]
+        
+        # Check if response is satisfactory
+        if satisfactory_response?(response.out)
+          return response.out
+        end
+        
+        attempts += 1
+        puts "Retry attempt #{attempts}" if attempts < @max_retries
+        
+      rescue => e
+        attempts += 1
+        puts "Error: #{e.message}. Retry #{attempts}/#{@max_retries}"
+        return "Failed after #{@max_retries} attempts" if attempts >= @max_retries
+      end
+    end
+    
+    "Unable to generate satisfactory response after #{@max_retries} attempts"
+  end
+  
+  private
+  
+  def satisfactory_response?(response)
+    response.length > 10 && 
+    !response.include?("Error:") && 
+    !response.include?("I don't know")
+  end
+end
+```
+
+---
+
+## Advanced Patterns
+
+### Conversation Templates
+
+```ruby
+class ConversationTemplate
+  def initialize(id, template)
+    @ai = Pedicab[id]
+    @template = template
+  end
+  
+  def ask(variables = {})
+    prompt = apply_template(@template, variables)
+    response = @ai[prompt]
+    post_process(response, variables)
+  end
+  
+  private
+  
+  def apply_template(template, variables)
+    result = template.dup
+    variables.each do |key, value|
+      result.gsub!("{{#{key}}}", value.to_s)
+    end
+    result
+  end
+  
+  def post_process(response, variables)
+    # Apply any post-processing based on variables
+    response.out
+  end
+end
+
+# Usage
+code_review = ConversationTemplate['review_bot', <<~TEMPLATE]
+  Review the following code:
+  
+  Language: {{language}}
+  Code: {{code}}
+  
+  Provide feedback on:
+  1. Code quality
+  2. Best practices
+  3. Potential improvements
+TEMPLATE
+
+result = code_review.ask(
+  language: 'Ruby',
+  code: 'def hello; puts "world"; end'
+)
+puts result
+```
+
+### Multi-Expert System
+
+```ruby
+class ExpertSystem
+  def initialize
+    @experts = {
+      programming: Pedicab['programming_expert'],
+      writing: Pedicab['writing_expert'],
+      analysis: Pedicab['analysis_expert']
+    }
+  end
+  
+  def consult(question, domain = nil)
+    if domain && @experts[domain]
+      expert_response = @experts[domain][question]
+      
+      # Have analysis expert review the response
+      review_prompt = "Review this expert response for accuracy and completeness:\n\n#{expert_response.out}"
+      review = @experts[:analysis][review_prompt]
+      
+      "Expert Response:\n#{expert_response.out}\n\nReview:\n#{review.out}"
+    else
+      # Use analysis expert to determine domain
+      domain_prompt = "What domain of expertise does this question belong to: #{question}"
+      suggested_domain = determine_domain(@experts[:analysis][domain_prompt].out)
+      
+      consult(question, suggested_domain)
+    end
+  end
+  
+  private
+  
+  def determine_domain(response_text)
+    case response_text.downcase
+    when /programming|code|software|development/
+      :programming
+    when /writing|grammar|composition|literature/
+      :writing
+    else
+      :analysis
+    end
+  end
+end
+
+# Usage
+system = ExpertSystem.new
+puts system.consult("How do I implement a binary search tree in Ruby?")
+```
+
+---
+
+## Real-world Examples
+
+### Code Review Assistant
+
+```ruby
+class CodeReviewer
+  def initialize
+    @ai = Pedicab['code_reviewer']
+    setup_handler
+  end
+  
+  def review_code(code, language = 'Ruby')
+    prompt = <<~PROMPT
+      Please review this #{language} code for:
+      1. Code quality and readability
+      2. Best practices adherence
+      3. Security vulnerabilities
+      4. Performance considerations
+      5. Potential bugs
+      
+      Code to review:
+      ```#{language.downcase}
+      #{code}
+      ```
+      
+      Provide specific, actionable feedback.
+    PROMPT
+    
+    response = @ai[prompt]
+    format_review(response.out)
+  end
+  
+  private
+  
+  def setup_handler
+    @ai.handle do |response|
+      # Add structure to the review
+      response.out = add_review_sections(response.out)
+      response
+    end
+  end
+  
+  def add_review_sections(review_text)
+    sections = {
+      'Summary' => extract_section(review_text, ['overall', 'summary', 'general']),
+      'Issues' => extract_section(review_text, ['issue', 'problem', 'bug', 'concern']),
+      'Recommendations' => extract_section(review_text, ['recommend', 'suggest', 'improve']),
+      'Positive Notes' => extract_section(review_text, ['good', 'well', 'correct', 'nice'])
+    }
+    
+    formatted = []
+    sections.each do |title, content|
+      formatted << "\n## #{title}\n#{content}" if content && !content.empty?
+    end
+    
+    formatted.empty? ? review_text : formatted.join("\n")
+  end
+  
+  def extract_section(text, keywords)
+    lines = text.split("\n")
+    relevant = []
+    
+    lines.each do |line|
+      if keywords.any? { |kw| line.downcase.include?(kw) }
+        relevant << line
+      end
+    end
+    
+    relevant.join("\n")
+  end
+  
+  def format_review(review)
+    "# Code Review Report\n\n#{review}\n\n---\n*Generated by AI Code Reviewer*"
+  end
+end
+
+# Usage
+reviewer = CodeReviewer.new
+code = <<~RUBY
+  def calculate_sum(numbers)
+    total = 0
+    numbers.each do |num|
+      total = total + num
+    end
+    return total
+  end
+RUBY
+
+puts reviewer.review_code(code)
+```
+
+### Learning Assistant
+
+```ruby
+class LearningAssistant
+  def initialize(student_name)
+    @student = student_name
+    @ai = Pedicab['learning_assistant']
+    @ride = @ai.ride
+    
+    # Initialize student state
+    @ride[:student_name] = student_name
+    @ride[:learning_history] = []
+    @ride[:current_topic] = nil
+    @ride[:proficiency_level] = 'beginner'
+  end
+  
+  def learn(topic, question = nil)
+    @ride[:current_topic] = topic
+    
+    if question
+      ask_question(topic, question)
+    else
+      start_lesson(topic)
+    end
+  end
+  
+  def ask_question(topic, question)
+    prompt = <<~PROMPT
+      #{@student} is learning about #{topic} and asks: "#{question}"
+      
+      Provide a clear, educational answer that:
+      1. Is appropriate for a #{@ride[:proficiency_level]} level
+      2. Builds on previous learning if relevant
+      3. Is encouraging and motivating
+      4. Suggests follow-up questions or exercises
+      
+      Previous topics: #{@ride[:learning_history].join(', ')}
+    PROMPT
+    
+    response = @ai[prompt]
+    record_interaction(topic, question, response.out)
+    response.out
+  end
+  
+  def start_lesson(topic)
+    prompt = <<~PROMPT
+      #{@student} wants to learn about #{topic}.
+      
+      Create an engaging introduction that:
+      1. Explains what #{topic} is
+      2. Shows why it's important or interesting
+      3. Sets appropriate expectations for a #{@ride[:proficiency_level]}
+      4. Provides 2-3 key concepts to start with
+      5. Suggests a first learning activity
+      
+      Make it conversational and encouraging.
+    PROMPT
+    
+    response = @ai[prompt]
+    record_interaction(topic, "Introduction to #{topic}", response.out)
+    response.out
+  end
+  
+  def assess_progress(topic)
+    prompt = <<~PROMPT
+      Based on this learning history about #{topic}, assess #{@student}'s progress:
+      
+      #{@ride[:learning_history].map { |h| "- #{h}" }.join("\n")}
+      
+      Provide:
+      1. Current proficiency assessment
+      2. Strengths demonstrated
+      3. Areas for improvement
+      4. Next learning recommendations
+    PROMPT
+    
+    response = @ai[prompt]
+    update_proficiency(response.out)
+    response.out
+  end
+  
+  private
+  
+  def record_interaction(topic, question, answer)
+    interaction = "#{Time.now.strftime('%Y-%m-%d')}: #{topic} - #{question}"
+    @ride[:learning_history] << interaction
+    
+    # Keep history manageable
+    if @ride[:learning_history].length > 50
+      @ride[:learning_history] = @ride[:learning_history].last(30)
+    end
+  end
+  
+  def update_proficiency(assessment)
+    # Simple logic to update proficiency based on assessment
+    if assessment.include?('intermediate') || assessment.include?('progressing')
+      @ride[:proficiency_level] = 'intermediate'
+    elsif assessment.include?('advanced') || assessment.include?('excellent')
+      @ride[:proficiency_level] = 'advanced'
+    end
+  end
+end
+
+# Usage
+assistant = LearningAssistant['Sarah']
+
+puts assistant.learn('Ruby variables')
+puts assistant.learn('Ruby variables', 'What is a symbol in Ruby?')
+puts assistant.assess_progress('Ruby variables')
+```
+
+### Content Generator
+
+```ruby
+class ContentGenerator
+  def initialize
+    @ai = Pedicab['content_generator']
+    @ride = @ai.ride
+  end
+  
+  def blog_post(topic, tone = 'informative', length = 'medium')
+    prompt = <<~PROMPT
+      Write a #{length} blog post about #{topic} with a #{tone} tone.
+      
+      Structure:
+      1. Catchy title
+      2. Engaging introduction
+      3. 3-5 main points with clear explanations
+      4. Practical examples or applications
+      5. Conclusion with call-to-action
+      
+      Guidelines:
+      - Use clear, accessible language
+      - Include relevant subheadings
+      - Add formatting for readability
+      - Ensure logical flow
+      - Target word count: #{word_count(length)}
+    PROMPT
+    
+    response = @ai[prompt]
+    format_content(response.out, 'blog')
+  end
+  
+  def tutorial(topic, difficulty = 'beginner')
+    prompt = <<~PROMPT
+      Create a step-by-step tutorial for #{difficulty} level learners about #{topic}.
+      
+      Include:
+      1. Prerequisites
+      2. Learning objectives
+      3. Step-by-step instructions
+      4. Code examples (if applicable)
+      5. Practice exercises
+      6. Common pitfalls and solutions
+      7. Next steps for further learning
+      
+      Make it hands-on and practical.
+    PROMPT
+    
+    response = @ai[prompt]
+    format_content(response.out, 'tutorial')
+  end
+  
+  def social_media_post(topic, platform = 'twitter')
+    prompts = {
+      'twitter' => "Write a tweet about #{topic}. Include relevant hashtags and keep it under 280 characters.",
+      'linkedin' => "Write a LinkedIn post about #{topic}. Make it professional and insightful, include 3-5 hashtags.",
+      'instagram' => "Write an Instagram caption about #{topic}. Include engaging questions and relevant hashtags."
+    }
+    
+    response = @ai[prompts[platform]]
+    format_content(response.out, 'social')
+  end
+  
+  private
+  
+  def word_count(length)
+    counts = {
+      'short' => '300-500',
+      'medium' => '800-1200', 
+      'long' => '1500-2000'
+    }
+    counts[length] || counts['medium']
+  end
+  
+  def format_content(content, type)
+    case type
+    when 'blog'
+      "# Blog Post\n\n#{content}\n\n*Generated by AI Content Generator*"
+    when 'tutorial'
+      "# Tutorial\n\n#{content}\n\n*Generated by AI Content Generator*"
+    when 'social'
+      "#{content}\n\n*Generated by AI Content Generator*"
+    else
+      content
+    end
+  end
+end
+
+# Usage
+generator = ContentGenerator.new
+
+puts generator.blog_post('Machine Learning Basics')
+puts generator.tutorial('Getting Started with Git', 'beginner')
+puts generator.social_media_post('Importance of Code Reviews', 'linkedin')
+```
+
+---
+
+## Best Practices
+
+### Performance Tips
+
+1. **Choose appropriate models** - Smaller models for simple tasks, larger for complex analysis
+2. **Reset context appropriately** - Use `reset!` when changing topics
+3. **Monitor performance** - Track `took` and `life` metrics
+4. **Cache responses** - For common questions, consider caching
+
+### Security Considerations
+
+1. **Validate inputs** - Sanitize user inputs before sending to LLM
+2. **Filter outputs** - Check for sensitive information in responses
+3. **Rate limiting** - Implement limits to prevent abuse
+4. **Error boundaries** - Handle failures gracefully
+
+### Usability Tips
+
+1. **Provide clear prompts** - Be specific about what you want
+2. **Set expectations** - Let users know about capabilities and limitations
+3. **Use appropriate handlers** - Custom handlers can greatly improve user experience
+4. **Handle edge cases** - Prepare for empty or unexpected responses
+
+These examples should help you get the most out of Pedicab in various real-world scenarios!