ruby_llm 1.16.0 → 2.0.0.rc2

data/lib/generators/ruby_llm/provider/templates/gem/chat_streaming_spec.rb.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Chat, :live do
+  include_context 'with configured RubyLLM'
+
+  each_model(CHAT_MODELS) do |provider, model|
+    it "#{provider}/#{model} supports streaming responses" do
+      chunks = []
+      chat = RubyLLM.chat(model: model, provider: provider, assume_model_exists: true)
+
+      response = chat.ask('Count from 1 to 3') { |chunk| chunks << chunk }
+
+      expect(chunks).not_to be_empty
+      expect(chunks.first).to be_a(RubyLLM::Chunk)
+      expect(response.raw.status).to eq(200)
+      expect(response.raw.headers).not_to be_empty
+      expect(response.raw.env.request_body).not_to be_empty
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/chat_tools_spec.rb.erb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Chat, :live do
+  include_context 'with configured RubyLLM'
+
+  let(:weather_tool) do
+    Class.new(RubyLLM::Tool) do
+      description 'Gets current weather for a location'
+      parameter :latitude, description: 'Latitude'
+      parameter :longitude, description: 'Longitude'
+
+      def execute(latitude:, longitude:)
+        "Current weather at #{latitude}, #{longitude}: 15°C, Wind: 10 km/h"
+      end
+    end
+  end
+
+  each_model(TOOL_MODELS) do |provider, model|
+    it "#{provider}/#{model} can use tools" do
+      chat = RubyLLM.chat(model: model, provider: provider, assume_model_exists: true).with_tools(weather_tool)
+      response = chat.ask("What's the weather in Berlin? Use 52.5200, 13.4050.")
+
+      expect(response.content).to include('15')
+      expect(response.content).to include('10')
+      expect(chat.messages.any?(&:tool_call?)).to be(true)
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/ci.yml.erb

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.1", "3.2", "3.3", "3.4", "4.0"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - run: bundle exec rake
+        if: matrix.ruby-version != '3.1'
+
+      - run: bundle exec rake rubocop flay spec
+        if: matrix.ruby-version == '3.1'

data/lib/generators/ruby_llm/provider/templates/gem/embedding_spec.rb.erb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Embedding, :live do
+  include_context 'with configured RubyLLM'
+
+  each_model(EMBEDDING_MODELS) do |provider, model, model_info|
+    it "#{provider}/#{model} embeds one text" do
+      embedding = RubyLLM.embed(
+        "Ruby is a programmer's best friend",
+        model: model,
+        provider: provider,
+        assume_model_exists: true
+      )
+
+      expect(embedding.vectors).to be_an(Array)
+      expect(embedding.vectors.first).to be_a(Numeric)
+      expect(embedding.model).to eq(model)
+      expect(embedding.tokens.input.to_i).to be >= 0
+    end
+
+    it "#{provider}/#{model} embeds several texts" do
+      embeddings = RubyLLM.embed(
+        %w[Ruby Python JavaScript],
+        model: model,
+        provider: provider,
+        assume_model_exists: true
+      )
+
+      expect(embeddings.vectors.size).to eq(3)
+      expect(embeddings.vectors).to all(be_an(Array))
+    end
+
+    next unless model_info[:dimensions]
+
+    it "#{provider}/#{model} supports custom dimensions" do
+      embedding = RubyLLM.embed(
+        'Ruby',
+        model: model,
+        provider: provider,
+        assume_model_exists: true,
+        dimensions: model_info[:dimensions]
+      )
+
+      expect(embedding.vectors.length).to eq(model_info[:dimensions])
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/env.erb

@@ -0,0 +1,2 @@
+<%= api_key_env %>=$(op read "op://RubyLLM/<%= class_name %>/credential")
+<%= api_base_env %>=<%= api_base %>

data/lib/generators/ruby_llm/provider/templates/gem/fixtures_gitkeep.erb

@@ -0,0 +1 @@
+

data/lib/generators/ruby_llm/provider/templates/gem/flayignore.erb

@@ -0,0 +1 @@
+spec/support/streaming_error_helpers.rb

data/lib/generators/ruby_llm/provider/templates/gem/gemfile.erb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'archspec' if RUBY_ENGINE == 'ruby' && Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.2')
+  gem 'bundler', '>= 2.0'
+  gem 'dotenv'
+  gem 'flay'
+  gem 'irb'
+  gem 'overcommit', '>= 0.66'
+  gem 'pry', '>= 0.14'
+  gem 'rake', '>= 13.0'
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '>= 1.0'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake', '>= 0.6'
+  gem 'rubocop-rspec'
+  gem 'vcr'
+  gem 'webmock', '~> 3.18'
+end

