little_ghost 0.3.0 → 0.4.0

data/lib/little_ghost/data_map.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # DataMap holds JSON-compatible application data with indifferent key access.
+  # It stores every key as a String while accepting String and Symbol keys for
+  # lookup and mutation, including in nested maps.
+  #
+  #   state = DataMap.new(plan: {status: "active"})
+  #   state.dig("plan", :status) # => "active"
+  #   state.to_h                  # => {"plan" => {"status" => "active"}}
+  #
+  # State and metadata exposed by Sessions and RunContexts use DataMap so they
+  # remain easy to work with in Ruby and portable across session stores. Values
+  # are limited to JSON primitives, Arrays, and mappings. A mapping that
+  # supplies both a String and Symbol form of the same key is ambiguous and
+  # raises ArgumentError.
+  class DataMap < Hash
+    alias_method :store_raw_value, :[]=
+    private :store_raw_value
+
+    # Builds a deeply normalized map from +value+.
+    def initialize(value = {})
+      super()
+      replace(value)
+    end
+
+    # Returns +value+ when it is already a DataMap, or normalizes a mapping.
+    def self.coerce(value)
+      return value if value.is_a?(self)
+
+      new(value)
+    end
+
+    # Looks up +key+ after canonicalizing it to a String.
+    def [](key) = super(normalize_key(key))
+
+    # Stores +value+ under the canonical String form of +key+.
+    def []=(key, value)
+      super(normalize_key(key), normalize_value(value))
+    end
+    alias_method :store, :[]=
+
+    # Fetches +key+ with Hash#fetch's default and block behavior.
+    def fetch(key, *defaults, &block) = super(normalize_key(key), *defaults, &block)
+
+    # Checks for +key+ after canonicalizing it to a String.
+    def key?(key) = super(normalize_key(key))
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Removes +key+ after canonicalizing it to a String.
+    def delete(key, &block) = super(normalize_key(key), &block)
+
+    # Traverses nested DataMaps with String or Symbol keys.
+    def dig(key, *names) = super(normalize_key(key), *names)
+
+    # Returns a normalized copy merged with +other+.
+    def merge(other, &block)
+      dup.merge!(other, &block)
+    end
+
+    # Merges +other+ after deeply normalizing its keys and values.
+    def merge!(other)
+      canonical_pairs(other).each do |key, value|
+        self[key] = (block_given? && key?(key)) ? yield(key, self[key], value) : value
+      end
+      self
+    end
+    alias_method :update, :merge!
+
+    # Replaces all entries with a deeply normalized copy of +other+.
+    def replace(other)
+      pairs = canonical_pairs(other)
+      clear
+      pairs.each { |key, value| self[key] = value }
+      self
+    end
+
+    # Returns a deep independent DataMap copy.
+    def initialize_copy(other)
+      super
+      replace(other.to_h)
+    end
+
+    # Produces a deep ordinary Hash with canonical String keys.
+    def to_h
+      plain_value(self)
+    end
+
+    private
+
+    def canonical_pairs(value, normalize_values: true)
+      hash = Hash.try_convert(value)
+      raise ArgumentError, "DataMap requires a mapping" unless hash
+
+      seen = {}
+      hash.map do |key, child|
+        normalized = normalize_key(key)
+        raise ArgumentError, "DataMap keys must not contain both String and Symbol forms" if seen[normalized]
+
+        seen[normalized] = true
+        [normalized, normalize_values ? normalize_value(child) : child]
+      end
+    end
+
+    def normalize_key(key)
+      return key if key.is_a?(String)
+      return key.to_s if key.is_a?(Symbol)
+
+      raise ArgumentError, "DataMap keys must be Strings or Symbols"
+    end
+
+    def normalize_value(value)
+      return normalize_scalar(value) unless container?(value)
+
+      copy = container_copy(value)
+      stack = [[:visit, value, copy]]
+      ancestors = {}
+      until stack.empty?
+        action, current, target = stack.pop
+        if action == :leave
+          ancestors.delete(current)
+          next
+        end
+
+        raise ArgumentError, "DataMap cannot contain cyclic values" if ancestors[current.object_id]
+
+        ancestors[current.object_id] = true
+        stack << [:leave, current.object_id, nil]
+        if current.is_a?(Hash)
+          canonical_pairs(current, normalize_values: false).reverse_each do |key, child|
+            child_copy = container?(child) ? container_copy(child) : normalize_scalar(child)
+            target.send(:store_raw_value, key, child_copy)
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        else
+          current.each_with_index do |child, index|
+            child_copy = container?(child) ? container_copy(child) : normalize_scalar(child)
+            target[index] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        end
+      end
+
+      copy
+    end
+
+    def plain_value(value)
+      return value unless container?(value)
+
+      copy = value.is_a?(Array) ? [] : {}
+      stack = [[:visit, value, copy]]
+      ancestors = {}
+      until stack.empty?
+        action, current, target = stack.pop
+        if action == :leave
+          ancestors.delete(current)
+          next
+        end
+
+        raise ArgumentError, "DataMap cannot contain cyclic values" if ancestors[current.object_id]
+
+        ancestors[current.object_id] = true
+        stack << [:leave, current.object_id, nil]
+        if current.is_a?(Hash)
+          canonical_pairs(current, normalize_values: false).each do |key, child|
+            child_copy = container?(child) ? plain_container_copy(child) : normalize_scalar(child)
+            target[key] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        else
+          current.each_with_index do |child, index|
+            child_copy = container?(child) ? plain_container_copy(child) : normalize_scalar(child)
+            target[index] = child_copy
+            stack << [:visit, child, child_copy] if container?(child)
+          end
+        end
+      end
+
+      copy
+    end
+
+    def container?(value)
+      value.is_a?(Hash) || value.is_a?(Array)
+    end
+
+    def container_copy(value)
+      value.is_a?(Array) ? [] : self.class.new
+    end
+
+    def plain_container_copy(value)
+      value.is_a?(Array) ? [] : {}
+    end
+
+    def normalize_scalar(value)
+      case value
+      when String, Integer, TrueClass, FalseClass, NilClass
+        value
+      when Float
+        raise ArgumentError, "DataMap values must be JSON-compatible" unless value.finite?
+
+        value
+      else
+        raise ArgumentError, "DataMap values must be JSON-compatible"
+      end
+    end
+  end
+end

