little_ghost 0.1.0 → 0.2.0

data/lib/little_ghost/errors.rb

@@ -5,6 +5,12 @@ module LittleGhost
   class Error < StandardError; end
   # Raised for invalid framework or application configuration.
   class ConfigurationError < Error; end
+  # Raised when an abstract framework method has no concrete implementation.
+  class AbstractMethodError < Error; end
+  # Raised when a configured provider adapter cannot be constructed.
+  class AdapterLoadError < ConfigurationError; end
+  # Raised when no usable credentials can be resolved for a provider.
+  class CredentialError < ConfigurationError; end
   # Raised when an invocation payload or operation is invalid.
   class InvocationError < Error; end
   # Raised when an invocation contains an unsupported input form.

data/lib/little_ghost/invocation.rb

@@ -33,12 +33,11 @@ module LittleGhost
       "history" => -> { [] },
       "settings" => -> { {} },
       "context" => -> { {} },
-      "metadata" => -> { {} },
-      "model_profiles" => -> { {} }
+      "metadata" => -> { {} }
     }.freeze # :nodoc:
 
     ACCESSORS = %i[
-      message history settings context metadata model_profiles
+      message history settings context metadata
       run_id invocation_id session_id actor_id
     ].freeze # :nodoc:
 
@@ -88,14 +87,6 @@ module LittleGhost
     # :call-seq:
     #   metadata() -> Hash
 
-    ##
-    # Per-request overrides for logical model profiles. Overrides can select a
-    # provider and model, so applications must construct or allowlist them at a
-    # trusted control-plane boundary.
-    # :method: model_profiles
-    # :call-seq:
-    #   model_profiles() -> Hash
-
     ##
     # The caller-supplied or generated top-level run identifier.
     # :method: run_id
@@ -138,12 +129,6 @@ module LittleGhost
     # :call-seq:
     #   metadata=(value) -> value
 
-    ##
-    # Replaces the trusted per-request model profile overrides.
-    # :method: model_profiles=
-    # :call-seq:
-    #   model_profiles=(value) -> value
-
     ##
     # Replaces the top-level run identifier.
     # :method: run_id=

data/lib/little_ghost/model.rb

@@ -1,84 +1,104 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  # Model is the configured connection between an agent role and a provider. It
-  # keeps provider choice and defaults out of the agent class that uses them.
+  # Interface for executable model implementations accepted by agents.
+  module ModelInterface
+    # Canonical physical provider and model identifier.
+    def target = Models::Target.parse("custom:#{self.class.name || "anonymous"}")
+    # Provider-owned model identifier without the connection name.
+    def model_id = target.model_id
+    # Logical application role that selected this model, when available.
+    def role = nil
+    # Immutable capabilities, limits, modalities, and pricing facts.
+    def details = Models::Details.new(target:)
+    # Normalized feature support used for request strategy selection.
+    def capabilities = ModelCapabilities.permissive
+  end
+
+  # Model is the resolved connection between an agent selection and a provider.
+  # It keeps provider behavior behind one executable interface whether an agent
+  # selected a role, canonical target, or inline configuration.
   #
   # It merges profile settings into every ModelRequest, validates attachment
   # modalities declared in metadata, lets providers prepare capability-sensitive
   # requests, and delegates the normalized stream to the provider.
   class Model
-    IDENTITY_METADATA_KEYS = %w[provider model_id model_role].freeze # :nodoc:
+    include ModelInterface
 
-    # Provider object and name, provider model ID, default settings, normalized
-    # metadata, and logical application role.
-    attr_reader :provider, :provider_name, :id, :settings, :metadata, :role
+    # Provider object, canonical target, default settings, normalized model
+    # details, and logical application role.
+    attr_reader :provider, :target, :settings, :details, :role
 
