little_ghost 0.1.0

data/lib/little_ghost/model_registry.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Give application roles stable model choices without coupling agents to vendors.
+  # A registry joins provider factories with named, inheritable profiles.
+  #
+  # A support application can keep its general and research agents on related
+  # profiles while selecting one provider in one place:
+  #
+  #   class CustomerSupportModels < LittleGhost::ModelRegistry
+  #     def initialize
+  #       super
+  #       provider(:openai) do |model:, **|
+  #         LittleGhost::Providers::OpenAI.new(
+  #           api_key: ENV.fetch("OPENAI_API_KEY"), model: model
+  #         )
+  #       end
+  #       profile "customer_support", provider: :openai, model: "gpt-5"
+  #       profile "customer_support.research", inherit: "customer_support",
+  #         settings: {temperature: 0.1}
+  #     end
+  #   end
+  #
+  #   model = CustomerSupportModels.new.resolve("customer_support.research")
+  #   model.id       # => "gpt-5"
+  #   model.settings # => {temperature: 0.1}
+  #
+  # Dotted roles resolve from the exact role toward shorter registered parents.
+  # Explicit profile inheritance supplies provider, model, settings, and metadata;
+  # per-invocation overrides then layer from inherited parents through the exact
+  # requested role. A final +override+ passed to +resolve+ wins over both.
+  # Settings and overrides are control-plane input: construct or allowlist them
+  # in application code rather than copying unchecked request fields. An
+  # override can select a different registered provider or model and change the
+  # destination, capability, and cost of a request.
+  #
+  # Provider factories receive the resolved identity, settings, metadata,
+  # invocation, run context, and forwarding options. Resolution raises
+  # ConfigurationError for missing roles, providers, models, factories, or
+  # circular inheritance; exceptions raised inside a factory are not masked.
+  class ModelRegistry
+    # Starts an empty registry ready for provider factories and model profiles.
+    def initialize
+      @providers = {}
+      @profiles = {}
+    end
+
+    # Associates +name+ with a provider factory and returns +self+.
+    #
+    # The factory receives the resolved +model+, logical +role+, profile
+    # +settings+ and +metadata+, invocation, run context, and resolution options.
+    def provider(name, callable = nil, &factory)
+      @providers[name.to_sym] = factory || callable || raise(ArgumentError, "provider factory is required")
+      self
+    end
+
+    # Adds an inheritable model profile named +name+ and returns +self+.
+    #
+    # Parent settings and metadata merge into the child. A child may inherit its
+    # provider and model or replace either one.
+    def profile(name, provider: nil, model: nil, settings: {}, metadata: {}, inherit: nil)
+      @profiles[name.to_s] = {
+        provider: provider&.to_sym,
+        model: model&.to_s,
+        settings: settings.to_h.transform_keys(&:to_sym),
+        metadata: metadata.to_h,
+        inherit: inherit&.to_s
+      }
+      self
+    end
+
+    # Materializes +name+ as a configured Model for the current invocation.
+    #
+    # +override+ applies after registered profiles and invocation profile
+    # overrides. +context+ takes precedence over the legacy +run+ argument when
+    # passed to the provider factory.
+    def resolve(name, invocation: nil, override: nil, run: nil, context: nil, **options)
+      role = name.to_s
+      profile_name = profile_for(role)
+      configuration = resolved_profile(profile_name)
+      override_profiles(profile_name, role).each do |profile|
+        configuration = merge(configuration, profile_override(invocation, profile))
+      end
+      configuration = merge(configuration, override)
+      provider_name = configuration[:provider]
+      model_id = configuration[:model]
+      raise ConfigurationError, "Model profile #{profile_name} does not define a provider" unless provider_name
+      raise ConfigurationError, "Model profile #{profile_name} does not define a model" unless model_id
+
+      factory = @providers.fetch(provider_name) do
+        raise ConfigurationError, "No provider is registered for #{provider_name}"
+      end
+      provider = factory.call(
+        model: model_id,
+        role:,
+        settings: configuration.fetch(:settings),
+        metadata: configuration.fetch(:metadata),
+        invocation:,
+        context: context || run,
+        **options
+      )
+      Model.new(
+        provider:,
+        provider_name:,
+        model: model_id,
+        settings: configuration.fetch(:settings),
+        metadata: configuration.fetch(:metadata),
+        role:
+      )
+    end
+
+    private
+
+    def merge(configuration, override)
+      values = (override || {}).to_h.transform_keys(&:to_sym)
+      settings = values.fetch(:settings, values.fetch(:parameters, {})).to_h.transform_keys(&:to_sym)
+      configuration
+        .merge(values.except(:settings, :parameters, :model_id))
+        .merge(
+          provider: values.key?(:provider) ? values[:provider]&.to_sym : configuration[:provider],
+          model: values.fetch(:model, values.fetch(:model_id, configuration[:model])),
+          settings: configuration.fetch(:settings).merge(settings),
+          metadata: configuration.fetch(:metadata).merge(values.fetch(:metadata, {}))
+        )
+    end
+
+    def profile_for(role)
+      parts = role.to_s.split(".")
+      until parts.empty?
+        candidate = parts.join(".")
+        return candidate if @profiles.key?(candidate)
+
+        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)
+
+      profile = @profiles.fetch(name) do
+        raise ConfigurationError, "Unknown model profile: #{name}"
+      end
+      parent_name = profile.fetch(:inherit)
+      return profile unless parent_name
+
+      parent = resolved_profile(parent_name, [*seen, name])
+      {
+        provider: profile.fetch(:provider) || parent.fetch(:provider),
+        model: profile.fetch(:model) || parent.fetch(:model),
+        settings: parent.fetch(:settings).merge(profile.fetch(:settings)),
+        metadata: parent.fetch(:metadata).merge(profile.fetch(:metadata)),
+        inherit: parent_name
+      }
+    end
+
+    def override_profiles(profile_name, role)
+      names = []
+      current = profile_name
+      while current
+        names.unshift(current)
+        current = @profiles.fetch(current).fetch(:inherit)
+      end
+      names << role unless names.include?(role)
+      names
+    end
+
+    def profile_override(invocation, role)
+      profiles = invocation&.model_profiles || {}
+      profiles[role.to_s] || {}
+    end
+  end
+end