data/lib/generators/ruby_llm/provider/templates/gem/gemspec.erb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = '<%= gem_name %>'
+  spec.version = '0.1.0'
+  spec.authors = ['<%= github_owner %>']
+  spec.email = ['maintainers@example.com']
+
+  spec.summary = 'RubyLLM provider for <%= class_name %>.'
+  spec.description = 'Adds <%= class_name %> provider support to RubyLLM.'
+  spec.homepage = 'https://github.com/<%= github_owner %>/<%= gem_name %>'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/releases"
+  spec.metadata['bug_tracker_uri'] = "#{spec.homepage}/issues"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.glob('{lib,spec}/**/*') +
+               Dir.glob('.github/workflows/*.yml') +
+               Dir.glob('models.json') +
+               %w[.flayignore .overcommit.yml .rspec .rubocop.yml Archspec.rb LICENSE README.md]
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'ruby_llm', '>= 2.0.0.rc1'
+end

data/lib/generators/ruby_llm/provider/templates/gem/gitignore.erb

@@ -0,0 +1,7 @@
+/.bundle/
+/.yardoc
+/doc/
+/pkg/
+/tmp/
+*.gem
+.env

data/lib/generators/ruby_llm/provider/templates/gem/gitleaks.yml.erb

@@ -0,0 +1,22 @@
+name: Gitleaks
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

data/lib/generators/ruby_llm/provider/templates/gem/image_spec.rb.erb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Image, :live do
+  include_context 'with configured RubyLLM'
+
+  each_model(IMAGE_GENERATION_MODELS) do |provider, model, model_info|
+    it "#{provider}/#{model} paints an image" do
+      image = RubyLLM.paint(
+        'a siamese cat',
+        model: model,
+        provider: provider,
+        assume_model_exists: true,
+        provider_options: model_info.fetch(:provider_options, {})
+      )
+
+      expect(image.mime_type).to include('image')
+      expect(image.model).to eq(model)
+      expect(image.to_blob.bytesize).to be > 1000
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/license.erb

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) <%= Time.now.year %> <%= github_owner %>
+
+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/lib/generators/ruby_llm/provider/templates/gem/models.rb.erb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Remove chat-derived matrices the model does not support and add real ids for the empty operation matrices.
+# See RubyLLM's full live matrix and specs: https://github.com/crmne/ruby_llm/tree/main/spec
+PROVIDER = :<%= slug %>
+CHAT_MODELS = [].freeze
+TOOL_MODELS = CHAT_MODELS
+STRUCTURED_OUTPUT_MODELS = CHAT_MODELS
+
+EMBEDDING_MODELS = [].freeze
+IMAGE_GENERATION_MODELS = [].freeze
+SPEECH_MODELS = [].freeze
+VIDEO_GENERATION_MODELS = [].freeze
+MODERATION_MODELS = [].freeze
+RERANK_MODELS = [].freeze
+
+def each_model(models)
+  models.each { |model_info| yield model_info[:provider], model_info[:model], model_info }
+end

data/lib/generators/ruby_llm/provider/templates/gem/models_spec.rb.erb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Models do
+  include_context 'with configured RubyLLM'
+
+<% if dynamic_models? -%>
+  it 'allows provider model ids that are missing from the registry' do
+    expect(RubyLLM::Providers::<%= class_name %>.assume_models_exist?).to be(true)
+  end
+<% else -%>
+  it 'expects generated providers to add registry metadata before use' do
+    expect(RubyLLM::Providers::<%= class_name %>.assume_models_exist?).to be(false)
+  end
+<% end -%>
+end

data/lib/generators/ruby_llm/provider/templates/gem/moderation_spec.rb.erb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Moderation, :live do
+  include_context 'with configured RubyLLM'
+
+  each_model(MODERATION_MODELS) do |provider, model|
+    it "#{provider}/#{model} moderates content" do
+      moderation = RubyLLM.moderate(
+        'This is a safe message',
+        model: model,
+        provider: provider,
+        assume_model_exists: true
+      )
+
+      expect(moderation).to be_a(described_class)
+      expect(moderation.results).to all(be_a(RubyLLM::Moderation::Result))
+      expect(moderation.flagged?).to be_in([true, false])
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/overcommit.yml.erb