-    # Wraps an object that responds to +stream+.
-    def initialize(provider:, provider_name:, id: nil, model: nil, settings: {}, metadata: {}, role: nil)
-      raise ArgumentError, "provider must respond to stream" unless provider.respond_to?(:stream)
-      raise ArgumentError, "provider_name is required" if provider_name.nil? || provider_name.to_s.empty?
-      raise ArgumentError, "model is required" if (id || model).nil? || (id || model).to_s.empty?
+    # Connects a provider adapter to its canonical +target+, profile +settings+,
+    # optional model +details+, and logical +role+.
+    def initialize(provider:, target:, settings: {}, details: nil, role: nil)
+      raise ArgumentError, "provider must be a LittleGhost::Providers::Base" unless provider.is_a?(Providers::Base)
 
       @provider = provider
-      @provider_name = provider_name.to_sym
-      @id = (id || model)&.to_s
+      @target = Models::Target.parse(target)
       @settings = settings.to_h.transform_keys(&:to_sym).freeze
       @role = role&.to_s
-      profile_metadata = metadata.to_h.reject { |key, _value| IDENTITY_METADATA_KEYS.include?(key.to_s) }
-      @metadata = profile_metadata.merge(
-        provider: @provider_name,
-        model_id: @id,
-        model_role: @role
-      ).freeze
+      @details = details || Models::Details.new(target: @target)
     end
 
+    # Provider-owned identifier from the canonical target.
+    def model_id = target.model_id
+
     # Streams +request+ through the configured provider.
     #
     # Profile settings are defaults; settings on +request+ take precedence.
     def stream(request, &block)
       validate_input_modalities!(request)
+      configured_settings = settings.merge(request.settings)
+      configured_max_tokens = if request.settings.key?(:max_tokens)
+        request.settings[:max_tokens]
+      elsif request.settings.key?("max_tokens")
+        request.settings["max_tokens"]
+      else
+        settings[:max_tokens] || settings["max_tokens"]
+      end
+      if configured_max_tokens && details.max_output_tokens
+        configured_settings.delete(:max_tokens)
+        configured_settings.delete("max_tokens")
+        configured_settings[:max_tokens] = [configured_max_tokens, details.max_output_tokens].min
+      end
       configured_request = ModelRequest.new(
         messages: request.messages,
         tools: request.tools,
-        settings: settings.merge(request.settings),
+        settings: configured_settings,
         output_schema: request.output_schema,
         tool_choice: request.tool_choice,
         required_capabilities: request.required_capabilities,
         cancellation_token: request.cancellation_token,
         deadline: request.deadline
       )
-      if provider.respond_to?(:prepare_request)
-        configured_request = provider.prepare_request(configured_request, capabilities:)
-      end
+      configured_request = provider.prepare_request(configured_request, capabilities:)
       provider.stream(configured_request, &block)
     end
 
-    # Uses advertised provider capabilities, falling back to the permissive legacy
-    # contract for providers that do not advertise them.
+    # Uses advertised provider capabilities.
     def capabilities
-      @capabilities ||= if provider.respond_to?(:capabilities)
-        provider.capabilities(metadata:)
-      else
-        ModelCapabilities.legacy
-      end
+      @capabilities ||= provider.capabilities(metadata: details.attributes)
     end
 
     private
 
     def validate_input_modalities!(request)
-      supported = metadata[:input_modalities] || metadata["input_modalities"]
+      supported = details.input_modalities
       return unless supported
 
       required = request.messages.flat_map do |message|
         message.content.filter_map do |block|
           case block
           when Content::Image then "image"
-          when Content::Document then "file"
+          when Content::Document then (block.media_type == "application/pdf") ? "pdf" : "file"
           end
         end
       end.uniq
-      missing = required - Array(supported).map { |value| value.to_s.downcase }
+      available = Array(supported).map { |value| value.to_s.downcase }
+      missing = required.reject do |modality|
+        available.include?(modality) || (modality == "pdf" && available.include?("file"))
+      end
       return if missing.empty?
 
       raise UnsupportedInputError,

data/lib/little_ghost/model_capabilities.rb

@@ -45,8 +45,9 @@ module LittleGhost
       names.flatten.any? { |name| supported_parameters.include?(name.to_s) }
     end
 
