lex-llm 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bba21b096146376e92e11aa2a001e7f13cd91e453ecd2907c44cc1c39dcbe3a1
-  data.tar.gz: ad320998555a6e6f8eda82b0dac1bc376415def07c15228400c60f0638a82b1c
+  metadata.gz: acd86ca9d14268a164c9492297186706a93770c93f4e312f45d6e54cec8bd565
+  data.tar.gz: b78f52a9e0cebfedb102b7809aaf3affc20440e1fcd68a9f815e00f4a129b440
 SHA512:
-  metadata.gz: 7b657bf222fa57ad9bd887d6e964a9bb1664c732b894dc760f33fe5396b44c136a19ae96d859036c63449f307f6eb613ef27862ace25fd634a95dafb9c3b5c96
-  data.tar.gz: f1799aba3ec971591f68e7cfe6ad144742acd82582af1e44de251d3ada828773e64f2b617be9482f7fc31c15e2f2a22861630d5383e614565465d6ae050e9e5e
+  metadata.gz: cb2b53cfc698777af6dbfbd735a8d12c0ed5eb94a3dbea88fb91a4951946ac2c3f42790b316bfa34e9f56f822ce3c1be6a07cdc8298525f8d317895269fb2348
+  data.tar.gz: b7392fe404a9bee6f2cde122522016b43f193c4df546a69732f9d238161f61a8a6dcb93b685fc2de5a1f9703ecf2c14c433e1a790039d8489b302afbb8cce2ef

data/.gitignore

@@ -1,5 +1,6 @@
 /.bundle/
 Gemfile.lock
+*.gem
 /.yardoc
 /_yardoc/
 /coverage/

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.4 - 2026-04-28
+
+- Add non-live provider readiness metadata for routing without expensive health or model calls by default.
+- Map OpenAI-compatible model listings to normalized capabilities and modalities for routing.
+
+## 0.1.3 - 2026-04-27
+
+- Convert the gem to a standard Legion extension runtime under `Legion::Extensions::Llm`.
+- Remove the fork-era compatibility namespace, Rails railtie, generators, rake tasks, dummy app, and ActiveRecord helpers.
+- Move provider-neutral chat, schema, model, routing, streaming, and fleet primitives under `lib/legion/extensions/llm`.
+
 ## 0.1.2 - 2026-04-27
 
 - Add a shared OpenAI-compatible provider adapter for `lex-llm-openai`, `lex-llm-vllm`, `lex-llm-mlx`, and other compatible servers.
@@ -13,7 +24,7 @@
 
 ## 0.1.0 - 2026-04-26
 
-- Rename the forked base gem to `lex-llm` with `LexLLM` runtime namespaces and `Legion::Extensions::Llm` integration.
+- Rename the forked base gem to `lex-llm` with Legion extension 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

@@ -4,21 +4,18 @@ source 'https://rubygems.org'
 
 gemspec
 
-group :development do # rubocop:disable Metrics/BlockLength
+group :development do
   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'
@@ -30,21 +27,6 @@ group :development do # rubocop:disable Metrics/BlockLength
   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/README.md

@@ -4,33 +4,28 @@
 
 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.
+`lex-llm` is a standard Legion extension gem. It does not expose a standalone RubyLLM-compatible API, Rails integration, generators, rake tasks, or concrete providers. Its runtime contract is `Legion::Extensions::Llm`, which provider gems extend through nested namespaces such as `Legion::Extensions::Llm::Ollama`.
 
 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
+That lets Legion reason about one local Ollama instance with many models, multiple remote Ollama or vLLM instances, Bedrock accounts in different regions, direct frontier providers, and 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.
+`lex-llm` provides provider-neutral 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`
+- provider-neutral request, response, message, content, token, and tool objects
+- schema bridging through `Legion::Extensions::Llm::Schema`
+- model metadata and capability normalization
+- routing structures such as `Legion::Extensions::Llm::Routing::ModelOffering`
 - fleet lane key generation for shared RabbitMQ work lanes
-- common chat, embedding, tool, streaming, ActiveRecord, and schema helpers
+- shared chat, embedding, moderation, image, transcription, streaming, and OpenAI-compatible adapter 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.
+Concrete provider gems should depend on this gem and implement the provider-specific transport, authentication, model discovery, request translation, response translation, and health checks.
 
 Expected provider gems include:
 
@@ -53,32 +48,34 @@ gem 'lex-llm'
 Provider extensions should declare `lex-llm` as a gemspec dependency:
 
 ```ruby
