phronomy 0.7.0 → 0.8.0

data/lib/phronomy/fsm_session.rb

@@ -1,201 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Event-driven execution wrapper for a single workflow run.
-  #
-  # Created by WorkflowRunner and registered with EventLoop. All public methods
-  # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
-  # not be accessed concurrently from multiple threads.
-  #
-  # == Lifecycle
-  #
-  #   register(session) → EventLoop posts :start → session.start
-  #                                 ↓ (auto-transition present)
-  #                        EventLoop posts :state_completed → session.handle
-  #                                 ↓ (repeat)
-  #                        session posts :finished or :halted
-  #                                 ↓
-  #                        EventLoop pushes ctx to completion_queue → caller unblocks
-  #
-  # == Async IO pattern (EventLoop mode only)
-  #
-  # When a state has no auto-transition and is not a wait_state, but has an
-  # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
-  # the FSMSession stays registered in the EventLoop and waits for that event.
-  # The entry action is expected to spawn an IO thread that posts the event back:
-  #
-  #   entry :fetching, ->(ctx) {
-  #     Thread.new {
-  #       ctx.result = http.get(ctx.url)
-  #       Phronomy::EventLoop.instance.post(
-  #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
-  #       )
-  #     }
-  #   }
-  #   transition from: :fetching, on: :fetch_done, to: :process
-  class FSMSession
-    FINISH = WorkflowRunner::FINISH
-
-    # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
-    attr_reader :id
-
-    # @param id                  [String]
-    # @param context             [Object]        includes Phronomy::WorkflowContext
-    # @param entry_point         [Symbol]        initial state name
-    # @param entry_actions       [Hash]          { state_name => [callable, ...] }
-    # @param auto_state_set      [Hash]          { state_name => true }
-    # @param declared_states     [Array<Symbol>] all action state names
-    # @param wait_state_names    [Array<Symbol>]
-    # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
-    # @param phase_machine_class [Class]         state_machines-backed phase tracker class
-    # @param recursion_limit     [Integer]
-    # @param resume_event        [Symbol, nil]   external event to fire when resuming
-    # @param resume_phase        [Symbol, nil]   wait state name to resume from
-    # @api private
-    def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
-      declared_states:, wait_state_names:, external_events:, phase_machine_class:,
-      recursion_limit:, resume_event: nil, resume_phase: nil)
-      @id = id
-      @ctx = context
-      @entry_point = entry_point
-      @entry_actions = entry_actions
-      @auto_state_set = auto_state_set
-      @declared_states = declared_states
-      @wait_state_names = wait_state_names
-      @external_events = external_events
-      @phase_machine_class = phase_machine_class
-      @recursion_limit = recursion_limit
-      @resume_event = resume_event
-      @resume_phase = resume_phase
-      @step = 0
-      @done = false
-      @current_state = nil
-      @tracker = nil
-    end
-
-    # Begins workflow execution. Called by EventLoop on :start event.
-    def start
-      if @resume_event
-        # Resume from wait state: position tracker at the wait state, then fire the
-        # external event. state_machines fires before_transition (exit) and
-        # after_transition (entry) callbacks, so both actions execute here.
-        @current_state = @resume_phase
-        @tracker = build_tracker(@current_state)
-        @tracker.context = @ctx
-        fire_and_advance!(@resume_event)
-      else
-        # Fresh start: state_machines does not fire callbacks on initialization,
-        # so we invoke the entry action for the initial state manually.
-        @current_state = @entry_point
-        @tracker = build_tracker(@current_state)
-        @tracker.context = @ctx
-        (@entry_actions[@current_state] || []).each do |c|
-          result = c.call(@ctx)
-          @ctx = result if result.is_a?(Phronomy::WorkflowContext)
-        end
-        @tracker.context = @ctx
-        advance_or_halt
-      end
-    rescue => e
-      finish_with_error(e)
-    end
-
-    # Processes an event dispatched from EventLoop.
-    # Called for :state_completed and all user-defined external events.
-    #
-    # @param event [Phronomy::Event]
-    # @api private
-    def handle(event)
-      return if @done
-
-      fire_and_advance!(event.type)
-    rescue => e
-      finish_with_error(e)
-    end
-
-    private
-
-    # Fires event_name on the phase tracker, updates @current_state, then
-    # calls advance_or_halt to decide what to do next.
-    def fire_and_advance!(event_name)
-      if @step >= @recursion_limit
-        raise Phronomy::RecursionLimitError,
-          "Recursion limit (#{@recursion_limit}) exceeded"
-      end
-
-      fire_event!(@tracker, event_name, @current_state)
-      @ctx = @tracker.context
-      next_phase = @tracker.phase.to_sym
-      # When next_phase == @current_state, no transition matched → treat as terminal.
-      @current_state = (next_phase == @current_state) ? FINISH : next_phase
-      @step += 1
-      advance_or_halt
-    end
-
-    # Determines the next action after the FSM has entered @current_state.
-    def advance_or_halt
-      return finish! if @current_state == FINISH
-
-      if @wait_state_names.include?(@current_state)
-        return halt!
-      end
-
-      if @auto_state_set.key?(@current_state)
-        event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
-        return
-      end
-
-      if has_external_event_from?(@current_state)
-        # Async IO pattern: the entry action spawned an IO thread that will post
-        # an external event back. Stay registered; do nothing here.
-        return
-      end
-
-      # No transition declared — validate the state is known, then treat as terminal.
-      unless @declared_states.include?(@current_state)
-        raise ArgumentError, "State #{@current_state.inspect} is not defined"
-      end
-
-      finish!
-    end
-
-    def finish!
-      @done = true
-      @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
-      event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
-    end
-
-    def halt!
-      @done = true
-      @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
-      event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
-    end
-
-    def finish_with_error(err)
-      @done = true
-      event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
-    end
-
-    def fire_event!(tracker, event_name, from_state)
-      return if tracker.send(event_name)
-
-      raise ArgumentError,
-        "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
-        "Ensure at least one guard matches or add a fallback (no-guard) transition."
-    end
-
-    def has_external_event_from?(state)
-      @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
-    end
-
-    def build_tracker(from_state)
-      machine = @phase_machine_class.new
-      machine.instance_variable_set(:@phase, from_state.to_s)
-      machine
-    end
-
-    def event_loop
-      Phronomy::EventLoop.instance
-    end
-  end
-end