-    # Supplies the backwards-compatible capability set for legacy providers.
-    def self.legacy
+    # Supplies a permissive capability set when a provider accepts every
+    # optional model feature.
+    def self.permissive
       new(native_structured_output: true, tools: true, tool_choice: true)
     end
 
@@ -115,9 +116,9 @@ module LittleGhost
     # capability set supports every name.
 
     ##
-    # :singleton-method: legacy
-    # Supplies the permissive capability set for providers that predate explicit
-    # capability reporting.
+    # :singleton-method: permissive
+    # Supplies a permissive capability set for providers that accept every
+    # optional model feature.
 
     ##
     # :singleton-method: unknown

data/lib/little_ghost/model_resolver.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Resolves logical profiles, canonical +provider:model-id+ targets, and inline
+  # model mappings into executable Model objects. Subclasses may override
+  # #resolve, #details, or #refresh! while preserving those public signatures.
+  class ModelResolver
+    DEFAULT_CREDENTIALS = [ # :nodoc:
+      ["LITTLEGHOST_OPENROUTER_API_KEY", "openrouter"],
+      ["LITTLEGHOST_OPENAI_API_KEY", "openai"],
+      ["OPENROUTER_API_KEY", "openrouter"],
+      ["OPENAI_API_KEY", "openai"]
+    ].freeze
+    DEFAULT_MODELS = { # :nodoc:
+      "openrouter" => "openai/gpt-5.6-luna",
+      "openai" => "gpt-5.6-luna"
+    }.freeze
+
+    # Provider configuration and model metadata catalog.
+    attr_reader :providers, :catalog
+
+    # Builds a resolver from explicit provider connections and profiles. With
+    # neither, conventional credentials select GPT-5.6 Luna.
+    def initialize(providers: nil, profiles: nil, default_model: nil, provider_registry: ProviderRegistry.new,
+      catalog: nil, catalog_sources: [], provider_adapters: {}, credential_resolver: nil)
+      unless providers.nil? || providers.is_a?(Providers::Configuration)
+        raise ArgumentError, "providers must be a LittleGhost::Providers::Configuration"
+      end
+
+      @providers = providers
+      @connections = providers&.connections || {}
+      @profiles = normalize_profiles(profiles || {})
+      @default_model = default_model&.to_s || "default"
+      @provider_registry = provider_adapters.empty? ? provider_registry : ProviderRegistry.new(adapters: provider_adapters)
+      @credential_resolver = credential_resolver
+      configure_default_providers unless providers
+      configure_default_profiles unless profiles
+      sources = catalog_sources.empty? ? built_in_catalog_sources : catalog_sources
+      @catalog = catalog || Models::Catalog.new(sources:)
+    end
+
+    # Logical role used when an agent does not declare one.
+    attr_reader :default_model
+
+    # Resolves a logical role, canonical target, or inline model mapping into an
+    # executable Model. Inline mappings require +provider+ and +model+; remaining
+    # entries are trusted model settings. The optional +profiles+ mapping applies
+    # only to role selections and is never read from +invocation+.
+    def resolve(selection, invocation: nil, context: nil, profiles: nil, **options)
+      base, role = normalize_selection(selection)
+      if role
+        base = resolved_role(role)
+        profile_overlays = profiles || {}
+        override_names(role).each do |profile|
+          base = merge(base, profile_overlays[profile] || profile_overlays[profile.to_sym])
+        end
+      end
+      target = Models::Target.parse(base.fetch(:target))
+      provider_config = @connections.fetch(target.provider) do
+        raise ConfigurationError, "Model target references unknown provider #{target.provider}"
+      end
+      provider_config = provider_config.merge(resolved_credentials(target.provider, provider_config)) if @credential_resolver
+      details = details_for(target, base[:details])
+      settings = clamp_output_tokens(base.fetch(:settings), details)
+      adapter = provider_config.fetch("adapter")
+      provider = @provider_registry.build(
+        adapter:,
+        model: target.model_id,
+        configuration: provider_config,
+        request: base.fetch(:request),
+        role:,
+        settings:,
+        details:,
+        invocation:,
+        context:,
+        **options
+      )
+      Model.new(provider:, target:, settings:, details:, role:)
+    end
+
+    # Returns normalized metadata for +target+ without constructing a provider.
+    def details(target) = catalog.details(target)
+    # Refreshes configured metadata sources, retaining stale data on failure.
+    def refresh!(target: nil) = catalog.refresh!(target:)
+
+    private
+
+    def resolved_credentials(provider, configuration)
+      values = @credential_resolver.call(
+        provider:,
+        adapter: configuration.fetch("adapter"),
+        configuration: configuration.dup.freeze
+      )
+      raise CredentialError, "Credential resolver for #{provider} must return a mapping" unless values.is_a?(Hash)
+
+      values.to_h { |key, value| [key.to_s, value] }
+    end
+
+    def details_for(target, snapshot)
+      return details(target) unless snapshot
+
+      values = snapshot.to_h.transform_keys(&:to_sym)
+      snapshot_target = Models::Target.parse(values.delete(:target) || target)
+      raise ConfigurationError, "Model details target must match #{target}" unless snapshot_target == target
+
+      Models::Details.new(
+        target:,
+        attributes: values.except(:provenance, :observed_at),
+        provenance: values[:provenance] || {},
+        observed_at: values[:observed_at]
+      )
+    end
+
+    def clamp_output_tokens(settings, details)
+      configured = settings[:max_tokens]
+      advertised = details.max_output_tokens
+      return settings unless configured && advertised
+
+      settings.merge(max_tokens: [configured, advertised].min)
+    end
+
+    def built_in_catalog_sources
+      adapters = @connections.to_h { |name, values| [name, values["adapter"].to_s] }
+      sources = [Models::Catalog::ModelsDevSource.new(provider_adapters: adapters)]
+      @connections.each do |name, values|
+        credentials = -> { catalog_credentials(name, values) }
+        case values["adapter"].to_s
+        when "openrouter"
+          sources << Providers::OpenRouter::CatalogSource.new(provider: name, credential_resolver: credentials)
+        when "anthropic"
+          sources << Providers::Anthropic::CatalogSource.new(provider: name, credential_resolver: credentials)
+        when "gemini"
+          sources << Providers::Gemini::CatalogSource.new(provider: name, credential_resolver: credentials)
+        when "bedrock"
+          resolver = values["credential_resolver"] || bedrock_credential_resolver(name, values)
+          region = values["region"] || (resolver.region if resolver.is_a?(Providers::Bedrock::CredentialResolver))
+          sources << Providers::Bedrock::CatalogSource.new(provider: name, region:, credential_resolver: resolver) if region
+        end
+      end
+      sources
+    end
+
+    def catalog_credentials(provider, configuration)
+      return configuration unless @credential_resolver
+
+      configuration.merge(resolved_credentials(provider, configuration))
+    end
+
+    def bedrock_credential_resolver(provider, configuration)
+      return Providers::Bedrock::CredentialResolver.new unless @credential_resolver
+
+      fallback = Providers::Bedrock::CredentialResolver.new
+      lambda do
+        values = catalog_credentials(provider, configuration)
+        next values["credentials"] if values["credentials"]
+
+        access_key_id = values["access_key_id"] || values["aws_access_key_id"]
+        secret_access_key = values["secret_access_key"] || values["aws_secret_access_key"]
+        if access_key_id || secret_access_key
+          Providers::Bedrock::Credentials.new(
+            access_key_id:,
+            secret_access_key:,
+            session_token: values["session_token"] || values["aws_session_token"]
+          )
+        else
+          fallback.call
+        end
+      end
+    end
+
+    def configure_default_providers
+      connections = DEFAULT_CREDENTIALS.each_with_object({}) do |(variable, provider), configured|
+        next if configured.key?(provider) || ENV[variable].to_s.strip.empty?
+
+        configured[provider] = {"adapter" => provider, "api_key" => ENV.fetch(variable)}
+      end
+      if connections.any?
+        @connections = connections
+      else
+        @connections = {"unconfigured" => {"adapter" => "unconfigured"}}
+        missing = "No API key is configured for the default model. Set #{DEFAULT_CREDENTIALS.map(&:first).join(", ")}, configure providers inline, or add config/little_ghost/providers.yml."
+        @provider_registry = ProviderRegistry.new(adapters: {
+          "unconfigured" => ->(**) { raise CredentialError, missing }
+        })
+      end
+    end
+
+    def configure_default_profiles
+      connection, values = @connections.find { |_name, options| DEFAULT_MODELS.key?(options["adapter"].to_s) }
+      @profiles = if connection
+        {"default" => {"target" => "#{connection}:#{DEFAULT_MODELS.fetch(values["adapter"].to_s)}"}}
+      else
+        {"default" => {"target" => "unconfigured:#{DEFAULT_MODELS.fetch("openai")}"}}
+      end
+    end
+
+    def normalize_selection(selection)
+      case selection
+      when Hash
+        [inline_selection(selection), nil]
+      when String, Symbol
+        value = selection.to_s
+        value.include?(":") ? [{target: value, settings: {}, request: {}}, nil] : [nil, value]
+      else
+        raise ConfigurationError, "Model selection must be a role, provider:model target, or configuration mapping"
+      end
+    end
+
+    def inline_selection(selection)
+      values = selection.to_h do |key, value|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise ConfigurationError, "Inline model configuration keys must be strings or symbols"
+        end
+
+        [key.to_sym, immutable_selection_value(value)]
+      end
+      provider = values.delete(:provider)
+      model_id = values.delete(:model)
+      raise ConfigurationError, "Inline model configuration requires provider" if provider.to_s.strip.empty?
+      raise ConfigurationError, "Inline model configuration requires model" if model_id.to_s.strip.empty?
+
+      {
+        target: Models::Target.new(provider:, model_id:),
+        settings: values.freeze,
+        request: {}
+      }
+    end
+
+    def immutable_selection_value(value)
+      case value
+      when Hash
+        value.to_h { |key, child| [key, immutable_selection_value(child)] }.freeze
+      when Array
+        value.map { |child| immutable_selection_value(child) }.freeze
+      when String
+        value.dup.freeze
+      else
+        value
+      end
+    end
+
+    def resolved_role(role)
+      profile_name = profile_for(role)
+      resolved_profile(profile_name)
+    end
+
+    def normalize_profiles(profiles)
+      raise ConfigurationError, "models must be a mapping" unless profiles.is_a?(Hash)
+
+      profiles.to_h do |name, profile|
+        role = name.to_s
+        validate_role_name!(role)
+        raise ConfigurationError, "models.#{role} must be a mapping" unless profile.is_a?(Hash)
+
+        parent = profile["inherits"] || profile[:inherits]
+        validate_role_name!(parent.to_s) if parent
+        [role, profile.to_h]
+      end
+    end
+
+    def validate_role_name!(role)
+      return unless role.include?(":")
+
+      raise ConfigurationError, "Model role names cannot contain ':' (#{role})"
+    end
+
+    def profile_for(role)
+      parts = role.split(".")
+      until parts.empty?
+        name = parts.join(".")
+        return name if @profiles.key?(name)
+        parts.pop
+      end
+      raise ConfigurationError, "Unknown model profile: #{role}"
+    end
+
+    def resolved_profile(name, seen = [])
+      raise ConfigurationError, "Circular model profile inheritance: #{[*seen, name].join(" -> ")}" if seen.include?(name)
+
+      raw = @profiles.fetch(name)
+      profile = normalize(raw)
+      parent_name = raw["inherits"] || raw[:inherits]
+      return profile unless parent_name
+
+      merge(resolved_profile(parent_name.to_s, [*seen, name]), profile)
+    end
+
+    def normalize(value)
+      values = value.to_h.transform_keys(&:to_sym)
+      {
+        target: values[:target],
+        settings: values.fetch(:settings, {}).to_h.transform_keys(&:to_sym),
+        request: values.fetch(:request, {}).to_h.transform_keys(&:to_sym),
+        details: values[:details]
+      }.compact
+    end
+
+    def merge(base, override)
+      return base unless override
+
+      values = normalize(override)
+      base.merge(values).merge(
+        target: values[:target] || base[:target],
+        settings: base.fetch(:settings, {}).merge(values.fetch(:settings, {})),
+        request: base.fetch(:request, {}).merge(values.fetch(:request, {}))
+      )
+    end
+
+    def override_names(role)
+      names = []
+      parts = role.split(".")
+      1.upto(parts.length) { |length| names << parts.first(length).join(".") }
+      names
+    end
+  end
+end

