llm_conductor 0.1.0

data/lib/llm_conductor/clients/base_client.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'tiktoken_ruby'
+require 'ollama-ai'
+require 'openai'
+
+module LlmConductor
+  module Clients
+    # Base client class providing common functionality for all LLM providers
+    # including prompt building, token counting, and response formatting.
+    class BaseClient
+      include Prompts
+
+      attr_reader :model, :type
+
+      def initialize(model:, type:)
+        @model = model
+        @type = type
+      end
+
+      def generate(data:)
+        prompt = build_prompt(data)
+        input_tokens = calculate_tokens(prompt)
+        output_text = generate_content(prompt)
+        output_tokens = calculate_tokens(output_text || '')
+
+        build_response(output_text, input_tokens, output_tokens, { prompt: })
+      rescue StandardError => e
+        build_error_response(e)
+      end
+
+      # Simple generation method that accepts a direct prompt and returns a Response object
+      def generate_simple(prompt:)
+        input_tokens = calculate_tokens(prompt)
+        output_text = generate_content(prompt)
+        output_tokens = calculate_tokens(output_text || '')
+
+        build_response(output_text, input_tokens, output_tokens)
+      rescue StandardError => e
+        build_error_response(e)
+      end
+
+      private
+
+      def build_response(output_text, input_tokens, output_tokens, additional_metadata = {})
+        Response.new(
+          output: output_text,
+          model:,
+          input_tokens:,
+          output_tokens:,
+          metadata: build_metadata.merge(additional_metadata)
+        )
+      end
+
+      def build_error_response(error)
+        Response.new(
+          output: nil,
+          model:,
+          metadata: { error: error.message, error_class: error.class.name }
+        )
+      end
+
+      def build_prompt(data)
+        # Check if this is a registered prompt type
+        if PromptManager.registered?(type)
+          PromptManager.render(type, data)
+        else
+          # Fallback to legacy prompt methods
+          send(:"prompt_#{type}", data)
+        end
+      end
+
+      def generate_content(prompt)
+        raise NotImplementedError
+      end
+
+      def calculate_tokens(content)
+        encoder.encode(content).length
+      end
+
+      def encoder
+        @encoder ||= Tiktoken.get_encoding('cl100k_base')
+      end
+
+      def client
+        raise NotImplementedError
+      end
+
+      # Build metadata for the response
+      def build_metadata
+        {
+          vendor: self.class.name.split('::').last.gsub('Client', '').downcase.to_sym,
+          timestamp: Time.zone.now.iso8601
+        }
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/gpt_client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Clients
+    # OpenAI GPT client implementation for accessing GPT models via OpenAI API
+    class GptClient < BaseClient
+      private
+
+      def generate_content(prompt)
+        client.chat(parameters: { model:, messages: [{ role: 'user', content: prompt }] })
+              .dig('choices', 0, 'message', 'content')
+      end
+
+      def client
+        @client ||= begin
+          config = LlmConductor.configuration.provider_config(:openai)
+          options = { access_token: config[:api_key] }
+          options[:organization_id] = config[:organization] if config[:organization]
+          OpenAI::Client.new(options)
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/ollama_client.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Clients
+    # Ollama client implementation for accessing local or self-hosted Ollama models
+    class OllamaClient < BaseClient
+      private
+
+      def generate_content(prompt)
+        client.generate({ model:, prompt:, stream: false }).first['response']
+      end
+
+      def client
+        @client ||= begin
+          config = LlmConductor.configuration.provider_config(:ollama)
+          Ollama.new(
+            credentials: { address: config[:base_url] },
+            options: { server_sent_events: true }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/clients/openrouter_client.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Clients
+    # OpenRouter client implementation for accessing various LLM providers through OpenRouter API
+    class OpenrouterClient < BaseClient
+      private
+
+      def generate_content(prompt)
+        client.chat(
+          parameters: {
+            model:,
+            messages: [{ role: 'user', content: prompt }],
+            provider: { sort: 'throughput' }
+          }
+        ).dig('choices', 0, 'message', 'content')
+      end
+
+      def client
+        @client ||= begin
+          config = LlmConductor.configuration.provider_config(:openrouter)
+          OpenAI::Client.new(
+            access_token: config[:api_key],
+            uri_base: config[:uri_base] || 'https://openrouter.ai/api/'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/llm_conductor/configuration.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# LLM Conductor provides a unified interface for multiple Language Model providers
+module LlmConductor
+  # Configuration class for managing API keys, endpoints, and default settings
+  class Configuration
+    attr_accessor :default_model, :default_vendor, :timeout, :max_retries, :retry_delay
+    attr_reader :providers
+
+    def initialize
+      # Default settings
+      @default_model = 'gpt-5-mini'
+      @default_vendor = :openai
+      @timeout = 30
+      @max_retries = 3
+      @retry_delay = 1.0
+
+      # Provider configurations
+      @providers = {}
+
+      # Initialize with environment variables if available
+      setup_defaults_from_env
+    end
+
+    # Configure OpenAI provider
+    def openai(api_key: nil, organization: nil, **options)
+      @providers[:openai] = {
+        api_key: api_key || ENV['OPENAI_API_KEY'],
+        organization: organization || ENV['OPENAI_ORG_ID'],
+        **options
+      }
+    end
+
+    # Configure Ollama provider
+    def ollama(base_url: nil, **options)
+      @providers[:ollama] = {
+        base_url: base_url || ENV['OLLAMA_ADDRESS'] || 'http://localhost:11434',
+        **options
+      }
+    end
+
+    # Configure OpenRouter provider
+    def openrouter(api_key: nil, **options)
+      @providers[:openrouter] = {
+        api_key: api_key || ENV['OPENROUTER_API_KEY'],
+        **options
+      }
+    end
+
+    # Get provider configuration
+    def provider_config(provider)
+      @providers[provider.to_sym] || {}
+    end
+
+    # Legacy compatibility methods
+    def openai_api_key
+      provider_config(:openai)[:api_key]
+    end
+
+    def openai_api_key=(value)
+      openai(api_key: value)
+    end
+
+    def openrouter_api_key
+      provider_config(:openrouter)[:api_key]
+    end
+
+    def openrouter_api_key=(value)
+      openrouter(api_key: value)
+    end
+
+    def ollama_address
+      provider_config(:ollama)[:base_url]
+    end
+
+    def ollama_address=(value)
+      ollama(base_url: value)
+    end
+
+    private
+
+    def setup_defaults_from_env
+      # Auto-configure providers if environment variables are present
+      openai if ENV['OPENAI_API_KEY']
+      openrouter if ENV['OPENROUTER_API_KEY']
+      ollama # Always configure Ollama with default URL
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/llm_conductor/data_builder.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  # Base class for building structured data from source objects for LLM consumption.
+  # Provides helper methods for data extraction, formatting, and safe handling of nested data.
+  #
+  # @example Basic usage
+  #   class CompanyDataBuilder < LlmConductor::DataBuilder
+  #     def build
+  #       {
+  #         id: source_object.id,
+  #         name: source_object.name,
+  #         metrics: build_metrics
+  #       }
+  #     end
+  #
+  #     private
+  #
+  #     def build_metrics
+  #       {
+  #         employees: safe_extract(:employee_count, default: 'Unknown')
+  #       }
+  #     end
+  #   end
+  #
+  #   builder = CompanyDataBuilder.new(company)
+  #   data = builder.build
+  class DataBuilder
+    attr_reader :source_object
+
+    def initialize(source_object)
+      @source_object = source_object
+    end
+
+    # Abstract method to be implemented by subclasses
+    # @return [Hash] The built data structure
+    def build
+      raise NotImplementedError, "#{self.class} must implement the #build method"
+    end
+
+    protected
+
+    # Safely extract a value from the source object with a default fallback
+    # @param attribute [Symbol, String] The attribute name to extract
+    # @param default [Object] Default value if extraction fails
+    # @return [Object] The extracted value or default
+    def safe_extract(attribute, default: nil)
+      return default if source_object.nil?
+
+      if source_object.respond_to?(attribute)
+        value = source_object.public_send(attribute)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) ? default : value
+      else
+        default
+      end
+    end
+
+    # Extract nested data from a hash-like structure
+    # @param root_key [Symbol, String] The root key to start extraction from
+    # @param *path [Array<String, Symbol>] The path to navigate through nested structures
+    # @return [Object, nil] The extracted value or nil if not found
+    def extract_nested_data(root_key, *path)
+      return nil if source_object.nil?
+
+      data = safe_extract(root_key)
+      return nil unless hash_like?(data)
+
+      navigate_nested_path(data, path)
+    rescue StandardError
+      nil
+    end
+
+    # Format a value for LLM consumption with appropriate fallbacks
+    # @param value [Object] The value to format
+    # @param options [Hash] Formatting options
+    # @option options [String] :default ('N/A') Default value for nil/empty values
+    # @option options [String] :prefix ('') Prefix to add to non-empty values
+    # @option options [String] :suffix ('') Suffix to add to non-empty values
+    # @option options [Integer] :max_length (nil) Maximum length to truncate to
+    # @return [String] Formatted value suitable for LLM consumption
+    def format_for_llm(value, options = {})
+      default = options.fetch(:default, 'N/A')
+      prefix = options.fetch(:prefix, '')
+      suffix = options.fetch(:suffix, '')
+      max_length = options[:max_length]
+
+      # Handle nil or empty values
+      return default if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      # Convert to string and apply formatting
+      formatted = "#{prefix}#{value}#{suffix}"
+
+      # Apply length limit if specified
+      formatted = "#{formatted[0...max_length]}..." if max_length && formatted.length > max_length
+
+      formatted
+    end
+
+    # Extract and format a list of items
+    # @param attribute [Symbol, String] The attribute containing the list
+    # @param options [Hash] Formatting options
+    # @option options [String] :separator (', ') Separator for joining items
+    # @option options [Integer] :limit (nil) Maximum number of items to include
+    # @option options [String] :default ('None') Default value for empty lists
+    # @return [String] Formatted list suitable for LLM consumption
+    def extract_list(attribute, options = {})
+      separator = options.fetch(:separator, ', ')
+      limit = options[:limit]
+      default = options.fetch(:default, 'None')
+
+      items = safe_extract(attribute, default: [])
+      return default unless items.respond_to?(:map) && !items.empty?
+
+      # Apply limit if specified
+      items = items.first(limit) if limit
+
+      items.map(&:to_s).join(separator)
+    end
+
+    # Build a summary string from multiple attributes
+    # @param attributes [Array<Symbol>] List of attributes to include
+    # @param options [Hash] Formatting options
+    # @option options [String] :separator (' | ') Separator between attributes
+    # @option options [Boolean] :skip_empty (true) Whether to skip empty values
+    # @return [String] Combined summary string
+    def build_summary(*attributes, **options)
+      separator = options.fetch(:separator, ' | ')
+      skip_empty = options.fetch(:skip_empty, true)
+
+      parts = attributes.map do |attr|
+        value = safe_extract(attr)
+        next if skip_empty && (value.nil? || (value.respond_to?(:empty?) && value.empty?))
+
+        format_for_llm(value)
+      end.compact
+
+      parts.join(separator)
+    end
+
+    # Helper method to safely convert numeric values with formatting
+    # @param value [Numeric, String] The value to format
+    # @param options [Hash] Formatting options
+    # @option options [String] :currency ('$') Currency symbol for monetary values
+    # @option options [Boolean] :as_currency (false) Whether to format as currency
+    # @option options [Integer] :precision (0) Decimal precision
+    # @return [String] Formatted numeric value
+    def format_number(value, options = {})
+      return format_for_llm(nil, options) if value.nil?
+
+      begin
+        numeric_value = Float(value)
+        formatted = format_numeric_value(numeric_value, options[:precision] || 0)
+        formatted = add_thousands_separators(formatted)
+
+        apply_currency_formatting(formatted, options)
+      rescue ArgumentError
+        format_for_llm(value, options)
+      end
+    end
+
+    private
+
+    # Helper to check if an object has a specific method
+    def attribute?(attribute)
+      source_object&.respond_to?(attribute)
+    end
+
+    # Check if data structure supports hash-like access
+    def hash_like?(data)
+      data.respond_to?(:[])
+    end
+
+    # Navigate through nested hash path
+    def navigate_nested_path(data, path)
+      path.reduce(data) do |current_data, key|
+        return nil unless hash_like?(current_data)
+
+        find_key_variant(current_data, key)
+      end
+    end
+
+    # Find key in various formats (string, symbol)
+    def find_key_variant(data, key)
+      data[key] || data[key.to_s] || data[key.to_sym]
+    end
+
+    # Format numeric value with precision
+    def format_numeric_value(numeric_value, precision)
+      if precision.positive?
+        format("%.#{precision}f", numeric_value)
+      else
+        numeric_value.to_i.to_s
+      end
+    end
+
+    # Add thousands separators to numeric string
+    def add_thousands_separators(formatted)
+      formatted.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+    end
+
+    # Apply currency formatting if requested
+    def apply_currency_formatting(formatted, options)
+      if options.fetch(:as_currency, false)
+        currency = options.fetch(:currency, '$')
+        "#{currency}#{formatted}"
+      else
+        formatted
+      end
+    end
+  end
+end

data/lib/llm_conductor/prompt_manager.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  # Manages registration and creation of prompt classes
+  class PromptManager
+    class PromptNotFoundError < StandardError; end
+    class InvalidPromptClassError < StandardError; end
+
+    @registry = {}
+
+    class << self
+      attr_reader :registry
+
+      # Register a prompt class with a given type
+      def register(type, prompt_class)
+        validate_prompt_class!(prompt_class)
+
+        @registry[type.to_sym] = prompt_class
+      end
+
+      # Unregister a prompt type (useful for testing)
+      def unregister(type)
+        @registry.delete(type.to_sym)
+      end
+
+      # Get a registered prompt class
+      def get(type)
+        @registry[type.to_sym] || raise(PromptNotFoundError, "Prompt type :#{type} not found")
+      end
+
+      # Check if a prompt type is registered
+      def registered?(type)
+        @registry.key?(type.to_sym)
+      end
+
+      # List all registered prompt types
+      def types
+        @registry.keys
+      end
+
+      # Clear all registrations (useful for testing)
+      def clear!
+        @registry.clear
+      end
+
+      # Create a prompt instance
+      def create(type, data = {})
+        prompt_class = get(type)
+        prompt_class.new(data)
+      end
+
+      # Create and render a prompt in one step
+      def render(type, data = {})
+        create(type, data).render
+      end
+
+      private
+
+      def validate_prompt_class!(prompt_class)
+        raise InvalidPromptClassError, 'Prompt must be a class' unless prompt_class.is_a?(Class)
+
+        unless prompt_class < Prompts::BasePrompt
+          raise InvalidPromptClassError, 'Prompt class must inherit from BasePrompt'
+        end
+
+        return if prompt_class.instance_methods(false).include?(:render)
+
+        raise InvalidPromptClassError, 'Prompt class must implement #render method'
+      end
+    end
+  end
+end

data/lib/llm_conductor/prompts/base_prompt.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module LlmConductor
+  module Prompts
+    # Base class for all prompt templates
+    # Provides common functionality and data access patterns
+    class BasePrompt
+      attr_reader :data
+
+      def initialize(data = {})
+        @data = data || {}
+        setup_data_methods
+      end
+
+      # Override this method in subclasses to define the prompt
+      def render
+        raise NotImplementedError, 'Subclasses must implement #render method'
+      end
+
+      # Get the rendered prompt as a string
+      def to_s
+        render.strip
+      end
+
+      # Safe access to nested hash values
+      def data_dig(*keys)
+        @data.dig(*keys) if @data.respond_to?(:dig)
+      end
+
+      # Convenience alias for data_dig
+      alias dig data_dig
+
+      protected
+
+      # Truncate text to a maximum length with ellipsis
+      def truncate_text(text, max_length: 100)
+        return '' if text.nil?
+
+        text = text.to_s
+        return text if text.length <= max_length
+
+        "#{text[0...max_length]}..."
+      end
+
+      # Format a list as a numbered list
+      def numbered_list(items)
+        return '' if items.nil? || items.empty?
+
+        items.map.with_index(1) { |item, index| "#{index}. #{item}" }.join("\n")
+      end
+
+      # Format a list as a bulleted list
+      def bulleted_list(items)
+        return '' if items.nil? || items.empty?
+
+        items.map { |item| "• #{item}" }.join("\n")
+      end
+
+      private
+
+      # Create dynamic method accessors for data keys
+      def setup_data_methods
+        return unless @data.respond_to?(:each)
+
+        @data.each do |key, value|
+          next unless key.respond_to?(:to_sym)
+
+          define_singleton_method(key.to_sym) { value }
+        end
+      end
+
+      # Handle missing methods by checking data hash
+      def method_missing(method_name, *args, &block)
+        if @data.respond_to?(:[]) && @data.key?(method_name)
+          @data[method_name]
+        elsif @data.respond_to?(:[]) && @data.key?(method_name.to_s)
+          @data[method_name.to_s]
+        else
+          super
+        end
+      end
+
+      # Support for respond_to? with dynamic methods
+      def respond_to_missing?(method_name, include_private = false)
+        (@data.respond_to?(:[]) &&
+         (@data.key?(method_name) || @data.key?(method_name.to_s))) || super
+      end
+    end
+  end
+end