data/lib/little_ghost/errors.rb

@@ -51,8 +51,8 @@ module LittleGhost
   class ToolLoopError < ProtocolError; end
   # Base class for failures while executing a tool.
   class ToolError < Error; end
-  # Raised when an active run cannot accept an interruption.
-  class AgentInterruptError < InvocationError; end
+  # Raised when an active run cannot accept an interjection.
+  class AgentInterjectionError < InvocationError; end
   # Raised when cancellation stops an operation.
   class CancelledError < Error; end
   # Raised when an operation reaches its deadline.

data/lib/little_ghost/execution.rb

@@ -2,13 +2,13 @@
 
 module LittleGhost
   # Runs one dormant Run in a supervised worker while the caller remains free to
-  # serve health checks, deliver interruptions, or coordinate process shutdown.
+  # serve health checks, deliver interjections, or coordinate process shutdown.
   #
   #   execution = agent.start_execution(message: "Investigate transfer 481") do |event|
   #     event_buffer << event
   #   end
   #
-  #   execution.interrupt_response(message: "Include the latest ledger entry")
+  #   execution.interject(message: "Include the latest ledger entry")
   #   execution.wait(deadline: Time.now + 30)
   #   execution.run.completed? # => true
   #
@@ -16,7 +16,7 @@ module LittleGhost
   # request-scoped ExecutionState. The Run continues to own its workspace,
   # sandbox, session, entrypoint, and registered resources. +close+ requests
   # cooperative cancellation and waits for both the worker and in-flight
-  # interruption calls.
+  # interjection calls.
   class Execution
     # The supervised Run and an exception raised outside the Run's ordinary
     # terminal outcome, such as event delivery or cleanup failure.
@@ -45,7 +45,7 @@ module LittleGhost
       @error = nil
       @mutex = Mutex.new
       @condition = ConditionVariable.new
-      @active_interruptions = 0
+      @active_interjections = 0
       @closing = false
       @execution_state = ExecutionState.capture
     end
@@ -60,36 +60,36 @@ module LittleGhost
       @mutex.synchronize { @error }
     end
 
-    # Indicates that the worker or an interruption call is still active.
+    # Indicates that the worker or an interjection call is still active.
     def active?
-      @mutex.synchronize { @state != :finished || @active_interruptions.positive? }
+      @mutex.synchronize { @state != :finished || @active_interjections.positive? }
     end
 
-    # Indicates that the worker and all interruption calls have finished.
+    # Indicates that the worker and all interjection calls have finished.
     def finished?
       !active?
     end
 
-    # Prepares and delivers one interruption to the active run.
+    # Prepares and delivers one interjection to the active run.
     #
     # +payload+ may be a message or a Hash containing +message+ and the options
-    # accepted by Run#interrupt_response. Runtime hooks receive the Hash before
+    # accepted by Run#interject. Runtime hooks receive the Hash before
     # delivery, allowing them to materialize trusted application attachments.
     # Calls may overlap, but +close+ prevents new calls and waits for calls that
     # have already begun.
-    def interrupt_response(payload = nil, **options)
+    def interject(payload = nil, **options)
       if payload.nil? && options.key?(:message)
         payload = options.delete(:message)
       end
