llm_conductor 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c692236c5d26b598a2275a3a6591022312aec4e4a4d4ee57a186abc774bc39ce
-  data.tar.gz: 3c20edc85442b8e5227fb6896d3899f08495fa1296306042c07c8bc62a883941
+  metadata.gz: 77bf332827087c373c19d318c72b21532974ae510b6b7958b8a5d77fc3e85833
+  data.tar.gz: 365717c91358d62d4a44264087d6500829d53ca1a9d1dc4550890282152ad75b
 SHA512:
-  metadata.gz: 8ed23461382c3a8ee2fddea05fdaef5c72111bac8e4b820e4310a40105a8b0bd78b8f1c36c9176f9ac7ddf8c7b4300e9208b45711a129ab0531dd579f9a52964
-  data.tar.gz: d446efb23252acee7ea453361d402089b87c56450e20ed7e45b1aab2cd0381bff442ed51ea7e2a52a544c39f3117795ad17ac2208dc12514f211d12ba150bb2c
+  metadata.gz: 547cb6b093784591aa0944e36cab482a380a2519fd73324a5dcefaae38fb4eade745f564ada7daee05cd7359515022f49492fee330fc0eee4e592eaf2e5d37bf
+  data.tar.gz: 1118f23b62a725962c7576ba368b5ddadd5fee7f5244f5aea1405d52bacd56708a14cbe50d833afc8e81e6916be8db5c50bb424c238f134957b7965272504944

data/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Ekohe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -1,10 +1,10 @@
 # LLM Conductor
 
