little_ghost 0.1.0 → 0.2.0

data/lib/little_ghost/runtime.rb

@@ -10,7 +10,10 @@ module LittleGhost
   #
   #   configuration = LittleGhost::Configuration.new(
   #     root: Dir.pwd,
-  #     models: CustomerSupportModels,
+  #     providers: {
+  #       openai: {adapter: :openai, api_key: ENV.fetch("OPENAI_API_KEY")}
+  #     },
+  #     models: {customer_support: {target: "openai:gpt-5.6-luna"}},
   #     default_model: "customer_support",
   #     service_name: "support-api"
   #   )
@@ -22,7 +25,7 @@ module LittleGhost
   # Without explicit +settings+, construction canonicalizes the root, loads
   # +config/little_ghost.rb+ once through the Configuration, snapshots settings,
   # configures instrumentation, eager-loads application constants, and builds the
-  # selected model registry and session store. Supplying +settings+ is the
+  # selected model resolver and session store. Supplying +settings+ is the
   # lower-level path used to create a sibling runtime from an existing snapshot.
   #
   # Reuse a runtime across runs. +build_run+ creates any missing workspace and
@@ -38,7 +41,7 @@ module LittleGhost
   class Runtime
     # The snapshotted setup and materialized services used by new runs.
     attr_reader :configuration, :settings, :root, :loader, :prompt_paths, :skill_paths,
-      :skill_resource_root, :models, :session_store, :workspace_class, :sandbox_class,
+      :skill_resource_root, :model_resolver, :session_store, :workspace_class, :sandbox_class,
       :runtime_hooks
 
     # Starts a runtime from +configuration+ or an existing settings snapshot.
@@ -75,9 +78,9 @@ module LittleGhost
         loader.setup
         loader.eager_load
 
-        @startup_phase = "models"
+        @startup_phase = "model_resolver"
         @invocation_class = @settings[:invocation] || Invocation
-        @models = build_service(@settings[:models], default: -> { DefaultModelRegistry.new })
+        @model_resolver = @settings.fetch(:model_resolver)
         @default_model = @settings.fetch(:default_model, "default").to_s
 
         @startup_phase = "session_store"
@@ -189,8 +192,8 @@ module LittleGhost
     end
 
     def model_for(agent_class, run) # :nodoc:
-      role = agent_class.model_role(run.invocation) || @default_model
-      models.resolve(role, invocation: run.invocation, run:)
+      selection = agent_class.model_selection(run.invocation) || @default_model
+      model_resolver.resolve(selection, invocation: run.invocation, context: run)
     end
 
     def open_session(run) # :nodoc:

data/lib/little_ghost/sandbox.rb

@@ -90,22 +90,22 @@ module LittleGhost
 
     # Reads UTF-8 text at a workspace-relative +path+.
     def read(path, context: nil)
-      raise NotImplementedError, "#{self.class} does not support filesystem reads"
+      raise AbstractMethodError, "#{self.class} does not support filesystem reads"
     end
 
     # Lists entries at a workspace-relative directory +path+.
     def list(path = ".", context: nil)
-      raise NotImplementedError, "#{self.class} does not support filesystem listings"
+      raise AbstractMethodError, "#{self.class} does not support filesystem listings"
     end
 
     # Writes +content+ to a workspace-relative +path+.
     def write(path, content, context: nil)
-      raise NotImplementedError, "#{self.class} does not support filesystem writes"
+      raise AbstractMethodError, "#{self.class} does not support filesystem writes"
     end
 
     # Replaces one exact +old_text+ occurrence with +new_text+.
     def replace(path, old_text, new_text, context: nil)
-      raise NotImplementedError, "#{self.class} does not support filesystem edits"
+      raise AbstractMethodError, "#{self.class} does not support filesystem edits"
     end
 
     # Executes +command+ through +/bin/sh+.
@@ -127,7 +127,7 @@ module LittleGhost
     # Implementations must enforce +timeout+ and +max_output_bytes+. Environment
     # inheritance is disabled by default to avoid leaking process credentials.
     def execute_program(command, timeout:, context: nil, max_output_bytes: 1_000_000, environment: {}, inherit_environment: false)
-      raise NotImplementedError, "#{self.class} does not support program execution"
+      raise AbstractMethodError, "#{self.class} does not support program execution"
     end
 
     # Releases sandbox resources. Runs close the sandbox before its workspace.

data/lib/little_ghost/session_store.rb

