lex-mlx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8c2365eeeb7c750cec33de25917a6f3b797378cfe1a23d14c72d168638dd0c52
+  data.tar.gz: 1e092244c8feb4b5a46cc316dbfce948cf3f1366644c2391b29b5b92786403b5
+SHA512:
+  metadata.gz: cd3d9d90dabd91955f44f7793bb43b35c6228bd009b58a36e6bd307ef0391ff61dcb6d2ebbe9f2b90fd1deb5dd6b7369aa673ce5597c5c33ac2cd03f180b286f
+  data.tar.gz: 2ee461a89bb99ab24cfb97c3331df5056cb649233c92b49e5295c578ef5a710f51d13a0860f60d735811e596b32fdeeef9ea3b8a8c6dbb220960f0a0c5aa3b6d

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+Gemfile.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,66 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
+Layout/LineLength:
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Metrics/MethodLength:
+  Max: 50
+
+Metrics/ClassLength:
+  Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
+Metrics/BlockLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
+Metrics/ParameterLists:
+  Max: 10
+
+Style/Documentation:
+  Enabled: false
+
+Style/SymbolArray:
+  Enabled: true
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
+  Enabled: false
+
+Naming/PredicateMethod:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Lint/EmptyClass:
+  Exclude:
+    - 'spec/**/*'

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## [0.1.0] - 2026-04-13
+
+### Added
+
+- Initial release
+- Chat completions via POST /v1/chat/completions (with SSE streaming)
+- Text completions via POST /v1/completions (with SSE streaming)
+- Embeddings via POST /v1/embeddings
+- Model listing via GET /v1/models
+- Retry logic with exponential backoff for transient failures
+- Standalone Client class for use outside LegionIO

data/CLAUDE.md

@@ -0,0 +1,44 @@
+# lex-mlx: Apple MLX Integration for LegionIO
+
+**Parent**: `/Users/miverso2/rubymine/legion/extensions-ai/CLAUDE.md`
+
+## Purpose
+
+Legion Extension that connects LegionIO to Apple MLX local LLM server (mlx_lm.server). Provides chat completions, text completions, embeddings, and model listing via the OpenAI-compatible API.
+
+**GitHub**: https://github.com/LegionIO/lex-mlx
+**License**: MIT
+
+## Architecture
+
+```
+Legion::Extensions::Mlx
+├── Runners/
+│   ├── Chat               # POST /v1/chat/completions (with SSE streaming)
+│   ├── Completions        # POST /v1/completions (with SSE streaming)
+│   ├── Embeddings         # POST /v1/embeddings
+│   └── Models             # GET /v1/models
+├── Helpers/
+│   ├── Client             # Faraday connection to MLX server
+│   ├── Errors             # Retry logic with exponential backoff
+│   └── Usage              # OpenAI-format usage extraction
+└── Client                 # Standalone client class
+```
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| faraday | HTTP client for MLX REST API |
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :test do
+  gem 'rake'
+  gem 'rspec'
+  gem 'rspec_junit_formatter'
+  gem 'rubocop'
+  gem 'rubocop-legion'
+  gem 'simplecov'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LegionIO
+
+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,44 @@
+# lex-mlx
+
+LegionIO extension for Apple MLX local LLM inference server (`mlx_lm.server`).
+
+## Installation
+
+```ruby
+gem 'lex-mlx'
+```
+
+## Usage
+
+```ruby
+require 'legion/extensions/mlx'
+
+client = Legion::Extensions::Mlx::Client.new
+# or with custom host:
+# client = Legion::Extensions::Mlx::Client.new(host: 'http://localhost:8080')
+
+# Chat
+result = client.chat(model: 'mlx-community/Llama-3-8B-Instruct-4bit',
+                     messages: [{ role: 'user', content: 'Hello!' }])
+
+# Streaming chat
+client.chat_stream(model: 'mlx-community/Llama-3-8B-Instruct-4bit',
+                   messages: [{ role: 'user', content: 'Hello!' }]) do |event|
+  print event[:text] if event[:type] == :delta
+end
+
+# Completions
+result = client.complete(model: 'mlx-community/Llama-3-8B-Instruct-4bit',
+                         prompt: 'Once upon a time')
+
+# Embeddings
+result = client.embed(model: 'mlx-community/Llama-3-8B-Instruct-4bit',
+                      input: 'Hello world')
+
+# List models
+result = client.list_models
+```
+
+## License
+
+MIT

data/lex-mlx.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/mlx/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-mlx'
+  spec.version       = Legion::Extensions::Mlx::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX MLX'
+  spec.description   = 'Connects LegionIO to Apple MLX local LLM server'
+  spec.homepage      = 'https://github.com/LegionIO/lex-mlx'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-mlx'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-mlx'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-mlx/blob/main/CHANGELOG.md'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-mlx/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'faraday', '>= 2.0'
+end