data/lib/phronomy/knowledge_source/base.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module KnowledgeSource
-    # Abstract base class for all KnowledgeSource implementations.
-    #
-    # Subclasses must implement #fetch(query:) and return an Array of chunk Hashes.
-    # Each chunk Hash must contain:
-    #   :content [String]  the text to inject into the context
-    #   :type    [Symbol]  semantic tag (e.g. :static, :rag, :entity)
-    class Base
-      # Retrieve knowledge chunks relevant to the given query.
-      #
-      # @param query              [String, nil]                    the current user input used to select relevant chunks
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional token; raises CancellationError when cancelled
-      # @return [Array<Hash>] array of { content: String, type: Symbol }
-      # @api public
-      def fetch(query: nil, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        raise NotImplementedError, "#{self.class}#fetch is not implemented"
-      end
-
-      # Returns true when this source's content is considered static (i.e. does
-      # not change between agent invocations). Static sources are eligible for
-      # fingerprint-based caching in ContextVersionCache.
-      #
-      # Override in subclasses that return fixed content.
-      #
-      # @return [Boolean]
-      # @api public
-      def static?
-        false
-      end
-    end
-  end
-end

data/lib/phronomy/knowledge_source/entity_knowledge.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module KnowledgeSource
-    # A KnowledgeSource that extracts named-entity facts from conversation history.
-    #
-    # This is the knowledge-injection counterpart of the old EntityMemory.
-    # It scans saved user messages with a regex heuristic (no LLM call) and
-    # returns the discovered facts as a single knowledge chunk tagged :entity.
-    #
-    # EntityKnowledge is stateful: it accumulates extracted facts via #update(messages:)
-    # which should be called each time new messages are saved.
-    #
-    # Supported extraction patterns (case-insensitive):
-    #   "my name is Alice"          → { name: "Alice" }
-    #   "I am Alice"                → { identity: "Alice" }
-    #   "I'm a software engineer"   → { occupation: "software engineer" }
-    #   "I work at / for Acme"      → { workplace: "Acme" }
-    #   "I live in Tokyo"           → { location: "Tokyo" }
-    #   "I'm from Tokyo"            → { location: "Tokyo" }
-    #   "I like / love Ruby"        → { preference: "Ruby" }
-    #
-    # @example
-    #   ks = Phronomy::KnowledgeSource::EntityKnowledge.new
-    #   ks.update(messages: chat_messages)
-    #   agent.invoke("What is my name?", config: { knowledge_sources: [ks] })
-    class EntityKnowledge < Base
-      PATTERNS = [
-        [:name, /\bmy name is\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-        [:identity, /\bI\s+am\s+([A-Z][A-Za-z0-9 \-']+)/],
-        [:occupation, /\bI(?:'m| am) a(?:n)?\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-        [:workplace, /\bI (?:work|worked) (?:at|for|in)\s+([A-Za-z0-9][A-Za-z0-9 \-'.&,]*)/i],
-        [:location, /\bI live in\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-        [:location, /\bI(?:'m| am) from\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-        [:preference, /\bI (?:like|love|enjoy)\s+([A-Za-z][A-Za-z0-9 \-']*)/i]
-      ].freeze
-
-      def initialize
-        @entities = {}
-      end
-
-      # Scan messages and accumulate entity facts.
-      # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
-      #
-      # @param messages [Array] message objects responding to #role and #content
-      # @api public
-      def update(messages:)
-        messages.each do |msg|
-          next unless msg.role.to_sym == :user
-
-          extract(msg.content.to_s).each { |key, value| @entities[key] = value }
-        end
-      end
-
-      # Returns a single chunk containing all known entity facts in XML context format.
-      # Returns an empty array when no entities have been discovered.
-      #
-      # @param query              [String, nil]                    unused — entity knowledge is always fully injected
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Hash>]
-      # @api public
-      def fetch(query: nil, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        return [] if @entities.empty?
-
-        lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
-        content = <<~CONTENT.chomp
-          Known facts about the user:
-          #{lines}
-        CONTENT
-        [{content: content, type: :entity}]
-      end
-
-      # Returns the current entity store (primarily for testing).
-      #
-      # @return [Hash]
-      # @api public
-      def entities
-        @entities.dup
-      end
-
-      private
-
-      def extract(text)
-        found = {}
-        PATTERNS.each do |key, pattern|
-          if (match = text.match(pattern))
-            value = match[1].strip.sub(/[.!?]\s+.*$/, "").gsub(/[.,;!?]+$/, "")
-            found[key] = value unless value.empty?
-          end
-        end
-        found
-      end
-    end
-  end
-end

data/lib/phronomy/knowledge_source/rag_knowledge.rb

@@ -1,57 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module KnowledgeSource
-    # A KnowledgeSource that retrieves semantically relevant chunks from a VectorStore.
-    #
-    # On each #fetch call, the query is embedded and the k nearest documents are
-    # returned as knowledge chunks.
-    #
-    # @example
-    #   store = Phronomy::VectorStore::InMemory.new
-    #   embeddings = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "text-embedding-3-small")
-    #   ks = Phronomy::KnowledgeSource::RAGKnowledge.new(
-    #     store: store,
-    #     embeddings: embeddings,
-    #     k: 5
-    #   )
-    class RAGKnowledge < Base
-      # @param store      [Phronomy::VectorStore::Base]    vector store holding documents
-      # @param embeddings [Phronomy::Embeddings::Base]     embeddings adapter
-      # @param k          [Integer]                        number of chunks to retrieve
-      # @param type       [Symbol]                         semantic tag (default :rag)
-      # @param source     [String, nil]                    default source label; falls back to
-      #   each document's :source metadata when nil
-      # @api public
-      def initialize(store:, embeddings:, k: 5, type: :rag, source: nil)
-        @store = store
-        @embeddings = embeddings
-        @k = k
-        @type = type
-        @source = source
-      end
-
-      # Embed the query and retrieve the k nearest chunks from the vector store.
-      #
-      # Returns an empty array when query is nil or blank.
-      #
-      # @param query              [String, nil]
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Hash>]
-      # @api public
-      def fetch(query: nil, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        return [] if query.nil? || query.strip.empty?
-
-        vector = @embeddings.embed(query, cancellation_token)
-        results = @store.search(query_embedding: vector, k: @k, cancellation_token: cancellation_token)
-        results.map do |doc|
-          chunk = {content: doc[:metadata][:content], type: @type}
-          src = @source || doc[:metadata][:source]
-          chunk[:source] = src if src
-          chunk
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/knowledge_source/static_knowledge.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module KnowledgeSource
-    # A KnowledgeSource backed by fixed text provided at construction time.
-    #
-    # Useful for injecting static documents, policy files, or configuration
-    # knowledge that does not change per request.
-    #
-    # @example
-    #   ks = Phronomy::KnowledgeSource::StaticKnowledge.new(
-    #     "Our refund policy: ...",
-    #     type: :policy
-    #   )
-    #   agent.invoke("What is the refund policy?", config: { knowledge_sources: [ks] })
-    class StaticKnowledge < Base
-      # @param text   [String] the static knowledge text to inject
-      # @param type   [Symbol] semantic tag for the chunk (default :static)
-      # @param source [String, nil] label identifying where this knowledge came from
-      #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
-      #   so that agents can produce grounded citations.
-      # @api public
-      def initialize(text, type: :static, source: nil)
-        @text = text.to_s
-        @type = type
-        @source = source
-      end
-
-      # Returns the fixed text as a single chunk, regardless of query.
-      #
-      # @param query              [String, nil]                    ignored for static knowledge
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
-      # @return [Array<Hash>]
-      # @api public
-      def fetch(query: nil, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        return [] if @text.empty?
-
-        chunk = {content: @text, type: @type}
-        chunk[:source] = @source if @source
-        [chunk]
-      end
-
-      # Static knowledge content never changes between invocations.
-      # @return [true]
-      # @api public
-      def static?
-        true
-      end
-    end
-  end
-end

data/lib/phronomy/loader/base.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  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

data/lib/phronomy/loader/csv_loader.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-require "csv"
-
-module Phronomy
-  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::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

data/lib/phronomy/loader/markdown_loader.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Loader
-    # Loads a Markdown file, optionally splitting on top-level headings.
-    #
-    # When +split_on_headings:+ is true (the default), each H1/H2 section
-    # becomes a separate document so that embeddings capture section semantics
-    # rather than the full file at once.
-    #
-    # @example Single document (heading split disabled)
-    #   loader = Phronomy::Loader::MarkdownLoader.new(split_on_headings: false)
-    #   docs   = loader.load("README.md")
-    #   # => [{ text: "# Title\n...", metadata: { source: "README.md" } }]
-    #
-    # @example Split per heading (default)
-    #   loader = Phronomy::Loader::MarkdownLoader.new
-    #   docs   = loader.load("guide.md")
-    #   # => [
-    #   #   { text: "# Section 1\n...", metadata: { source: "guide.md", section: "Section 1" } },
-    #   #   { text: "## Sub-section\n...", metadata: { source: "guide.md", section: "Sub-section" } },
-    #   # ]
-    class MarkdownLoader < Base
-      HEADING_RE = /^(\#{1,6})\s+(.+)$/
-
-      # @param split_on_headings [Boolean] split on H1–H6 boundaries (default: true)
-      # @api public
-      def initialize(split_on_headings: true)
-        @split_on_headings = split_on_headings
-      end
-
-      # @param source [String] path to a Markdown file
-      # @return [Array<Hash>]
-      # @raise [Errno::ENOENT] if the file does not exist
-      # @api public
-      def load(source)
-        content = File.read(source, encoding: "UTF-8")
-        return [{text: content, metadata: {source: source}}] unless @split_on_headings
-
-        split_by_headings(content, source)
-      end
-
-      private
-
-      def split_by_headings(content, source)
-        sections = []
-        current_lines = []
-        current_heading = nil
-
-        content.each_line do |line|
-          if (m = HEADING_RE.match(line.chomp))
-            flush_section(sections, current_lines, current_heading, source) if current_lines.any?
-            current_heading = m[2].strip
-            current_lines = [line]
-          else
-            current_lines << line
-          end
-        end
-
-        flush_section(sections, current_lines, current_heading, source) if current_lines.any?
-
-        # Fall back to single document if no headings were found
-        sections.empty? ? [{text: content, metadata: {source: source}}] : sections
-      end
-
-      def flush_section(sections, lines, heading, source)
-        text = lines.join
-        return if text.strip.empty?
-
-        metadata = {source: source}
-        metadata[:section] = heading if heading
-        sections << {text: text, metadata: metadata}
-      end
-    end
-  end
-end

data/lib/phronomy/loader/plain_text_loader.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Loader
-    # Loads a plain-text file as a single document.
-    #
-    # @example
-    #   loader = Phronomy::Loader::PlainTextLoader.new
-    #   docs   = loader.load("/path/to/file.txt")
-    #   # => [{ text: "...", metadata: { source: "/path/to/file.txt" } }]
-    class PlainTextLoader < Base
-      # @param source [String] absolute or relative path to a text file
-      # @return [Array<Hash>] single-element array with the file contents
-      # @raise [Errno::ENOENT] if the file does not exist
-      # @api public
-      def load(source)
-        text = File.read(source, encoding: "UTF-8")
-        [{text: text, metadata: {source: source}}]
-      end
-    end
-  end
-end