@@ -36,19 +36,19 @@ module LittleGhost
 
     # Finds the snapshot for +id+, or returns nil when it does not exist.
     def load(_id, actor_id: nil)
-      raise NotImplementedError
+      raise AbstractMethodError, "#{self.class} must implement #load"
     end
 
     # Atomically appends sanitized messages and stores state and metadata.
     # Implementations raise ProtocolError if the persisted message count differs
     # from +expected_count+.
     def append(_id, messages:, state:, metadata:, expected_count:, actor_id: nil)
-      raise NotImplementedError
+      raise AbstractMethodError, "#{self.class} must implement #append"
     end
 
     # Replaces the complete snapshot for +id+ atomically.
     def replace(_id, messages:, state:, metadata:, actor_id: nil)
-      raise NotImplementedError
+      raise AbstractMethodError, "#{self.class} must implement #replace"
     end
 
     # Stores may expose a clean conversational view without changing the stored

data/lib/little_ghost/structured_output.rb

@@ -56,11 +56,7 @@ module LittleGhost
       return unless configuration
 
       requested = configuration.fetch(:strategy, :auto).to_sym
-      capabilities = if model.respond_to?(:capabilities)
-        model.capabilities
-      else
-        ModelCapabilities.legacy
-      end
+      capabilities = model.capabilities
       strategy = case requested
       when :auto then automatic_strategy(model, capabilities, ordinary_tools)
       when :provider
@@ -117,9 +113,7 @@ module LittleGhost
     private_class_method :validate_explicit_tool!
 
     def model_identity(model)
-      provider = model.respond_to?(:provider_name) ? model.provider_name : model.class.name
-      id = model.respond_to?(:id) ? model.id : nil
-      [provider, id].compact.join("/")
+      [model.target.provider, model.model_id].join("/")
     end
     private_class_method :model_identity
   end