@@ -0,0 +1,31 @@
+PreCommit:
+  RuboCop:
+    enabled: true
+    auto_correct: true
+    on_warn: fail
+
+  Flay:
+    enabled: true
+    include:
+      - lib/**/*.rb
+      - spec/**/*.rb
+    mass_threshold: 70
+
+  ArchSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'archspec', 'check']
+    on_warn: fail
+
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']
+    on_warn: fail
+
+  TrailingWhitespace:
+    enabled: true
+    auto_correct: true
+
+  Gitleaks:
+    enabled: true
+    required_executable: gitleaks
+    command: ['gitleaks', 'protect', '--staged', '--redact', '--verbose']

data/lib/generators/ruby_llm/provider/templates/gem/provider.rb.erb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module RubyLLM
+  module Providers
+    # <%= provider_description %>
+    class <%= class_name %> < Provider
+      # <%= class_name %>'s <%= protocol_class_name %> protocol.
+      class <%= protocol_class_name %> < <%= protocol_superclass %>
+        def models_url
+          'models'
+        end
+      end
+
+      protocol :<%= protocol_name %>, <%= protocol_class_name %>
+
+      def api_base
+        @config.<%= api_base_config %> || '<%= api_base %>'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.<%= api_key_config %>}" }
+      end
+
+      class << self
+        def configuration_options
+          %i[<%= api_key_config %> <%= api_base_config %>]
+        end
+
+        def configuration_requirements
+          %i[<%= api_key_config %>]
+        end
+<% if dynamic_models? -%>
+
+        def assume_models_exist?
+          true
+        end
+<% else -%>
+
+        # Use this only when the provider has no model-listing endpoint.
+        # def assume_models_exist?
+        #   true
+        # end
+<% end -%>
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :<%= slug %>, RubyLLM::Providers::<%= class_name %>,
+                           models: File.expand_path('../../../models.json', __dir__)

data/lib/generators/ruby_llm/provider/templates/gem/provider_spec.rb.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Providers::<%= class_name %> do
+  subject(:provider) { described_class.new(config) }
+
+  let(:config) do
+    RubyLLM::Configuration.new.tap do |provider_config|
+      provider_config.<%= api_key_config %> = 'test-key'
+      provider_config.<%= api_base_config %> = 'https://example.test/v1'
+    end
+  end
+
+  it 'is registered with RubyLLM' do
+    expect(RubyLLM::Provider.resolve(:<%= slug %>)).to eq(described_class)
+  end
+
+  it 'registers a default protocol' do
+    expect(described_class.protocols).to include(<%= "#{protocol_name}:" %> described_class::<%= protocol_class_name %>)
+  end
+
+  it 'declares provider configuration' do
+    expect(described_class.configuration_options).to eq(%i[<%= api_key_config %> <%= api_base_config %>])
+    expect(described_class.configuration_requirements).to eq(%i[<%= api_key_config %>])
+  end
+
+  it 'uses configured API base and bearer token' do
+    expect(provider.api_base).to eq('https://example.test/v1')
+    expect(provider.headers).to eq('Authorization' => 'Bearer test-key')
+  end
+<% if dynamic_models? -%>
+
+  it 'allows provider model ids missing from the registry' do
+    expect(described_class.assume_models_exist?).to be(true)
+  end
+<% end -%>
+end

data/lib/generators/ruby_llm/provider/templates/gem/rakefile.erb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+
+desc 'Refresh the <%= class_name %> model catalog'
+task :models do
+  require 'dotenv/load'
+  require_relative 'lib/ruby_llm/providers/<%= slug %>'
+
+  RubyLLM.configure do |config|
+    config.<%= api_key_config %> = ENV.fetch('<%= api_key_env %>', nil)
+    config.<%= api_base_config %> = ENV.fetch('<%= api_base_env %>', '<%= api_base %>')
+  end
+
+  provider = RubyLLM::Provider.resolve!(:<%= slug %>).new(RubyLLM.config)
+  models = provider.list_models
+  abort '<%= class_name %> returned no models' if models.empty?
+
+  RubyLLM::Models.new(models).save_to_json(File.expand_path('models.json', __dir__))
+end
+
+desc 'Run Flay duplicate detection'
+task :flay do
+  sh 'bundle exec flay --mass 70 lib spec'
+end
+
+desc 'Run ArchSpec architecture checks'
+task :archspec do
+  sh 'bundle exec archspec check'
+end
+
+task default: %i[rubocop flay archspec spec]

data/lib/generators/ruby_llm/provider/templates/gem/readme.md.erb

