llm_conductor 0.1.0

data/examples/data_builder_usage.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+require_relative '../lib/llm_conductor'
+
+# Example: Company Data Builder
+#
+# This example demonstrates how to use LlmConductor::DataBuilder to structure
+# data from complex objects for LLM consumption.
+
+class CompanyDataBuilder < LlmConductor::DataBuilder
+  def build
+    {
+      id: source_object.id,
+      name: source_object.name,
+      domain_name: source_object.domain_name,
+      description: format_for_llm(source_object.description, max_length: 500),
+      industry: extract_nested_data(:data, 'categories', 'primary') || 'Unknown',
+      location: build_location,
+      metrics: build_metrics,
+      technology_stack: extract_list(:technologies, limit: 5, separator: ', '),
+      summary: build_company_summary
+    }
+  end
+
+  private
+
+  def build_location
+    city = safe_extract(:city, default: nil)
+    country = safe_extract(:country, default: nil)
+
+    return 'Unknown' if city.nil? && country.nil?
+    return city if country.nil?
+    return country if city.nil?
+
+    "#{city}, #{country}"
+  end
+
+  def build_metrics
+    {
+      employees: format_employee_count,
+      revenue: format_revenue,
+      founded: safe_extract(:founded_year, default: 'Unknown'),
+      funding: extract_nested_data(:financial_data, 'total_funding'),
+      stage: extract_nested_data(:financial_data, 'stage')
+    }
+  end
+
+  def format_employee_count
+    count = safe_extract(:employee_count)
+    return 'Unknown' if count.nil?
+
+    case count
+    when 0..10
+      'Small (1-10)'
+    when 11..50
+      'Medium (11-50)'
+    when 51..200
+      'Large (51-200)'
+    when 201..1000
+      'Enterprise (201-1000)'
+    else
+      'Large Enterprise (1000+)'
+    end
+  end
+
+  def format_revenue
+    revenue = safe_extract(:revenue)
+    return 'Not disclosed' if revenue.nil? || revenue.zero?
+
+    format_number(revenue, as_currency: true, precision: 0)
+  end
+
+  def build_company_summary
+    name = safe_extract(:name, default: 'Unknown Company')
+    industry = extract_nested_data(:data, 'categories', 'primary') || 'Unknown Industry'
+    employees = format_employee_count
+    location = build_location
+
+    "#{name} is a #{industry.downcase} company with #{employees.downcase} employees, " \
+    "based in #{location}"
+  end
+end
+
+# Example: User Profile Builder
+class UserProfileBuilder < LlmConductor::DataBuilder
+  def build
+    {
+      basic_info: build_basic_info,
+      professional: build_professional_info,
+      preferences: build_preferences,
+      activity_summary: build_activity_summary
+    }
+  end
+
+  private
+
+  def build_basic_info
+    {
+      name: format_for_llm(build_full_name),
+      email: safe_extract(:email, default: 'Not provided'),
+      age: calculate_age,
+      location: build_summary(:city, :state, :country, separator: ', ')
+    }
+  end
+
+  def build_full_name
+    first = safe_extract(:first_name, default: '')
+    last = safe_extract(:last_name, default: '')
+    "#{first} #{last}".strip
+  end
+
+  def calculate_age
+    birth_date = safe_extract(:birth_date)
+    return 'Unknown' if birth_date.nil?
+
+    begin
+      ((Time.zone.now - birth_date) / 365.25 / 24 / 60 / 60).to_i
+    rescue StandardError
+      'Unknown'
+    end
+  end
+
+  def build_professional_info
+    {
+      title: safe_extract(:job_title, default: 'Not specified'),
+      company: safe_extract(:company_name, default: 'Not specified'),
+      experience_years: safe_extract(:years_experience, default: 'Unknown'),
+      skills: extract_list(:skills, limit: 10, separator: ', '),
+      industry: extract_nested_data(:profile, 'professional', 'industry')
+    }
+  end
+
+  def build_preferences
+    preferences = safe_extract(:preferences, default: {})
+    return 'No preferences set' unless preferences.respond_to?(:[])
+
+    {
+      communication: preferences['communication'] || 'Email',
+      notifications: preferences['notifications'] ? 'Enabled' : 'Disabled',
+      privacy_level: preferences['privacy'] || 'Standard'
+    }
+  end
+
+  def build_activity_summary
+    summary_parts = []
+
+    add_membership_info(summary_parts)
+    add_activity_info(summary_parts)
+
+    summary_parts.empty? ? 'No activity data' : summary_parts.join(' • ')
+  end
+
+  def add_membership_info(summary_parts)
+    account_created = safe_extract(:created_at)
+    return unless account_created
+
+    formatted_date = format_creation_date(account_created)
+    summary_parts << "Member since #{formatted_date}"
+  end
+
+  def add_activity_info(summary_parts)
+    last_login = safe_extract(:last_login_at)
+    return unless last_login
+
+    days_ago = calculate_days_since_login(last_login)
+    return unless days_ago
+
+    summary_parts << format_activity_status(days_ago)
+  end
+
+  def format_creation_date(account_created)
+    account_created.strftime('%B %Y')
+  rescue StandardError
+    'Unknown'
+  end
+
+  def calculate_days_since_login(last_login)
+    ((Time.zone.now - last_login) / 86_400).to_i
+  rescue StandardError
+    nil
+  end
+
+  def format_activity_status(days_ago)
+    case days_ago
+    when 0
+      'Active today'
+    when 1
+      'Last active yesterday'
+    when 2..7
+      "Last active #{days_ago} days ago"
+    else
+      'Inactive user'
+    end
+  end
+end
+
+# Example usage with mock data
+puts '=== Company Data Builder Example ==='
+
+# Mock company object
+company_data = OpenStruct.new(
+  id: 1,
+  name: 'InnovateTech Solutions',
+  domain_name: 'innovatetech.com',
+  description: 'A cutting-edge technology company focused on AI and machine learning solutions ' \
+               'for enterprise customers.',
+  city: 'San Francisco',
+  country: 'USA',
+  employee_count: 150,
+  revenue: 25_000_000,
+  founded_year: 2018,
+  technologies: %w[Ruby Python JavaScript AWS Docker Kubernetes],
+  data: {
+    'categories' => {
+      'primary' => 'Software Development',
+      'secondary' => 'AI/ML'
+    }
+  },
+  financial_data: {
+    'total_funding' => '$5.2M',
+    'stage' => 'Series A'
+  }
+)
+
+company_builder = CompanyDataBuilder.new(company_data)
+company_result = company_builder.build
+
+puts 'Company data structure:'
+puts JSON.pretty_generate(company_result)
+
+puts "\n=== Using with LLM Conductor ==="
+
+# Example of using the built data with LLM Conductor
+# response = LlmConductor.generate(
+#   model: 'gpt-3.5-turbo',
+#   data: company_result,
+#   type: :company_analysis
+# )
+
+puts 'Built data ready for LLM consumption:'
+puts "- Company: #{company_result[:name]}"
+puts "- Industry: #{company_result[:industry]}"
+puts "- Summary: #{company_result[:summary]}"
+
+puts "\n=== User Profile Builder Example ==="
+
+# Mock user object
+user_data = OpenStruct.new(
+  first_name: 'John',
+  last_name: 'Doe',
+  email: 'john.doe@example.com',
+  birth_date: Time.zone.parse('1985-03-15'),
+  city: 'Austin',
+  state: 'Texas',
+  country: 'USA',
+  job_title: 'Senior Software Engineer',
+  company_name: 'TechCorp',
+  years_experience: 8,
+  skills: %w[Ruby Rails JavaScript React PostgreSQL],
+  created_at: Time.zone.parse('2020-01-15'),
+  last_login_at: Time.zone.now - (2 * 24 * 60 * 60), # 2 days ago
+  preferences: {
+    'communication' => 'Email',
+    'notifications' => true,
+    'privacy' => 'High'
+  },
+  profile: {
+    'professional' => {
+      'industry' => 'Technology'
+    }
+  }
+)
+
+user_builder = UserProfileBuilder.new(user_data)
+user_result = user_builder.build
+
+puts 'User profile structure:'
+puts JSON.pretty_generate(user_result)
+
+puts "\n=== Error Handling Example ==="
+
+# Example with missing/nil data
+incomplete_company = OpenStruct.new(
+  id: 2,
+  name: 'StartupCorp',
+  domain_name: nil,
+  description: '',
+  employee_count: nil,
+  revenue: 0,
+  city: 'New York'
+  # Missing many other fields
+)
+
+incomplete_builder = CompanyDataBuilder.new(incomplete_company)
+incomplete_result = incomplete_builder.build
+
+puts 'Handling incomplete data:'
+puts "- Revenue: #{incomplete_result[:metrics][:revenue]}"
+puts "- Industry: #{incomplete_result[:industry]}"
+puts "- Location: #{incomplete_result[:location]}"
+puts "- Employee Count: #{incomplete_result[:metrics][:employees]}"

