laiya 0.0.2

data/guides/providers-and-models/readme.md

@@ -0,0 +1,104 @@
+# Providers and Models
+
+This guide explains how to route model IDs to providers and when to discover a provider's model catalog.
+
+## Default Provider
+
+Use a default provider when one upstream should receive any model name:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new
+	builder.default_provider :ollama
+end
+```
+
+With no explicit model routes or discovery setting, Laiya forwards
+`GET /v1/models` to the default provider and passes completion requests through
+to it.
+
+## Discover Models from an Upstream
+
+Providers such as Ollama expose an OpenAI-compatible `GET /v1/models` endpoint.
+Use `models: :discover` to query it at runtime instead of copying model names
+into configuration:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	builder.default_provider :ollama
+end
+```
+
+`Laiya::Models::Discover` fetches and caches the provider's catalog for 60
+seconds. Laiya uses the discovered IDs for `GET /v1/models` and routes requests
+for those IDs to the provider. The builder itself does not make network calls.
+
+For multiple providers, enable discovery on each provider. Distinct model IDs
+are routed automatically. If two providers advertise the same ID, the default
+provider wins; an explicit `builder.model` route overrides discovery:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :openai, Laiya::Provider::OpenAI.new(
+		api_key: ENV.fetch("OPENAI_API_KEY")
+	), models: :discover
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	
+	builder.model "llama3.2", provider: :ollama
+	builder.default_provider :openai
+end
+```
+
+## Expose Model Limits
+
+OpenAI's standard model-list format has no context-window fields. Laiya lets
+you attach a display name and limits to an explicit model route; it publishes
+them under its `laiya` extension field:
+
+```ruby
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, Laiya::Provider::Ollama.new, models: :discover
+	builder.model "llama3.2",
+		provider: :ollama,
+		display_name: "Llama 3.2",
+		limits: {context: 32_768, input: 28_672, output: 4_096}
+	builder.default_provider :ollama
+end
+```
+
+The `limits` keys are `context`, `input`, and `output`, and values are positive
+token counts. OpenCode does not currently infer these custom fields from
+`GET /v1/models`; configure its model `limit.context`, `limit.input`, and
+`limit.output` values on each client as well. The `context` limit should match
+the effective upstream model configuration (for Ollama, including `num_ctx`).
+
+## Customize Discovery
+
+Subclass `Laiya::Models::Discover` to filter models or attach provider-specific
+metadata. Override `include_model?` to filter entries and `normalize_model` to
+add or adjust model fields:
+
+```ruby
+class LocalModels < Laiya::Models::Discover
+	protected
+	
+	def include_model?(model)
+		super && model["id"].start_with?("llama")
+	end
+	
+	def normalize_model(model)
+		super.merge("laiya" => {"limits" => {"context" => 32_768, "output" => 4_096}})
+	end
+end
+
+ollama = Laiya::Provider::Ollama.new
+configuration = Laiya::Configuration.build do |builder|
+	builder.provider :ollama, ollama, models: LocalModels.new(ollama)
+	builder.default_provider :ollama
+end
+```
+
+The model list includes configured IDs and discovered metadata. Custom discovery
+metadata is provider-specific and is likewise exposed under Laiya's extension
+field; standard clients may ignore it.

data/lib/laiya/configuration/builder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Laiya
+	class Configuration
+		# Mutable DSL for configuring a Laiya::Configuration.
+		class Builder
+			# Attach a DSL builder to the configuration it will update.
+			# @parameter configuration [Laiya::Configuration] The mutable configuration.
+			def initialize(configuration)
+				@configuration = configuration
+			end
+			
+			# Configure a provider on the attached configuration.
+			# @parameter name [String | Symbol] The provider's routing name.
+			# @parameter instance [Interface(:call)] The provider implementation.
+			# @option :models [Symbol | Interface(:each, :find) | Nil] The model source or `:discover`.
+			def provider(name, instance, models: nil)
+				@configuration.provider(name, instance, models: models)
+			end
+			
+			# Configure a model route on the attached configuration.
+			# @parameter name [String | Symbol] The model ID.
+			# @parameter provider [String | Symbol] The provider name.
+			# @option :display_name [String | Nil] A human-readable model name.
+			# @option :limits [Hash | Nil] Positive context, input, and output token limits.
+			def model(name, provider:, display_name: nil, limits: nil)
+				@configuration.model(name, provider: provider, display_name: display_name, limits: limits)
+			end
+			
+			# Set the default provider on the attached configuration.
+			# @parameter name [String | Symbol] The provider name.
+			def default_provider(name)
+				@configuration.default_provider = name
+			end
+		end
+	end
+end

data/lib/laiya/configuration.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "models/catalog"
+require_relative "models/discover"
+require_relative "configuration/builder"
+
+module Laiya
+	# Mutable provider and model routing configuration.
+	class Configuration
+		# Build a mutable configuration by evaluating a builder block.
+		# @yields {|builder| ...} The builder used to configure the new object.
+		# @parameter builder [Laiya::Configuration::Builder] The configuration DSL.
+		# @returns [Laiya::Configuration] The configured, mutable object.
+		def self.build(&block)
+			configuration = self.new
+			builder = Builder.new(configuration)
+			
+			if block
+				if block.arity.zero?
+					builder.instance_eval(&block)
+				else
+					block.call(builder)
+				end
+			end
+			
+			return configuration
+		end
+		
+		# Initialize an empty provider and model catalog.
+		def initialize
+			@providers = {}
+			@model_routes = {}
+			@model_sources = {}
+			@model_metadata = {}
+			@models = Models::Catalog.new(
+				routes: @model_routes,
+				sources: @model_sources,
+				metadata: @model_metadata,
+			)
+			@default_provider = nil
+		end
+		
+		attr :providers
+		attr :models
+		attr :default_provider
+		
+		# Register a provider and optionally a model source.
+		# @parameter name [String | Symbol] The provider's routing name.
+		# @parameter instance [Interface(:call)] The provider implementation.
+		# @option :models [Symbol | Interface(:each, :find) | Nil] The model source or `:discover`.
+		# @raises [ArgumentError] If the provider or model source is invalid.
+		def provider(name, instance, models: nil)
+			name = name.to_sym
+			raise ArgumentError, "Provider #{name.inspect} is already configured" if @providers.key?(name)
+			
+			unless instance.respond_to?(:call)
+				raise ArgumentError, "Provider #{name.inspect} must respond to #call"
+			end
+			
+			case models
+			when nil, :configured
+				# Model routes will be configured separately with #model.
+			when :discover
+				@model_sources[name] = Models::Discover.new(instance)
+			else
+				unless models.respond_to?(:each) && models.respond_to?(:find)
+					raise ArgumentError, "Model source for provider #{name.inspect} must implement #each and #find"
+				end
+				
+				@model_sources[name] = models
+			end
+			
+			@providers[name] = instance
+		end
+		
+		# Route a model ID to a configured provider and attach optional metadata.
+		# @parameter name [String | Symbol] The model ID.
+		# @parameter provider [String | Symbol] The provider name.
+		# @option :display_name [String | Nil] A human-readable model name.
+		# @option :limits [Hash | Nil] Positive context, input, and output token limits.
+		# @raises [ArgumentError] If the provider, model ID, or limits are invalid.
+		def model(name, provider:, display_name: nil, limits: nil)
+			provider = provider.to_sym
+			unless @providers.key?(provider)
+				raise ArgumentError, "Provider #{provider.inspect} for model #{name.inspect} is not configured"
+			end
+			
+			name = name.to_s
+			raise ArgumentError, "Model #{name.inspect} is already configured" if @model_routes.key?(name)
+			
+			metadata = {}
+			metadata["name"] = display_name.to_s if display_name
+			metadata["limits"] = normalize_limits(limits) if limits
+			
+			@model_routes[name] = provider
+			@model_metadata[name] = metadata.freeze unless metadata.empty?
+		end
+		
+		# Set the provider used when no explicit or discovered route matches.
+		# @parameter name [String | Symbol | Nil] The provider name, or `nil` to clear the default.
+		# @raises [ArgumentError] If the provider is not configured.
+		def default_provider=(name)
+			name = name&.to_sym
+			if name && !@providers.key?(name)
+				raise ArgumentError, "Default provider #{name.inspect} is not configured"
+			end
+			
+			@default_provider = name
+		end
+		
+		# Find the provider instance that serves a model ID.
+		# @parameter model [String | Nil] The model ID to route.
+		# @returns [Interface(:call) | Nil] The matching provider, if any.
+		def provider_for_model(model)
+			if name = @models.provider_for(model, default_provider: @default_provider)
+				return @providers.fetch(name)
+			end
+		end
+		
+		# Freeze configuration-owned state and finalize this object.
+		# @returns [Laiya::Configuration] This frozen configuration.
+		def freeze
+			return self if frozen?
+			
+			@providers.freeze
+			@models.freeze
+			
+			super
+		end
+		
+		private
+		
+		def normalize_limits(limits)
+			unless limits.is_a?(Hash)
+				raise ArgumentError, "Model limits must be a Hash"
+			end
+			
+			allowed = %w[context input output]
+			limits.each_with_object({}) do |(key, value), normalized|
+				key = key.to_s
+				unless allowed.include?(key) && value.is_a?(Integer) && value.positive?
+					raise ArgumentError, "Invalid model limit #{key.inspect}: #{value.inspect}"
+				end
+				
+				normalized[key] = value
+			end.freeze
+		end
+	end
+end

data/lib/laiya/environment/application.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/http"
+require "async/service/managed/environment"
+require_relative "../configuration"
+require_relative "../provider/openai"
+require_relative "../service/application"
+
+module Laiya
+	# @namespace
+	module Environment
+		# Default Async::Service environment for the Laiya HTTP API.
+		module Application
+			include Async::Service::Managed::Environment
+			
+			# Return the service implementation class.
+			# @returns [Class] The Laiya service class.
+			def service_class
+				Laiya::Service::Application
+			end
+			
+			# Parse the HTTP bind endpoint from the environment.
+			# @returns [Async::HTTP::Endpoint] The configured endpoint.
+			def endpoint
+				Async::HTTP::Endpoint.parse(ENV.fetch("LAIYA_URL", "http://localhost:9292"))
+			end
+			
+			# Run one Laiya service instance.
+			# @returns [Integer] The desired service count.
+			def count
+				1
+			end
+			
+			# Build the default OpenAI-backed configuration.
+			# @returns [Laiya::Configuration] The service configuration.
+			def configuration
+				Laiya::Configuration.build do |builder|
+					builder.provider :openai, Laiya::Provider::OpenAI.new
+					builder.default_provider :openai
+				end
+			end
+			
+			# Build the HTTP application for this environment.
+			# @returns [Laiya::Web::Application] The configured API application.
+			def application
+				Laiya::Web::Application.new(configuration: self.configuration)
+			end
+		end
+	end
+end

data/lib/laiya/models/catalog.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Laiya
+	module Models
+		# Read-only view of configured and provider-backed model catalogs.
+		class Catalog
+			# Build a catalog view over configuration-owned model data.
+			# @parameter routes [Hash(String, Symbol)] Explicit model routes.
+			# @parameter sources [Hash(Symbol, Interface(:each, :find))] Provider discovery sources.
+			# @parameter metadata [Hash(String, Hash)] Metadata for explicit model routes.
+			def initialize(routes:, sources:, metadata:)
+				@routes = routes
+				@sources = sources
+				@metadata = metadata
+			end
+			
+			attr :routes
+			attr :sources
+			attr :metadata
+			
+			# Check whether the catalog contains routes or discovery sources.
+			# @returns [Boolean] `true` when the catalog is empty.
+			def empty?
+				@routes.empty? && @sources.empty?
+			end
+			
+			# Check whether the catalog has any provider discovery sources.
+			# @returns [Boolean] `true` when discovery is configured.
+			def discover?
+				!@sources.empty?
+			end
+			
+			# Resolve the provider name for a model, using the default as fallback.
+			# @parameter model [String | Nil] The model ID to look up.
+			# @option :default_provider [Symbol | Nil] The fallback provider name.
+			# @returns [Symbol | Nil] The selected provider name.
+			def provider_for(model, default_provider: nil)
+				return @routes[model] if @routes.key?(model)
+				
+				if model
+					matches = @sources.filter_map do |provider, source|
+						provider if source.find(model)
+					end
+					
+					return default_provider if matches.include?(default_provider)
+					return matches.first unless matches.empty?
+				end
+				
+				return default_provider
+			end
+			
+			# Enumerate explicit and discovered models without duplicate IDs.
+			# @option :default_provider [Symbol | Nil] The preferred owner of duplicate IDs.
+			# @yields {|model| ...} Each model entry in OpenAI model-list format.
+			#  @parameter model [Hash] A model-list entry.
+			# @returns [Enumerator | Nil] An enumerator without a block, otherwise `nil`.
+			def each(default_provider: nil, &block)
+				return to_enum(__method__, default_provider: default_provider) unless block
+				
+				models = {}
+				owners = {}
+				
+				@routes.each do |id, provider|
+					models[id] = {
+						"id" => id,
+						"object" => "model",
+						"created" => 0,
+						"owned_by" => provider.to_s,
+					}.tap do |entry|
+						if metadata = @metadata[id]
+							entry["laiya"] = metadata
+						end
+					end
+					owners[id] = provider
+				end
+				
+				@sources.each do |provider, source|
+					source.each do |model|
+						id = model["id"]
+						next unless id.is_a?(String) && !id.empty?
+						next if @routes.key?(id)
+						next if owners.key?(id) && provider != default_provider
+						
+						models[id] = model.merge("owned_by" => provider.to_s)
+						owners[id] = provider
+					end
+				end
+				
+				models.each_value(&block)
+			end
+			
+			# Freeze the catalog and its shared configuration data.
+			# @returns [Laiya::Models::Catalog] This frozen catalog.
+			def freeze
+				return self if frozen?
+				
+				@routes.freeze
+				@sources.freeze
+				@metadata.freeze
+				
+				super
+			end
+		end
+	end
+end

data/lib/laiya/models/discover.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "json"
+
+module Laiya
+	# Model catalog sources.
+	module Models
+		# Discovers models from an OpenAI-compatible provider and caches its catalog.
+		# Subclasses can filter or enrich entries by overriding #include_model? and #normalize_model.
+		class Discover
+			DEFAULT_TTL = 60
+			
+			# Initialize a cached model source for an upstream provider.
+			# @parameter provider [Interface(:models)] The provider to query.
+			# @option :ttl [Numeric] How long to cache the model list, in seconds.
+			def initialize(provider, ttl: DEFAULT_TTL)
+				@provider = provider
+				@ttl = ttl
+				@lock = Async::Semaphore.new(1)
+				@models = nil
+				@expires_at = 0
+			end
+			
+			attr :provider
+			
+			# Enumerate the normalized, cached model list.
+			# @yields {|model| ...} Each discovered model.
+			#  @parameter model [Hash] A normalized model entry.
+			# @returns [Enumerator | Nil] An enumerator without a block, otherwise `nil`.
+			def each(&block)
+				return enum_for(__method__) unless block
+				
+				self.all.each(&block)
+			end
+			
+			# Find one model by its upstream ID.
+			# @parameter id [String] The model ID.
+			# @returns [Hash | Nil] The matching model entry, if present.
+			def find(id)
+				self.all.find{|model| model["id"] == id}
+			end
+			
+			# Fetch and cache the provider's normalized model catalog.
+			# @returns [Array(Hash)] The cached model entries.
+			def all
+				if @models && Process.clock_gettime(Process::CLOCK_MONOTONIC) < @expires_at
+					return @models
+				end
+				
+				@lock.acquire do
+					now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+					next @models if @models && now < @expires_at
+					
+					@models = fetch_models.freeze
+					@expires_at = now + @ttl
+				end
+				
+				return @models
+			end
+			
+			protected
+			
+			def include_model?(model)
+				model.is_a?(Hash) && model["id"].is_a?(String) && !model["id"].empty?
+			end
+			
+			def normalize_model(model)
+				result = model.dup
+				result["object"] ||= "model"
+				result["created"] ||= 0
+				return result.freeze
+			end
+			
+			private
+			
+			def fetch_models
+				response = @provider.models
+				unless response.status >= 200 && response.status < 300
+					status = response.status
+					response.close
+					raise Error, "Model discovery failed with HTTP #{status}"
+				end
+				
+				begin
+					payload = JSON.parse(response.read)
+					data = payload.fetch("data")
+					unless data.is_a?(Array)
+						raise Error, "Model discovery returned an invalid catalog"
+					end
+					
+					return data.filter_map do |model|
+						self.normalize_model(model) if self.include_model?(model)
+					end
+				rescue JSON::ParserError, KeyError
+					raise Error, "Model discovery returned an invalid catalog"
+				ensure
+					response.close
+				end
+			end
+			
+			# Raised when an upstream model catalog is unavailable or invalid.
+			class Error < StandardError
+			end
+		end
+	end
+end