data/lib/little_ghost/model_request.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # ModelRequest carries everything a provider needs for one model stream. It
+  # keeps messages, tools, settings, structured-output requirements, and
+  # cooperative execution controls together.
+  #
+  # Messages are coerced into Message objects, and required capabilities are
+  # normalized to unique symbols. The messages, tools, settings, and capability
+  # containers are frozen; output schema and tool choice values are retained as
+  # supplied.
+  #
+  # Only those outer containers are frozen. Do not mutate retained output
+  # schemas, tool choices, or nested settings after construction, and do not
+  # share mutable control values across concurrent requests.
+  ModelRequest = Data.define( # :nodoc:
+    :messages,
+    :tools,
+    :settings,
+    :output_schema,
+    :tool_choice,
+    :required_capabilities,
+    :cancellation_token,
+    :deadline
+  ) do
+    # Creates a model request with optional tools, structured output, tool choice,
+    # cancellation, and deadline controls.
+    def initialize(
+      messages:,
+      tools: [],
+      settings: {},
+      output_schema: nil,
+      tool_choice: nil,
+      required_capabilities: [],
+      cancellation_token: Support::CancellationToken.new,
+      deadline: nil
+    )
+      super(
+        messages: messages.map { |message| Message.coerce(message) }.freeze,
+        tools: tools.freeze,
+        settings: settings.freeze,
+        output_schema:,
+        tool_choice:,
+        required_capabilities: required_capabilities.map(&:to_sym).uniq.freeze,
+        cancellation_token: cancellation_token,
+        deadline:
+      )
+    end
+  end
+
+  # Carries everything a provider needs for one model stream. Messages are
+  # normalized to Message objects, and required capabilities become unique
+  # symbols. The main request containers are frozen, but nested values are not
+  # defensively copied.
+  #
+  # Treat settings, output schemas, and tool-choice values as immutable after
+  # construction. Create a separate copy before using mutable control data in
+  # another request or thread.
+  class ModelRequest < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(messages:, tools: [], settings: {}, output_schema: nil,
+    #       tool_choice: nil, required_capabilities: [],
+    #       cancellation_token: Support::CancellationToken.new,
+    #       deadline: nil) -> ModelRequest
+    #
+    # Creates one normalized provider request with cooperative cancellation and
+    # deadline controls. Freezing is shallow; retained nested control values must
+    # not be mutated afterward.
+
+    ##
+    # :attr_reader: messages
+    # The normalized conversation in a frozen Array.
+
+    ##
+    # :attr_reader: tools
+    # The model-visible tool specifications in a frozen Array.
+
+    ##
+    # :attr_reader: settings
+    # Trusted provider settings in the caller's now-frozen Hash. Nested values
+    # remain mutable and must not change after construction.
+
+    ##
+    # :attr_reader: output_schema
+    # The requested structured-output schema, or +nil+ for ordinary text. The
+    # caller-owned value is retained and must not be mutated afterward.
+
+    ##
+    # :attr_reader: tool_choice
+    # The requested tool-selection policy, when one applies. The caller-owned
+    # value is retained and must not be mutated afterward.
+
+    ##
+    # :attr_reader: required_capabilities
+    # The normalized capabilities the selected model must support.
+
+    ##
+    # :attr_reader: cancellation_token
+    # The cooperative cancellation token shared with the provider.
+
+    ##
+    # :attr_reader: deadline
+    # The absolute request deadline, or +nil+ when none was configured.
+  end
+end

data/lib/little_ghost/model_response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # ModelResponse is the final result shared by every provider stream. It keeps
+  # provider-specific response shapes out of the agent loop.
+  #
+  # +message+ is the assistant Message, +stop_reason+ is a normalized symbol,
+  # and +usage+ contains provider-independent token counts.
+  ModelResponse = Data.define(:message, :stop_reason, :usage, :metadata) do # :nodoc:
+    # Creates an immutable response and coerces +message+ into a Message.
+    def initialize(message:, stop_reason:, usage: Usage.new, metadata: {})
+      super(
+        message: Message.coerce(message),
+        stop_reason: stop_reason&.to_sym,
+        usage: usage,
+        metadata: metadata.freeze
+      )
+    end
+  end
+
+  # Represents the final result shared by every provider stream. It keeps
+  # provider-specific response shapes out of the agent loop.
+  class ModelResponse < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(message:, stop_reason:, usage: Usage.new, metadata: {}) -> ModelResponse
+    #
+    # Coerces +message+ to Message, normalizes +stop_reason+ to a Symbol, and
+    # freezes +metadata+.
+
+    ##
+    # :attr_reader: message
+    # The normalized assistant Message.
+
+    ##
+    # :attr_reader: stop_reason
+    # The normalized reason the model stopped.
+
+    ##
+    # :attr_reader: usage
+    # Provider-independent token usage for this response.
+
+    ##
+    # :attr_reader: metadata
+    # Frozen provider-specific response metadata.
+  end
+end

data/lib/little_ghost/path_set.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # PathSet keeps prompt or skill lookup roots in deterministic search order. It
+  # is immutable, so appending a path does not change a running configuration.
+  class PathSet
+    include Enumerable
+
+    # The immutable Lookup::Root values in search order.
+    attr_reader :paths
+
+    # Accepts path strings and Lookup::Root objects.
+    def initialize(paths = [])
+      @paths = Array(paths).map { |path| path.is_a?(Lookup::Root) ? path : Lookup::Root.new(path:) }.freeze
+    end
+
+    # Yields each Lookup::Root in order.
+    def each(&block)
+      paths.each(&block)
+    end
+
+    # Copies the roots into a mutable array.
+    def to_a
+      paths.dup
+    end
+
+    # Appends +other+ in a new path set; neither input is mutated.
+    def +(other)
+      PathSet.new([*paths, *Array(other)])
+    end
+  end
+end

data/lib/little_ghost/prompt_resolver.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module LittleGhost
+  # TrustedPath marks a caller-supplied prompt directory as trusted application
+  # code. Invocation-specific prompt roots must use this wrapper.
+  #
+  # Invocation paths must use this wrapper. Construction resolves symbolic
+  # links immediately and rejects missing or non-directory paths.
+  TrustedPath = Data.define(:path) do # :nodoc:
+    def initialize(path:)
+      expanded = File.realpath(path)
+      raise ArgumentError, "trusted template path must be a directory" unless File.directory?(expanded)
+      super(path: expanded.freeze)
+    rescue Errno::ENOENT
+      raise ArgumentError, "trusted template path must exist"
+    end
+  end
+
+  # Marks a caller-supplied prompt directory as trusted application code.
+  # Construction resolves symbolic links immediately and rejects paths that are
+  # missing or are not directories.
+  #
+  # === Security and trust
+  #
+  # Construction is a trust assertion, not a sanitizer. It does not inspect
+  # ownership, permissions, or who can modify the directory. ERB templates run
+  # as Ruby inside the current process, so create TrustedPath values only from
+  # allowlisted, application-controlled, non-user-writable roots. Never wrap a
+  # path taken from unchecked request or model input.
+  class TrustedPath < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(path:) -> TrustedPath
+    #
+    # Resolves +path+ to an existing directory the caller asserts is trusted
+    # prompt code. This checks existence and type, not ownership or permissions.
+
+    ##
+    # :attr_reader: path
+    # The resolved, existing directory asserted as trusted by the caller.
+  end
+
+  # Base error raised while locating or rendering a prompt template.
+  class PromptTemplateError < Error; end
+  # Raised when no configured root contains the requested template.
+  class MissingPromptTemplateError < PromptTemplateError; end
+  # Raised for unsafe names, escaped roots, cycles, or excessive recursion.
+  class InvalidPromptTemplateError < PromptTemplateError; end
+  # Raised when an ERB template references a missing local variable.
+  class MissingPromptLocalError < PromptTemplateError; end
+
+  # PromptResolver turns conventional ERB files into an agent's system prompt. It
+  # supports ordered application roots and partials without allowing a template
+  # name to escape those roots.
+  #
+  #   resolver = LittleGhost::PromptResolver.new(paths: ["app/prompts"])
+  #   prompt = resolver.render("support/system", locals: {product: "Acme"})
+  #   prompt.include?("Acme") # => true
+  #
+  # In +support/system.erb+:
+  #
+  #   <%= partial "shared/rules", locals: {product: product} %>
+  #
+  # Earlier invocation roots override configured roots. Template names must be
+  # relative, and both lexical traversal and symbolic-link escapes are rejected.
+  # Partials use an underscore-prefixed filename and receive only their
+  # explicitly supplied locals.
+  #
+  # Every configured root is trusted Ruby code because ERB executes inside the
+  # current process. Keep roots application-controlled and non-user-writable.
+  class PromptResolver
+    DEFAULT_MAX_DEPTH = 20 # :nodoc:
+
+    # Configures ordered application roots and a partial recursion bound, which
+    # defaults to 20 nested templates.
+    def initialize(paths: [], max_depth: DEFAULT_MAX_DEPTH)
+      @paths = normalize_roots(paths)
+      @max_depth = Integer(max_depth)
+      raise ArgumentError, "max_depth must be positive" unless @max_depth.positive?
+
+      @cache = {}
+      @cache_mutex = Mutex.new
+    end
+
+    # Renders +name+ with validated local variables.
+    #
+    # +invocation_paths+ accepts only TrustedPath values because those roots
+    # take precedence over application configuration. The wrapper records the
+    # caller's trust decision; it does not make an untrusted directory safe.
+    def render(name, locals: {}, invocation_paths: [])
+      roots = normalize_invocation_roots(invocation_paths) + @paths
+      render_template(normalize_name(name), locals, roots, [])
+    end
+
+    private
+
+    def render_template(name, locals, roots, stack)
+      raise InvalidPromptTemplateError, "Prompt template recursion exceeds #{@max_depth} levels" if stack.length >= @max_depth
+
+      path = resolve(name, roots)
+      raise InvalidPromptTemplateError, "Prompt template cycle detected: #{(stack + [path]).join(" -> ")}" if stack.include?(path)
+
+      template = compiled_template(path)
+      context = RenderContext.new(self, roots, stack + [path], name, locals)
+      template.result(context.template_binding)
+    rescue NameError => error
+      if error.name && local_name?(error.name)
+        raise MissingPromptLocalError, "Missing prompt template local: #{error.name}"
+      end
+
+      raise
+    end
+
+    def render_partial(name, locals, roots, stack, parent_name)
+      logical_name = partial_name(name, parent_name)
+      render_template(logical_name, locals, roots, stack)
+    end
+
+    def partial_name(name, parent_name)
+      normalized = normalize_name(name)
+      directory = File.dirname(parent_name)
+      directory = "" if directory == "."
+      basename = File.basename(normalized)
+      basename = "_#{basename}" unless basename.start_with?("_")
+      path = File.join(File.dirname(normalized), basename)
+      path = File.join(directory, path) unless directory.empty? || name.to_s.include?("/")
+      path
+    end
+
+    def resolve(name, roots)
+      candidates = template_candidates(name)
+      roots.each do |root_spec|
+        root, real_root = validate_root(root_spec)
+        candidates.each do |candidate|
+          path = File.expand_path(candidate, root)
+          next unless inside_root?(path, root) && File.file?(path)
+
+          real_path = File.realpath(path)
+          return real_path if inside_root?(real_path, real_root)
+        end
+      end
+
+      raise MissingPromptTemplateError, "Prompt template not found: #{name}"
+    end
+
+    def template_candidates(name)
+      name.end_with?(".erb") ? [name] : ["#{name}.erb", name]
+    end
+
+    def compiled_template(path)
+      stat = File.stat(path)
+      fingerprint = [stat.mtime.to_r, stat.size]
+
+      @cache_mutex.synchronize do
+        cached = @cache[path]
+        return cached[:template] if cached && cached[:fingerprint] == fingerprint
+
+        template = ERB.new(File.read(path), trim_mode: "-")
+        @cache[path] = {fingerprint: fingerprint, template: template}
+        template
+      end
+    end
+
+    def normalize_roots(paths)
+      Array(paths).map do |path|
+        path.is_a?(Lookup::Root) ? path : Lookup::Root.new(path: path.to_s)
+      end.freeze
+    end
+
+    def normalize_invocation_roots(paths)
+      Array(paths).map do |path|
+        unless path.is_a?(TrustedPath)
+          raise ArgumentError, "invocation template paths must be LittleGhost::TrustedPath values"
+        end
+        Lookup::Root.new(path: path.path)
+      end.freeze
+    end
+
+    def validate_root(root)
+      real_root = File.realpath(root.path)
+      raise InvalidPromptTemplateError, "Prompt template root is not a directory" unless File.directory?(real_root)
+      if root.boundary
+        boundary = File.realpath(root.boundary)
+        unless inside_root?(real_root, boundary)
+          raise InvalidPromptTemplateError, "Prompt template root escapes its trusted boundary"
+        end
+      end
+      [root.path, real_root]
+    rescue Errno::ENOENT
+      [root.path, root.path]
+    end
+
+    def normalize_name(name)
+      value = String(name)
+      path_parts = value.split(/[\\\/]/)
+      if value.empty? || value.include?("\0") || File.absolute_path(value) == value || path_parts.include?("..")
+        raise InvalidPromptTemplateError, "Unsafe prompt template name: #{value.inspect}"
+      end
+
+      value.sub(%r{\A\./}, "")
+    end
+
+    def inside_root?(path, root)
+      path == root || path.start_with?("#{root}#{File::SEPARATOR}")
+    end
+
+    def local_name?(name)
+      name.to_s.match?(/\A[a-z_]\w*\z/)
+    end
+
+    class RenderContext # :nodoc:
+      def initialize(resolver, roots, stack, name, locals)
+        @resolver = resolver
+        @roots = roots
+        @stack = stack
+        @name = name
+        @locals = validate_locals(locals)
+      end
+
+      def partial(name, locals: {})
+        @resolver.send(:render_partial, name, locals, @roots, @stack, @name)
+      end
+
+      def template_binding
+        context_binding = binding
+        @locals.each { |name, value| context_binding.local_variable_set(name, value) }
+        context_binding
+      end
+
+      private
+
+      def validate_locals(locals)
+        unless locals.respond_to?(:each_pair)
+          raise ArgumentError, "locals must be a hash"
+        end
+
+        locals.each_with_object({}) do |(name, value), result|
+          symbol = name.to_sym
+          unless symbol.to_s.match?(/\A[a-z_]\w*\z/)
+            raise ArgumentError, "Invalid local name: #{name.inspect}"
+          end
+
+          result[symbol] = value
+        end
+      end
+    end
+  end
+end