data/examples/prompt_registration.rb

@@ -0,0 +1,133 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of the new prompt registration system
+require_relative '../lib/llm_conductor'
+
+# Configure the gem
+LlmConductor.configure do |config|
+  config.default_model = 'gpt-3.5-turbo'
+  config.openai(api_key: ENV['OPENAI_API_KEY'])
+end
+
+# Define a custom prompt class
+class CompanyAnalysisPrompt < LlmConductor::Prompts::BasePrompt
+  def render
+    <<~PROMPT
+      Company: #{name}
+      Domain: #{domain_name}
+      Description: #{truncate_text(description, max_length: 1000)}
+
+      Please analyze this company and provide:
+      1. Core business model
+      2. Target market
+      3. Competitive advantages
+      4. Growth potential
+
+      Format as JSON with the following structure:
+      {
+        "business_model": "description",
+        "target_market": "description",#{' '}
+        "competitive_advantages": ["advantage1", "advantage2"],
+        "growth_potential": "high|medium|low"
+      }
+    PROMPT
+  end
+end
+
+# Define another prompt for summarization
+class CompanySummaryPrompt < LlmConductor::Prompts::BasePrompt
+  def render
+    <<~PROMPT
+      Company Information:
+      #{company_details}
+
+      Please provide a brief summary of this company in #{word_limit || 100} words or less.
+      Focus on:
+      #{bulleted_list(focus_areas || ['Main business', 'Key products/services', 'Market position'])}
+    PROMPT
+  end
+
+  private
+
+  def company_details
+    details = []
+    details << "Name: #{name}" if name
+    details << "Domain: #{domain_name}" if domain_name
+    details << "Description: #{description}" if description
+    details << "Industry: #{industry}" if industry
+    details.join("\n")
+  end
+end
+
+# Register the prompt classes
+LlmConductor::PromptManager.register(:detailed_analysis, CompanyAnalysisPrompt)
+LlmConductor::PromptManager.register(:company_summary, CompanySummaryPrompt)
+
+# Example company data
+company_data = {
+  name: 'TechCorp',
+  domain_name: 'techcorp.com',
+  description: 'A leading technology company specializing in artificial intelligence and machine learning ' \
+               'solutions for enterprise clients. We help businesses automate their processes and make ' \
+               'data-driven decisions through our cutting-edge AI platform.',
+  industry: 'Technology',
+  founded_year: 2020
+}
+
+puts '=== Example 1: Detailed Analysis ==='
+
+# Use the registered prompt
+response = LlmConductor.generate(
+  model: 'gpt-3.5-turbo',
+  data: company_data,
+  type: :detailed_analysis
+)
+
+puts 'Generated Prompt Preview:'
+puts LlmConductor::PromptManager.render(:detailed_analysis, company_data)
+puts "\n#{'=' * 50}\n"
+
+if response.success?
+  puts "Response: #{response.output}"
+
+  # Try to parse as JSON
+  begin
+    analysis = response.parse_json
+    puts "\nParsed Analysis:"
+    puts "Business Model: #{analysis['business_model']}"
+    puts "Target Market: #{analysis['target_market']}"
+    puts "Growth Potential: #{analysis['growth_potential']}"
+  rescue JSON::ParserError => e
+    puts "Note: Response is not valid JSON: #{e.message}"
+  end
+else
+  puts "Error: #{response.metadata[:error]}"
+end
+
+puts "\n=== Example 2: Company Summary ==="
+
+# Use the summary prompt with custom parameters
+summary_data = company_data.merge(
+  word_limit: 50,
+  focus_areas: ['AI capabilities', 'Client base', 'Innovation']
+)
+
+response = LlmConductor.generate(
+  model: 'gpt-3.5-turbo',
+  data: summary_data,
+  type: :company_summary
+)
+
+puts 'Generated Prompt Preview:'
+puts LlmConductor::PromptManager.render(:company_summary, summary_data)
+puts "\n#{'=' * 50}\n"
+
+if response.success?
+  puts "Summary: #{response.output}"
+else
+  puts "Error: #{response.metadata[:error]}"
+end
+
+puts "\n=== Available Prompt Types ==="
+puts "Registered types: #{LlmConductor::PromptManager.types.join(', ')}"

