little_ghost 0.1.0 → 0.2.1

data/lib/little_ghost/agent.rb

@@ -35,12 +35,12 @@ module LittleGhost
   # Capabilities such as skills, context management, loop detection, and
   # delegation remain inactive until their DSL methods are called.
   #
-  # The class-level +ask+ helper creates a standalone entrypoint and returns a
-  # completed Run. Create a standalone instance explicitly to reuse one Runtime
-  # or call +stream_ask+ for StreamEvent objects. Runtimes build bound instances
-  # internally; their +call+ method returns a RunResult and their +stream+ method
-  # follows the owning run's single-execution lifecycle. Closing an agent closes
-  # owned tools and any standalone workspace and sandbox.
+  # The class-level +ask+ and +stream_ask+ helpers create fresh standalone
+  # entrypoints. Create an instance explicitly to reuse one Runtime across
+  # calls. Runtimes build bound instances internally; their +call+ method
+  # returns a RunResult and their +stream+ method follows the owning run's
+  # single-execution lifecycle. Closing an agent closes owned tools and any
+  # standalone workspace and sandbox.
   # LittleGhost::Agent.ask uses <tt>You are a helpful agent.</tt> as its system
   # prompt. Subclasses continue to use their inline or conventional prompts.
   #
@@ -89,6 +89,19 @@ module LittleGhost
         new.ask(message, **options)
       end
 
+      # Streams +message+ through a fresh standalone entrypoint and returns an
+      # Enumerator of LittleGhost::StreamEvent objects. Invocation +options+
+      # are forwarded to #stream_ask.
+      #
+      # Create an instance explicitly when reusing one Runtime across calls.
+      def stream_ask(message, **options)
+        stream = nil
+        Enumerator.new do |events|
+          stream ||= new.stream_ask(message, **options)
+          stream.each { |event| events << event }
+        end
+      end
+
       # :call-seq:
       #   agent_id() -> String
       #   agent_id(value) -> String
@@ -121,23 +134,35 @@ module LittleGhost
       end
 
       # :call-seq:
-      #   model() -> String, Proc, nil
-      #   model(role) -> String
+      #   model() -> String, Symbol, Hash, Proc, nil
+      #   model(role_or_target) -> String, Symbol
+      #   model(provider:, model:, **settings) -> Hash
       #   model { |invocation| ... } -> Proc
       #
-      # The logical model role for this agent.
+      # Selects this agent's model by logical role, canonical
+      # <tt>provider:model-id</tt> target, or an inline mapping with +provider+,
+      # +model+, and trusted model settings. The provider names a configured
+      # connection, not necessarily its adapter.
       #
-      # Pass a block to choose a role from each Invocation at run time.
+      # Pass a block to choose any supported form from each Invocation at run
+      # time. Inline mappings use flat settings, for example:
+      #
+      #   model(provider: "openai", model: "gpt-5.6-luna", reasoning_effort: "high")
       def model(*values, &block)
         return model_value if values.empty? && !block
+        if block && !values.empty?
+          raise ArgumentError, "model accepts either one selection or a block"
+        end
+        if values.length > 1
+          raise ArgumentError, "model accepts one selection"
+        end
 
-        self.model_value = block || values.fetch(0).to_s
+        self.model_value = block || copy_model_selection(values.fetch(0))
       end
 
-      def model_role(invocation) # :nodoc:
+      def model_selection(invocation) # :nodoc:
         value = model_value
-        resolved = value.respond_to?(:call) ? value.call(invocation) : value
-        resolved&.to_s
+        value.is_a?(Proc) ? value.call(invocation) : value
       end
 
       # :call-seq:
@@ -350,6 +375,32 @@ module LittleGhost
 
       private
 
+      def copy_model_selection(value)
+        case value
+        when String
+          value.dup.freeze
+        when Symbol
+          value
+        when Hash
+          value.to_h { |key, child| [key, copy_model_selection_value(child)] }.freeze
+        else
+          raise ConfigurationError, "model must be a role, provider:model target, or configuration mapping"
+        end
+      end
+
+      def copy_model_selection_value(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key, copy_model_selection_value(child)] }.freeze
+        when Array
+          value.map { |child| copy_model_selection_value(child) }.freeze
+        when String
+          value.dup.freeze
+        else
+          value
+        end
+      end
+
       def validate_result_schema_keywords!(schema, path = "$")
         unsupported = schema.keys - RESULT_SCHEMA_KEYWORDS
         unless unsupported.empty?
@@ -455,9 +506,9 @@ module LittleGhost
 
     # Creates either a standalone entrypoint or a run-scoped agent.
     #
