lex-llm 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 40556884bda9b7daeff510f1ee58532cfcecb01c30b942bbc17637ae2eb1aa14
+  data.tar.gz: 4a1448028063a4976a4dab4c5058927b3e79b4c2bbff897c44075e90c879097e
+SHA512:
+  metadata.gz: 156e17beda598522ff95facb2eae951ccc2cc13693e4f4f11346e6f403cf73f76e358f4ef57518f2ad92dff9e63cddbc04510c9a3fce18789d90ed062084b629
+  data.tar.gz: adb0fca5733239dc70894d2fc606da5dc2018d4ba83f47e1cf645048c2a956d3a3da6a7f08cd946c8dfc1e473c29cbeb83675f2e452a40fb53302f5df770a8e0

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: ai
+#
+# To apply: scripts/apply-codeowners.sh lex-openai
+
+* @LegionIO/maintainers
+* @LegionIO/ai

data/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"

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,19 @@
+/.bundle/
+Gemfile.lock
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status*
+
+# local/editor/runtime
+.env
+.claude
+AGENTS.md
+CLAUDE.md
+lib/lex_llm/models.failed.json

data/.rubocop.yml

@@ -0,0 +1,42 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.4
+  Exclude:
+    - docs/**/*
+    - vendor/**/*
+    - gemfiles/**/*
+    - lib/generators/**/templates/**/*
+  SuggestExtensions: false
+
+Metrics/ClassLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ModuleLength:
+  Enabled: false
+Performance/CollectionLiteralInLoop:
+  Exclude:
+    - spec/**/*
+Performance/RedundantBlockCall:
+  Enabled: false # TODO: temporarily disabled to avoid potential breaking change
+Performance/StringInclude:
+  Exclude:
+    - lib/lex_llm/providers/**/capabilities.rb
+Performance/UnfreezeString:
+  Exclude:
+    - spec/**/*
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+RSpec/LeakyLocalVariable:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.1 - 2026-04-27
+
+- Remove fork-carried concrete provider implementations and VCR-backed provider specs from the base gem.
+- Add fake-provider end-to-end specs for shared chat, tools, schemas, embeddings, moderation, images, transcription, model lookup, and fleet lane wiring.
+- Add shared provider settings construction for `lex-llm-*` gems.
+- Make base defaults provider-neutral and move provider-specific defaults into provider gems.
+
+## 0.1.0 - 2026-04-26
+
+- Rename the forked base gem to `lex-llm` with `LexLLM` runtime namespaces and `Legion::Extensions::Llm` integration.
+- Add provider-neutral routing metadata for concrete model offerings and shared fleet lane keys.
+- Use Legion JSON/settings/logging runtime dependencies for shared extension behavior.
+- Remove the upstream RubyLLM docs site and issue templates from the LegionIO fork.

