llm_conductor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 94848876574eca5294236d61d79175b6e28fc918c6bcbd0af969d70fc50cc6c8
+  data.tar.gz: 18865a4228201006c9ebf84e0aac4bd6b946e1c551a121e323eed827477bb3ca
+SHA512:
+  metadata.gz: f16ee4255f54f3daef35a2557cd19fc171dbc238c2525475d95c3209ca5771f07f9ccd7d6e485f6adef979625008c0fb360d5705adea23bd14d987f051b236c0
+  data.tar.gz: 62f464b4dcc76ce676f735db190e9a16ba9bee5f10b4dbdbd4c212badbfb7c8a736465bc40cd8228c11e2e1fed6f7afe823d05dfcd2dfc6c0cb689870e0e4acc

data/.rspec

@@ -0,0 +1,4 @@
+--format documentation
+--color
+--require spec_helper
+--exclude-pattern "cache/**/*"

data/.rubocop.yml

@@ -0,0 +1,103 @@
+# RuboCop configuration for GitLab CI
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+
+require: 
+  - rubocop-capybara
+  - rubocop-factory_bot
+  - rubocop-rspec
+
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.4.1
+  NewCops: disable
+  SuggestExtensions: false
+  Exclude:
+    - 'cache/**/*'
+    - 'vendor/**/*'
+  
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: always
+# This is not rails application.
+# Rails/Blank:
+#   Enabled: false
+
+# Rails/Present:
+#   Enabled: false
+
+# Rails/TimeZone:
+#   Enabled: false
+
+Lint/ConstantDefinitionInBlock:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 15
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/FilePath:
+  Enabled: false
+
+RSpec/UnspecifiedException:
+  Enabled: false
+
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+RSpec/LeakyConstantDeclaration:
+  Enabled: false
+
+RSpec/DescribeMethod:
+  Enabled: false
+
+# Disable Ruby version mismatch warning
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+# GitLab CI specific - generate JSON report
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - '*.gemspec'
+
+Layout/LineLength:
+  Max: 120
+
+# Performance cops (from .rubocop_todo.yml)
+Performance/RedundantEqualityComparisonBlock:
+  Exclude:
+    - 'spec/llm_conductor/performance_spec.rb'

data/.rubocop_todo.yml

@@ -0,0 +1,54 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2024-09-12 using RuboCop version 1.80.2.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 10
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: CheckForMethodsWithNoSideEffects.
+Performance/RedundantEqualityComparisonBlock:
+  Exclude:
+    - 'spec/llm_conductor/performance_spec.rb'
+
+# Offense count: 2
+# Configuration parameters: .
+RSpec/ContextWording:
+  Exclude:
+    - 'spec/llm_conductor/client_factory_spec.rb'
+
+# Offense count: 2
+RSpec/DescribeClass:
+  Exclude:
+    - 'spec/llm_conductor/error_handling_spec.rb'
+    - 'spec/llm_conductor/performance_spec.rb'
+
+# Offense count: 1
+RSpec/MultipleDescribes:
+  Exclude:
+    - 'spec/llm_conductor/configuration_spec.rb'
+
+# Offense count: 10
+# Configuration parameters: Max, AllowSubject.
+RSpec/NestedGroups:
+  Exclude:
+    - 'spec/llm_conductor/client_factory_spec.rb'
+    - 'spec/llm_conductor/integration_spec.rb'
+
+# Offense count: 1
+RSpec/SpecFilePathFormat:
+  Exclude:
+    - 'spec/llm_conductor/integration_spec.rb'
+
+# Offense count: 1
+RSpec/UnspecifiedException:
+  Exclude:
+    - 'spec/llm_conductor/error_handling_spec.rb'
+
+# Offense count: 33
+# Configuration parameters: EnforcedStyle, IgnoreNameless, IgnoreSymbolicNames.
+# SupportedStyles: strict, flexible
+RSpec/VerifiedDoubles:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.4.1

data/README.md