-    # Calling <tt>new</tt> without +model+ and +run+ creates the console-friendly
-    # standalone form. Runtime builders supply the remaining dependencies and
-    # apply class-level limits and declarations.
+    # Calling <tt>new</tt> without +model+ and +run+ creates the standalone form
+    # used by +ask+ and +stream_ask+. Runtime builders supply the remaining
+    # dependencies and apply class-level limits and declarations.
     def initialize(
       model: nil,
       runtime: nil,
@@ -563,7 +614,7 @@ module LittleGhost
       result
     end
 
-    # Console-friendly name for +#call+.
+    # Runs +message+ to completion through the standalone or run-scoped agent.
     def ask(message, **options)
       call(message, **options)
     end
@@ -690,7 +741,13 @@ module LittleGhost
       if @standalone
         raise ArgumentError, "input is required" if input.nil?
 
-        return build_run(entrypoint_payload(input, {})).each
+        return build_run(entrypoint_payload(input, {
+          history:,
+          context:,
+          settings:,
+          template_paths:,
+          deadline_at: deadline
+        }.compact)).each
       end
 
       raise ArgumentError, "input is required" if input.nil?
@@ -744,8 +801,19 @@ module LittleGhost
       end
     end
 
-    # Console-friendly name for +#stream+.
+    # Streams +message+ through the standalone or run-scoped agent.
+    # Standalone +options+ become Invocation fields; run-scoped options are
+    # forwarded to #stream.
     def stream_ask(message, **options)
+      if @standalone
+        options[:deadline_at] = options.delete(:deadline) if options.key?(:deadline)
+        stream = nil
+        return Enumerator.new do |events|
+          stream ||= build_run(entrypoint_payload(message, options)).each
+          stream.each { |event| events << event }
+        end
+      end
+
       stream(message, **options)
     end
 
@@ -1146,7 +1214,7 @@ module LittleGhost
               outcome: :completed,
               turn: turn + 1
             )
-            metadata = model.respond_to?(:metadata) ? model.metadata : {}
+            metadata = model.details.to_h.merge(model_role: model.role)
             finish_instrumentation(
               agent_handle,
               outcome: :completed,
@@ -1228,7 +1296,7 @@ module LittleGhost
         diagnostic: {exception: diagnostic_exception(error)},
         **usage_attributes(context.usage)
       )
-      metadata = model.respond_to?(:metadata) ? model.metadata : {}
+      metadata = model.details.to_h.merge(model_role: model.role)
       emit(events, :invocation_error, error:, usage: context.usage, metadata:)
       raise
     end
@@ -1874,7 +1942,7 @@ module LittleGhost
         outcome: :completed,
         turn:
       )
-      metadata = model.respond_to?(:metadata) ? model.metadata : {}
+      metadata = model.details.to_h.merge(model_role: model.role)
       finish_instrumentation(
         agent_handle,
         outcome: :completed,
@@ -1994,9 +2062,9 @@ module LittleGhost
 
     def model_attributes
       {
-        model_id: model.respond_to?(:id) ? model.id : nil,
-        model_role: model.respond_to?(:role) ? model.role : nil,
-        model_provider: model.respond_to?(:provider_name) ? model.provider_name : model.class.name
+        model_id: model.model_id,
+        model_role: model.role,
+        model_provider: model.target.provider
       }.compact
     end
 

data/lib/little_ghost/agent_builder.rb

@@ -171,7 +171,7 @@ module LittleGhost
 
     def close_tools(tools)
       Array(tools).reverse_each do |tool|
-        tool.close if tool.is_a?(Tool) && tool.respond_to?(:close)
+        tool.close if tool.is_a?(Tool)
       rescue
         nil
       end

data/lib/little_ghost/configuration.rb

@@ -8,7 +8,6 @@ module LittleGhost
   # instrumentation, and runtime hooks for an application.
   #
   #   LittleGhost.configure do |config|
-  #     config.models CustomerSupportModels
   #     config.default_model :customer_support
   #     config.service_name "support-api"
   #   end
@@ -30,7 +29,7 @@ module LittleGhost
   # not from an unverified request field.
   class Configuration
     FILE_LOAD_MUTEX = Mutex.new # :nodoc:
-    CONFIGURATION_KEYS = %i[invocation models default_model service_name].freeze # :nodoc:
+    CONFIGURATION_KEYS = %i[invocation service_name].freeze # :nodoc:
     DEFAULT_PROMPT_PATHS = ["app/prompts"].freeze # :nodoc:
     DEFAULT_SKILL_PATHS = ["app/skills"].freeze # :nodoc:
 
@@ -43,24 +42,6 @@ module LittleGhost
     #   invocation(value) -> value
 
     ##
-    # The model registry class or instance used to resolve logical roles. By
-    # default, +DefaultModelRegistry+ selects a built-in provider from supported
-    # environment variables.
-    #
-    # :method: models
-    # :call-seq:
-    #   models() -> value
-    #   models(value) -> value
-
-    ##
-    # The fallback logical model role for agents without an explicit role.
-    # Values are normalized to strings.
-    #
-    # :method: default_model
-    # :call-seq:
-    #   default_model() -> String, nil
-    #   default_model(value) -> String
-
     ##
     # The low-cardinality service name attached to instrumentation.
     #
@@ -72,7 +53,7 @@ module LittleGhost
       define_method(name) do |value = :__read__|
         return configuration_values[name] if value == :__read__
 
-        configuration_values[name] = (name == :default_model) ? value.to_s : value
+        configuration_values[name] = value
       end
     end
 
@@ -83,17 +64,12 @@ module LittleGhost
     #   invocation=(value) -> value
 
     ##
-    # Replaces the model registry declaration for subsequently built runtimes.
-    # :method: models=
+    # Replaces the model resolver declaration for subsequently built runtimes.
+    # :method: model_resolver=
     # :call-seq:
-    #   models=(value) -> value
+    #   model_resolver=(value) -> value
 
     ##
-    # Replaces the fallback logical model role and normalizes it to a String.
-    # :method: default_model=
-    # :call-seq:
-    #   default_model=(value) -> String
-
     ##
     # Replaces the service name attached to telemetry from new runtimes.
     # :method: service_name=
@@ -124,6 +100,9 @@ module LittleGhost
         @configuration_values[:instrumentation_subscribers]
       ).dup
       @configuration_values[:runtime_hooks] = Array(@configuration_values[:runtime_hooks]).dup