data/Gemfile

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do # rubocop:disable Metrics/BlockLength
+  gem 'appraisal'
+  gem 'async', platform: :mri
+  gem 'bundler', '>= 2.0'
+  gem 'colorize'
+  gem 'dotenv'
+  gem 'ferrum'
+  gem 'flay'
+  gem 'image_processing', '~> 1.2'
+  gem 'irb'
+  gem 'json-schema'
+  gem 'nokogiri'
+  gem 'overcommit', '>= 0.66'
+  gem 'pry', '>= 0.14'
+  gem 'rails'
+  gem 'rake', '>= 13.0'
+  gem 'reline'
+  gem 'rspec', '~> 3.12'
+  gem 'rubocop', '>= 1.0'
+  gem 'rubocop-performance'
+  gem 'rubocop-rake', '>= 0.6'
+  gem 'rubocop-rspec'
+  gem 'simplecov', '>= 0.21'
+  gem 'simplecov-cobertura'
+  gem 'test-queue'
+
+  # database drivers for MRI and JRuby
+  gem 'activerecord-jdbcsqlite3-adapter', platform: 'jruby'
+  gem 'jdbc-sqlite3', platform: 'jruby'
+  gem 'sqlite3', platform: 'mri'
+
+  gem 'vcr'
+  gem 'webmock', '~> 3.18'
+
+  # Optional dependency for Vertex AI
+  gem 'googleauth'
+
+  # Optional dependency for Bedrock
+  gem 'aws-eventstream'
+end
+
+group :development, :test do
+  gem 'turbo-rails'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Carmine Paolino
+
+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,279 @@
+# lex-llm
+
+[![CI](https://github.com/LegionIO/lex-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/LegionIO/lex-llm/actions/workflows/ci.yml)
+
+Shared LegionIO framework for LLM provider extensions.
+
+`lex-llm` is the provider-neutral base layer for LegionIO LLM work. It defines the common Ruby API, schema bridge, model metadata, routing structures, request/response helpers, streaming helpers, and Legion extension namespace that concrete provider gems build on.
+
+The routing principle is simple: provider is not the routing unit anymore. A concrete model offering is.
+
+That means Legion can reason about:
+
+- one local Ollama instance with many models
+- multiple remote Ollama or vLLM instances
+- several Bedrock accounts or regions exposing overlapping Anthropic models
+- direct frontier providers such as OpenAI or Anthropic
+- fleet workers on MacBooks, GPU servers, or cloud-side proxy nodes
+
+## What This Gem Owns
+
+`lex-llm` provides shared primitives only. Provider-specific behavior belongs in provider gems.
+
+This gem owns:
+
+- `LexLLM`, the shared Ruby API and base provider framework
+- `Legion::Extensions::Llm`, the Legion extension namespace used by autoloading and settings
+- provider-neutral model metadata and capability normalization
+- routing structures such as `LexLLM::Routing::ModelOffering`
+- fleet lane key generation for shared RabbitMQ work lanes
+- common chat, embedding, tool, streaming, ActiveRecord, and schema helpers
+- shared runtime dependencies such as `legion-json`, `legion-settings`, and `legion-logging`
+
+Concrete provider gems should depend on this gem and implement the provider-specific transport, authentication, model discovery, request translation, and response translation.
+
+Expected provider gems include:
+
+- `lex-llm-ollama`
+- `lex-llm-vllm`
+- `lex-llm-anthropic`
+- `lex-llm-openai`
+- `lex-llm-gemini`
+- `lex-llm-mlx`
+- `lex-llm-bedrock`
+- `lex-llm-vertex`
+- `lex-llm-azure`
+
+## Install
+
+```ruby
+gem 'lex-llm'
+```
+
+Provider extensions should declare `lex-llm` as a gemspec dependency:
+
+```ruby
+spec.add_dependency 'lex-llm', '>= 0.1.0'
+```
+
+For local development across LegionIO repos, prefer a local path override in the app or test `Gemfile`, not a permanent git dependency in the gemspec.
+
+## Namespaces
+
+This gem exposes two runtime namespaces:
+
+- `LexLLM` for shared Ruby classes, provider primitives, schemas, and helpers
+- `Legion::Extensions::Llm` for LegionIO extension loading and default settings
+
+Provider gems must use nested Legion extension namespaces so LegionIO autoloading can find them consistently.
+
+Example for `lex-llm-ollama`:
+
+```ruby
+require 'legion/extensions/llm/ollama'
+
+module Legion
+  module Extensions
+    module Llm
+      module Ollama
+        def self.default_settings
+          Legion::Extensions::Llm.default_settings.merge(
+            provider_family: :ollama
+          )
+        end
+      end
+    end
+  end
+end
+```
+
+## Model Offerings
+
+A model offering describes one concrete model made available by one provider instance. It is the base unit for routing, filtering, fleet lane creation, health, policy, and cost decisions.
+
+```ruby
+offering = LexLLM::Routing::ModelOffering.new(
+  provider_family: :ollama,
+  instance_id: :macbook_m4_max,
+  transport: :local,
+  tier: :local,
+  model: 'qwen3.6:27b-q4_K_M',
+  usage_type: :inference,
+  capabilities: %i[chat tools vision thinking],
+  limits: {
+    context_window: 32_768,
+    max_output_tokens: 8_192
+  },
+  health: {
+    ready: true,
+    latency_ms: 180
+  },
+  policy_tags: %i[internal_only phi_allowed],
+  metadata: {
+    enabled: true,
+    eligibility: {
+      ac_power: true
+    }
+  }
+)
+
+offering.eligible_for?(
+  usage_type: :inference,
+  required_capabilities: %i[tools],
+  min_context_window: 16_000,
+  policy_tags: %i[internal_only]
+)
+# => true
+```
+
+Common offering fields:
+
+- `provider_family`: provider implementation family, such as `:ollama`, `:vllm`, `:bedrock`, `:anthropic`, or `:openai`
+- `instance_id`: concrete provider instance, account, node, region, or local runtime
+- `transport`: `:local`, `:http`, `:rabbitmq`, `:sdk`, or another provider-supported transport
+- `tier`: `:local`, `:private`, `:fleet`, `:cloud`, `:frontier`, or deployment-specific policy tier
+- `model`: provider model name or normalized model alias
+- `usage_type`: `:inference` or `:embedding`
+- `capabilities`: normalized feature flags such as `:chat`, `:tools`, `:json_schema`, `:vision`, `:thinking`, or `:embedding`
+- `limits`: context window, output token limits, rate limits, concurrency limits, and provider-specific bounds
+- `health`: readiness, latency, recent failures, and provider-specific health metadata
+- `policy_tags`: routing and compliance tags such as `:internal_only`, `:phi_allowed`, or `:hipaa`
+- `metadata`: extension-specific metadata; sensitive values are excluded from fleet eligibility fingerprints
+
+## Fleet Lanes
+
+Fleet routing uses shared work lanes derived from model offerings. A lane describes the work required, not the worker that happens to do it.
+
+```ruby
+offering.lane_key
+# => "llm.fleet.inference.qwen3-6-27b-q4-k-m.ctx32768"
+```
+
+Embedding lanes omit context size:
+
+```ruby
+LexLLM::Routing::ModelOffering.new(
+  provider_family: :ollama,
+  instance_id: :gpu_embed_01,
+  transport: :rabbitmq,
+  model: 'nomic-embed-text',
+  usage_type: :embedding,
+  capabilities: %i[embedding]
+).lane_key
+# => "llm.fleet.embed.nomic-embed-text"
+```
+
+The intent is that any eligible worker can bind to the same lane:
+
+- local MacBook workers
+- GPU servers in a datacenter
+- vLLM workers
+- Ollama workers
+- cloud-side LegionIO workers near Bedrock, Vertex, Azure, or another provider
+
+Busy endpoint workers should not reject/requeue in a hot loop. Endpoint fleet workers can use pull-style scheduling, while server-class workers can use normal consumers with prefetch and consumer priority.
+
+## Default Fleet Settings
+
+`Legion::Extensions::Llm.default_settings` provides defaults that provider extensions inherit and override:
+
+```ruby
+Legion::Extensions::Llm.default_settings
+# => {
+#      fleet: {
+#        enabled: false,
+#        scheduler: :basic_get,
+#        consumer_priority: 0,
+#        queue_expires_ms: 60_000,
+#        message_ttl_ms: 120_000,
+#        queue_max_length: 100,
+#        delivery_limit: 3,
+#        consumer_ack_timeout_ms: 300_000,
+#        endpoint: {
+#          enabled: false,
+#          empty_lane_backoff_ms: 250,
+#          idle_backoff_ms: 1_000,
+#          max_consecutive_pulls_per_lane: 0,
+#          accept_when: []
+#        }
+#      }
+#    }
+```
+
+The defaults are conservative:
+
+- fleet participation is off unless configured
+- endpoint fleet mode is separately disabled by default
+- queue and message TTLs are bounded
+- pull scheduling is the default for endpoint-style workers
+- provider gems can override defaults through `Legion::Settings`
+
+Provider gems can build a complete provider settings hash without duplicating merge logic:
+
+```ruby
+Legion::Extensions::Llm.provider_settings(
+  family: :ollama,
+  instance: {
+    base_url: "http://localhost:11434",
+    fleet: { enabled: true, consumer_priority: 10 }
+  }
+)
+```
+
+## Provider Extension Contract
+
+A provider gem should use `lex-llm` for shared behavior and implement only the provider-specific pieces.
+
+At minimum, a provider extension should define:
+
+- `Legion::Extensions::Llm::<Provider>`
+- provider default settings
+- model discovery or a static model offering registry
+- provider request translation
+- provider response translation
+- health and readiness checks
+- embedding support separately from inference support when the provider exposes both
+
+Provider extensions should avoid duplicating shared classes, schema logic, fleet lane construction, JSON handling, or common request/response objects.
+
+## Schema Status
+
+`lex-llm` still depends on `ruby_llm-schema` because the current schema bridge exposes:
+
+```ruby
+LexLLM::Schema
+```
+
+as:
+
+```ruby
+RubyLLM::Schema
+```
+
+That dependency should stay until LegionIO owns or replaces the schema layer directly.
+
+## Development
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run lint:
+
+```bash
+bundle exec rubocop -A
+```
+
+Run the full test suite:
+
+```bash
+bundle exec rspec --format json --out tmp/rspec_results.json --format progress --out tmp/rspec_progress.txt
+```
+
+`Gemfile.lock` is intentionally not committed for this repo.
+
+## Attribution
+
+`lex-llm` began as a LegionIO fork of RubyLLM. RubyLLM remains credited under the MIT license in `LICENSE`.

data/lex-llm.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative 'lib/lex_llm/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-llm'
+  spec.version       = LexLLM::VERSION
+  spec.authors       = ['LegionIO', 'Carmine Paolino']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'Shared LegionIO LLM provider framework'
+  spec.description   = 'Provider-neutral LLM primitives, schemas, routing metadata, and shared codecs for LegionIO ' \
+                       'LLM provider extensions.'
+
+  spec.homepage      = 'https://github.com/LegionIO/lex-llm'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 3.4')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-llm'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-llm/blob/main/CHANGELOG.md'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-llm'
+  spec.metadata['bug_tracker_uri'] = "#{spec.metadata['source_code_uri']}/issues"
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(spec|test|features|tmp|coverage)/}) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  spec.add_dependency 'base64'
+  spec.add_dependency 'event_stream_parser', '~> 1'
+  spec.add_dependency 'faraday', ENV['FARADAY_VERSION'] || '>= 1.10.0'
+  spec.add_dependency 'faraday-multipart', '>= 1'
+  spec.add_dependency 'faraday-net_http', '>= 1'
+  spec.add_dependency 'faraday-retry', '>= 1'
+  spec.add_dependency 'legion-json', '>= 1.2.1'
+  spec.add_dependency 'legion-logging', '>= 1.3.2'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+  spec.add_dependency 'marcel', '~> 1'
+  spec.add_dependency 'ruby_llm-schema', '~> 0'
+  spec.add_dependency 'zeitwerk', '~> 2'
+end

data/lib/generators/lex_llm/agent/agent_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module LexLLM
+  module Generators
+    # Generator for LexLLM agent classes and prompt files.
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+
+      namespace 'lex_llm:agent'
+
+      desc 'Creates a LexLLM agent class and default instructions prompt'
+
+      def create_agent_file
+        template 'agent.rb.tt', File.join('app/agents', class_path, "#{agent_file_name}.rb")
+      end
+
+      def create_prompt_file
+        empty_directory File.join('app/prompts', class_path, agent_file_name)
+        template 'instructions.txt.erb.tt',
+                 File.join('app/prompts', class_path, agent_file_name, 'instructions.txt.erb')
+      end
+
+      private
+
+      def agent_class_name
+        class_name.end_with?('Agent') ? class_name : "#{class_name}Agent"
+      end
+
+      def agent_file_name
+        agent_class_name.demodulize.underscore
+      end
+    end
+  end
+end

data/lib/generators/lex_llm/agent/templates/agent.rb.tt

@@ -0,0 +1,6 @@
+class <%= agent_class_name %> < LexLLM::Agent
+  # Change `Chat` to your app's chat model for Rails persistence.
+  # Remove this line to skip persistence and use plain LexLLM chats.
+  chat_model Chat
+  instructions
+end