@@ -0,0 +1,413 @@
+# LLM Conductor
+
+A powerful Ruby gem for orchestrating multiple Language Model providers with a unified, modern interface. LLM Conductor provides seamless integration with OpenAI GPT and Ollama with advanced prompt management, data building patterns, and comprehensive response handling.
+
+## Features
+
+🚀 **Multi-Provider Support** - OpenAI GPT and Ollama with automatic vendor detection  
+🎯 **Unified Modern API** - Simple `LlmConductor.generate()` interface with rich Response objects  
+📝 **Advanced Prompt Management** - Registrable prompt classes with inheritance and templating  
+🏗️ **Data Builder Pattern** - Structured data preparation for complex LLM inputs  
+⚡ **Smart Configuration** - Rails-style configuration with environment variable support  
+💰 **Cost Tracking** - Automatic token counting and cost estimation  
+🔧 **Extensible Architecture** - Easy to add new providers and prompt types  
+🛡️ **Robust Error Handling** - Comprehensive error handling with detailed metadata  
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'llm_conductor'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install llm_conductor
+```
+
+## Quick Start
+
+### 1. Simple Text Generation
+
+```ruby
+# Direct prompt generation - easiest way to get started
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  prompt: 'Explain quantum computing in simple terms'
+)
+
+puts response.output           # The generated text
+puts response.total_tokens     # Token usage
+puts response.estimated_cost   # Cost in USD
+```
+
+### 2. Template-Based Generation
+
+```ruby
+# Use built-in templates with structured data
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :summarize_description,
+  data: {
+    name: 'TechCorp',
+    domain_name: 'techcorp.com', 
+    description: 'An AI company specializing in...'
+  }
+)
+
+# Response object provides rich information
+if response.success?
+  puts "Generated: #{response.output}"
+  puts "Tokens: #{response.total_tokens}"
+  puts "Cost: $#{response.estimated_cost}"
+else
+  puts "Error: #{response.metadata[:error]}"
+end
+```
+
+## Configuration
+
+### Rails-Style Configuration
+
+Create `config/initializers/llm_conductor.rb` (Rails) or configure in your application:
+
+```ruby
+LlmConductor.configure do |config|
+  # Default settings
+  config.default_model = 'gpt-5-mini'
+  config.default_vendor = :openai
+  config.timeout = 30
+  config.max_retries = 3
+  config.retry_delay = 1.0
+
+  # Provider configurations
+  config.openai(
+    api_key: ENV['OPENAI_API_KEY'],
+    organization: ENV['OPENAI_ORG_ID'] # Optional
+  )
+
+  config.ollama(
+    base_url: ENV['OLLAMA_ADDRESS'] || 'http://localhost:11434'
+  )
+end
+```
+
+### Environment Variables
+
+The gem automatically detects these environment variables:
+
+- `OPENAI_API_KEY` - OpenAI API key
+- `OPENAI_ORG_ID` - OpenAI organization ID (optional)
+- `OLLAMA_ADDRESS` - Ollama server address
+
+## Supported Providers & Models
+
+### OpenAI (Automatic for GPT models)
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',  # Auto-detects OpenAI
+  prompt: 'Your prompt here'
+)
+```
+
+### Ollama (Default for non-GPT models)
+```ruby
+response = LlmConductor.generate(
+  model: 'llama3.2',  # Auto-detects Ollama for non-GPT models
+  prompt: 'Your prompt here'
+)
+```
+
+## Advanced Features
+
+### 1. Custom Prompt Registration
+
+Create reusable, testable prompt classes:
+
+```ruby
+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.
+    PROMPT
+  end
+end
+
+# Register the prompt
+LlmConductor::PromptManager.register(:detailed_analysis, CompanyAnalysisPrompt)
+
+# Use the registered prompt
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :detailed_analysis,
+  data: {
+    name: 'TechCorp',
+    domain_name: 'techcorp.com',
+    description: 'A leading AI company...'
+  }
+)
+
+# Parse structured responses
+analysis = response.parse_json
+puts analysis
+```
+
+### 2. Data Builder Pattern
+
+Structure complex data for LLM consumption:
+
+```ruby
+class CompanyDataBuilder < LlmConductor::DataBuilder
+  def build
+    {
+      id: source_object.id,
+      name: source_object.name,
+      description: format_for_llm(source_object.description, max_length: 500),
+      industry: extract_nested_data(:data, 'categories', 'primary'),
+      metrics: build_metrics,
+      summary: build_company_summary,
+      domain_name: source_object.domain_name
+
+    }
+  end
+
+  private
+
+  def build_metrics
+    {
+      employees: format_number(source_object.employee_count),
+      revenue: format_number(source_object.annual_revenue),
+      growth_rate: "#{source_object.growth_rate}%"
+    }
+  end
+
+  def build_company_summary
+    name = safe_extract(:name, default: 'Company')
+    industry = extract_nested_data(:data, 'categories', 'primary')
+    "#{name} is a #{industry} company..."
+  end
+end
+
+# Usage
+company = Company.find(123)
+data = CompanyDataBuilder.new(company).build
+
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :detailed_analysis, 
+  data: data
+)
+```
+
+### 3. Built-in Prompt Templates
+
+#### Featured Links Extraction
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :featured_links,
+  data: {
+    htmls: '<html>...</html>',
+    current_url: 'https://example.com'
+  }
+)
+```
+
+#### HTML Summarization
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini', 
+  type: :summarize_htmls,
+  data: { htmls: '<html>...</html>' }
+)
+```
+
+#### Description Summarization
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :summarize_description,
+  data: {
+    name: 'Company Name',
+    description: 'Long description...',
+    industries: ['Tech', 'AI']
+  }
+)
+```
+
+#### Custom Templates
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  type: :custom,
+  data: {
+    template: "Analyze this data: %{data}",
+    data: "Your data here"
+  }
+)
+```
+
+### 4. Response Object
+
+All methods return a rich `LlmConductor::Response` object:
+
+```ruby
+response = LlmConductor.generate(...)
+
+# Main content
+response.output           # Generated text
+response.success?         # Boolean success status
+
+# Token information
+response.input_tokens     # Input tokens used
+response.output_tokens    # Output tokens generated  
+response.total_tokens     # Total tokens
+
+# Cost tracking (for supported models)
+response.estimated_cost   # Estimated cost in USD
+
+# Metadata
+response.model           # Model used
+response.metadata        # Hash with vendor, timestamp, etc.
+
+# Structured data parsing
+response.parse_json                    # Parse as JSON
+response.extract_code_block('json')    # Extract code blocks
+```
+
+### 5. Error Handling
+
+The gem provides comprehensive error handling:
+
+```ruby
+response = LlmConductor.generate(
+  model: 'gpt-5-mini',
+  prompt: 'Your prompt'
+)
+
+if response.success?
+  puts response.output
+else
+  puts "Error: #{response.metadata[:error]}"
+  puts "Failed model: #{response.model}"
+end
+
+# Exception handling for critical errors
+begin
+  response = LlmConductor.generate(...)
+rescue LlmConductor::Error => e
+  puts "LLM Conductor error: #{e.message}"
+rescue StandardError => e
+  puts "General error: #{e.message}" 
+end
+```
+
+## Extending the Gem
+
+### Adding Custom Clients
+
+```ruby
+module LlmConductor
+  module Clients
+    class CustomClient < BaseClient
+      private
+
+      def generate_content(prompt)
+        # Implement your provider's API call
+        your_custom_api.generate(prompt)
+      end
+    end
+  end
+end
+```
+
+### Adding Prompt Types
+
+```ruby
+module LlmConductor
+  module Prompts
+    def prompt_custom_analysis(data)
+      <<~PROMPT
+        Custom analysis for: #{data[:subject]}
+        Context: #{data[:context]}
+        
+        Please provide detailed analysis.
+      PROMPT
+    end
+  end
+end
+```
+
+## Examples
+
+Check the `/examples` directory for comprehensive usage examples:
+
+- `simple_usage.rb` - Basic text generation
+- `prompt_registration.rb` - Custom prompt classes
+- `data_builder_usage.rb` - Data structuring patterns
+- `rag_usage.rb` - RAG implementation examples
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests.
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests 
+rake spec
+
+# Run RuboCop
+rubocop
+
+# Interactive console
+bin/console
+```
+
+## Testing
+
+The gem includes comprehensive test coverage with unit, integration, and performance tests. See `spec/TESTING_GUIDE.md` for detailed testing information.
+
+## Performance
+
+- **Token Efficiency**: Automatic prompt optimization and token counting
+- **Cost Tracking**: Real-time cost estimation for all supported models
+- **Response Caching**: Built-in mechanisms to avoid redundant API calls
+- **Async Support**: Ready for async/background processing
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ekohe/llm_conductor.
+
+1. Fork the repository
+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`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+This project is intended to be a safe, welcoming space for collaboration. Contributors are expected to adhere to the [code of conduct](https://github.com/ekohe/llm_conductor/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/config/initializers/llm_conductor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Example configuration file for LlmConductor
+# Place this file in config/initializers/llm_conductor.rb in Rails applications
+
+LlmConductor.configure do |config|
+  # Default settings
+  config.default_model = 'gpt-5-mini'
+  config.default_vendor = :openai
+  config.timeout = 30
+  config.max_retries = 3
+  config.retry_delay = 1.0
+
+  # Configure providers
+  config.openai(
+    api_key: ENV['OPENAI_API_KEY'],
+    organization: ENV['OPENAI_ORG_ID'] # optional
+  )
+
+  config.ollama(
+    base_url: ENV['OLLAMA_ADDRESS'] || 'http://localhost:11434'
+  )
+
+  config.openrouter(
+    api_key: ENV['OPENROUTER_API_KEY']
+  )
+end