+      @configuration_values[:provider_adapters] = @configuration_values.fetch(:provider_adapters, {}).dup
+      @configuration_values[:catalog_sources] = Array(@configuration_values[:catalog_sources]).dup
+      @configuration_values[:provider_credentials] ||= nil
     end
 
     # Yields this builder for setup and returns the same instance.
@@ -139,6 +118,153 @@ module LittleGhost
     # Session-store declaration used for subsequently built runtimes.
     def session_store = configuration_values[:session_store]
 
+    # Trusted provider connections for the default or custom resolver.
+    def providers(value = :__read__)
+      return configuration_values[:providers] if value == :__read__
+
+      unless value.is_a?(Hash) || value.is_a?(Providers::Configuration)
+        raise ArgumentError, "providers must be a Hash or LittleGhost::Providers::Configuration"
+      end
+
+      configuration_values[:providers] = value
+      reset_model_resolver
+      value
+    end
+
+    # Replaces trusted provider connections for subsequently built runtimes.
+    def providers=(value)
+      providers(value)
+    end
+
+    # Logical model profiles for the default resolver. Role names cannot contain
+    # a colon because that syntax identifies a canonical model target.
+    def models(value = :__read__)
+      return configuration_values[:models] if value == :__read__
+      raise ArgumentError, "models must be a Hash" unless value.is_a?(Hash)
+
+      configuration_values[:models] = value
+      reset_model_resolver
+      value
+    end
+
+    # Replaces logical model profiles for subsequently built runtimes.
+    def models=(value)
+      models(value)
+    end
+
+    # Fallback logical role for the default resolver.
+    def default_model(value = :__read__)
+      return configuration_values[:default_model] if value == :__read__
+
+      configuration_values[:default_model] = value.to_s
+      reset_model_resolver
+      value.to_s
+    end
+
+    # Replaces the fallback logical role and normalizes it to a String.
+    def default_model=(value)
+      default_model(value)
+    end
+
+    # Provider YAML path. The conventional path is optional; an explicitly set
+    # path must exist when a runtime is built.
+    def providers_path(value = :__read__) = configuration_path(:providers_path, "providers.yml", value)
+
+    # Replaces the provider YAML path for subsequently built runtimes.
+    def providers_path=(value)
+      providers_path(value)
+    end
+
+    # Model YAML path. The conventional path is optional; an explicitly set
+    # path must exist when a runtime is built.
+    def models_path(value = :__read__) = configuration_path(:models_path, "models.yml", value)
+
+    # Replaces the model YAML path for subsequently built runtimes.
+    def models_path=(value)
+      models_path(value)
+    end
+
+    # Installs a complete resolver override for subsequently built runtimes.
+    def model_resolver(value = :__read__)
+      if value != :__read__
+        validate_model_resolver_class!(value)
+
+        configuration_values[:model_resolver] = value
+        @resolved_model_resolver = nil
+        return value
+      end
+
+      @model_resolver_mutex ||= Mutex.new
+      @model_resolver_mutex.synchronize do
+        @resolved_model_resolver ||= begin
+          providers = resolved_providers
+          credential_resolver = configuration_values[:provider_credentials] || providers&.method(:credentials)
+          configured = configuration_values[:model_resolver]
+          if configured
+            validate_model_resolver_configuration!
+            configured.new(
+              providers:,
+              provider_adapters: configuration_values[:provider_adapters],
+              catalog_sources: configuration_values[:catalog_sources],
+              credential_resolver:
+            )
+          else
+            profiles, file_default = resolved_models
+            ModelResolver.new(
+              providers:,
+              profiles:,
+              default_model: configuration_values.fetch(:default_model, file_default),
+              provider_adapters: configuration_values[:provider_adapters],
+              catalog_sources: configuration_values[:catalog_sources],
+              credential_resolver:
+            )
+          end
+        end
+      end
+    end
+
+    def model_resolver=(value)
+      model_resolver(value)
+    end
+
+    # Registers a provider adapter factory under +name+.
+    def provider_adapter(name, callable = nil, &factory)
+      implementation = factory || callable
+      if implementation.is_a?(Class)
+        unless implementation <= Providers::Base
+          raise ArgumentError, "provider adapter class must inherit LittleGhost::Providers::Base"
+        end
+      elsif !implementation.respond_to?(:call)
+        raise ArgumentError, "provider adapter must be a Providers::Base class or callable factory"
+      end
+
+      configuration_values[:provider_adapters][name.to_s] = implementation
+      @resolved_model_resolver = nil
+      implementation
+    end
+
+    # Adds an explicit catalog source. Sources refresh only when callers invoke
+    # ModelResolver#refresh!.
+    def catalog_source(source)
+      raise ArgumentError, "catalog source must be a Models::Catalog::Source" unless source.is_a?(Models::Catalog::Source)
+
+      configuration_values[:catalog_sources] << source
+      @resolved_model_resolver = nil
+      source
+    end
+
+    # Installs a trusted callable that returns credential options for a named
+    # provider connection when each executable model is constructed.
+    def provider_credentials(callable = nil, &resolver)
+      value = resolver || callable
+      return configuration_values[:provider_credentials] unless value
+      raise ArgumentError, "provider credential resolver must be callable" unless value.respond_to?(:call)
+
+      configuration_values[:provider_credentials] = value
+      @resolved_model_resolver = nil
+      value
+    end
+
     # Selects the Workspace subclass instantiated for each run.
     def workspace=(value)
       @configuration_values[:workspace] = component_class(value, Workspace, :workspace)