-spec.add_dependency 'lex-llm', '>= 0.1.0'
+spec.add_dependency 'lex-llm', '>= 0.1.4'
 ```
 
 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
+## Namespace
 
-This gem exposes two runtime namespaces:
+Load the extension through the Legion namespace:
 
-- `LexLLM` for shared Ruby classes, provider primitives, schemas, and helpers
-- `Legion::Extensions::Llm` for LegionIO extension loading and default settings
+```ruby
+require 'legion/extensions/llm'
+```
 
 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'
+require 'legion/extensions/llm'
 
 module Legion
   module Extensions
     module Llm
       module Ollama
         def self.default_settings
-          Legion::Extensions::Llm.default_settings.merge(
-            provider_family: :ollama
+          Legion::Extensions::Llm.provider_settings(
+            family: :ollama,
+            instance: { base_url: 'http://localhost:11434' }
           )
         end
       end
@@ -92,7 +89,7 @@ end
 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(
+offering = Legion::Extensions::Llm::Routing::ModelOffering.new(
   provider_family: :ollama,
   instance_id: :macbook_m4_max,
   transport: :local,
@@ -152,7 +149,7 @@ offering.lane_key
 Embedding lanes omit context size:
 
 ```ruby
-LexLLM::Routing::ModelOffering.new(
+Legion::Extensions::Llm::Routing::ModelOffering.new(
   provider_family: :ollama,
   instance_id: :gpu_embed_01,
   transport: :rabbitmq,
@@ -214,7 +211,7 @@ Provider gems can build a complete provider settings hash without duplicating me
 Legion::Extensions::Llm.provider_settings(
   family: :ollama,
   instance: {
-    base_url: "http://localhost:11434",
+    base_url: 'http://localhost:11434',
     fleet: { enabled: true, consumer_priority: 10 }
   }
 )
@@ -236,12 +233,14 @@ At minimum, a provider extension should define:
 
 Provider extensions should avoid duplicating shared classes, schema logic, fleet lane construction, JSON handling, or common request/response objects.
 
+All providers inherit `#readiness(live: false)`, which returns configured state, provider locality, API base, endpoint helpers, and non-live health metadata without probing remote services. Providers with a cheap health endpoint can pass `live: true` to include that endpoint response. OpenAI-compatible providers also inherit shared model-list parsing that maps discovered models into normalized capabilities and modalities for Legion routing.
+
 ## Schema Status
 
 `lex-llm` still depends on `ruby_llm-schema` because the current schema bridge exposes:
 
 ```ruby
-LexLLM::Schema
+Legion::Extensions::Llm::Schema
 ```
 
 as:

data/lex-llm.gemspec

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require_relative 'lib/lex_llm/version'
+require_relative 'lib/legion/extensions/llm/version'
 
 Gem::Specification.new do |spec|
   spec.name          = 'lex-llm'
-  spec.version       = LexLLM::VERSION
+  spec.version       = Legion::Extensions::Llm::VERSION
   spec.authors       = ['LegionIO', 'Carmine Paolino']
   spec.email         = ['matthewdiverson@gmail.com']
 

data/lib/legion/extensions/llm/agent.rb

@@ -0,0 +1,366 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'forwardable'
+require 'pathname'
+require 'ruby_llm/schema'
+
+module Legion
+  module Extensions
+    module Llm
+      # Base class for simple, class-configured agents.
+      class Agent
+        extend Forwardable
+        include Enumerable
+
+        class << self
+          def inherited(subclass)
+            super
+            subclass.instance_variable_set(:@chat_kwargs, (@chat_kwargs || {}).dup)
+            subclass.instance_variable_set(:@tools, (@tools || []).dup)
+            subclass.instance_variable_set(:@instructions, @instructions)
+            subclass.instance_variable_set(:@temperature, @temperature)
+            subclass.instance_variable_set(:@thinking, @thinking)
+            subclass.instance_variable_set(:@params, (@params || {}).dup)
+            subclass.instance_variable_set(:@headers, (@headers || {}).dup)
+            subclass.instance_variable_set(:@schema, @schema)
+            subclass.instance_variable_set(:@context, @context)
+            subclass.instance_variable_set(:@chat_model, @chat_model)
+            subclass.instance_variable_set(:@input_names, (@input_names || []).dup)
+          end
+
+          def model(model_id = nil, **options)
+            options[:model] = model_id unless model_id.nil?
+            @chat_kwargs = options
+          end
+
+          def tools(*tools, &block)
+            return @tools || [] if tools.empty? && !block_given?
+
+            @tools = block_given? ? block : tools.flatten
+          end
+
+          def instructions(text = nil, **prompt_locals, &block)
+            if text.nil? && prompt_locals.empty? && !block_given?
+              @instructions ||= { prompt: 'instructions', locals: {} }
+              return @instructions
+            end
+
+            @instructions = block || text || { prompt: 'instructions', locals: prompt_locals }
+          end
+
+          def temperature(value = nil)
+            return @temperature if value.nil?
+
+            @temperature = value
+          end
+
+          def thinking(effort: nil, budget: nil)
+            return @thinking if effort.nil? && budget.nil?
+
+            @thinking = { effort: effort, budget: budget }
+          end
+
+          def params(**params, &block)
+            return @params || {} if params.empty? && !block_given?
+
+            @params = block_given? ? block : params
+          end
+
+          def headers(**headers, &block)
+            return @headers || {} if headers.empty? && !block_given?
+
+            @headers = block_given? ? block : headers
+          end
+
+          def schema(value = nil, &block)
+            return @schema if value.nil? && !block_given?
+
+            @schema = block_given? ? block : value
+          end
+
+          def context(value = nil)
+            return @context if value.nil?
+
+            @context = value
+          end
+
+          def chat_model(value = nil)
+            return @chat_model if value.nil?
+
+            @chat_model = value
+            remove_instance_variable(:@resolved_chat_model) if instance_variable_defined?(:@resolved_chat_model)
+          end
+
+          def inputs(*names)
+            return @input_names || [] if names.empty?
+
+            @input_names = names.flatten.map(&:to_sym)
+          end
+
+          def chat_kwargs
+            @chat_kwargs || {}
+          end
+
+          def chat(**kwargs)
+            input_values, chat_options = partition_inputs(kwargs)
+            chat = Legion::Extensions::Llm.chat(**chat_kwargs, **chat_options)
+            apply_configuration(chat, input_values:, persist_instructions: true)
+            chat
+          end
+
+          def create(**)
+            with_chat_record(:create, **)
+          end
+
+          def create!(**)
+            with_chat_record(:create!, **)
+          end
+
+          def find(id, **kwargs)
+            raise ArgumentError, 'chat_model must be configured to use find' unless resolved_chat_model
+
+            input_values, = partition_inputs(kwargs)
+            record = resolved_chat_model.find(id)
+            apply_configuration(record, input_values:, persist_instructions: false)
+
+            record
+          end
+
+          def sync_instructions!(chat_or_id, **kwargs)
+            raise ArgumentError, 'chat_model must be configured to use sync_instructions!' unless resolved_chat_model
+
+            input_values, = partition_inputs(kwargs)
+            record = chat_or_id.is_a?(resolved_chat_model) ? chat_or_id : resolved_chat_model.find(chat_or_id)
+            apply_assume_model_exists(record)
+            runtime = runtime_context(chat: record, inputs: input_values)
+            instructions_value = resolved_instructions_value(record, runtime, inputs: input_values)
+            return record if instructions_value.nil?
+
+            record.with_instructions(instructions_value)
+            record
+          end
+
+          def render_prompt(name, chat:, inputs:, locals:)
+            path = prompt_path_for(name)
+            unless File.exist?(path)
+              raise Legion::Extensions::Llm::PromptNotFoundError,
+                    "Prompt file not found for #{self}: #{path}. Create the file or use inline instructions."
+            end
+
+            resolved_locals = resolve_prompt_locals(locals, runtime: runtime_context(chat:, inputs:), chat:, inputs:)
+            ERB.new(File.read(path)).result_with_hash(resolved_locals)
+          end
+
+          private
+
+          def with_chat_record(method_name, **kwargs)
+            raise ArgumentError, 'chat_model must be configured to use create/create!' unless resolved_chat_model
+
+            input_values, chat_options = partition_inputs(kwargs)
+            record = resolved_chat_model.public_send(method_name, **chat_kwargs, **chat_options)
+            apply_configuration(record, input_values:, persist_instructions: true) if record
+            record
+          end
+
+          def apply_configuration(chat_object, input_values:, persist_instructions:)
+            runtime = runtime_context(chat: chat_object, inputs: input_values)
+            llm_chat = llm_chat_for(chat_object)
+
+            apply_context(llm_chat)
+            apply_instructions(chat_object, runtime, inputs: input_values, persist: persist_instructions)
+            apply_tools(llm_chat, runtime)
+            apply_temperature(llm_chat)
+            apply_thinking(llm_chat)
+            apply_params(llm_chat, runtime)
+            apply_headers(llm_chat, runtime)
+            apply_schema(llm_chat, runtime)
+          end
+
+          def apply_context(llm_chat)
+            llm_chat.with_context(context) if context
+          end
+
+          def apply_instructions(chat_object, runtime, inputs:, persist:)
+            value = resolved_instructions_value(chat_object, runtime, inputs:)
+            return if value.nil?
+
+            target = instruction_target(chat_object, persist:)
+            return target.with_runtime_instructions(value) if use_runtime_instructions?(target, persist:)
+
+            target.with_instructions(value)
+          end
+
+          def apply_tools(llm_chat, runtime)
+            tools_to_apply = Array(evaluate(tools, runtime))
+            llm_chat.with_tools(*tools_to_apply) unless tools_to_apply.empty?
+          end
+
+          def apply_temperature(llm_chat)
+            llm_chat.with_temperature(temperature) unless temperature.nil?
+          end
+
+          def apply_thinking(llm_chat)
+            llm_chat.with_thinking(**thinking) if thinking
+          end
+
+          def apply_params(llm_chat, runtime)
+            value = evaluate(params, runtime)
+            llm_chat.with_params(**value) if value && !value.empty?
+          end
+
+          def apply_headers(llm_chat, runtime)
+            value = evaluate(headers, runtime)
+            llm_chat.with_headers(**value) if value && !value.empty?
+          end
+
+          def apply_schema(llm_chat, runtime)
+            value = resolved_schema_value(runtime)
+            llm_chat.with_schema(value) if value
+          end
+
+          def resolved_schema_value(runtime)
+            value = schema
+            return value unless value.is_a?(Proc)
+
+            evaluate(value, runtime)
+          rescue NoMethodError => e
+            raise unless e.receiver.equal?(runtime)
+
+            Legion::Extensions::Llm::Schema.create(&value)
+          end
+
+          def llm_chat_for(chat_object)
+            apply_assume_model_exists(chat_object)
+            chat_object.respond_to?(:to_llm) ? chat_object.to_llm : chat_object
+          end
+
+          def apply_assume_model_exists(chat_object)
+            return unless chat_kwargs.key?(:assume_model_exists) &&
+                          resolved_chat_model &&
+                          chat_object.is_a?(resolved_chat_model)
+
+            chat_object.assume_model_exists = chat_kwargs[:assume_model_exists]
+          end
+
+          def evaluate(value, runtime)
+            value.is_a?(Proc) ? runtime.instance_exec(&value) : value
+          end
+
+          def resolved_instructions_value(chat_object, runtime, inputs:)
+            value = evaluate(@instructions, runtime)
+            return value unless prompt_instruction?(value)
+
+            runtime.prompt(
+              value[:prompt],
+              **resolve_prompt_locals(value[:locals] || {}, runtime:, chat: chat_object, inputs:)
+            )
+          end
+
+          def prompt_instruction?(value)
+            value.is_a?(Hash) && value[:prompt]
+          end
+
+          def instruction_target(chat_object, persist:)
+            if persist || !chat_object.respond_to?(:to_llm)
+              chat_object
+            else
+              runtime_instruction_target(chat_object)
+            end
+          end
+
+          def runtime_instruction_target(chat_object)
+            return chat_object if chat_object.respond_to?(:with_runtime_instructions)
+
+            chat_object.to_llm
+          end
+
+          def use_runtime_instructions?(target, persist:)
+            !persist && target.respond_to?(:with_runtime_instructions)
+          end
+
+          def resolve_prompt_locals(locals, runtime:, chat:, inputs:)
+            base = { chat: chat }.merge(inputs)
+            evaluated = locals.each_with_object({}) do |(key, value), acc|
+              acc[key.to_sym] = value.is_a?(Proc) ? runtime.instance_exec(&value) : value
+            end
+            base.merge(evaluated)
+          end
+
+          def partition_inputs(kwargs)
+            input_values = {}
+            chat_options = {}
+
+            kwargs.each do |key, value|
+              symbolized_key = key.to_sym
+              if inputs.include?(symbolized_key)
+                input_values[symbolized_key] = value
+              else
+                chat_options[symbolized_key] = value
+              end
+            end
+
+            [input_values, chat_options]
+          end
+
+          def runtime_context(chat:, inputs:)
+            agent_class = self
+            Object.new.tap do |runtime|
+              runtime.define_singleton_method(:chat) { chat }
+              runtime.define_singleton_method(:prompt) do |name, **locals|
+                agent_class.render_prompt(name, chat:, inputs:, locals:)
+              end
+
+              inputs.each do |name, value|
+                runtime.define_singleton_method(name) { value }
+              end
+            end
+          end
+
+          def prompt_path_for(name)
+            filename = name.to_s
+            filename += '.txt.erb' unless filename.end_with?('.txt.erb')
+            prompt_root.join(prompt_agent_path, filename)
+          end
+
+          def prompt_agent_path
+            class_name = name || 'agent'
+            class_name.gsub('::', '/')
+                      .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                      .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                      .tr('-', '_')
+                      .downcase
+          end
+
+          def prompt_root
+            Pathname.new(Dir.pwd).join('app/prompts')
+          end
+
+          def resolved_chat_model
+            return @resolved_chat_model if defined?(@resolved_chat_model)
+
+            @resolved_chat_model = case @chat_model
+                                   when String then Object.const_get(@chat_model)
+                                   else @chat_model
+                                   end
+          end
+        end
+
+        def initialize(chat: nil, inputs: nil, persist_instructions: true, **kwargs)
+          input_values, chat_options = self.class.send(:partition_inputs, kwargs)
+          @chat = chat || Legion::Extensions::Llm.chat(**self.class.chat_kwargs, **chat_options)
+          self.class.send(:apply_configuration, @chat, input_values: input_values.merge(inputs || {}),
+                                                       persist_instructions:)
+        end
+
+        attr_reader :chat
+
+        def_delegators :chat, :model, :messages, :tools, :params, :headers, :schema, :ask, :say,
+                       :with_tool, :with_tools,
+                       :with_model, :with_temperature, :with_thinking, :with_context, :with_params, :with_headers,
+                       :with_schema, :on_new_message, :on_end_message, :on_tool_call, :on_tool_result, :each, :complete,
+                       :add_message, :reset_messages!
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/aliases.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Llm
+      # Manages model aliases for provider-specific versions
+      class Aliases
+        class << self
+          def resolve(model_id, provider = nil)
+            return model_id unless aliases[model_id]
+
+            if provider
+              aliases[model_id][provider.to_s] || model_id
+            else
+              aliases[model_id].values.first || model_id
+            end
+          end
+
+          def aliases
+            @aliases ||= load_aliases
+          end
+
+          def aliases_file
+            File.expand_path('aliases.json', __dir__)
+          end
+
+          def load_aliases
+            if File.exist?(aliases_file)
+              Legion::JSON.parse(File.read(aliases_file), symbolize_names: false)
+            else
+              {}
+            end
+          end
+
+          def reload!
+            @aliases = load_aliases
+          end
+        end
+      end
+    end
+  end
+end