@@ -0,0 +1,50 @@
+# <%= gem_name %>
+
+RubyLLM provider gem for <%= class_name %>.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem '<%= gem_name %>', require: '<%= require_path %>'
+```
+
+Then configure the provider:
+
+```ruby
+require '<%= require_path %>'
+
+RubyLLM.configure do |config|
+  config.<%= api_key_config %> = ENV['<%= api_key_env %>']
+  config.<%= api_base_config %> = ENV.fetch('<%= api_base_env %>', '<%= api_base %>')
+end
+```
+
+## Usage
+
+```ruby
+model = RubyLLM.models.by_provider(:<%= slug %>).chat_models.first
+chat = RubyLLM.chat(model: model.id)
+response = chat.ask('Hello')
+puts response.content
+```
+
+## Development
+
+The generator installs the bundle and creates an ignored `.env`. Edit the generated `op read` reference so it points to your 1Password credential. If you do not use the 1Password CLI, replace the expression with the provider key.
+
+```sh
+bundle exec rake models
+bundle exec rake
+```
+
+`rake models` calls only <%= class_name %>'s model-listing endpoint and writes `models.json` at the gem root. RubyLLM loads that catalog as a fallback when this provider is registered, so applications do not need to combine registry files. The main RubyLLM registry always wins when both catalogs carry the same model. If the API uses a different path, change `models_url` in `lib/ruby_llm/providers/<%= slug %>.rb`.
+
+Run `rake models` from this provider gem when you want to update its packaged catalog. `RubyLLM.models.refresh` updates the application's main registry and does not refresh provider gem catalogs.
+
+If the provider has no model-listing endpoint, uncomment `assume_models_exist?` in the provider and do not run `rake models`.
+
+The suite always runs the provider integration specs. The first local run calls the API and records VCR cassettes; CI only replays committed cassettes. A failing example deletes its cassette so the next local run tests the live API again.
+
+After refreshing the catalog, add real model IDs to `spec/support/models.rb`. Keep only the operation matrices the provider supports. The portable contract specs are adapted from [RubyLLM's live specs](https://github.com/crmne/ruby_llm/tree/main/spec/ruby_llm); use those as the reference when your provider needs coverage for another feature or dialect.

data/lib/generators/ruby_llm/provider/templates/gem/release.yml.erb

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - run: bundle exec rake
+
+      - name: Build gem
+        run: gem build <%= gem_name %>.gemspec
+
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p "$HOME/.gem"
+          touch "$HOME/.gem/credentials"
+          chmod 0600 "$HOME/.gem/credentials"
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > "$HOME/.gem/credentials"
+          gem push <%= gem_name %>-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}

data/lib/generators/ruby_llm/provider/templates/gem/rerank_spec.rb.erb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Rerank, :live do
+  include_context 'with configured RubyLLM'
+
+  each_model(RERANK_MODELS) do |provider, model|
+    it "#{provider}/#{model} orders documents by relevance" do
+      rerank = RubyLLM.rerank(
+        'What is the capital of the United States?',
+        ['Carson City is the capital of Nevada.', 'Washington, D.C. is the capital of the United States.'],
+        model: model,
+        provider: provider,
+        assume_model_exists: true
+      )
+
+      expect(rerank.results.first.document).to include('Washington')
+      expect(rerank.results.first.score).to be > rerank.results.last.score
+      expect(rerank.results.map(&:index)).to contain_exactly(0, 1)
+    end
+  end
+end

data/lib/generators/ruby_llm/provider/templates/gem/rspec.erb

@@ -0,0 +1,2 @@
+--require spec_helper
+--format progress

data/lib/generators/ruby_llm/provider/templates/gem/rubocop.yml.erb

@@ -0,0 +1,29 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  Exclude:
+    - Archspec.rb
+    - vendor/**/*
+    - gemfiles/**/*
+  SuggestExtensions: false
+
+Metrics/AbcSize:
+  Max: 80
+Metrics/MethodLength:
+  Max: 40
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false

data/lib/generators/ruby_llm/provider/templates/gem/rubyllm_configuration.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+RSpec.shared_context 'with configured RubyLLM' do
+  before do
+    RubyLLM.configure do |config|
+      config.<%= api_key_config %> = ENV.fetch('<%= api_key_env %>', 'test')
+      config.<%= api_base_config %> = ENV.fetch('<%= api_base_env %>', '<%= api_base %>')
+      config.max_retries = 0
+      config.retry_backoff_factor = 0
+      config.retry_interval = 0
+      config.retry_interval_randomness = 0
+    end
+  end
+end