-A powerful Ruby gem from [Ekohe](https://ekohe.com) for orchestrating multiple Language Model providers with a unified, modern interface. LLM Conductor provides seamless integration with OpenAI GPT, Anthropic Claude, Google Gemini, and Ollama with advanced prompt management, data building patterns, and comprehensive response handling.
+A powerful Ruby gem from [Ekohe](https://ekohe.com) for orchestrating multiple Language Model providers with a unified, modern interface. LLM Conductor provides seamless integration with OpenAI GPT, Anthropic Claude, Google Gemini, Groq, and Ollama with advanced prompt management, data building patterns, and comprehensive response handling.
 
 ## Features
 
-🚀 **Multi-Provider Support** - OpenAI GPT, Anthropic Claude, Google Gemini, and Ollama with automatic vendor detection
+🚀 **Multi-Provider Support** - OpenAI GPT, Anthropic Claude, Google Gemini, Groq, 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  
@@ -106,9 +106,40 @@ LlmConductor.configure do |config|
     api_key: ENV['GEMINI_API_KEY']
   )
 
+  config.groq(
+    api_key: ENV['GROQ_API_KEY']
+  )
+
   config.ollama(
     base_url: ENV['OLLAMA_ADDRESS'] || 'http://localhost:11434'
   )
+
+  # Optional: Configure custom logger
+  config.logger = Logger.new($stdout)                  # Log to stdout
+  config.logger = Logger.new('log/llm_conductor.log')  # Log to file
+  config.logger = Rails.logger                         # Use Rails logger (in Rails apps)
+end
+```
+
+### Logging Configuration
+
+LLM Conductor supports flexible logging using Ruby's built-in Logger class. By default, when a logger is configured, it uses the DEBUG log level to provide detailed information during development.
+
+```ruby
+LlmConductor.configure do |config|
+  # Option 1: Log to stdout - uses DEBUG level by default
+  config.logger = Logger.new($stdout)
+
+  # Option 2: Log to file - set appropriate level
+  config.logger = Logger.new('log/llm_conductor.log')
+
+  # Option 3: Use Rails logger (Rails apps)
+  config.logger = Rails.logger
+
+  # Option 4: Custom logger with formatting
+  config.logger = Logger.new($stderr).tap do |logger|
+    logger.formatter = proc { |severity, datetime, progname, msg| "#{msg}\n" }
+  end
 end
 ```
 
@@ -120,6 +151,7 @@ The gem automatically detects these environment variables:
 - `OPENAI_ORG_ID` - OpenAI organization ID (optional)
 - `ANTHROPIC_API_KEY` - Anthropic API key
 - `GEMINI_API_KEY` - Google Gemini API key
+- `GROQ_API_KEY` - Groq API key
 - `OLLAMA_ADDRESS` - Ollama server address
 
 ## Supported Providers & Models
@@ -162,10 +194,31 @@ response = LlmConductor.generate(
 )
 ```
 
-### Ollama (Default for non-GPT/Claude/Gemini models)
+### Groq (Automatic for Llama, Mixtral, Gemma, Qwen models)
+```ruby
+response = LlmConductor.generate(
+  model: 'llama-3.1-70b-versatile',  # Auto-detects Groq
+  prompt: 'Your prompt here'
+)
+
+# Supported Groq models
+response = LlmConductor.generate(
+  model: 'mixtral-8x7b-32768',  # Auto-detects Groq
+  prompt: 'Your prompt here'
+)
+
+# Or explicitly specify vendor
+response = LlmConductor.generate(
+  model: 'qwen-2.5-72b-instruct',
+  vendor: :groq,
+  prompt: 'Your prompt here'
+)
+```
+
+### Ollama (Default for other models)
 ```ruby
 response = LlmConductor.generate(
-  model: 'llama3.2',  # Auto-detects Ollama for non-GPT/Claude/Gemini models
+  model: 'deepseek-r1',
   prompt: 'Your prompt here'
 )
 ```
@@ -177,13 +230,15 @@ The gem automatically detects the appropriate provider based on model names:
 - **OpenAI**: Models starting with `gpt-` (e.g., `gpt-4`, `gpt-3.5-turbo`)
 - **Anthropic**: Models starting with `claude-` (e.g., `claude-3-5-sonnet-20241022`)
 - **Google Gemini**: Models starting with `gemini-` (e.g., `gemini-2.5-flash`, `gemini-2.0-flash`)
+- **Groq**: Models starting with `llama`, `mixtral`, `gemma`, or `qwen` (e.g., `llama-3.1-70b-versatile`, `mixtral-8x7b-32768`, `gemma-7b-it`, `qwen-2.5-72b-instruct`)
 - **Ollama**: All other models (e.g., `llama3.2`, `mistral`, `codellama`)
 
 You can also explicitly specify the vendor:
 
 ```ruby
 response = LlmConductor.generate(
-  model: 'llama3.2',  # Auto-detects Ollama for non-GPT models
+  model: 'llama-3.1-70b-versatile',
+  vendor: :groq,  # Explicitly use Groq
   prompt: 'Your prompt here'
 )
 ```
@@ -426,6 +481,8 @@ Check the `/examples` directory for comprehensive usage examples:
 - `prompt_registration.rb` - Custom prompt classes
 - `data_builder_usage.rb` - Data structuring patterns
 - `rag_usage.rb` - RAG implementation examples
+- `gemini_usage.rb` - Google Gemini integration
+- `groq_usage.rb` - Groq integration with various models
 
 ## Development
 

data/config/initializers/llm_conductor.rb

@@ -10,7 +10,8 @@ LlmConductor.configure do |config|
   config.timeout = 30
   config.max_retries = 3
   config.retry_delay = 1.0
-
+  # Use Ruby's built-in Logger class directly
+  config.logger = Logger.new($stdout)
   # Configure providers
   config.openai(
     api_key: ENV['OPENAI_API_KEY'],

data/examples/groq_usage.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'llm_conductor'
+
+# Configure Groq
+LlmConductor.configure do |config|
+  config.groq(api_key: ENV['GROQ_API_KEY'])
+end
+
+# Example 1: Using Groq with automatic model detection
+puts '=== Example 1: Automatic model detection ==='
+client = LlmConductor::ClientFactory.build(
+  model: 'llama-3.1-70b-versatile',
+  type: :summarize_text
+)
+
+data = {
+  text: 'Groq is a cloud-based AI platform that provides fast inference for large language models. ' \
+        'It offers various models including Llama, Mixtral, Gemma, and Qwen models with ' \
+        'optimized performance for production use cases.'
+}
+
+response = client.generate(data:)
+puts "Model: #{response.model}"
+puts "Vendor: #{response.metadata[:vendor]}"
+puts "Input tokens: #{response.input_tokens}"
+puts "Output tokens: #{response.output_tokens}"
+puts "Summary: #{response.output}"
+puts
+
+# Example 2: Using Groq with explicit vendor specification
+puts '=== Example 2: Explicit vendor specification ==='
+client = LlmConductor::ClientFactory.build(
+  model: 'mixtral-8x7b-32768',
+  type: :summarize_text,
+  vendor: :groq
+)
+
+response = client.generate(data:)
+puts "Model: #{response.model}"
+puts "Vendor: #{response.metadata[:vendor]}"
+puts "Summary: #{response.output}"
+puts
+
+# Example 3: Using Groq with simple generation
+puts '=== Example 3: Simple generation ==='
+client = LlmConductor::ClientFactory.build(
+  model: 'gemma-7b-it',
+  type: :summarize_text,
+  vendor: :groq
+)
+
+response = client.generate_simple(prompt: 'Explain what Groq is in one sentence.')
+puts "Model: #{response.model}"
+puts "Response: #{response.output}"
+puts
+
+# Example 4: Using different Groq models
+puts '=== Example 4: Different Groq models ==='
+models = [
+  'llama-3.1-70b-versatile',
+  'mixtral-8x7b-32768',
+  'gemma-7b-it',
+  'qwen-2.5-72b-instruct'
+]
+
+models.each do |model|
+  client = LlmConductor::ClientFactory.build(
+    model:,
+    type: :summarize_text,
+    vendor: :groq
+  )
+
+  response = client.generate_simple(prompt: 'What is artificial intelligence?')
+  puts "#{model}: #{response.output[0..100]}..."
+  puts
+end

data/lib/llm_conductor/client_factory.rb

@@ -18,14 +18,13 @@ module LlmConductor
         openrouter: Clients::OpenrouterClient,
         ollama: Clients::OllamaClient,
         gemini: Clients::GeminiClient,
-        google: Clients::GeminiClient
+        google: Clients::GeminiClient,
+        groq: Clients::GroqClient
       }
 
-      client_classes[vendor] || raise(
-        ArgumentError,
-        "Unsupported vendor: #{vendor}. " \
-        'Supported vendors: anthropic, openai, openrouter, ollama, gemini'
-      )
+      client_classes.fetch(vendor) do
+        raise ArgumentError, "Unsupported vendor: #{vendor}. Supported vendors: #{client_classes.keys.uniq.join(', ')}"
+      end
     end
 
     def self.determine_vendor(model)
@@ -36,6 +35,8 @@ module LlmConductor
         :openai
       when /^gemini/i
         :gemini
+      when /^(llama|mixtral|gemma|qwen)/i
+        :groq
       else
         :ollama # Default to Ollama for non-specific model names
       end

data/lib/llm_conductor/clients/base_client.rb

@@ -24,6 +24,12 @@ module LlmConductor
         output_text = generate_content(prompt)
         output_tokens = calculate_tokens(output_text || '')
 
+        # Logging AI request metadata if logger is set
+        configuration.logger&.debug(
+          "Vendor: #{vendor_name}, Model: #{@model} " \
+          "Output_tokens: #{output_tokens} Input_tokens: #{input_tokens}"
+        )
+
         build_response(output_text, input_tokens, output_tokens, { prompt: })
       rescue StandardError => e
         build_error_response(e)
@@ -35,6 +41,12 @@ module LlmConductor
         output_text = generate_content(prompt)
         output_tokens = calculate_tokens(output_text || '')
 
+        # Logging AI request metadata if logger is set
+        configuration.logger&.debug(
+          "Vendor: #{vendor_name}, Model: #{@model} " \
+          "Output_tokens: #{output_tokens} Input_tokens: #{input_tokens}"
+        )
+
         build_response(output_text, input_tokens, output_tokens)
       rescue StandardError => e
         build_error_response(e)
@@ -89,10 +101,18 @@ module LlmConductor
       # Build metadata for the response
       def build_metadata
         {
-          vendor: self.class.name.split('::').last.gsub('Client', '').downcase.to_sym,
+          vendor: vendor_name,
           timestamp: Time.now.utc.iso8601
         }
       end
+
+      def vendor_name
+        self.class.name.split('::').last.gsub('Client', '').downcase.to_sym
+      end
+
+      def configuration
+        LlmConductor.configuration
+      end
     end
   end
 end

data/lib/llm_conductor/clients/groq_client.rb

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

data/lib/llm_conductor/configuration.rb

@@ -4,7 +4,7 @@
 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_accessor :default_model, :default_vendor, :timeout, :max_retries, :retry_delay, :logger
     attr_reader :providers
 
     def initialize
@@ -14,6 +14,7 @@ module LlmConductor
       @timeout = 30
       @max_retries = 3
       @retry_delay = 1.0
+      @logger = nil
 
       # Provider configurations
       @providers = {}
@@ -63,6 +64,14 @@ module LlmConductor
       }
     end
 