data/lib/little_ghost/support/http_client.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module LittleGhost
+  module Support
+    # HTTPClient gives integrations a shared, bounded streaming HTTP layer.
+    # It applies cancellation, deadlines, timeouts, and response-size limits while
+    # yielding response chunks as they arrive.
+    #
+    # === Security and trust
+    #
+    # HTTPS is required by default. Enabling +allow_insecure_http+ can expose API
+    # keys and model content in transit; use it only with a trusted local
+    # development endpoint.
+    class HTTPClient
+      # Default upper bound for a complete provider response (50 MiB).
+      DEFAULT_MAX_RESPONSE_BYTES = 50 * 1024 * 1024
+      DEFAULT_MAX_ERROR_BODY_BYTES = 4 * 1024 # :nodoc:
+      TRANSIENT_NETWORK_ERRORS = [
+        Net::OpenTimeout,
+        Net::ReadTimeout,
+        Net::WriteTimeout,
+        EOFError,
+        SocketError,
+        SystemCallError,
+        IOError,
+        OpenSSL::SSL::SSLError,
+        Net::ProtocolError,
+        Net::HTTPBadResponse,
+        Net::HTTPHeaderSyntaxError
+      ].freeze # :nodoc:
+
+      # Configures +base_url+ with connection, read, and response
+      # size limits.
+      def initialize(
+        base_url: nil,
+        open_timeout: 10,
+        read_timeout: 120,
+        allow_insecure_http: false,
+        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES,
+        max_error_body_bytes: DEFAULT_MAX_ERROR_BODY_BYTES
+      )
+        if base_url
+          @base_url = URI(base_url.end_with?("/") ? base_url : "#{base_url}/")
+          validate_uri!(@base_url, allow_insecure_http:)
+        end
+
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+        @allow_insecure_http = allow_insecure_http
+        @max_response_bytes = positive_integer(max_response_bytes, :max_response_bytes)
+        @max_error_body_bytes = positive_integer(max_error_body_bytes, :max_error_body_bytes)
+      end
+
+      # Posts +body+ and yields response chunks until completion.
+      #
+      # Cancellation and +deadline+ interrupt the request. Without a block, this
+      # method returns an Enumerator.
+      def stream(path:, headers:, body:, cancellation_token:, deadline: nil)
+        return enum_for(__method__, path:, headers:, body:, cancellation_token:, deadline:) unless block_given?
+        raise ConfigurationError, "HTTP client requires base_url for streaming" unless @base_url
+
+        stream = Support::InterruptibleStream.new(cancellation_token:, deadline:) do |emit|
+          uri = URI.join(@base_url.to_s, path.sub(%r{\A/}, ""))
+          each_chunk(
+            uri:,
+            method: :post,
+            headers:,
+            body:,
+            deadline:,
+            allow_insecure_http: @allow_insecure_http,
+            label: "Provider"
+          ) { |chunk| emit.call(chunk) }
+        end
+        stream.each { |chunk| yield chunk }
+      end
+
+      # Executes a bounded request and returns the complete response body.
+      def request(uri:, method: :get, headers: {}, body: nil, allow_insecure_http: false,
+        cancellation_token: nil, deadline: nil)
+        response_body = +""
+        each_chunk(
+          uri:,
+          method:,
+          headers:,
+          body:,
+          cancellation_token:,
+          deadline: deadline || Time.now + @read_timeout,
+          allow_insecure_http:
+        ) { |chunk| response_body << chunk }
+        response_body
+      end
+
+      # Executes a bounded request and yields response chunks as they arrive.
+      def each_chunk(uri:, method: :get, headers: {}, body: nil, deadline: nil,
+        cancellation_token: nil, allow_insecure_http: false, label: "HTTP request")
+        unless block_given?
+          return enum_for(
+            __method__, uri:, method:, headers:, body:, deadline:, cancellation_token:, allow_insecure_http:, label:
+          )
+        end
+
+        uri = URI(uri.to_s)
+        validate_uri!(uri, allow_insecure_http:)
+        check_control!(cancellation_token, deadline)
+        request_class = {get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put}.fetch(method.to_sym) do
+          raise ArgumentError, "unsupported HTTP method: #{method}"
+        end
+        request = request_class.new(uri)
+        headers.each { |name, value| request[name] = value unless value.to_s.empty? }
+        request.body = body if body
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = remaining_timeout(deadline, @open_timeout)
+        http.read_timeout = remaining_timeout(deadline, @read_timeout)
+        http.write_timeout = remaining_timeout(deadline, @read_timeout)
+        http.request(request) do |response|
+          unless response.is_a?(Net::HTTPSuccess)
+            response_body = read_limited(response, @max_error_body_bytes)
+            raise Providers::HTTPError.new(
+              "#{label} failed with HTTP #{response.code}",
+              status: response.code.to_i,
+              body: response_body
+            )
+          end
+
+          bytes_read = 0
+          response.read_body do |chunk|
+            check_control!(cancellation_token, deadline)
+            bytes_read += chunk.bytesize
+            raise ProtocolError, "#{label} response exceeded #{@max_response_bytes} bytes" if bytes_read > @max_response_bytes
+
+            yield chunk
+          end
+        end
+      rescue *TRANSIENT_NETWORK_ERRORS => error
+        raise Providers::HTTPError, "#{label} failed (#{error.class})"
+      end
+
+      private
+
+      def check_control!(cancellation_token, deadline)
+        cancellation_token&.raise_if_cancelled!
+        raise DeadlineExceededError, "The request deadline was reached" if deadline && Time.now >= deadline
+      end
+
+      def validate_uri!(uri, allow_insecure_http:)
+        unless %w[http https].include?(uri.scheme) && uri.host
+          raise ConfigurationError, "HTTP endpoint must be an HTTP(S) URL"
+        end
+        if uri.scheme == "http" && !allow_insecure_http
+          raise ConfigurationError, "HTTP endpoint must use HTTPS unless allow_insecure_http is enabled"
+        end
+      end
+
+      def remaining_timeout(deadline, maximum)
+        return maximum unless deadline
+
+        remaining = deadline - Time.now
+        raise DeadlineExceededError, "The run deadline was reached" unless remaining.positive?
+
+        [remaining, maximum].min
+      end
+
+      def read_limited(response, limit)
+        body = +""
+        response.read_body do |chunk|
+          remaining = limit - body.bytesize
+          body << chunk.byteslice(0, remaining) if remaining.positive?
+          break if body.bytesize >= limit
+        end
+        body
+      end
+
+      def positive_integer(value, name)
+        integer = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless integer.positive?
+
+        integer
+      end
+    end
+  end
+end

data/lib/little_ghost/{providers → support}/sse_parser.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  module Providers
+  module Support
     class SSEParser # :nodoc:
       def initialize
         @buffer = +""

data/lib/little_ghost/tool.rb

@@ -306,7 +306,11 @@ module LittleGhost
     # Subclasses must override this method. The current RunContext is available
     # through +context+ while the call executes.
     def call(_input)