data/examples/rag_usage.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of RAG (Retrieval-Augmented Generation) usage with LlmConductor
+require_relative '../lib/llm_conductor'
+
+# Configure the gem
+LlmConductor.configure do |config|
+  config.default_model = 'gpt-3.5-turbo'
+  config.openai(api_key: ENV['OPENAI_API_KEY'])
+end
+
+# RAG Example 1: Using template-based generation with structured data
+puts '=== RAG Example 1: Template-based with structured data ==='
+
+# Simulate retrieved context from your knowledge base
+retrieved_context = {
+  title: 'Quantum Computing Overview',
+  content: 'Quantum computing leverages quantum mechanical phenomena like superposition and entanglement...',
+  source: 'Scientific Journal of Computing, 2024',
+  relevance_score: 0.95
+}
+
+# Use the legacy template approach for structured RAG
+result = LlmConductor.generate(
+  model: 'gpt-3.5-turbo',
+  type: :custom,
+  data: {
+    template: "Based on the following context: {{context}}\n\nAnswer this question: {{question}}",
+    context: "#{retrieved_context[:title]}: #{retrieved_context[:content]} (Source: #{retrieved_context[:source]})",
+    question: 'What are the key principles of quantum computing?'
+  }
+)
+
+puts 'Template-based RAG Response:'
+puts result[:output] if result[:output]
+puts "Tokens: #{result[:input_tokens]} + #{result[:output_tokens]} = #{result[:input_tokens] + result[:output_tokens]}"
+puts
+
+# RAG Example 2: Using simple prompt generation with embedded context
+puts '=== RAG Example 2: Simple prompt with embedded context ==='
+
+# Build your RAG prompt manually for maximum control
+rag_prompt = <<~PROMPT
+  You are an expert assistant. Use the following context to answer the question accurately.
+
+  Context:
+  #{retrieved_context[:content]}
+  Source: #{retrieved_context[:source]}
+
+  Question: What are the practical applications of quantum computing?
+
+  Please provide a comprehensive answer based on the context above.
+PROMPT
+
+# Use the new simple API
+response = LlmConductor.generate(
+  model: 'gpt-3.5-turbo',
+  prompt: rag_prompt
+)
+
+puts 'Simple RAG Response:'
+puts response.output if response.success?
+puts "Tokens used: #{response.total_tokens}"
+puts "Estimated cost: $#{response.estimated_cost}"
+puts
+
+# RAG Example 3: Multi-document RAG with multiple contexts
+puts '=== RAG Example 3: Multi-document RAG ==='
+
+contexts = [
+  'Quantum computers use qubits that can exist in superposition states...',
+  'Current quantum computers are limited by decoherence and error rates...',
+  'Major companies like IBM, Google, and Microsoft are investing heavily in quantum research...'
+]
+
+multi_doc_prompt = <<~PROMPT
+  Based on the following multiple sources, provide a comprehensive answer:
+
+  #{contexts.map.with_index { |ctx, i| "Source #{i + 1}: #{ctx}" }.join("\n\n")}
+
+  Question: What is the current state and future outlook of quantum computing?
+PROMPT
+
+response = LlmConductor.generate(prompt: multi_doc_prompt)
+
+puts 'Multi-document RAG Response:'
+puts response.output if response.success?
+puts "Success: #{response.success?}"
+puts
+
+# RAG Example 4: Error handling in RAG scenarios
+puts '=== RAG Example 4: Error handling ==='
+
+begin
+  response = LlmConductor.generate(
+    model: 'invalid-model',
+    prompt: 'This should fail gracefully'
+  )
+
+  if response.success?
+    puts response.output
+  else
+    puts "RAG Error handled gracefully: #{response.metadata[:error]}"
+  end
+rescue StandardError => e
+  puts "Exception in RAG: #{e.message}"
+end