+    # Configure Groq provider
+    def groq(api_key: nil, **options)
+      @providers[:groq] = {
+        api_key: api_key || ENV['GROQ_API_KEY'],
+        **options
+      }
+    end
+
     # Get provider configuration
     def provider_config(provider)
       @providers[provider.to_sym] || {}
@@ -109,6 +118,14 @@ module LlmConductor
       gemini(api_key: value)
     end
 
+    def groq_api_key
+      provider_config(:groq)[:api_key]
+    end
+
+    def groq_api_key=(value)
+      groq(api_key: value)
+    end
+
     private
 
     def setup_defaults_from_env
@@ -117,6 +134,7 @@ module LlmConductor
       openai if ENV['OPENAI_API_KEY']
       openrouter if ENV['OPENROUTER_API_KEY']
       gemini if ENV['GEMINI_API_KEY']
+      groq if ENV['GROQ_API_KEY']
       ollama # Always configure Ollama with default URL
     end
   end

data/lib/llm_conductor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmConductor
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/lib/llm_conductor.rb

@@ -10,13 +10,14 @@ require_relative 'llm_conductor/prompt_manager'
 require_relative 'llm_conductor/clients/base_client'
 require_relative 'llm_conductor/clients/anthropic_client'
 require_relative 'llm_conductor/clients/gpt_client'