data/lib/little_ghost/models/catalog/models_dev_source.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module LittleGhost
+  module Models
+    class Catalog
+      MAX_CATALOG_BYTES = 25 * 1024 * 1024 # :nodoc:
+
+      # Refreshes normalized facts from the public models.dev catalog.
+      class ModelsDevSource < Source
+        URL = URI("https://models.dev/api.json") # :nodoc:
+        NAMESPACES = { # :nodoc:
+          "openai" => "openai", "openrouter" => "openrouter", "anthropic" => "anthropic",
+          "gemini" => "google", "vertex_ai" => "google-vertex", "bedrock" => "amazon-bedrock"
+        }.freeze
+
+        # Creates a source that maps application provider names to adapters.
+        def initialize(provider_adapters:)
+          super(name: "models.dev")
+          @provider_adapters = provider_adapters.to_h.transform_keys(&:to_s)
+        end
+
+        # Fetches normalized model facts, optionally for one canonical +target+.
+        def refresh(target: nil)
+          document = JSON.parse(
+            Support::HTTPClient.new(open_timeout: 5, read_timeout: 30, max_response_bytes: MAX_CATALOG_BYTES)
+              .request(uri: URL)
+          )
+          providers = target ? [target.provider] : @provider_adapters.keys
+          providers.each_with_object({}) do |provider, result|
+            namespace = NAMESPACES[@provider_adapters[provider]]
+            next unless namespace && document[namespace]
+
+            models = document.fetch(namespace).fetch("models")
+            selected = target ? models.slice(target.model_id) : models
+            selected.each { |id, value| result["#{provider}:#{id}"] = normalize(value) }
+          end
+        rescue JSON::ParserError, KeyError => error
+          raise ProviderError, "models.dev returned an invalid catalog: #{error.message}"
+        end
+
+        private
+
+        def normalize(value)
+          parameters = []
+          parameters << "tools" if value["tool_call"]
+          parameters << "structured_outputs" if value["structured_output"]
+          parameters << "temperature" if value["temperature"]
+          parameters << "reasoning" if value["reasoning"]
+          {
+            context_window: value.dig("limit", "context"), max_output_tokens: value.dig("limit", "output"),
+            input_modalities: value.dig("modalities", "input"), output_modalities: value.dig("modalities", "output"),
+            supported_parameters: parameters.empty? ? nil : parameters, pricing: value["cost"],
+            observed_at: value["last_updated"] || value["release_date"]
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/models/catalog/source.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module Models
+    class Catalog
+      # Interface for catalog refresh implementations.
+      class Source
+        DEFAULT_ATTRIBUTE_MERGE_STRATEGIES = {}.freeze # :nodoc:
+
+        # Stable provenance name recorded for refreshed facts.
+        attr_reader :name
+
+        # Creates a source with its provenance +name+.
+        def initialize(name:)
+          @name = name.to_s.freeze
+        end
+
+        # Returns exceptional attribute merge strategies for records from this
+        # source. Attributes replace older values unless an array is mapped to
+        # +:union+.
+        def attribute_merge_strategies = DEFAULT_ATTRIBUTE_MERGE_STRATEGIES
+
+        # Returns normalized model records, optionally scoped to +target+.
+        def refresh(target: nil)
+          raise AbstractMethodError, "#{self.class} must implement #refresh"
+        end
+      end
+    end
+  end
+end