-      interruption_started = false
-      begin_interruption!
-      interruption_started = true
-      run.interrupt_response_with do
-        prepared = run.prepare_interruption(interruption_payload(payload, options))
-        interruption_arguments(prepared, options)
+      interjection_started = false
+      begin_interjection!
+      interjection_started = true
+      run.interject_with do
+        prepared = run.prepare_interjection(interjection_payload(payload, options))
+        interjection_arguments(prepared, options)
       end
     ensure
-      finish_interruption! if interruption_started
+      finish_interjection! if interjection_started
     end
 
     # Requests cooperative cancellation and returns +self+.
@@ -98,7 +98,7 @@ module LittleGhost
       self
     end
 
-    # Waits for the worker and in-flight interruptions, then returns the Run.
+    # Waits for the worker and in-flight interjections, then returns the Run.
     #
     # +deadline+ is an absolute Time. Reaching it raises DeadlineExceededError
     # without cancelling the run. An event-delivery or cleanup failure raised by
@@ -112,7 +112,7 @@ module LittleGhost
       run
     end
 
-    # Prevents new interruptions, requests cancellation, and waits for shutdown.
+    # Prevents new interjections, requests cancellation, and waits for shutdown.
     # The operation is idempotent. +deadline+ has the same meaning as in #wait.
     def close(deadline: nil)
       @mutex.synchronize { @closing = true }
@@ -147,37 +147,37 @@ module LittleGhost
       end
     end
 
-    def begin_interruption!
+    def begin_interjection!
       @mutex.synchronize do
-        raise AgentInterruptError, "Execution is closing" if @closing
-        raise AgentInterruptError, "Execution has already finished" if @state == :finished
+        raise AgentInterjectionError, "Execution is closing" if @closing
+        raise AgentInterjectionError, "Execution has already finished" if @state == :finished
 
-        @active_interruptions += 1
+        @active_interjections += 1
       end
     end
 
-    def finish_interruption!
+    def finish_interjection!
       @mutex.synchronize do
-        @active_interruptions -= 1 if @active_interruptions.positive?
+        @active_interjections -= 1 if @active_interjections.positive?
         @condition.broadcast
       end
     end
 
-    def interruption_payload(payload, options)
+    def interjection_payload(payload, options)
       values = payload.is_a?(Hash) ? payload.dup : {message: payload}
       options.each { |key, value| values[key] = value }
       values
     end
 
-    def interruption_arguments(prepared, fallback)
+    def interjection_arguments(prepared, fallback)
       unless prepared.is_a?(Hash)
-        return [prepared, fallback.slice(:interruption_id, :batch_key, :metadata, :cancellation_token, :deadline)]
+        return [prepared, fallback.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline)]
       end
 
       values = prepared.transform_keys(&:to_sym)
-      message = values.delete(:message) { raise ArgumentError, "prepared interruption must include a message" }
-      allowed = values.slice(:interruption_id, :batch_key, :metadata, :cancellation_token, :deadline)
-      [message, fallback.slice(:interruption_id, :batch_key, :metadata, :cancellation_token, :deadline).merge(allowed)]
+      message = values.delete(:message) { raise ArgumentError, "prepared interjection must include a message" }
+      allowed = values.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline)
+      [message, fallback.slice(:interjection_id, :batch_key, :metadata, :cancellation_token, :deadline).merge(allowed)]
     end
 
     def wait_until_finished(deadline:)
@@ -185,7 +185,7 @@ module LittleGhost
         monotonic_time + [deadline - Time.now, 0].max
       end
       @mutex.synchronize do
-        until @state == :finished && @active_interruptions.zero?
+        until @state == :finished && @active_interjections.zero?
           if monotonic_deadline
             remaining = monotonic_deadline - monotonic_time
             raise DeadlineExceededError, "Execution did not finish before the wait deadline" unless remaining.positive?

data/lib/little_ghost/graph.rb

@@ -25,10 +25,15 @@ module LittleGhost
   #   SupportFlowGraph.validate!
   #   run = SupportFlowGraph.ask("Why is my transfer pending?")
   #
+  # Call a named Graph with ask[rdoc-ref:LittleGhost::Assembly.ask] for its final
+  # Run, or the streaming entrypoint[rdoc-ref:LittleGhost::Assembly.stream_ask]
+  # for routing and final-response events.
+  #
   # Conditions and input mappers receive immutable Graph::State. Nodes do not
   # receive caller history or application context unless their declaration opts