-      raise NotImplementedError, "#{self.class} must implement #call"
+      raise AbstractMethodError, "#{self.class} must implement #call"
+    end
+
+    # Releases resources owned by this tool. Subclasses may override it.
+    def close
     end
 
     protected

data/lib/little_ghost/tool_registry.rb

@@ -12,7 +12,7 @@ module LittleGhost
   # Entries may be Tool instances, Tool subclasses, nested arrays, or provider
   # classes that implement <tt>tools(binding)</tt>. Names must be unique, contain only
   # letters, numbers, underscores, or hyphens, and be at most 64 characters.
-  # Owned tools that implement +close+ are closed once in reverse order.
+  # Owned tools are closed once in reverse order.
   class ToolRegistry
     MAX_NAME_LENGTH = 64 # :nodoc:
     NAME_PATTERN = /\A[a-zA-Z0-9_-]+\z/ # :nodoc:
@@ -76,7 +76,7 @@ module LittleGhost
       raise error
     end
 
-    # Closes every owned tool that responds to +close+.
+    # Closes every owned tool.
     def close
       return if @closed
 
@@ -113,7 +113,6 @@ module LittleGhost
     def close_instances(instances)
       first_error = nil
       instances.reverse_each do |instance|
-        next unless instance.respond_to?(:close)
         next if @closed_tool_ids[instance.object_id]
 
         @closed_tool_ids[instance.object_id] = true

data/lib/little_ghost/version.rb

@@ -2,5 +2,5 @@
 
 module LittleGhost
   # Current LittleGhost gem version.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/little_ghost/workflow.rb

@@ -246,7 +246,7 @@ module LittleGhost
     # Implements the composition and returns its final unconsumed invocation.
     # Subclasses must override this hook.
     def perform
-      raise NotImplementedError, "#{self.class} must implement #perform"
+      raise AbstractMethodError, "#{self.class} must implement #perform"
     end
 
     # :doc:

data/lib/little_ghost.rb

@@ -18,15 +18,27 @@ require_relative "little_ghost/model_request"
 require_relative "little_ghost/model_response"
 require_relative "little_ghost/run_result"
 require_relative "little_ghost/model_capabilities"
+require_relative "little_ghost/models/target"
+require_relative "little_ghost/models/details"
 require_relative "little_ghost/model"
-require_relative "little_ghost/model_registry"
-require_relative "little_ghost/providers/sse_parser"
-require_relative "little_ghost/providers/http_transport"
+require_relative "little_ghost/support/sse_parser"
+require_relative "little_ghost/support/http_client"
+require_relative "little_ghost/providers/base"
+require_relative "little_ghost/providers/configuration"
+require_relative "little_ghost/models/catalog/source"
+require_relative "little_ghost/models/catalog/models_dev_source"
 require_relative "little_ghost/providers/openai_compatible"
 require_relative "little_ghost/providers/openai"
 require_relative "little_ghost/providers/open_router"
 require_relative "little_ghost/providers/bedrock"
-require_relative "little_ghost/default_model_registry"
+require_relative "little_ghost/providers/anthropic"
+require_relative "little_ghost/providers/gemini"
+require_relative "little_ghost/providers/vertex_ai"
+require_relative "little_ghost/models/catalog"
+require_relative "little_ghost/models/catalog_snapshot"
+require_relative "little_ghost/models/configuration"
+require_relative "little_ghost/provider_registry"
+require_relative "little_ghost/model_resolver"
 require_relative "little_ghost/run_context"
 require_relative "little_ghost/workspace"
 require_relative "little_ghost/sandbox"
@@ -60,19 +72,14 @@ require_relative "little_ghost/runtime"
 # A customer support agent can answer directly, use an application tool, or ask a
 # specialist for research while the caller observes one run:
 #
-#   LittleGhost.configure do |config|
-#     config.models CustomerSupportModels
-#     config.default_model :customer_support
-#   end
-#
 #   class ResearchAgent < LittleGhost::Agent
 #     description "Researches difficult support questions"
-#     model "customer_support.research"
+#     model "openai:gpt-5.6-luna"
 #   end
 #
 #   class CustomerSupportAgent < LittleGhost::Agent
 #     description "Handles support requests"
-#     model :customer_support
+#     model "openai:gpt-5.6-luna"
 #     tools AccountTool
 #     subagent ResearchAgent, kind: "research"
 #   end