data/lib/legion/extensions/mlx/client.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'helpers/client'
+require_relative 'runners/completions'
+require_relative 'runners/chat'
+require_relative 'runners/models'
+require_relative 'runners/embeddings'
+
+module Legion
+  module Extensions
+    module Mlx
+      class Client
+        include Helpers::Client
+        include Runners::Completions
+        include Runners::Chat
+        include Runners::Models
+        include Runners::Embeddings
+
+        attr_reader :opts
+
+        def initialize(host: Helpers::Client::DEFAULT_HOST, **)
+          @opts = { host: host }.compact
+        end
+
+        def client(**override)
+          super(**@opts, **override)
+        end
+
+        def streaming_client(**override)
+          super(**@opts, **override)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/helpers/client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Legion
+  module Extensions
+    module Mlx
+      module Helpers
+        module Client
+          DEFAULT_HOST = 'http://localhost:8080'
+
+          def client(host: DEFAULT_HOST, **)
+            Faraday.new(url: host) do |conn|
+              conn.request :json
+              conn.response :json, content_type: /\bjson$/
+              conn.headers['Content-Type'] = 'application/json'
+              conn.options.timeout = 300
+              conn.options.open_timeout = 10
+            end
+          end
+
+          def streaming_client(host: DEFAULT_HOST, **)
+            Faraday.new(url: host) do |conn|
+              conn.request :json
+              conn.headers['Content-Type'] = 'application/json'
+              conn.options.timeout = 300
+              conn.options.open_timeout = 10
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/helpers/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mlx
+      module Helpers
+        module Errors
+          MAX_RETRIES = 3
+          BASE_DELAY = 0.5
+          MAX_DELAY = 16
+
+          RETRYABLE_EXCEPTIONS = [
+            Faraday::TimeoutError,
+            Faraday::ConnectionFailed
+          ].freeze
+
+          module_function
+
+          def retryable?(exception)
+            RETRYABLE_EXCEPTIONS.any? { |klass| exception.is_a?(klass) }
+          end
+
+          def with_retry(max_retries: MAX_RETRIES)
+            retries = 0
+            begin
+              yield
+            rescue *RETRYABLE_EXCEPTIONS
+              retries += 1
+              raise if retries > max_retries
+
+              delay = [BASE_DELAY * (2**(retries - 1)), MAX_DELAY].min
+              sleep(delay)
+              retry
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/helpers/usage.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mlx
+      module Helpers
+        module Usage
+          EMPTY_USAGE = {
+            input_tokens:  0,
+            output_tokens: 0,
+            total_tokens:  0
+          }.freeze
+
+          module_function
+
+          def from_response(body)
+            return EMPTY_USAGE.dup unless body.is_a?(Hash)
+
+            usage = body['usage']
+            return EMPTY_USAGE.dup unless usage.is_a?(Hash)
+
+            {
+              input_tokens:  usage['prompt_tokens'] || 0,
+              output_tokens: usage['completion_tokens'] || 0,
+              total_tokens:  usage['total_tokens'] || 0
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/runners/chat.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'legion/extensions/mlx/helpers/client'
+require 'legion/extensions/mlx/helpers/errors'
+require 'legion/extensions/mlx/helpers/usage'
+
+module Legion
+  module Extensions
+    module Mlx
+      module Runners
+        module Chat
+          extend Legion::Extensions::Mlx::Helpers::Client
+
+          def chat(model:, messages:, temperature: nil, max_tokens: nil, top_p: nil, stream: false, **)
+            body = { model: model, messages: messages, temperature: temperature,
+                     max_tokens: max_tokens, top_p: top_p, stream: stream }.compact
+            response = Helpers::Errors.with_retry { client(**).post('/v1/chat/completions', body) }
+            { result: response.body, usage: Helpers::Usage.from_response(response.body), status: response.status }
+          end
+
+          def chat_stream(model:, messages:, temperature: nil, max_tokens: nil, top_p: nil, **, &block)
+            body = { model: model, messages: messages, temperature: temperature,
+                     max_tokens: max_tokens, top_p: top_p, stream: true }.compact
+            accumulated = +''
+            usage = nil
+            buffer = +''
+
+            Helpers::Errors.with_retry do
+              streaming_client(**).post('/v1/chat/completions', body) do |req|
+                req.options.on_data = proc do |chunk, _size|
+                  buffer << chunk
+                  while (idx = buffer.index("\n\n"))
+                    line = buffer.slice!(0, idx + 2).strip
+                    next if line.empty?
+                    next unless line.start_with?('data: ')
+
+                    payload = line.sub('data: ', '')
+                    break if payload == '[DONE]'
+
+                    parsed = ::JSON.parse(payload)
+                    usage = Helpers::Usage.from_response(parsed) if parsed['usage']
+                    text = parsed.dig('choices', 0, 'delta', 'content') || ''
+                    unless text.empty?
+                      accumulated << text
+                      block&.call({ type: :delta, text: text })
+                    end
+                    block&.call({ type: :done, data: parsed }) if parsed.dig('choices', 0, 'finish_reason')
+                  end
+                end
+              end
+            end
+
+            usage ||= Helpers::Usage::EMPTY_USAGE.dup
+            { result: accumulated, usage: usage, status: 200 }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/runners/completions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'legion/extensions/mlx/helpers/client'
+require 'legion/extensions/mlx/helpers/errors'
+require 'legion/extensions/mlx/helpers/usage'
+
+module Legion
+  module Extensions
+    module Mlx
+      module Runners
+        module Completions
+          extend Legion::Extensions::Mlx::Helpers::Client
+
+          def complete(model:, prompt:, temperature: nil, max_tokens: nil, top_p: nil, stream: false, **)
+            body = { model: model, prompt: prompt, temperature: temperature,
+                     max_tokens: max_tokens, top_p: top_p, stream: stream }.compact
+            response = Helpers::Errors.with_retry { client(**).post('/v1/completions', body) }
+            { result: response.body, usage: Helpers::Usage.from_response(response.body), status: response.status }
+          end
+
+          def complete_stream(model:, prompt:, temperature: nil, max_tokens: nil, top_p: nil, **, &block)
+            body = { model: model, prompt: prompt, temperature: temperature,
+                     max_tokens: max_tokens, top_p: top_p, stream: true }.compact
+            accumulated = +''
+            usage = nil
+            buffer = +''
+
+            Helpers::Errors.with_retry do
+              streaming_client(**).post('/v1/completions', body) do |req|
+                req.options.on_data = proc do |chunk, _size|
+                  buffer << chunk
+                  while (idx = buffer.index("\n\n"))
+                    line = buffer.slice!(0, idx + 2).strip
+                    next if line.empty?
+                    next unless line.start_with?('data: ')
+
+                    payload = line.sub('data: ', '')
+                    break if payload == '[DONE]'
+
+                    parsed = ::JSON.parse(payload)
+                    usage = Helpers::Usage.from_response(parsed) if parsed['usage']
+                    text = parsed.dig('choices', 0, 'text') || ''
+                    unless text.empty?
+                      accumulated << text
+                      block&.call({ type: :delta, text: text })
+                    end
+                    block&.call({ type: :done, data: parsed }) if parsed.dig('choices', 0, 'finish_reason')
+                  end
+                end
+              end
+            end
+
+            usage ||= Helpers::Usage::EMPTY_USAGE.dup
+            { result: accumulated, usage: usage, status: 200 }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/runners/embeddings.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mlx/helpers/client'
+require 'legion/extensions/mlx/helpers/errors'
+
+module Legion
+  module Extensions
+    module Mlx
+      module Runners
+        module Embeddings
+          extend Legion::Extensions::Mlx::Helpers::Client
+
+          def embed(model:, input:, **)
+            body = { model: model, input: input }.compact
+            response = Helpers::Errors.with_retry { client(**).post('/v1/embeddings', body) }
+            { result: response.body, status: response.status }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/runners/models.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mlx/helpers/client'
+require 'legion/extensions/mlx/helpers/errors'
+
+module Legion
+  module Extensions
+    module Mlx
+      module Runners
+        module Models
+          extend Legion::Extensions::Mlx::Helpers::Client
+
+          def list_models(**)
+            response = Helpers::Errors.with_retry { client(**).get('/v1/models') }
+            { result: response.body, status: response.status }
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/mlx/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Mlx
+      VERSION = '0.1.0'
+    end
+  end
+end

data/lib/legion/extensions/mlx.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/mlx/version'
+require 'legion/extensions/mlx/helpers/client'
+require 'legion/extensions/mlx/helpers/errors'
+require 'legion/extensions/mlx/helpers/usage'
+require 'legion/extensions/mlx/runners/completions'
+require 'legion/extensions/mlx/runners/chat'
+require 'legion/extensions/mlx/runners/models'
+require 'legion/extensions/mlx/runners/embeddings'
+require 'legion/extensions/mlx/client'
+
+module Legion
+  module Extensions
+    module Mlx
+      extend Legion::Extensions::Core if Legion::Extensions.const_defined? :Core
+    end
+  end
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: lex-mlx
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Connects LegionIO to Apple MLX local LLM server
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-mlx.gemspec
+- lib/legion/extensions/mlx.rb
+- lib/legion/extensions/mlx/client.rb
+- lib/legion/extensions/mlx/helpers/client.rb
+- lib/legion/extensions/mlx/helpers/errors.rb
+- lib/legion/extensions/mlx/helpers/usage.rb
+- lib/legion/extensions/mlx/runners/chat.rb
+- lib/legion/extensions/mlx/runners/completions.rb
+- lib/legion/extensions/mlx/runners/embeddings.rb
+- lib/legion/extensions/mlx/runners/models.rb
+- lib/legion/extensions/mlx/version.rb
+homepage: https://github.com/LegionIO/lex-mlx
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-mlx
+  source_code_uri: https://github.com/LegionIO/lex-mlx
+  documentation_uri: https://github.com/LegionIO/lex-mlx
+  changelog_uri: https://github.com/LegionIO/lex-mlx/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/LegionIO/lex-mlx/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX MLX
+test_files: []