data/examples/simple_usage.rb

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example of simple LlmConductor usage
+require_relative '../lib/llm_conductor'
+
+# Configure the gem (optional - will use environment variables by default)
+LlmConductor.configure do |config|
+  config.default_model = 'gpt-3.5-turbo'
+  config.openai(api_key: ENV['OPENAI_API_KEY'])
+end
+
+# Simple text generation
+response = LlmConductor.generate(
+  model: 'gpt-3.5-turbo',
+  prompt: 'Explain quantum computing in simple terms'
+)
+
+puts response.output
+puts "Tokens used: #{response.total_tokens}"
+puts "Cost: $#{response.estimated_cost}" if response.estimated_cost
+
+# Example with default model (from configuration)
+response2 = LlmConductor.generate(
+  prompt: 'What are the benefits of renewable energy?'
+)
+
+puts "\n--- Second Example ---"
+puts response2.output
+puts "Input tokens: #{response2.input_tokens}"
+puts "Output tokens: #{response2.output_tokens}"
+puts "Success: #{response2.success?}"
+
+# Example with error handling
+begin
+  response3 = LlmConductor.generate(
+    model: 'invalid-model',
+    prompt: 'This should fail'
+  )
+
+  if response3.success?
+    puts response3.output
+  else
+    puts "Error: #{response3.metadata[:error]}"
+  end
+rescue StandardError => e
+  puts "Exception: #{e.message}"
+end

data/lib/llm_conductor/client_factory.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  # Factory class for creating appropriate LLM client instances based on model and vendor
+  class ClientFactory
+    def self.build(model:, type:, vendor: nil)
+      vendor ||= determine_vendor(model)
+
+      client_class = case vendor
+                     when :openai, :gpt
+                       Clients::GptClient
+                     when :openrouter
+                       Clients::OpenrouterClient
+                     when :ollama
+                       Clients::OllamaClient
+                     else
+                       raise ArgumentError,
+                             "Unsupported vendor: #{vendor}. Supported vendors: openai, openrouter, ollama"
+                     end
+
+      client_class.new(model:, type:)
+    end
+
+    def self.determine_vendor(model)
+      case model
+      when /^gpt/i
+        :openai
+      else
+        :ollama # Default to Ollama for non-specific model names
+      end
+    end
+  end
+end