Project

llm_conductor

0.0
The project is in a healthy, maintained state
llm_conductorekohe/llm_conductorHomepageDocumentationSource CodeBug Tracker
LLM Conductor provides a clean, unified interface for working with multiple Language Model providers including OpenAI GPT, Anthropic Claude, Google Gemini, Groq, OpenRouter, and Ollama. Features include prompt templating, token counting, and extensible client architecture.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
2,733
Stars
16
Forks
0
Watchers
0
 Releases
Current version
1.5.0
Total releases
12
First release
2025-09-19
Latest release
2025-12-12
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2025-10-26
Reverse Dependencies
0

 Dependencies

Development

rubocop-performance
~> 1.19
rubocop-rspec
~> 3.0

Runtime

activesupport
>= 6.0
ollama-ai
~> 1.3
ruby-openai
~> 7.0
tiktoken_ruby
~> 0.0.7
anthropic
~> 1.7
gemini-ai
~> 4.3
groq
~> 0.3
 Project Readme

LLM Conductor

A unified Ruby interface for multiple Language Model providers from Ekohe. Seamlessly integrate OpenAI GPT, Anthropic Claude, Google Gemini, Groq, Ollama, OpenRouter, and Z.ai (Zhipu AI) with a single, consistent API.

Features

  • 🚀 Multi-Provider Support - 7+ LLM providers with automatic vendor detection
  • 🎯 Unified API - Same interface across all providers
  • 🖼️ Vision Support - Send images alongside text (OpenAI, Anthropic, OpenRouter, Z.ai, Gemini)
  • 🔧 Custom Parameters - Fine-tune with temperature, top_p, and more
  • 💰 Cost Tracking - Automatic token counting and cost estimation
  • ⚡ Smart Configuration - Environment variables or code-based setup

Installation

gem 'llm_conductor'
bundle install

Quick Start

1. Simple Generation

require 'llm_conductor'

# Set up your API key (or use ENV variables)
LlmConductor.configure do |config|
  config.openai(api_key: 'your-api-key')
end

# Generate text
response = LlmConductor.generate(
  model: 'gpt-4o-mini',
  prompt: 'Explain quantum computing in simple terms'
)

puts response.output           # Generated text
puts response.total_tokens     # Token count
puts response.estimated_cost   # Cost in USD

2. With Custom Parameters

# Control creativity with temperature
response = LlmConductor.generate(
  model: 'llama2',
  prompt: 'Write a creative story',
  vendor: :ollama,
  params: { temperature: 0.9 }
)

3. Vision/Multimodal

# Send images with your prompt
response = LlmConductor.generate(
  model: 'gpt-4o',
  prompt: {
    text: 'What is in this image?',
    images: ['https://example.com/image.jpg']
  }
)

Configuration

Environment Variables (Easiest)

Set these environment variables and the gem auto-configures:

export OPENAI_API_KEY=your-key-here
export ANTHROPIC_API_KEY=your-key-here
export GEMINI_API_KEY=your-key-here
export GROQ_API_KEY=your-key-here
export OLLAMA_ADDRESS=http://localhost:11434  # Optional
export OPENROUTER_API_KEY=your-key-here
export ZAI_API_KEY=your-key-here

Code Configuration

LlmConductor.configure do |config|
  config.default_model = 'gpt-4o-mini'
  
  config.openai(api_key: ENV['OPENAI_API_KEY'])
  config.anthropic(api_key: ENV['ANTHROPIC_API_KEY'])
  config.gemini(api_key: ENV['GEMINI_API_KEY'])
  config.groq(api_key: ENV['GROQ_API_KEY'])
  config.ollama(base_url: 'http://localhost:11434')
  config.openrouter(api_key: ENV['OPENROUTER_API_KEY'])
  config.zai(api_key: ENV['ZAI_API_KEY'])
end

Supported Providers

Provider Auto-Detect Vision Custom Params
OpenAI (GPT) ✅ gpt-* ✅ 🔜
Anthropic (Claude) ✅ claude-* ✅ 🔜
Google (Gemini) ✅ gemini-* ✅ 🔜
Groq ✅ llama/mixtral ❌ 🔜
Ollama ✅ (default) ❌ ✅
OpenRouter 🔧 Manual ✅ 🔜
Z.ai (Zhipu) ✅ glm-* ✅ 🔜

