little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/agent_builder.rb

@@ -29,17 +29,18 @@ module LittleGhost
       model: nil,
       tools: [],
       conversation_id: nil,
-      agent_path: Subagents::AgentPath::ROOT
+      agent_path: Subagents::AgentPath::ROOT,
+      agent_stream_path: []
     )
       agent_class = @resolve_agent.call(agent_class_or_name)
-      build_agent(agent_class, run:, model:, tools:, conversation_id:, agent_path:)
+      build_agent(agent_class, run:, model:, tools:, conversation_id:, agent_path:, agent_stream_path:)
     end
 
     private
 
     attr_reader :runtime, :prompt_paths
 
-    def instantiate(agent_class, run:, tools:, model:, delegation_activity:, agent_path:)
+    def instantiate(agent_class, run:, tools:, model:, delegation_activity:, agent_path:, agent_stream_path:)
       agent_class.new(
         model:,
         runtime:,
@@ -51,7 +52,7 @@ module LittleGhost
         delegation_activity:,
         agent_path:,
         **agent_class.limits
-      )
+      ).bind_agent_stream_path(agent_stream_path)
     end
 
     def build_agent(
@@ -60,12 +61,13 @@ module LittleGhost
       model:,
       tools:,
       conversation_id: nil,
-      agent_path: Subagents::AgentPath::ROOT
+      agent_path: Subagents::AgentPath::ROOT,
+      agent_stream_path: []
     )
       delegation_activity = ActivityRelay.new
       configured_tools = Array(tools).dup
       configured_tools.concat(
-        delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
+        delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:, agent_stream_path:)
       )
       resolved_model = model || runtime.model_for(agent_class, run)
       transferred = true
@@ -75,25 +77,33 @@ module LittleGhost
         model: resolved_model,
         tools: configured_tools,
         delegation_activity:,
-        agent_path:
+        agent_path:,
+        agent_stream_path:
       )
     rescue
       close_tools(configured_tools) unless transferred
       raise
     end
 
-    def delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
-      tools = agent_tools(agent_class, run)
-      tools.concat(subagent_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:))
+    def delegation_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:, agent_stream_path:)
+      tools = agent_tools(agent_class, run, agent_stream_path:)
+      tools.concat(subagent_tools(
+        agent_class,
+        run,
+        conversation_id:,
+        delegation_activity:,
+        agent_path:,
+        agent_stream_path:
+      ))
     rescue
       close_tools(tools)
       raise
     end
 
-    def agent_tools(agent_class, run)
+    def agent_tools(agent_class, run, agent_stream_path:)
       tools = []
       agent_class.assembly_tool_declarations.each do |declaration|
-        child = declared_assembly(declaration, run)
+        child = declared_assembly(declaration, run, agent_stream_path:)
         begin
           tools << child.as_tool(
             name: declaration.fetch(:name),
@@ -111,18 +121,18 @@ module LittleGhost
       raise
     end
 
-    def declared_assembly(declaration, run)
+    def declared_assembly(declaration, run, agent_stream_path:)
       assembly_class = declaration.fetch(:assembly)
       if assembly_class.is_a?(AssemblyDefinition) && assembly_class.kind == :agent
-        declared_agent(declaration.merge(agent: assembly_class.implementation), run)
+        declared_agent(declaration.merge(agent: assembly_class.implementation), run, agent_stream_path:)
       elsif assembly_class <= Agent
-        declared_agent(declaration.merge(agent: assembly_class), run)
+        declared_agent(declaration.merge(agent: assembly_class), run, agent_stream_path:)
       else
-        runtime.build_assembly(assembly_class, run:)
+        runtime.build_assembly(assembly_class, run:, agent_stream_path:)
       end
     end
 
-    def subagent_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:)
+    def subagent_tools(agent_class, run, conversation_id:, delegation_activity:, agent_path:, agent_stream_path:)
       definitions = agent_class.subagent_declarations.map do |declaration|
         Subagents::Definition.new(
           kind: declaration.fetch(:kind),
@@ -132,13 +142,16 @@ module LittleGhost
           factory: lambda do |subagent_id, child_conversation_id = nil|
             factory = declaration[:factory]
             if factory
-              invoke_factory(factory, subagent_id, run)
+              invoke_factory(factory, subagent_id, run).tap do |agent|
+                agent.bind_agent_stream_path(agent_stream_path) if agent.respond_to?(:bind_agent_stream_path)
+              end
             else
               declared_agent(
                 declaration,
                 run,
                 conversation_id: child_conversation_id,
-                agent_path: subagent_id
+                agent_path: subagent_id,
+                agent_stream_path:
               )
             end
           end
@@ -150,7 +163,11 @@ module LittleGhost
         unless resolved.all? { |definition| definition.is_a?(Subagents::Definition) }
           raise ConfigurationError, "Subagent resolvers must return LittleGhost::Subagents::Definition objects"
         end
-        definitions.concat(resolved.reject { |definition| declared_kinds.include?(definition.kind) })
+        definitions.concat(
+          resolved
+            .reject { |definition| declared_kinds.include?(definition.kind) }
+            .map { |definition| stream_bound_definition(definition, agent_stream_path) }
+        )
       end
       return [] if definitions.empty?
 
@@ -169,7 +186,13 @@ module LittleGhost
       ).tools
     end
 
-    def declared_agent(declaration, run, conversation_id: nil, agent_path: Subagents::AgentPath::ROOT)
+    def declared_agent(
+      declaration,
+      run,
+      conversation_id: nil,
+      agent_path: Subagents::AgentPath::ROOT,
+      agent_stream_path: []
+    )
       reference = declaration.fetch(:agent)
       agent_class = if reference.is_a?(AssemblyDefinition)
         reference.implementation
@@ -181,7 +204,23 @@ module LittleGhost
         model: resolve(declaration[:model], run),
         tools: Array(resolve(declaration[:tools], run)),
         conversation_id:,
-        agent_path:
+        agent_path:,
+        agent_stream_path:
+      )
+    end
+
+    def stream_bound_definition(definition, agent_stream_path)
+      factory = definition.factory
+      Subagents::Definition.new(
+        kind: definition.kind,
+        description: definition.description,
+        persist: definition.persist,
+        accepts_conversation_id: definition.accepts_conversation_id,
+        factory: lambda do |*arguments, **_options|
+          invoke_factory(factory, *arguments).tap do |agent|
+            agent.bind_agent_stream_path(agent_stream_path) if agent.respond_to?(:bind_agent_stream_path)
+          end
+        end
       )
     end
 

data/lib/little_ghost/{agent_interruptions.rb → agent_interjections.rb}

@@ -3,16 +3,16 @@
 require "securerandom"
 
 module LittleGhost
-  class AgentInterruptions # :nodoc: all
+  class AgentInterjections # :nodoc: all
     MAX_BATCH_SIZE = 100
-    MAX_INTERRUPTION_COUNT = 1_000
+    MAX_INTERJECTION_COUNT = 1_000
 
-    Response = Data.define(:text, :tool_calls, :interruption_ids, :batch_key) do
-      def initialize(text:, tool_calls:, interruption_ids: [], batch_key: nil)
+    Result = Data.define(:text, :tool_calls, :interjection_ids, :batch_key) do
+      def initialize(text:, tool_calls:, interjection_ids: [], batch_key: nil)
         super(
           text: String(text),
           tool_calls: !!tool_calls,
-          interruption_ids: Array(interruption_ids).map { |id| String(id).dup.freeze }.freeze,
+          interjection_ids: Array(interjection_ids).map { |id| String(id).dup.freeze }.freeze,
           batch_key: batch_key.nil? ? nil : String(batch_key).dup.freeze
         )
       end
@@ -21,7 +21,7 @@ module LittleGhost
     end
 
     Batch = Data.define(:tickets) do
-      def interruption_ids = tickets.map(&:id)
+      def interjection_ids = tickets.map(&:id)
       def batch_key = tickets.first&.batch_key
       def metadata = tickets.last&.metadata
     end
@@ -99,7 +99,7 @@ module LittleGhost
 
     def enqueue(message, id: SecureRandom.uuid, batch_key: nil, metadata: {})
       id = String(id)
-      raise ArgumentError, "interruption_id cannot be empty" if id.empty?
+      raise ArgumentError, "interjection_id cannot be empty" if id.empty?
 
       batch_key = String(batch_key) unless batch_key.nil?
       metadata = metadata.to_h
@@ -111,14 +111,14 @@ module LittleGhost
           unless existing.message.to_h == message.to_h &&
               existing.batch_key == batch_key &&
               existing.metadata == metadata
-            raise ArgumentError, "interruption_id has already been used with different input"
+            raise ArgumentError, "interjection_id has already been used with different input"
           end
 
           @waiters[existing] += 1
           return existing
         end
-        if @tickets_by_id.length >= MAX_INTERRUPTION_COUNT
-          raise AgentInterruptError, "Agent interruption capacity reached"
+        if @tickets_by_id.length >= MAX_INTERJECTION_COUNT
+          raise AgentInterjectionError, "Agent interjection capacity reached"
         end
 
         ticket = Ticket.new(message, id: id.freeze, batch_key: batch_key&.freeze, metadata:)
@@ -128,7 +128,7 @@ module LittleGhost
         ticket
       end
     rescue TypeError, NoMethodError
-      raise ArgumentError, "interruption_id, batch_key, and metadata are invalid"
+      raise ArgumentError, "interjection_id, batch_key, and metadata are invalid"
     end
 
     def deliver
@@ -166,7 +166,7 @@ module LittleGhost
         return true if @closed_error
         return false if @delivered || !@queue.empty?
 
-        @closed_error = AgentInterruptError.new("Agent is not currently running")
+        @closed_error = AgentInterjectionError.new("Agent is not currently running")
         true
       end
     end

data/lib/little_ghost/agent_stream_source.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  AgentStreamStep = Data.define( # :nodoc:
+    :assembly_id,
+    :assembly_kind,
+    :participant,
+    :step_id,
+    :branch_id
+  ) do
+    def self.build(assembly_id:, assembly_kind:, participant:, step_id:, branch_id: nil) # :nodoc:
+      new(
+        assembly_id: assembly_id.to_s.dup.freeze,
+        assembly_kind: assembly_kind.to_sym,
+        participant: participant.to_s.dup.freeze,
+        step_id: step_id.to_s.dup.freeze,
+        branch_id: branch_id&.to_s&.dup&.freeze
+      ).freeze
+    end
+  end
+
+  # Identifies one assembly step in the path to a streamed Agent invocation.
+  # Paths list outer steps before inner steps, so the final value identifies the
+  # participant that directly contains the Agent.
+  class AgentStreamStep < Data # :doc:
+    ##
+    # :attr_reader: assembly_id
+    # Stable String identifier for the containing assembly.
+
+    ##
+    # :attr_reader: assembly_kind
+    # The +:workflow+, +:swarm+, +:graph+, or custom assembly kind.
+
+    ##
+    # :attr_reader: participant
+    # String name used to route to this participant.
+
+    ##
+    # :attr_reader: step_id
+    # Unique String identifier for this assembly step.
+
+    ##
+    # :attr_reader: branch_id
+    # String branch identifier for a graph branch, or +nil+.
+  end
+
+  AgentStreamSource = Data.define( # :nodoc:
+    :agent_id,
+    :agent_path,
+    :operation_id,
+    :parent_operation_id,
+    :assembly_path
+  ) do
+    def self.build(agent_id:, agent_path:, operation_id:, parent_operation_id:, assembly_path:) # :nodoc:
+      new(
+        agent_id: agent_id.to_s.dup.freeze,
+        agent_path: agent_path.to_s.dup.freeze,
+        operation_id: operation_id.to_s.dup.freeze,
+        parent_operation_id: parent_operation_id&.to_s&.dup&.freeze,
+        assembly_path: Array(assembly_path).dup.freeze
+      ).freeze
+    end
+  end
+
+  # Describes which Agent produced an event during a Run.
+  #
+  # A +:agent_stream+ StreamEvent carries this value in +data[:source]+ and the
+  # Agent's event as a separate frozen StreamEvent in +data[:event]+.
+  # +assembly_path+ is empty for a top-level Agent and contains one
+  # AgentStreamStep for each enclosing composite assembly participant.
+  class AgentStreamSource < Data # :doc:
+    ##
+    # :attr_reader: agent_id
+    # Stable String identifier declared by the Agent class.
+
+    ##
+    # :attr_reader: agent_path
+    # Stable subagent path, beginning at <tt>/root</tt>.
+
+    ##
+    # :attr_reader: operation_id
+    # Unique String identifier for this Agent invocation.
+
+    ##
+    # :attr_reader: parent_operation_id
+    # Parent operation identifier, or +nil+ when the caller did not supply one.
+
+    ##
+    # :attr_reader: assembly_path
+    # Frozen Array of AgentStreamStep values from the outermost assembly inward.
+  end
+
+  module AgentStreamSnapshot # :nodoc: all
+    module_function
+
+    def event(event)
+      data = copy(event.data)
+      freeze_value(StreamEvent.build(event.type, **data))
+    end
+
+    def message(message)
+      freeze_value(copy(message))
+    end
+
+    def copy(value, copies = {})
+      return value if immutable_scalar?(value)
+      return copies.fetch(value.object_id) if copies.key?(value.object_id)
+
+      case value
+      when Message
+        copy_message(value, copies)
+      when DataMap
+        copy_data_map(value, copies)
+      when Hash
+        copy_hash(value, copies)
+      when Array
+        copy_array(value, copies)
+      when String
+        value.dup.freeze
+      when Data
+        copy_data(value, copies)
+      when Exception
+        copy_exception(value, copies)
+      else
+        copy_object(value, copies)
+      end
+    end
+
+    def copy_message(value, copies)
+      content = copy_array(value.content, copies)
+      metadata = copy_data_map(value.metadata, copies)
+      Message.new(role: value.role, content:, metadata:).freeze.tap do |snapshot|
+        copies[value.object_id] = snapshot
+      end
+    end
+
+    def copy_data_map(value, copies)
+      snapshot = DataMap.new
+      copies[value.object_id] = snapshot
+      value.each do |key, child|
+        snapshot[key] = copy(child, copies)
+      end
+      snapshot.freeze
+    end
+
+    def copy_hash(value, copies)
+      snapshot = {}
+      copies[value.object_id] = snapshot
+      value.each do |key, child|
+        snapshot[copy(key, copies)] = copy(child, copies)
+      end
+      snapshot.freeze
+    end
+
+    def copy_array(value, copies)
+      snapshot = []
+      copies[value.object_id] = snapshot
+      value.each { |child| snapshot << copy(child, copies) }
+      snapshot.freeze
+    end
+
+    def copy_data(value, copies)
+      attributes = value.members.to_h do |member|
+        [member, copy(value.public_send(member), copies)]
+      end
+      value.class.new(**attributes).freeze.tap do |snapshot|
+        copies[value.object_id] = snapshot
+      end
+    end
+
+    def copy_object(value, copies)
+      return value if value.is_a?(Module)
+
+      snapshot = value.dup
+      copies[value.object_id] = snapshot
+      value.instance_variables.each do |name|
+        snapshot.instance_variable_set(name, copy(value.instance_variable_get(name), copies))
+      end
+      snapshot.freeze
+    rescue TypeError
+      value.frozen? ? value : value.to_s.dup.freeze
+    end
+
+    def copy_exception(value, copies)
+      message = value.message.to_s.dup.freeze
+      snapshot = value.exception(message)
+      if snapshot.equal?(value)
+        snapshot = value.class.allocate
+        Exception.instance_method(:initialize).bind_call(snapshot, message)
+      end
+      copies[value.object_id] = snapshot
+      if value.cause
+        cause = copy(value.cause, copies)
+        begin
+          raise snapshot, cause:
+        rescue => raised
+          snapshot = raised
+          copies[value.object_id] = snapshot
+        end
+      end
+      value.instance_variables.each do |name|
+        snapshot.instance_variable_set(name, copy(value.instance_variable_get(name), copies))
+      end
+      backtrace = copy(value.backtrace, copies)
+      snapshot.set_backtrace(backtrace)
+      freeze_value(snapshot.backtrace) if snapshot.backtrace
+      snapshot.freeze
+    end
+
+    def immutable_scalar?(value)
+      value.nil? || value == true || value == false || value.is_a?(Numeric) || value.is_a?(Symbol)
+    end
+
+    def freeze_value(value, seen = {})
+      return value if immutable_scalar?(value) || value.is_a?(Module)
+      return value if seen[value.object_id]
+
+      seen[value.object_id] = true
+      case value
+      when Message
+        freeze_value(value.content, seen)
+        freeze_value(value.metadata, seen)
+      when Hash
+        value.each do |key, child|
+          freeze_value(key, seen)
+          freeze_value(child, seen)
+        end
+      when Array
+        value.each { |child| freeze_value(child, seen) }
+      when Data
+        value.members.each { |member| freeze_value(value.public_send(member), seen) }
+      else
+        value.instance_variables.each do |name|
+          freeze_value(value.instance_variable_get(name), seen)
+        end
+      end
+      value.freeze
+    end
+  end
+
+  class AgentStreamSink # :nodoc: all
+    def initialize(destination:, run:, source:, input:)
+      @destination = destination
+      @run = run
+      @source = source
+      @input = input
+    end
+
+    def <<(event)
+      data = {source: @source, event: AgentStreamSnapshot.event(event)}
+      data[:input] = AgentStreamSnapshot.message(normalized_input) if event.type == :invocation_start
+      @run.publish(:agent_stream, **data)
+      @destination << event
+    end
+
+    private
+
+    def normalized_input
+      @input.is_a?(Message) ? @input : Message.new(role: :user, content: @input)
+    end
+  end
+end

data/lib/little_ghost/artifact.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Represents a file, image, or document produced by a Tool or supplied to a
+  # Run. LittleGhost sends supported media to the model once and may store the
+  # same bytes for filesystem Tools. Inline artifacts contain their bytes.
+  # Deferred artifacts contain an application-defined reference that the block
+  # passed to Configuration#artifacts may use to load the bytes.
+  #
+  #   image = LittleGhost::Artifact.new(
+  #     data: File.binread("chart.png"),
+  #     media_type: "image/png",
+  #     name: "chart.png"
+  #   )
+  #
+  #   download = LittleGhost::Artifact.deferred(
+  #     reference: {file_id: "file-481"},
+  #     media_type: "application/pdf",
+  #     name: "report.pdf"
+  #   )
+  class Artifact
+    # Creates an inline artifact from binary +data+ and a MIME +media_type+.
+    def initialize(data:, media_type:, name: nil, metadata: {})
+      data = String(data).b
+      initialize_fields(
+        data: data.freeze,
+        reference: nil,
+        media_type:,
+        name:,
+        bytes: data.bytesize,
+        metadata:
+      )
+    rescue TypeError
+      raise ArgumentError, "artifact data must be a string"
+    end
+
+    # Creates an artifact whose bytes may be loaded later by the block passed to
+    # Configuration#artifacts.
+    def self.deferred(reference:, media_type:, name: nil, metadata: {})
+      raise ArgumentError, "artifact reference is required" if reference.nil?
+      reference = immutable_reference(reference)
+
+      allocate.tap do |artifact|
+        artifact.__send__(
+          :initialize_fields,
+          data: nil,
+          reference:,
+          media_type:,
+          name:,
+          bytes: nil,
+          metadata:
+        )
+      end
+    end
+
+    # Binary content for an inline artifact, otherwise nil.
+    attr_reader :data
+    # Application-defined deferred reference, or generated Workspace reference
+    # after storage; otherwise nil.
+    attr_reader :reference
+    # Optional display filename.
+    attr_reader :name
+    # MIME media type used to present the artifact.
+    attr_reader :media_type
+    # Known byte count, otherwise nil for an unresolved artifact.
+    attr_reader :bytes
+    # Deeply frozen application metadata.
+    attr_reader :metadata
+
+    # Whether this artifact contains its bytes directly.
+    def inline? = !data.nil?
+
+    # Whether this artifact requires an application resolver.
+    def deferred? = !reference.nil? && bytes.nil?
+
+    # Compares all immutable artifact fields.
+    def ==(other)
+      other.instance_of?(self.class) &&
+        [data, reference, name, media_type, bytes, metadata] ==
+          [other.data, other.reference, other.name, other.media_type, other.bytes, other.metadata]
+    end
+    # Uses the same field comparison when an artifact is a Hash key.
+    alias_method :eql?, :==
+
+    # Computes a Hash key from all immutable artifact fields.
+    def hash = [self.class, data, reference, name, media_type, bytes, metadata].hash
+
+    # Avoids placing bytes, names, metadata, or deferred references in diagnostics.
+    def inspect
+      kind = if inline?
+        "inline"
+      elsif deferred?
+        "deferred"
+      else
+        "stored"
+      end
+      "#<#{self.class} kind=#{kind.inspect} media_type=#{media_type.inspect} bytes=#{bytes.inspect}>"
+    end
+
+    class << self
+      def materialized(reference:, bytes:, media_type:, name: nil, metadata: {}) # :nodoc:
+        reference = String(reference)
+        bytes = Integer(bytes)
+        raise ArgumentError, "artifact reference is required" if reference.empty?
+        raise ArgumentError, "artifact bytes must not be negative" if bytes.negative?
+
+        allocate.tap do |artifact|
+          artifact.__send__(
+            :initialize_fields,
+            data: nil,
+            reference: reference.freeze,
+            media_type:,
+            name:,
+            bytes:,
+            metadata:
+          )
+        end
+      rescue TypeError
+        raise ArgumentError, "materialized artifact fields are invalid"
+      end
+
+      private
+
+      def immutable_reference(value)
+        case value
+        when String
+          raise ArgumentError, "artifact reference is required" if value.empty?
+
+          value.dup.freeze
+        when Hash
+          value.each_with_object({}) do |(key, child), copy|
+            copy[immutable_reference(key)] = immutable_reference(child)
+          end.freeze
+        when Array
+          value.map { |child| immutable_reference(child) }.freeze
+        else
+          unless value.frozen?
+            raise ArgumentError, "artifact reference must be immutable"
+          end
+
+          value
+        end
+      end
+    end
+
+    private
+
+    def initialize_fields(data:, reference:, media_type:, name:, bytes:, metadata:)
+      media_type = String(media_type)
+      raise ArgumentError, "artifact media_type is required" if media_type.empty?
+
+      name = String(name) if name
+      @data = data
+      @reference = reference
+      @name = name&.freeze
+      @media_type = media_type.freeze
+      @bytes = bytes
+      @metadata = deep_freeze(DataMap.new(metadata))
+      freeze
+    rescue TypeError
+      raise ArgumentError, "artifact fields are invalid"
+    end
+
+    def deep_freeze(value)
+      pending = [value]
+      until pending.empty?
+        current = pending.pop
+        case current
+        when Hash
+          current.each do |key, child|
+            key.freeze
+            pending << child
+          end
+        when Array
+          current.each { |child| pending << child }
+        end
+        current.freeze
+      end
+      value
+    end
+  end
+end