@@ -97,10 +104,6 @@ module LittleGhost
       ExecutionState[:configuration] || (@configuration ||= Configuration.new)
     end
 
-    # Alias for .configuration. Without an execution-scoped override, this is the
-    # process-wide default Configuration.
-    alias_method :default_configuration, :configuration
-
     # Opens the active Configuration for application setup and returns it.
     #
     # Configuration files are loaded lazily when a runtime is first built, so
@@ -109,6 +112,9 @@ module LittleGhost
       configuration.configure(&block)
     end
 
+    # Returns the model resolver owned by the active process configuration.
+    def model_resolver = configuration.model_resolver
+
     # Makes +configuration+ current only while the block runs.
     #
     # Execution state restores the previous configuration even when the block

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little_ghost
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -117,8 +117,8 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
-- docs/guides/Core Concepts.md
-- docs/guides/Getting Started.md
+- docs/guides/core_concepts.md
+- docs/guides/getting_started.md
 - lib/little_ghost.rb
 - lib/little_ghost/ag_ui.rb
 - lib/little_ghost/ag_ui/adapter.rb
@@ -131,7 +131,7 @@ files:
 - lib/little_ghost/agent_interruptions.rb
 - lib/little_ghost/configuration.rb
 - lib/little_ghost/content.rb
-- lib/little_ghost/default_model_registry.rb
+- lib/little_ghost/data/model_catalog.json
 - lib/little_ghost/errors.rb
 - lib/little_ghost/events.rb
 - lib/little_ghost/execution_state.rb
@@ -143,17 +143,36 @@ files:
 - lib/little_ghost/message.rb
 - lib/little_ghost/model.rb
 - lib/little_ghost/model_capabilities.rb
-- lib/little_ghost/model_registry.rb
 - lib/little_ghost/model_request.rb
+- lib/little_ghost/model_resolver.rb
 - lib/little_ghost/model_response.rb
+- lib/little_ghost/models/catalog.rb
+- lib/little_ghost/models/catalog/models_dev_source.rb
+- lib/little_ghost/models/catalog/source.rb
+- lib/little_ghost/models/catalog_snapshot.rb
+- lib/little_ghost/models/configuration.rb
+- lib/little_ghost/models/details.rb
+- lib/little_ghost/models/target.rb
 - lib/little_ghost/path_set.rb
 - lib/little_ghost/prompt_resolver.rb
+- lib/little_ghost/provider_registry.rb
+- lib/little_ghost/providers/anthropic.rb
+- lib/little_ghost/providers/anthropic/catalog_source.rb
+- lib/little_ghost/providers/base.rb
 - lib/little_ghost/providers/bedrock.rb
-- lib/little_ghost/providers/http_transport.rb
+- lib/little_ghost/providers/bedrock/aws_protocol.rb
+- lib/little_ghost/providers/bedrock/catalog_source.rb
+- lib/little_ghost/providers/bedrock/credential_resolver.rb
+- lib/little_ghost/providers/bedrock/http_client.rb
+- lib/little_ghost/providers/configuration.rb
+- lib/little_ghost/providers/gemini.rb
+- lib/little_ghost/providers/gemini/catalog_source.rb
 - lib/little_ghost/providers/open_router.rb
+- lib/little_ghost/providers/open_router/catalog_source.rb
 - lib/little_ghost/providers/openai.rb
 - lib/little_ghost/providers/openai_compatible.rb
-- lib/little_ghost/providers/sse_parser.rb
+- lib/little_ghost/providers/vertex_ai.rb
+- lib/little_ghost/providers/vertex_ai/credential_resolver.rb
 - lib/little_ghost/run.rb
 - lib/little_ghost/run_context.rb
 - lib/little_ghost/run_result.rb
@@ -178,10 +197,12 @@ files:
 - lib/little_ghost/support/class_attributes.rb
 - lib/little_ghost/support/content_capture.rb
 - lib/little_ghost/support/executor.rb
+- lib/little_ghost/support/http_client.rb
 - lib/little_ghost/support/interruptible_stream.rb
 - lib/little_ghost/support/loader.rb
 - lib/little_ghost/support/output_truncation.rb
 - lib/little_ghost/support/redactor.rb
+- lib/little_ghost/support/sse_parser.rb
 - lib/little_ghost/tool.rb
 - lib/little_ghost/tool_execution.rb
 - lib/little_ghost/tool_registry.rb