Common Use Cases

Simple Q&A

response = LlmConductor.generate(
  model: 'gpt-4o-mini',
  prompt: 'What is Ruby programming language?'
)

Content Summarization

response = LlmConductor.generate(
  model: 'claude-3-5-sonnet-20241022',
  type: :summarize_text,
  data: {
    text: 'Long article content here...',
    max_length: '100 words',
    style: 'professional'
  }
)

Deterministic Output (Testing)

response = LlmConductor.generate(
  model: 'llama2',
  prompt: 'Extract email addresses from: contact@example.com',
  vendor: :ollama,
  params: { temperature: 0.0, seed: 42 }
)

Vision Analysis

response = LlmConductor.generate(
  model: 'gpt-4o',
  prompt: {
    text: 'Describe this image in detail',
    images: [
      'https://example.com/photo.jpg',
      'https://example.com/diagram.png'
    ]
  }
)

Response Object

response = LlmConductor.generate(...)

response.output           # String - Generated text
response.success?         # Boolean - Success status
response.model            # String - Model used
response.input_tokens     # Integer - Input token count
response.output_tokens    # Integer - Output token count
response.total_tokens     # Integer - Total tokens
response.estimated_cost   # Float - Cost in USD (if available)
response.metadata         # Hash - Additional info

# Parse JSON responses
response.parse_json       # Hash - Parsed JSON output

# Extract code blocks
response.extract_code_block('ruby')  # String - Code content

Advanced Features

Custom Prompt Classes

Create reusable, testable prompt templates:

class AnalysisPrompt < LlmConductor::Prompts::BasePrompt
  def render
    <<~PROMPT
      Analyze: #{title}
      Content: #{truncate_text(content, max_length: 500)}
      
      Provide insights in JSON format.
    PROMPT
  end
end

# Register and use
LlmConductor::PromptManager.register(:analyze, AnalysisPrompt)

response = LlmConductor.generate(
  model: 'gpt-4o-mini',
  type: :analyze,
  data: { title: 'Article', content: '...' }
)

Data Builder Pattern

Structure complex data for LLM consumption:

class CompanyDataBuilder < LlmConductor::DataBuilder
  def build
    {
      name: source_object.name,
      description: format_for_llm(source_object.description, max_length: 500),
      metrics: build_metrics,
      summary: build_company_summary
    }
  end
  
  private
  
  def build_metrics
    {
      employees: format_number(source_object.employee_count),
      revenue: format_number(source_object.annual_revenue, format: :currency)
    }
  end
end

Error Handling

response = LlmConductor.generate(...)

if response.success?
  puts response.output
else
  puts "Error: #{response.metadata[:error]}"
  puts "Error class: #{response.metadata[:error_class]}"
end

Documentation

Examples

Check the examples/ directory for comprehensive examples:

  • simple_usage.rb - Basic text generation
  • ollama_params_usage.rb - Custom parameters with Ollama
  • gpt_vision_usage.rb - Vision with OpenAI
  • claude_vision_usage.rb - Vision with Anthropic
  • gemini_vision_usage.rb - Vision with Gemini
  • openrouter_vision_usage.rb - Vision with OpenRouter
  • zai_usage.rb - Using Z.ai GLM models
  • data_builder_usage.rb - Data builder patterns
  • prompt_registration.rb - Custom prompt classes
  • rag_usage.rb - Retrieval-Augmented Generation

Run any example:

ruby examples/simple_usage.rb

Development

# Clone and setup
git clone https://github.com/ekohe/llm-conductor.git
cd llm-conductor
bundle install

# Run tests
bundle exec rspec

# Run linter
bundle exec rubocop

# Interactive console
bin/console

Contributing

  1. Fork it
  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 new Pull Request

Ensure tests pass and RuboCop is clean before submitting.

License

The gem is available as open source under the terms of the MIT License.

Credits

Developed with ❤️ by Ekohe - Making AI practical, achievable, and useful.