+require_relative 'llm_conductor/clients/groq_client'
 require_relative 'llm_conductor/clients/ollama_client'
 require_relative 'llm_conductor/clients/openrouter_client'
 require_relative 'llm_conductor/clients/gemini_client'
 require_relative 'llm_conductor/client_factory'
 
 # LLM Conductor provides a unified interface for multiple Language Model providers
-# including OpenAI GPT, Anthropic Claude, Google Gemini, OpenRouter, and Ollama
+# including OpenAI GPT, Anthropic Claude, Google Gemini, Groq, OpenRouter, and Ollama
 # with built-in prompt templates, token counting, and extensible client architecture.
 module LlmConductor
   class Error < StandardError; end
@@ -61,16 +62,17 @@ module LlmConductor
       when :openrouter then Clients::OpenrouterClient
       when :ollama then Clients::OllamaClient
       when :gemini, :google then Clients::GeminiClient
+      when :groq then Clients::GroqClient
       else
         raise ArgumentError,
               "Unsupported vendor: #{vendor}. " \
-              'Supported vendors: anthropic, openai, openrouter, ollama, gemini'
+              'Supported vendors: anthropic, openai, openrouter, ollama, gemini, groq'
       end
     end
   end
 
   # List of supported vendors
-  SUPPORTED_VENDORS = %i[anthropic openai openrouter ollama gemini].freeze
+  SUPPORTED_VENDORS = %i[anthropic openai openrouter ollama gemini groq].freeze
 
   # List of supported prompt types
   SUPPORTED_PROMPT_TYPES = %i[

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: llm_conductor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ben Zheng
 bindir: exe
 cert_chain: []
-date: 2025-09-26 00:00:00.000000000 Z
+date: 2025-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.3'
+- !ruby/object:Gem::Dependency
+  name: groq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: ollama-ai
   requirement: !ruby/object:Gem::Requirement
@@ -122,24 +136,26 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.0'
 description: LLM Conductor provides a clean, unified interface for working with multiple
-  Language Model providers including OpenAI GPT, OpenRouter, and Ollama. Features
-  include prompt templating, token counting, and extensible client architecture.
+  Language Model providers including OpenAI GPT, Anthropic Claude, Google Gemini,
+  Groq, OpenRouter, and Ollama. Features include prompt templating, token counting,
+  and extensible client architecture.
 email:
 - ben@ekohe.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
 - ".rspec"
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - ".ruby-version"
+- LICENSE
 - README.md
 - Rakefile
 - config/initializers/llm_conductor.rb
 - examples/data_builder_usage.rb
 - examples/gemini_usage.rb
+- examples/groq_usage.rb
 - examples/prompt_registration.rb
 - examples/rag_usage.rb
 - examples/simple_usage.rb
@@ -149,6 +165,7 @@ files:
 - lib/llm_conductor/clients/base_client.rb
 - lib/llm_conductor/clients/gemini_client.rb
 - lib/llm_conductor/clients/gpt_client.rb
+- lib/llm_conductor/clients/groq_client.rb
 - lib/llm_conductor/clients/ollama_client.rb
 - lib/llm_conductor/clients/openrouter_client.rb
 - lib/llm_conductor/configuration.rb
@@ -160,7 +177,8 @@ files:
 - lib/llm_conductor/version.rb
 - sig/llm_conductor.rbs
 homepage: https://github.com/ekohe/llm_conductor
-licenses: []
+licenses:
+- MIT
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/ekohe/llm_conductor