ruby_llm-providers-lms 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e6ecf4144c152ba49e31f4d1456e5998bc28db598698619a0be7c53bb1d45f01
+  data.tar.gz: c76b3200ac422e1ef9ce27344071b98206e1a1f7017f7e3a03e4f26bf5a5d6d3
+SHA512:
+  metadata.gz: 669b63bf1a9f3685c4419620be7fcb3218007c2e6e620617f5852ae32a53a21f4b9ae7b4f77cc788c7c2e02265e71d0010ba399eae60392143254feecc857d8e
+  data.tar.gz: 919adff659f4c78b594c137a659074af4d35383201b0338e0163d4e5cc2402db3b72ec23e6eaefdcea0de7b60c23429f2223d5630a293512194297c5701d871d

data/.flayignore

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

data/.github/workflows/ci.yml

@@ -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/.github/workflows/gitleaks.yml

@@ -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/.github/workflows/release.yml

@@ -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 ruby_llm-providers-lms.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 ruby_llm-providers-lms-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}

data/.overcommit.yml

@@ -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/.rspec

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

data/.rubocop.yml

@@ -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/Archspec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'lib/**/*.rb'
+
+component :provider,
+          in: %w[
+            lib/ruby_llm/providers/lms.rb
+            lib/ruby_llm/providers/lms/**/*.rb
+          ],
+          namespace: 'RubyLLM::Providers::LMS'
+
+provider.cannot_reference_constants 'RSpec', 'WebMock', 'VCR'
+
+preset :ruby_conventions

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 madbomber
+
+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

@@ -0,0 +1,87 @@
+# ruby_llm-providers-lms
+
+[RubyLLM](https://rubyllm.com) provider gem for [LM Studio](https://lmstudio.ai) — run
+local models through LM Studio's OpenAI-compatible server (`lms server start`,
+`http://localhost:1234/v1` by default).
+
+The provider works out of the box: no API key, no configuration. It speaks the
+Chat Completions dialect by default and also registers the Responses protocol
+(LM Studio serves `/v1/responses` too). Model listings are enriched with details
+from LM Studio's native REST API (`/api/v0/models`): architecture, quantization,
+load state, context length, and tool/vision capabilities.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-providers-lms', require: 'ruby_llm/providers/lms'
+```
+
+Configuration is optional. Override the defaults only when your server is not
+on `http://localhost:1234/v1` or sits behind an auth proxy:
+
+```ruby
+require 'ruby_llm/providers/lms'
+
+RubyLLM.configure do |config|
+  config.lms_api_base = ENV.fetch('LMS_API_BASE', 'http://localhost:1234/v1')
+  config.lms_api_key = ENV['LMS_API_KEY'] # only if your server requires auth
+end
+```
+
+## Usage
+
+Use the model identifier shown in LM Studio (not an OpenAI model name):
+
+```ruby
+chat = RubyLLM.chat(model: 'qwen/qwen3-4b', provider: :lms)
+response = chat.ask('Hello')
+puts response.content
+```
+
+Because LM Studio is a local provider, RubyLLM assumes any model id you pass
+exists — LM Studio will just-in-time load the model if it isn't loaded yet.
+To browse what the server offers:
+
+```ruby
+RubyLLM.models.refresh!
+RubyLLM.models.by_provider(:lms).each { |model| puts model.id }
+```
+
+Embeddings work the same way:
+
+```ruby
+RubyLLM.embed('Hello world', model: 'text-embedding-nomic-embed-text-v1.5', provider: :lms)
+```
+
+To use the Responses dialect instead of Chat Completions:
+
+```ruby
+RubyLLM.configure { |config| config.lms_protocol = :responses }
+```
+
+## Development
+
+Start the LM Studio server (`lms server start`), then:
+
+```sh
+bundle exec rake models   # refresh models.json from your local server
+bundle exec rake          # rubocop, flay, archspec, specs
+```
+
+`rake models` calls the local server's model-listing endpoints and writes
+`models.json` at the gem root. RubyLLM loads that catalog as a fallback when
+this provider is registered. Since LM Studio catalogs are machine-specific
+(they list whatever you have downloaded), the packaged catalog is only a
+sample — live listings via `RubyLLM.models.refresh!` reflect your machine.
+
+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, put real model IDs from your machine into
+`spec/support/models.rb`. Keep only the operation matrices LM Studio supports
+(chat, tools, structured output, embeddings). The portable contract specs are
+adapted from [RubyLLM's live specs](https://github.com/crmne/ruby_llm/tree/main/spec/ruby_llm).

data/lib/ruby_llm/providers/lms/models.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class LMS < Provider
+      # Model-listing methods for the LM Studio API integration.
+      # Enriches the OpenAI-compatible /v1/models listing with details from
+      # LM Studio's native REST API (/api/v0/models): model type, architecture,
+      # quantization, load state, and context length. The native endpoint is
+      # optional — when it is unavailable the plain listing still works.
+      module Models
+        NATIVE_MODELS_URL = '../api/v0/models'
+        CAPABILITY_MAP = {
+          'tool_use' => 'function_calling',
+          'vision' => 'vision'
+        }.freeze
+
+        def models_url
+          'models'
+        end
+
+        def model_capabilities
+          %w[streaming structured_output]
+        end
+
+        def list_models
+          response = @connection.get models_url
+          parse_list_models_response(response, @provider.slug, details: native_model_details)
+        end
+
+        def parse_list_models_response(response, slug, details: {})
+          Array(response.body['data']).map do |model|
+            detail = details[model['id']] || {}
+            Model.new(
+              id: model['id'],
+              name: model['id'],
+              provider: slug,
+              family: detail['arch'] || 'lms',
+              created_at: model['created'] ? Time.at(model['created']) : nil,
+              context_window: detail['max_context_length'],
+              modalities: build_modalities(detail),
+              capabilities: build_capabilities(detail),
+              pricing: {},
+              metadata: build_metadata(model, detail)
+            )
+          end
+        end
+
+        def build_modalities(detail)
+          return { input: %w[text], output: %w[embeddings] } if embedding?(detail)
+
+          input = %w[text]
+          input << 'image' if vision?(detail)
+          { input: input, output: %w[text] }
+        end
+
+        def build_capabilities(detail)
+          return [] if embedding?(detail)
+
+          reported = Array(detail['capabilities'])
+          derived = CAPABILITY_MAP.filter_map { |native, capability| capability if reported.include?(native) }
+          derived << 'vision' if vision?(detail) && !derived.include?('vision')
+          model_capabilities + derived
+        end
+
+        def build_metadata(model, detail)
+          {
+            owned_by: model['owned_by'],
+            publisher: detail['publisher'],
+            arch: detail['arch'],
+            compatibility_type: detail['compatibility_type'],
+            quantization: detail['quantization'],
+            state: detail['state']
+          }.compact
+        end
+
+        def embedding?(detail)
+          detail['type'] == 'embeddings'
+        end
+
+        def vision?(detail)
+          detail['type'] == 'vlm' || Array(detail['capabilities']).include?('vision')
+        end
+
+        private
+
+        def native_model_details
+          Array(@connection.get(NATIVE_MODELS_URL).body['data']).to_h { |detail| [detail['id'], detail] }
+        rescue Error, Faraday::Error => e
+          RubyLLM.logger.debug "LM Studio native model details unavailable (#{e.message})."
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/lms.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require 'ruby_llm/providers/lms/models'
+
+module RubyLLM
+  module Providers
+    # LM Studio API integration. Talks to the local LM Studio server
+    # (`lms server start`) through its OpenAI-compatible endpoints.
+    # Works out of the box against http://localhost:1234/v1 — no API key
+    # required.
+    class LMS < Provider
+      DEFAULT_API_BASE = 'http://localhost:1234/v1'
+
+      # LM Studio's dialect of the Chat Completions API.
+      class ChatCompletions < Protocols::ChatCompletions
+        include LMS::Models
+      end
+
+      protocol :chat_completions, ChatCompletions
+      protocol :responses, Protocols::Responses
+
+      def api_base
+        @config.lms_api_base || DEFAULT_API_BASE
+      end
+
+      def headers
+        return {} unless @config.lms_api_key
+
+        { 'Authorization' => "Bearer #{@config.lms_api_key}" }
+      end
+
+      class << self
+        def display_name
+          'LM Studio'
+        end
+
+        def configuration_options
+          %i[lms_api_base lms_api_key]
+        end
+
+        def configuration_requirements
+          []
+        end
+
+        def local?
+          true
+        end
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :lms, RubyLLM::Providers::LMS,
+                           models: File.expand_path('../../../models.json', __dir__)