ruby_llm-providers-lms 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e6ecf4144c152ba49e31f4d1456e5998bc28db598698619a0be7c53bb1d45f01
-  data.tar.gz: c76b3200ac422e1ef9ce27344071b98206e1a1f7017f7e3a03e4f26bf5a5d6d3
+  metadata.gz: cdaf33f5245f3b78bcfd33a13c7f2a0838149de0998b09c7f8e4256e447cda69
+  data.tar.gz: 285c1c5ddff4227b90b435755b8cc29b1a28bb695fa33c7f1c6510ce3a5853cb
 SHA512:
-  metadata.gz: 669b63bf1a9f3685c4419620be7fcb3218007c2e6e620617f5852ae32a53a21f4b9ae7b4f77cc788c7c2e02265e71d0010ba399eae60392143254feecc857d8e
-  data.tar.gz: 919adff659f4c78b594c137a659074af4d35383201b0338e0163d4e5cc2402db3b72ec23e6eaefdcea0de7b60c23429f2223d5630a293512194297c5701d871d
+  metadata.gz: 548a88a50a88795f9b5b7cd11c64ee1c43e76406c7730c34c42cf90bf2e748eded77029f38f9994f5ab8820a05d7e0479118e8a43f3dbb165a3bc11e0297a892
+  data.tar.gz: d01419d61951513cc00dcd72e546f7a56e2023fa59ff1bcadc99e0b117f1bdfab6b06c541078b0a984dede41f025e9668fd00921086b3163c5590654d1d99bc2

data/.github/workflows/ci.yml

@@ -16,7 +16,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        ruby-version: ["3.1", "3.2", "3.3", "3.4", "4.0"]
+        # Non-EOL Rubies only; must match the gemspec's required_ruby_version.
+        ruby-version: ["3.3", "3.4", "4.0"]
     steps:
       - uses: actions/checkout@v6
 
@@ -26,7 +27,3 @@ jobs:
           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/.rubocop.yml

@@ -5,7 +5,7 @@ plugins:
 
 AllCops:
   NewCops: enable
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.3
   Exclude:
     - Archspec.rb
     - vendor/**/*

data/README.md

@@ -40,15 +40,50 @@ response = chat.ask('Hello')
 puts response.content
 ```
 
+If the server isn't running, requests raise a `RubyLLM::Error` telling you to
+start it (`lms server start`) instead of a raw connection failure.
+
 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:
+To browse what the server offers right now, ask the provider directly:
 
 ```ruby
-RubyLLM.models.refresh!
-RubyLLM.models.by_provider(:lms).each { |model| puts model.id }
+provider = RubyLLM::Provider.resolve!(:lms).new(RubyLLM.config)
+provider.list_models.each { |model| puts model.id }
 ```
 
+## The model catalog (models.json)
+
+The gem ships a `models.json` at its root. **This file is only a sample**,
+recorded from the author's machine: LM Studio serves whatever models *you*
+have downloaded, so your catalog will be different. RubyLLM loads the shipped
+file as the provider's model registry so `RubyLLM.models` has something to
+show.
+
+Note that `RubyLLM.models.refresh` does **not** query your LM Studio server:
+provider gems that ship a registry file are excluded from the live fetch, and
+refresh just re-reads the registered `models.json`. Your live server is still
+the source of truth, reached differently depending on what you need:
+
+- **Chatting** needs no catalog at all — any model id LM Studio knows will
+  work (see above).
+- **Browsing what your server offers** is `provider.list_models` (see the
+  snippet above), which hits the live endpoints every time.
+- **Making `RubyLLM.models` reflect your machine** means registering your own
+  catalog file in place of the shipped sample:
+
+  ```ruby
+  require 'ruby_llm/providers/lms'
+
+  provider = RubyLLM::Provider.resolve!(:lms).new(RubyLLM.config)
+  RubyLLM::Models.new(provider.list_models).save_to_json('my_models.json')
+  RubyLLM::Provider.register :lms, RubyLLM::Providers::LMS, models: 'my_models.json'
+  RubyLLM.models.refresh
+  ```
+
+Don't edit the `models.json` inside the installed gem — it is overwritten on
+every gem update; re-register with your own file instead.
+
 Embeddings work the same way:
 
 ```ruby