-  # in with +history: true+ or +context: true+. Validate the topology before
-  # execution; +to_mermaid+ renders the same definition as a flowchart.
+  # in with <tt>history: true</tt> or <tt>context: true</tt>. Validate the
+  # topology before execution; +to_mermaid+ renders the same definition as a
+  # flowchart.
   class Graph < Assembly
     Node = Data.define(:name, :assembly, :policies, :inherit_history, :inherit_context) # :nodoc:
     Edge = Data.define(:from, :to, :condition, :input_mapper) # :nodoc:
@@ -108,7 +113,11 @@ module LittleGhost
         self.graph_start_value = normalize_node_name(name)
       end
 
-      # Declares one exclusive route with an optional condition and input mapper.
+      # Declares one possible next route with an optional condition and input mapper.
+      #
+      # +input+ receives Graph::State and returns the value passed to the target
+      # node. At most one conditional edge may match from the current node; one
+      # unconditional edge may act as the fallback.
       def edge(from, to, input: nil, **options, &condition)
         condition = extract_condition(options, condition)
         validate_callable!(input, "edge input mapper")
@@ -123,6 +132,9 @@ module LittleGhost
       end
 
       # Routes selected node errors after retries are exhausted.
+      #
+      # +on+ lists the exception classes this route accepts. An +input+ mapper
+      # may turn Graph::State, including +state.error+, into recovery input.
       def error_edge(from, to, on:, input: nil)
         errors = Array(on)
         unless errors.any? && errors.all? { |error| error.is_a?(Class) && error <= Exception }
@@ -140,6 +152,10 @@ module LittleGhost
       end
 
       # Starts two or more independent branches with bounded concurrency.
+      #
+      # +to+ names the first node in each branch. The matching
+      # Graph.join[rdoc-ref:LittleGhost::Graph.join] collects the terminal result
+      # from every branch.
       def fork(from, to:, max_concurrency: 8)
         targets = Array(to).map { |name| normalize_node_name(name) }
         raise ArgumentError, "fork requires at least two targets" if targets.length < 2
@@ -153,6 +169,9 @@ module LittleGhost
       end
 
       # Joins the terminal results of one declared fork.
+      #
+      # +input+ receives Graph::State and returns the value passed to the target
+      # node. Read each completed branch through +state.branch_results+.
       def join(from, to:, input: nil)
         sources = Array(from).map { |name| normalize_node_name(name) }
         raise ArgumentError, "join requires at least two sources" if sources.length < 2

data/lib/little_ghost/message.rb

@@ -21,8 +21,8 @@ module LittleGhost
     attr_reader :role, :content, :metadata
 
     # Creates a frozen message with a supported +role+, normalized +content+, and
-    # application-defined +metadata+. The content Array and metadata Hash are
-    # frozen, but nested caller-owned values are retained.
+    # application-defined +metadata+. Metadata becomes a frozen DataMap, so
+    # String and Symbol keys address the same JSON-compatible value.
     def initialize(role:, content:, metadata: {})
       @role = role.to_sym
       raise ArgumentError, "Unsupported message role: #{role.inspect}" unless ROLES.include?(@role)
@@ -35,7 +35,7 @@ module LittleGhost
         [content]
       end
       @content = blocks.map { |block| Content.normalize(block) }.freeze
-      @metadata = metadata.freeze
+      @metadata = DataMap.new(metadata).freeze
       freeze
     end
 
@@ -64,7 +64,7 @@ module LittleGhost
 
     # Produces the JSON-safe message representation.
     def to_h
-      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata}
+      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata.to_h}
     end
 
     # Encodes #to_h as JSON, forwarding generator +arguments+.

data/lib/little_ghost/model_resolver.rb

@@ -30,7 +30,7 @@ module LittleGhost
       @providers = providers
       @connections = providers&.connections || {}
       @profiles = normalize_profiles(profiles || {})
-      @default_model = default_model&.to_s || "default"
+      @default_model = (default_model&.to_s || "default").dup.freeze
       @provider_registry = provider_adapters.empty? ? provider_registry : ProviderRegistry.new(adapters: provider_adapters)
       @credential_resolver = credential_resolver
       configure_default_providers unless providers
@@ -254,7 +254,7 @@ module LittleGhost
 
         parent = profile["inherits"] || profile[:inherits]
         validate_role_name!(parent.to_s) if parent
-        [role, profile.to_h]
+        [role, immutable_selection_value(profile.to_h)]
       end
     end
 

data/lib/little_ghost/prompt_resolver.rb

@@ -71,6 +71,8 @@ module LittleGhost
   #
   # Every configured root is trusted Ruby code because ERB executes inside the
   # current process. Keep roots application-controlled and non-user-writable.
+  # See the {Prompts as Views guide}[rdoc-ref:docs/guides/prompt_views.md] for the
+  # conventional Agent workflow.
   class PromptResolver
     DEFAULT_MAX_DEPTH = 20 # :nodoc: