phronomy 0.7.1 → 0.8.0

data/lib/phronomy/agent/checkpoint.rb

@@ -56,6 +56,124 @@ module Phronomy
         @pending_tool_args = pending_tool_args
         @pending_tool_call_id = pending_tool_call_id
       end
+
+      # Converts this checkpoint to a plain Hash suitable for JSON / Marshal serialization.
+      #
+      # All values are plain Ruby objects (String, Symbol, Hash, Array, Numeric,
+      # nil). +RubyLLM::Message+ objects in +:messages+ are deep-converted so that
+      # any embedded +RubyLLM::ToolCall+ objects are also serialized as plain hashes.
+      #
+      # @example Round-trip via JSON
+      #   json = JSON.generate(checkpoint.to_h)
+      #   checkpoint2 = Phronomy::Agent::Checkpoint.from_h(JSON.parse(json))
+      #
+      # @return [Hash]
+      # @api public
+      def to_h
+        {
+          thread_id: @thread_id,
+          original_input: @original_input,
+          messages: @messages.map { |m| serialize_message(m) },
+          pending_tool_name: @pending_tool_name,
+          pending_tool_args: @pending_tool_args,
+          pending_tool_call_id: @pending_tool_call_id
+        }
+      end
+
+      # Reconstructs a +Checkpoint+ from a plain Hash (e.g. produced by {#to_h}
+      # and deserialized from JSON or Marshal).
+      #
+      # Hash keys may be either Symbols or Strings; both are accepted.
+      # +RubyLLM::ToolCall+ objects inside message +:tool_calls+ arrays are
+      # reconstructed from their hash representations.
+      #
+      # @param h [Hash] a hash previously produced by {#to_h}
+      # @return [Checkpoint]
+      # @api public
+      def self.from_h(h)
+        h = h.transform_keys { |k|
+          begin
+            k.to_sym
+          rescue
+            k
+          end
+        }
+        messages = Array(h[:messages]).map { |m| deserialize_message(m) }
+        new(
+          thread_id: h[:thread_id],
+          original_input: h[:original_input],
+          messages: messages,
+          pending_tool_name: h[:pending_tool_name]&.to_s,
+          pending_tool_args: h[:pending_tool_args] ? h[:pending_tool_args].transform_keys { |k|
+            begin
+              k.to_sym
+            rescue
+              k
+            end
+          } : {},
+          pending_tool_call_id: h[:pending_tool_call_id]&.to_s
+        )
+      end
+
+      private
+
+      # Converts a +RubyLLM::Message+ to a plain Hash, ensuring that any
+      # embedded +RubyLLM::ToolCall+ objects in +:tool_calls+ are also converted.
+      #
+      # @param msg [RubyLLM::Message]
+      # @return [Hash]
+      # @api private
+      def serialize_message(msg)
+        h = msg.to_h
+        return h unless h[:tool_calls]
+
+        h.merge(tool_calls: h[:tool_calls].map { |tc|
+          tc.respond_to?(:to_h) ? tc.to_h : tc
+        })
+      end
+
+      # Reconstructs a +RubyLLM::Message+ from a plain Hash.
+      # +RubyLLM::ToolCall+ entries in +:tool_calls+ are re-instantiated.
+      #
+      # @param h [Hash]
+      # @return [RubyLLM::Message]
+      # @api private
+      def self.deserialize_message(h)
+        h = h.transform_keys { |k|
+          begin
+            k.to_sym
+          rescue
+            k
+          end
+        }
+        if h[:tool_calls]
+          h = h.merge(tool_calls: Array(h[:tool_calls]).map { |tc|
+            next tc if tc.is_a?(RubyLLM::ToolCall)
+
+            tc = tc.transform_keys { |k|
+              begin
+                k.to_sym
+              rescue
+                k
+              end
+            }
+            RubyLLM::ToolCall.new(
+              id: tc[:id].to_s,
+              name: tc[:name].to_s,
+              arguments: (tc[:arguments] || {}).transform_keys { |k|
+                begin
+                  k.to_sym
+                rescue
+                  k
+                end
+              },
+              thought_signature: tc[:thought_signature]
+            )
+          })
+        end
+        RubyLLM::Message.new(h)
+      end
+      private_class_method :deserialize_message
     end
   end
 end

data/lib/phronomy/agent/context/conversation/compaction_context.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Conversation
+        # Context object passed to the +on_compact+ callback registered on an agent.
+        #
+        # The callback calls #compact one or more times to specify which ranges of
+        # messages to replace with a summary. Each call:
+        #   1. Yields the selected message elements to the block.
+        #   2. Receives the block's return value as the summary text.
+        #   3. Persists a compaction record to the memory store (if available).
+        #   4. Updates #result_messages so that the compacted range is replaced
+        #      by a single +:system+ summary message.
+        #
+        # The agent reads #result_messages after the callback returns and uses it
+        # as the new message list for this invocation.
+        #
+        # @example Summarise the oldest half of the conversation
+        #   on_compact do |ctx|
+        #     half = ctx.message_elements.length / 2
+        #     ctx.compact(0...half) do |elements|
+        #       texts = elements.map { |e| "#{e[:role]}: #{e[:message].content}" }.join("\n")
+        #       "Summary of earlier conversation:\n#{texts}"
+        #     end
+        #   end
+        class CompactionContext
+          # @return [Array<Hash>] message elements at compaction time
+          attr_reader :message_elements
+
+          # @return [Phronomy::LlmContextWindow::TokenBudget, nil]
+          attr_reader :budget
+
+          # @return [Integer] total estimated token count before compaction
+          attr_reader :total_tokens
+
+          # The current message list to be used after all compact calls have been made.
+          # Updated by each call to #compact.
+          #
+          # @return [Array]
+          attr_reader :result_messages
+
+          # @param message_elements [Array<Hash>]
+          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
+          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
+          # @param thread_id [String, nil] used when saving compaction records
+          # @param memory [Object, nil] memory object; must respond to #save_compaction
+          #   for compaction records to be persisted
+          # @api private
+          # mutant:disable - e[:tokens] vs e.fetch(:tokens) and e[:message] vs e.fetch(:message) are genuine equivalent mutations: elements always carry both keys
+          def initialize(message_elements:, budget:, thread_id: nil, memory: nil)
+            @message_elements = message_elements.dup
+            @budget = budget
+            @total_tokens = message_elements.sum { |e| e[:tokens] }
+            @thread_id = thread_id
+            @memory = memory
+            @result_messages = @message_elements.map { |e| e[:message] }
+          end
+
+          # Replace a range of messages with a summary produced by the block.
+          #
+          # The block receives the selected Array<Hash> elements and must return a
+          # String that serves as the summary text. After the call, #result_messages
+          # reflects the replacement.
+          #
+          # If the memory object responds to #save_compaction, a compaction record
+          # { start_seq:, end_seq:, summary_text: } is persisted for auditability.
+          #
+          # @param range [Range, Integer] index range into message_elements (0-based)
+          # @yieldparam elements [Array<Hash>] the selected message elements
+          # @yieldreturn [String] summary text to replace the selected messages
+          # @return [Array] the updated result_messages array
+          # @api private
+          # mutant:disable - multiple genuine equivalent mutations: is_a? vs instance_of? (Array/Range have no subclasses), yield.to_s vs yield (block always returns String), [:seq]/[:message] vs .fetch(:seq)/.fetch(:message) (keys always present), range.to_i vs range/to_int/Integer() (Integer is already integer), || [] vs nothing (Array#[] never returns nil for slice), RubyLLM::Message vs Message (killfork inherits Message=Struct from integration specs, both expose identical role/content interface)
+          def compact(range)
+            # Normalise: Integer index → single-element Array; Range → Array slice.
+            raw = @message_elements[range]
+            elements = if raw.is_a?(Array)
+              raw
+            elsif raw.nil?
+              []
+            else
+              [raw]
+            end
+            return @result_messages if elements.empty?
+
+            summary_text = yield(elements).to_s
+
+            start_seq = elements.first[:seq]
+            end_seq = elements.last[:seq]
+
+            if @memory && @thread_id && @memory.respond_to?(:save_compaction)
+              @memory.save_compaction(
+                thread_id: @thread_id,
+                start_seq: start_seq,
+                end_seq: end_seq,
+                summary_text: summary_text
+              )
+            end
+
+            # Compute the last included index in the original @message_elements array.
+            last_idx = if range.is_a?(Range)
+              range.exclude_end? ? range.last - 1 : range.last
+            else
+              range.to_i
+            end
+
+            remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
+            summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
+            @result_messages = [summary_msg] + remaining
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/conversation/trigger_context.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Conversation
+        # Read-only context passed to the +on_compaction_trigger+ callback.
+        #
+        # The callback inspects the current message list and budget, then returns
+        # a truthy value to trigger compaction or a falsy value to skip it.
+        #
+        # No mutations are allowed through this object; use CompactionContext
+        # (passed to +on_compact+) for actual modifications.
+        #
+        # @example Trigger compaction when messages exceed 80% of the input budget
+        #   on_compaction_trigger do |ctx|
+        #     limit = ctx.budget&.available(used: 0) || Float::INFINITY
+        #     ctx.total_tokens > limit * 0.8
+        #   end
+        class TriggerContext
+          # @return [Array<Hash>] frozen snapshot of message elements
+          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
+          attr_reader :message_elements
+
+          # @return [Phronomy::LlmContextWindow::TokenBudget, nil] token budget for this invocation
+          attr_reader :budget
+
+          # @return [Integer] total estimated token count of all message elements
+          attr_reader :total_tokens
+
+          # @param message_elements [Array<Hash>]
+          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
+          # @api private
+          def initialize(message_elements:, budget:)
+            @message_elements = message_elements.dup.freeze
+            @budget = budget
+            @total_tokens = message_elements.sum { |e| e[:tokens] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/conversation/trim_context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Conversation
+        # Context object passed to the +on_trim+ callback registered on an agent class.
+        #
+        # The callback receives a TrimContext and may call #remove to drop specific
+        # messages from the conversation before the LLM is called. Changes affect
+        # only the current invocation; the underlying memory store is not modified.
+        #
+        # Message elements are identified by a +:seq+ integer that is assigned
+        # sequentially (0-based) when messages are loaded from memory each turn.
+        #
+        # @example Remove the oldest two messages when the budget is tight
+        #   on_trim do |ctx|
+        #     if ctx.total_tokens > ctx.budget.available(used: 0) * 0.9
+        #       seqs_to_drop = ctx.message_elements.first(2).map { |e| e[:seq] }
+        #       ctx.remove(seqs_to_drop)
+        #     end
+        #   end
+        class TrimContext
+          # @return [Phronomy::LlmContextWindow::TokenBudget, nil] token budget for this invocation
+          attr_reader :budget
+
+          # @return [Integer] total estimated token count of all current message elements
+          attr_reader :total_tokens
+
+          # @param message_elements [Array<Hash>]
+          #   each element: { seq: Integer, message: Object, tokens: Integer, role: Symbol }
+          # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
+          # @api private
+          def initialize(message_elements:, budget:)
+            @message_elements = message_elements.dup
+            @budget = budget
+            recalculate!
+          end
+
+          # Returns a snapshot of the current message elements (defensive copy).
+          # Each element is a Hash with +:seq+, +:message+, +:tokens+, and +:role+.
+          #
+          # @return [Array<Hash>]
+          # @api private
+          def message_elements
+            @message_elements.dup
+          end
+
+          # Remove messages identified by seq numbers.
+          # Calling this multiple times accumulates removals.
+          #
+          # @param seqs [Integer, Array<Integer>] seq number(s) to remove
+          # @return [self]
+          # @api private
+          # mutant:disable - Array(seqs).to_set vs Array(seqs) and e[:seq] vs e.fetch(:seq) are genuine equivalent: Array#include? returns identical results for both
+          def remove(seqs)
+            seqs_set = Array(seqs).to_set
+            @message_elements.reject! { |e| seqs_set.include?(e[:seq]) }
+            recalculate!
+            self
+          end
+
+          # Convenience: returns the plain message objects (without element metadata).
+          #
+          # @return [Array]
+          # @api private
+          # mutant:disable - e[:message] vs e.fetch(:message) is a genuine equivalent mutation: elements always carry :message
+          def messages
+            @message_elements.map { |e| e[:message] }
+          end
+
+          private
+
+          # mutant:disable - e[:tokens] vs e.fetch(:tokens) is a genuine equivalent mutation: elements always carry :tokens
+          def recalculate!
+            @total_tokens = @message_elements.sum { |e| e[:tokens] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/instruction/prompt_template.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Instruction
+        # A prompt template that substitutes {{variable}} placeholders in a string.
+        #
+        # @example Simple human template
+        #   t = Phronomy::Agent::Context::Instruction::PromptTemplate.new(template: "Translate to {{lang}}: {{text}}")
+        #   t.format(lang: "French", text: "Hello")
+        #   # => "Translate to French: Hello"
+        #
+        # @example With a system template
+        #   t = Phronomy::Agent::Context::Instruction::PromptTemplate.new(
+        #     template: "{{question}}",
+        #     system_template: "You are a {{role}} assistant."
+        #   )
+        #   t.format_system(role: "helpful")
+        #   # => "You are a helpful assistant."
+        #
+        # As a Runnable, #invoke accepts a Hash of variables and returns a Hash
+        # with :prompt (and optionally :system) keys.
+        class PromptTemplate
+          include Phronomy::Runnable
+
+          PLACEHOLDER = /\{\{(\w+)\}\}/
+
+          attr_reader :template, :system_template
+
+          # @param template        [String] human message template with {{var}} placeholders
+          # @param system_template [String, nil] optional system message template
+          # @api public
+          def initialize(template:, system_template: nil)
+            @template = template
+            @system_template = system_template
+          end
+
+          # Substitute all {{var}} placeholders in the human template.
+          #
+          # @param variables [Hash{Symbol => String}]
+          # @return [String]
+          # @api public
+          def format(**variables)
+            substitute(@template, variables)
+          end
+
+          # Substitute all {{var}} placeholders in the system template.
+          # Returns nil when no system template was set.
+          #
+          # @param variables [Hash{Symbol => String}]
+          # @return [String, nil]
+          # @api public
+          def format_system(**variables)
+            @system_template && substitute(@system_template, variables)
+          end
+
+          # Runnable interface: accepts a Hash of variable values.
+          # Returns { prompt: String, system: String|nil }.
+          #
+          # @param input  [Hash{Symbol => String}]
+          # @return [Hash]
+          # @api public
+          def invoke(input, config: {})
+            vars = normalize_input(input)
+            result = {prompt: format(**vars)}
+            sys = format_system(**vars)
+            result[:system] = sys if sys
+            result
+          end
+
+          # Returns the list of placeholder names found in both templates.
+          #
+          # @return [Array<Symbol>]
+          # @api public
+          def variables
+            names = @template.scan(PLACEHOLDER).flatten
+            names += @system_template.scan(PLACEHOLDER).flatten if @system_template
+            names.map(&:to_sym).uniq
+          end
+
+          private
+
+          def substitute(text, variables)
+            text.gsub(PLACEHOLDER) do |match|
+              key = Regexp.last_match(1).to_sym
+              variables.fetch(key) { raise KeyError, "Missing variable: {{#{key}}}" }
+            end
+          end
+
+          def normalize_input(input)
+            case input
+            when Hash then input
+            when String then {input: input}
+            else raise ArgumentError, "PromptTemplate#invoke expects a Hash of variables, got #{input.class}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/embeddings/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        module Embeddings
+          # Abstract interface for embedding adapters.
+          #
+          # Concrete implementations must override {#embed} and return a vector
+          # as an +Array<Float>+.
+          class Base
+            # Embed the given text and return a vector representation.
+            #
+            # @param text               [String]                         the text to embed
+            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+            # @return [Array<Float>] the embedding vector
+            # @api public
+            def embed(text, cancellation_token = nil)
+              cancellation_token&.raise_if_cancelled!
+              raise NotImplementedError, "#{self.class}#embed is not implemented"
+            end
+
+            # Submits an {#embed} call to {BlockingAdapterPool} and returns a
+            # {BlockingAdapterPool::PendingOperation}.
+            #
+            # @param text               [String]
+            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+            # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+            # @return [BlockingAdapterPool::PendingOperation]
+            # @api public
+            def embed_async(text, cancellation_token = nil, timeout: nil)
+              Phronomy::Runtime.instance.blocking_io.submit(
+                timeout: timeout,
+                cancellation_token: cancellation_token
+              ) do
+                embed(text, cancellation_token)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/embeddings/ruby_llm_embeddings.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        module Embeddings
+          # Embeddings adapter backed by RubyLLM.
+          #
+          # Delegates to +RubyLLM.embed+ and returns the resulting vector as an
+          # +Array<Float>+.
+          #
+          # @example Default model
+          #   embeddings = Phronomy::Agent::Context::Knowledge::Embeddings::RubyLLMEmbeddings.new
+          #   vector = embeddings.embed("Hello, world!")
+          #
+          # @example Explicit model
+          #   embeddings = Phronomy::Agent::Context::Knowledge::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
+          #   vector = embeddings.embed("Hello, world!")
+          class RubyLLMEmbeddings < Base
+            # @param model               [String, nil] embedding model identifier; nil uses the RubyLLM default
+            # @param provider            [Symbol, nil] provider override (e.g. :openai); nil uses the RubyLLM default
+            # @param assume_model_exists [Boolean]     when true, skips RubyLLM model-registry validation
+            #                                          (useful for locally hosted models not in the registry)
+            # @api public
+            def initialize(model: nil, provider: nil, assume_model_exists: false)
+              @model = model
+              @provider = provider
+              @assume_model_exists = assume_model_exists
+            end
+
+            # Embed text via RubyLLM.
+            #
+            # @param text               [String]
+            # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+            # @return [Array<Float>]
+            # @api public
+            def embed(text, cancellation_token = nil)
+              cancellation_token&.raise_if_cancelled!
+              opts = {}
+              opts[:model] = @model if @model
+              opts[:provider] = @provider if @provider
+              opts[:assume_model_exists] = true if @assume_model_exists
+              RubyLLM.embed(text, **opts).vectors
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/loader/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        module Loader
+          # Abstract base class for document loaders.
+          #
+          # A loader converts an external source (file path, URL, etc.) into an
+          # Array of document hashes understood by the rest of the pipeline:
+          #
+          #   [{ text: String, metadata: Hash }, ...]
+          #
+          # Subclasses must implement {#load}.
+          class Base
+            # Load documents from +source+ and return an array of document hashes.
+            #
+            # @param source [String] file path, URL, or other source identifier
+            # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
+            # @raise [NotImplementedError] when not overridden by a subclass
+            # @api public
+            def load(source)
+              raise NotImplementedError, "#{self.class}#load is not implemented"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/loader/csv_loader.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "csv"
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        module Loader
+          # Loads a CSV file, converting each row into a separate document.
+          #
+          # By default the first row is treated as a header and column names are
+          # available in the document metadata.  The full row is serialised to
+          # a human-readable "key: value" string for embedding.
+          #
+          # @example
+          #   loader = Phronomy::Agent::Context::Knowledge::Loader::CsvLoader.new
+          #   docs   = loader.load("products.csv")
+          #   # => [
+          #   #   { text: "name: Widget\nprice: 9.99", metadata: { source: "...", row: 1, name: "Widget", price: "9.99" } },
+          #   #   ...
+          #   # ]
+          class CsvLoader < Base
+            # @param headers     [Boolean] treat the first row as headers (default: true)
+            # @param text_column [String, nil] if set, use only this column as the document text
+            # @api public
+            def initialize(headers: true, text_column: nil)
+              @headers = headers
+              @text_column = text_column
+            end
+
+            # @param source [String] path to a CSV file
+            # @return [Array<Hash>]
+            # @raise [Errno::ENOENT] if the file does not exist
+            # @api public
+            def load(source)
+              rows = CSV.read(source, headers: @headers, encoding: "UTF-8")
+
+              if @headers
+                rows.each_with_index.map do |row, idx|
+                  row_hash = row.to_h
+                  text = if @text_column
+                    row_hash[@text_column].to_s
+                  else
+                    row_hash.map { |k, v| "#{k}: #{v}" }.join("\n")
+                  end
+                  metadata = row_hash.transform_keys(&:to_sym).merge(source: source, row: idx + 1)
+                  {text: text, metadata: metadata}
+                end
+              else
+                rows.each_with_index.map do |row, idx|
+                  text = row.join(", ")
+                  {text: text, metadata: {source: source, row: idx + 1}}
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end