@@ -61,6 +96,99 @@ To use the Responses dialect instead of Chat Completions:
 RubyLLM.configure { |config| config.lms_protocol = :responses }
 ```
 
+## LM Studio server options
+
+LM Studio serves three API surfaces on one port (`http://localhost:1234` by
+default). This gem talks to the first two:
+
+| Surface | Endpoints | Used by this gem |
+| --- | --- | --- |
+| OpenAI-compatible | `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/completions`, `POST /v1/embeddings`, `POST /v1/responses` | chat, tools, structured output, embeddings, Responses protocol |
+| Native REST v0 | `GET /api/v0/models`, `GET /api/v0/models/{model}`, `POST /api/v0/chat/completions`, `POST /api/v0/completions`, `POST /api/v0/embeddings` | model-listing enrichment |
+| Native REST v1 | `POST /api/v1/chat`, `GET /api/v1/list`, `POST /api/v1/load`, `POST /api/v1/unload`, `POST /api/v1/download`, `GET /api/v1/download-status` | not yet (see below) |
+
+### Standard request parameters
+
+On its OpenAI-compatible chat endpoints LM Studio honors the usual OpenAI
+vocabulary: `model`, `messages`, `temperature`, `top_p`, `max_tokens`,
+`stream`, `stop`, `presence_penalty`, `frequency_penalty`, `logit_bias`,
+`seed`, `tools` / `tool_choice`, and `response_format` with a `json_schema`
+(strict structured output). Vision models accept image content parts. You
+reach all of these through RubyLLM's normal API — `with_temperature`,
+`with_max_output_tokens`, `with_tools`, `with_schema`, `chat.ask(with: 'image.png')`,
+and so on; nothing LM Studio-specific is required.
+
+### LM Studio extras
+
+LM Studio also accepts request fields that are not part of OpenAI's
+vocabulary. RubyLLM merges `with_provider_options` into the request payload
+as-is, so all of these work today:
+
+| Option | What it does |
+| --- | --- |
+| `ttl` | Idle time-to-live in seconds for the model handling this request. A JIT-loaded model unloads itself after sitting idle that long (LM Studio's default is 60 minutes; each request resets the timer). |
+| `draft_model` | Enables speculative decoding: a small draft model proposes tokens the main model verifies, often speeding up generation substantially. Both models must use the same tokenizer family. |
+| `top_k` | Sample only from the k most likely tokens. |
+| `min_p` | Discard tokens below this base probability. |
+| `repeat_penalty` | Penalize recently generated tokens to discourage repetition. |
+
+```ruby
+chat = RubyLLM.chat(model: 'qwen/qwen3-4b', provider: :lms)
+chat.with_provider_options(
+  ttl: 300,                        # unload after 5 idle minutes
+  draft_model: 'qwen/qwen3-0.6b',  # speculative decoding
+  top_k: 40,
+  min_p: 0.05,
+  repeat_penalty: 1.1
+)
+chat.ask('Hello')
+```
+
+### Model lifecycle: JIT loading, TTL, auto-evict
+
+Because LM Studio only serves models you have downloaded, the server manages
+memory rather than a fleet:
+
+- **JIT loading** — with just-in-time loading enabled (the server default),
+  `/v1/models` lists every downloaded model and an inference request for an
+  unloaded model loads it on demand. Expect a long time-to-first-token on
+  that first request. With JIT off, only already-loaded models are served.
+- **TTL** — JIT-loaded models default to a 60-minute idle TTL; override it
+  per request with the `ttl` option above, or at load time with
+  `lms load <model> --ttl 3600`. Models loaded explicitly via `lms load`
+  have no TTL and stay resident until unloaded.
+- **Auto-evict** — by default LM Studio keeps at most one JIT-loaded model
+  in memory, evicting the previous one before loading the next. Turn
+  auto-evict off in the server settings to keep several models resident at
+  once (each still subject to its own TTL).
+
+The `state` field in this gem's model metadata (`loaded` / `not-loaded`)
+comes from the native v0 API and tells you which models are resident right
+now.
+
+### Native REST APIs (not yet wired up)
+
+The native APIs offer capabilities the OpenAI-compatible surface cannot
+express. This gem does not use them yet, beyond the v0 model-listing
+enrichment:
+
+- **Performance stats** — native v0/v1 chat responses include a `stats`
+  object (tokens per second, time to first token, generation time, and
+  draft-token acceptance counts when speculative decoding is active) plus
+  `model_info` and `runtime` blocks.
+- **Stateful chats** — `/api/v1/chat` stores conversations server-side
+  (`store`, default true) and continues them via `previous_response_id`.
+- **Reasoning control** — `/api/v1/chat` takes a `reasoning` effort option
+  (`off` / `low` / `medium` / `high` / `on`) and returns reasoning output as
+  separate items.
+- **Server-side MCP tools** — `/api/v1/chat` can run tools itself through
+  `integrations`: pre-configured MCP plugins from `mcp.json` or ephemeral
+  MCP servers declared in the request, with `allowed_tools` filtering.
+- **Per-request context length** — `/api/v1/chat` accepts a
+  `context_length` override.
+- **Model management** — `/api/v1/load`, `/api/v1/unload`, `/api/v1/download`,
+  and `/api/v1/download-status` control what is in memory and on disk.
+
 ## Development
 
 Start the LM Studio server (`lms server start`), then:
@@ -70,11 +198,10 @@ 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.
+`rake models` calls the local server's model-listing endpoints and rewrites
+the sample `models.json` at the gem root (see "The model catalog" above) —
+it is a maintainer task for refreshing the shipped sample, not something gem
+users run.
 
 The suite always runs the provider integration specs. The first local run
 calls the API and records VCR cassettes; CI only replays committed cassettes.

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module RubyLLM
+  module Providers
+    class LMS < Provider
+      # Wraps the transport connection so a request against a server that
+      # is not running surfaces as a RubyLLM::Error explaining how to start
+      # LM Studio, instead of a raw Faraday::ConnectionFailed.
+      class ConnectionGuard < SimpleDelegator
+        %i[get post patch delete].each do |verb|
+          define_method(verb) do |*args, **kwargs, &block|
+            __getobj__.public_send(verb, *args, **kwargs, &block)
+          rescue Faraday::ConnectionFailed
+            raise Error, unreachable_message
+          end
+        end
+
+        def unreachable_message
+          "Cannot connect to the LM Studio server at #{provider.api_base}. " \
+            'Start it with `lms server start`.'
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/lms.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'ruby_llm'
+require 'ruby_llm/providers/lms/connection_guard'
 require 'ruby_llm/providers/lms/models'
 
 module RubyLLM
@@ -20,6 +21,11 @@ module RubyLLM
       protocol :chat_completions, ChatCompletions
       protocol :responses, Protocols::Responses
 
+      def initialize(config)
+        super
+        @connection = ConnectionGuard.new(@connection)
+      end
+
       def api_base
         @config.lms_api_base || DEFAULT_API_BASE
       end

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_can_handle_a_multi_turn_conversation.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"Who
@@ -44,7 +44,7 @@ http_interactions:
   recorded_at: Fri, 11 Sep 2026 17:27:55 GMT
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"Who

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_can_have_a_basic_conversation.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"What''s

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_can_use_tools.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"What''s
@@ -82,7 +82,7 @@ http_interactions:
   recorded_at: Fri, 11 Sep 2026 17:28:04 GMT
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"What''s

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_returns_the_raw_response.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"What

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_supports_streaming_responses.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"openai/gpt-oss-20b","messages":[{"role":"user","content":"Count

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_qwen3_0_6b_bible_assistant_can_have_a_basic_conversation.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"qwen3-0.6b-bible-assistant","messages":[{"role":"user","content":"What''s

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_qwen3_0_6b_bible_assistant_returns_structured_output.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"qwen3-0.6b-bible-assistant","messages":[{"role":"user","content":"Generate

data/spec/fixtures/vcr_cassettes/rubyllm_chat_lms_qwen3_0_6b_bible_assistant_returns_the_raw_response.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/chat/completions"
+    uri: "http://localhost:1234/v1/chat/completions"
     body:
       encoding: UTF-8
       string: '{"model":"qwen3-0.6b-bible-assistant","messages":[{"role":"user","content":"What

data/spec/fixtures/vcr_cassettes/rubyllm_embedding_lms_text_embedding_nomic_embed_text_v1_5_embeds_one_text.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/embeddings"
+    uri: "http://localhost:1234/v1/embeddings"
     body:
       encoding: UTF-8
       string: '{"model":"text-embedding-nomic-embed-text-v1.5","input":"Ruby is a

data/spec/fixtures/vcr_cassettes/rubyllm_embedding_lms_text_embedding_nomic_embed_text_v1_5_embeds_several_texts.yml

@@ -2,7 +2,7 @@
 http_interactions:
 - request:
     method: post
-    uri: "<LMS_API_BASE>/embeddings"
+    uri: "http://localhost:1234/v1/embeddings"
     body:
       encoding: UTF-8
       string: '{"model":"text-embedding-nomic-embed-text-v1.5","input":["Ruby","Python","JavaScript"]}'

data/spec/ruby_llm/providers/lms/connection_guard_spec.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe RubyLLM::Providers::LMS::ConnectionGuard do
+  subject(:guard) { described_class.new(connection) }
+
+  let(:provider) { instance_double(RubyLLM::Providers::LMS, api_base: 'http://localhost:1234/v1') }
+  let(:connection) { instance_double(RubyLLM::Transport::Connection, provider: provider) }
+
+  { get: ['models'], post: ['chat/completions', {}], patch: ['models', {}], delete: ['models'] }.each do |verb, args|
+    it "wraps a connection failure on ##{verb} in a RubyLLM::Error" do
+      allow(connection).to receive(verb).and_raise(Faraday::ConnectionFailed, 'Connection refused')
+
+      expect { guard.public_send(verb, *args) }.to raise_error(RubyLLM::Error) do |error|
+        expect(error.message).to include('http://localhost:1234/v1')
+        expect(error.message).to include('lms server start')
+        expect(error.cause).to be_a(Faraday::ConnectionFailed)
+      end
+    end
+  end
+
+  it 'passes successful calls through with arguments and block' do
+    response = instance_double(Faraday::Response)
+    request = Object.new
+    allow(connection).to receive(:post).with('chat/completions', { model: 'x' }, usage: nil)
+                                       .and_yield(request).and_return(response)
+
+    yielded = nil
+    result = guard.post('chat/completions', { model: 'x' }, usage: nil) { |req| yielded = req }
+
+    expect(result).to be(response)
+    expect(yielded).to be(request)
+  end
+
+  it 'lets other errors propagate untouched' do
+    allow(connection).to receive(:get).and_raise(RubyLLM::UnauthorizedError.new('nope'))
+
+    expect { guard.get('models') }.to raise_error(RubyLLM::UnauthorizedError, 'nope')
+  end
+
+  it 'names the server address and the start command in its message' do
+    expect(guard.unreachable_message)
+      .to eq('Cannot connect to the LM Studio server at http://localhost:1234/v1. ' \
+             'Start it with `lms server start`.')
+  end
+end

data/spec/ruby_llm/providers/lms_spec.rb

@@ -50,6 +50,10 @@ RSpec.describe RubyLLM::Providers::LMS do
     expect(provider.headers).to eq('Authorization' => 'Bearer test-key')
   end
 
+  it 'guards its connection against a server that is not running' do
+    expect(provider.connection).to be_a(described_class::ConnectionGuard)
+  end
+
   describe 'model listing' do
     subject(:protocol) do
       described_class::ChatCompletions.new(described_class.new(config))

data/spec/support/vcr_configuration.rb

@@ -6,7 +6,15 @@ VCR.configure do |config|
   config.default_cassette_options = { record: ENV['CI'] ? :none : :once }
   config.allow_http_connections_when_no_cassette = true
   config.filter_sensitive_data('<LMS_API_KEY>') { ENV.fetch('LMS_API_KEY', nil) }
-  config.filter_sensitive_data('<LMS_API_BASE>') { ENV.fetch('LMS_API_BASE', nil) }
+
+  # Normalize the recorder's server address to the default so cassettes
+  # replay on any machine (CI included) without LMS_API_BASE set. The
+  # placeholder must be a parseable URI, not a <TOKEN>: VCR parses every
+  # cassette URI on replay and raises URI::InvalidURIError otherwise.
+  config.filter_sensitive_data(RubyLLM::Providers::LMS::DEFAULT_API_BASE) do
+    base = ENV.fetch('LMS_API_BASE', nil)
+    base unless base.nil? || base == RubyLLM::Providers::LMS::DEFAULT_API_BASE
+  end
 
   config.before_record do |interaction|
     next unless interaction.request.headers['Authorization']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-providers-lms
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - madbomber
@@ -42,6 +42,7 @@ files:
 - LICENSE
 - README.md
 - lib/ruby_llm/providers/lms.rb
+- lib/ruby_llm/providers/lms/connection_guard.rb
 - lib/ruby_llm/providers/lms/models.rb
 - models.json
 - spec/fixtures/vcr_cassettes/rubyllm_chat_lms_openai_gpt_oss_20b_can_handle_a_multi_turn_conversation.yml
@@ -62,6 +63,7 @@ files:
 - spec/ruby_llm/image_spec.rb
 - spec/ruby_llm/models_spec.rb
 - spec/ruby_llm/moderation_spec.rb
+- spec/ruby_llm/providers/lms/connection_guard_spec.rb
 - spec/ruby_llm/providers/lms_spec.rb
 - spec/ruby_llm/rerank_spec.rb
 - spec/ruby_llm/speech_spec.rb
@@ -86,7 +88,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="