@@ -286,6 +412,8 @@ module LittleGhost
       values[:skill_paths] = Array(values[:skill_paths]).dup
       values[:instrumentation_subscribers] = Array(values[:instrumentation_subscribers]).dup
       values[:runtime_hooks] = Array(values[:runtime_hooks]).dup
+      values[:model_resolver] = model_resolver
+      values[:default_model] = values[:model_resolver].default_model
       values[:root] = requested_root || values[:root] || self.root
       values
     end
@@ -313,6 +441,59 @@ module LittleGhost
 
     attr_reader :configuration_values
 
+    def validate_model_resolver_class!(value)
+      return if value.is_a?(Class) && value <= ModelResolver
+
+      raise ArgumentError, "model_resolver must be a LittleGhost::ModelResolver subclass"
+    end
+
+    def configuration_path(key, filename, value)
+      if value != :__read__
+        configuration_values[key] = value
+        reset_model_resolver
+        return value
+      end
+
+      configuration_values.fetch(key) { root.join("config/little_ghost", filename) }
+    end
+
+    def resolved_providers
+      return unless configuration_values.key?(:providers) || (path = resolved_configuration_file(:providers_path, "providers.yml"))
+
+      configured = configuration_values[:providers]
+      return configured if configured.is_a?(Providers::Configuration)
+      return Providers::Configuration.new(configured) if configuration_values.key?(:providers)
+
+      Models::Configuration.providers(path)
+    end
+
+    def resolved_models
+      return [configuration_values[:models], nil] if configuration_values.key?(:models)
+
+      path = resolved_configuration_file(:models_path, "models.yml")
+      path ? Models::Configuration.models(path) : [nil, nil]
+    end
+
+    def resolved_configuration_file(key, filename)
+      explicit = configuration_values.key?(key)
+      path = Pathname(configuration_values.fetch(key) { root.join("config/little_ghost", filename) })
+      path = root.join(path) unless path.absolute?
+      return path if path.file?
+      raise ConfigurationError, "LittleGhost configuration file does not exist: #{path}" if explicit
+    end
+
+    def validate_model_resolver_configuration!
+      conflicting = %i[models models_path default_model].select { |key| configuration_values.key?(key) }
+      return if conflicting.empty?
+
+      raise ConfigurationError,
+        "custom model_resolver cannot be combined with #{conflicting.join(", ")}"
+    end
+
+    def reset_model_resolver
+      @resolved_model_resolver = nil
+    end
+
     def component_class(value, base_class, name)
       unless value.is_a?(Class) && value <= base_class
         raise ArgumentError, "#{name} must be a #{base_class} class"