phronomy 0.2.2 → 0.3.0

data/lib/phronomy/state_store/active_record.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module StateStore
-    # ActiveRecord-backed state store.
-    # Persists graph state to a relational database using an AR model.
-    #
-    # The model_class must respond to:
-    #   .find_by(thread_id:)
-    #   .find_or_initialize_by(thread_id:)
-    #   #state_json=, #save!
-    #   .where(thread_id:).delete_all
-    #
-    # Minimal migration:
-    #   create_table :phronomy_states do |t|
-    #     t.string  :thread_id, null: false, index: { unique: true }
-    #     t.text    :state_json, null: false
-    #     t.timestamps
-    #   end
-    #
-    # @example
-    #   Phronomy.configure do |c|
-    #     c.default_state_store = Phronomy::StateStore::ActiveRecord.new(
-    #       model_class: PhronomyState
-    #     )
-    #   end
-    class ActiveRecord < Base
-      # @param model_class [Class] ActiveRecord model with the schema above.
-      # @param encryptor [Phronomy::StateStore::Encryptor::Base, nil]
-      #   Optional encryption adapter. When supplied, the JSON payload is
-      #   encrypted before writing and decrypted after reading.
-      #   When nil (default), data is stored as plain JSON.
-      def initialize(model_class:, encryptor: nil)
-        @model_class = model_class
-        @encryptor = encryptor
-      end
-
-      # Serializes and upserts the state for the given thread_id.
-      # @param state [Object] includes Phronomy::WorkflowContext
-      # @return [self]
-      def save(state)
-        json = serialize_state(state)
-        payload = @encryptor ? @encryptor.encrypt(json) : json
-        # Use upsert to avoid a race condition where two concurrent saves for the
-        # same thread_id would both see "no record" and collide on the unique index.
-        @model_class.upsert(
-          {thread_id: state.thread_id, state_json: payload},
-          unique_by: :thread_id,
-          update_only: [:state_json]
-        )
-        self
-      end
-
-      # Loads and deserializes the state for the given thread_id.
-      # @param thread_id [String]
-      # @return [Object, nil] state instance or nil
-      def load(thread_id)
-        record = @model_class.find_by(thread_id: thread_id)
-        return nil unless record
-
-        payload = record.state_json
-        json = @encryptor ? @encryptor.decrypt(payload) : payload
-        deserialize_state(json)
-      end
-
-      # Deletes the state for the given thread_id.
-      # @return [self]
-      def clear(thread_id)
-        @model_class.where(thread_id: thread_id).delete_all
-        self
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/base.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module StateStore
-    # Abstract base class for state persistence backends.
-    # Subclasses must implement save, load, and clear.
-    #
-    # The state object passed to save must include Phronomy::WorkflowContext
-    # and have a non-nil thread_id (set automatically by WorkflowRunner#invoke).
-    class Base
-      # Persists the state. The thread_id is read from state.thread_id.
-      # @param state [Object] object including Phronomy::WorkflowContext
-      # @return [self]
-      def save(state)
-        raise NotImplementedError, "#{self.class}#save is not implemented"
-      end
-
-      # Loads the state for the given thread_id.
-      # @param thread_id [String]
-      # @return [Object, nil] state object or nil if not found
-      def load(thread_id)
-        raise NotImplementedError, "#{self.class}#load is not implemented"
-      end
-
-      # Removes the saved state for the given thread_id.
-      # @param thread_id [String]
-      # @return [self]
-      def clear(thread_id)
-        raise NotImplementedError, "#{self.class}#clear is not implemented"
-      end
-
-      private
-
-      # Serializes a state object to a JSON string.
-      # Includes user-defined fields and internal graph metadata.
-      def serialize_state(state)
-        JSON.generate(
-          state_class: state.class.name,
-          state_data: json_safe(state.to_h),
-          thread_id: state.thread_id,
-          phase: state.phase&.to_s
-        )
-      end
-
-      # Deserializes a JSON string back into a state object.
-      # @return [Object] state instance with graph metadata restored
-      def deserialize_state(json_str)
-        data = JSON.parse(json_str, symbolize_names: true)
-        state_class = safe_state_class(data[:state_class])
-        state_data = symbolize_keys(data[:state_data])
-        state = state_class.new(**state_data)
-        state.set_graph_metadata(
-          thread_id: data[:thread_id],
-          phase: data[:phase]&.to_sym
-        )
-        state
-      end
-
-      # Resolves and validates a context class name.
-      # When a registry has been configured via +Phronomy.register_workflow_context+,
-      # only registered classes are accepted — this prevents unintended autoloading
-      # of arbitrary files from an untrusted class name stored in Redis/DB.
-      # When no registry is configured, falls back to Object.const_get with a check
-      # that the resolved class includes Phronomy::WorkflowContext.
-      def safe_state_class(class_name)
-        registry = Phronomy.workflow_context_registry
-        if registry
-          klass = registry[class_name.to_s]
-          unless klass
-            raise ArgumentError,
-              "Unregistered context class: #{class_name.inspect}. " \
-              "Call Phronomy.register_workflow_context(#{class_name}) at startup."
-          end
-          return klass
-        end
-
-        klass = Object.const_get(class_name.to_s)
-        unless klass.is_a?(Class) && klass.include?(Phronomy::WorkflowContext)
-          raise ArgumentError, "Invalid context class: #{class_name.inspect}"
-        end
-        klass
-      rescue NameError
-        raise ArgumentError, "Unknown context class: #{class_name.inspect}"
-      end
-
-      # Recursively converts objects to JSON-safe primitives.
-      def json_safe(obj)
-        case obj
-        when Hash
-          obj.transform_keys(&:to_s).transform_values { |v| json_safe(v) }
-        when Array
-          obj.map { |v| json_safe(v) }
-        when String, Numeric, TrueClass, FalseClass, NilClass
-          obj
-        else
-          obj.respond_to?(:to_h) ? json_safe(obj.to_h) : obj.to_s
-        end
-      end
-
-      # Recursively symbolizes hash keys.
-      def symbolize_keys(obj)
-        case obj
-        when Hash then obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
-        when Array then obj.map { |v| symbolize_keys(v) }
-        else obj
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/encryptor/active_support.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module StateStore
-    module Encryptor
-      # Encryptor backed by ActiveSupport::MessageEncryptor.
-      #
-      # Requires the +activesupport+ gem to be available in the host application.
-      # Does NOT require rails — any Ruby project that depends on activesupport can
-      # use this adapter.
-      #
-      # @example
-      #   encryptor = Phronomy::StateStore::Encryptor::ActiveSupport.new(
-      #     secret_key_base: ENV.fetch("SECRET_KEY_BASE")
-      #   )
-      #   store = Phronomy::StateStore::ActiveRecord.new(
-      #     model_class: PhronomyState,
-      #     encryptor: encryptor
-      #   )
-      class ActiveSupport < Base
-        # @param secret_key_base [String] secret used to derive the encryption key.
-        #   Must be at least 30 random bytes (use +SecureRandom.hex(64)+ to generate).
-        # @param cipher [String] OpenSSL cipher name (default: "aes-256-gcm").
-        # @raise [LoadError] when activesupport is not available.
-        def initialize(secret_key_base:, cipher: "aes-256-gcm")
-          require "active_support/message_encryptor"
-          key = ::ActiveSupport::KeyGenerator.new(secret_key_base)
-            .generate_key("phronomy state store", 32)
-          @encryptor = ::ActiveSupport::MessageEncryptor.new(key, cipher: cipher)
-        end
-
-        # Encrypts the plaintext using AES-256-GCM.
-        # @param plaintext [String]
-        # @return [String] Base64-encoded authenticated ciphertext
-        def encrypt(plaintext)
-          @encryptor.encrypt_and_sign(plaintext)
-        end
-
-        # Decrypts and verifies the ciphertext.
-        # @param ciphertext [String]
-        # @return [String] the original plaintext
-        # @raise [ActiveSupport::MessageEncryptor::InvalidMessage] on tampered data
-        def decrypt(ciphertext)
-          @encryptor.decrypt_and_verify(ciphertext)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/encryptor/base.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module StateStore
-    module Encryptor
-      # Abstract base class for state encryption adapters.
-      #
-      # Subclass and implement {#encrypt} and {#decrypt} to integrate any
-      # symmetric encryption scheme. Pass an instance to
-      # {Phronomy::StateStore::ActiveRecord} via the +encryptor:+ argument.
-      #
-      # @example
-      #   class MyEncryptor < Phronomy::StateStore::Encryptor::Base
-      #     def encrypt(plaintext) = Base64.strict_encode64(plaintext.reverse)
-      #     def decrypt(ciphertext) = Base64.strict_decode64(ciphertext).reverse
-      #   end
-      class Base
-        # Encrypts a plaintext string.
-        # @param plaintext [String] the JSON string produced by the state store
-        # @return [String] the encrypted ciphertext
-        def encrypt(plaintext)
-          raise NotImplementedError, "#{self.class}#encrypt is not implemented"
-        end
-
-        # Decrypts a ciphertext string.
-        # @param ciphertext [String] previously produced by {#encrypt}
-        # @return [String] the original plaintext
-        def decrypt(ciphertext)
-          raise NotImplementedError, "#{self.class}#decrypt is not implemented"
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/encryptor.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "encryptor/base"
-require_relative "encryptor/active_support"
-
-module Phronomy
-  module StateStore
-    # Namespace for state encryption adapters.
-    #
-    # Available adapters:
-    # - {Phronomy::StateStore::Encryptor::Base}       — abstract interface
-    # - {Phronomy::StateStore::Encryptor::ActiveSupport} — AES-256-GCM via ActiveSupport
-    module Encryptor
-    end
-  end
-end

data/lib/phronomy/state_store/file.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-require "fileutils"
-require "json"
-
-module Phronomy
-  module StateStore
-    # File-system-backed state store.
-    # Persists graph state as a JSON file under a configurable directory.
-    # No additional server or database migration is required — it works with
-    # the local file system out of the box.
-    #
-    # Each thread_id is stored as a separate file named "<thread_id>.json".
-    # The thread_id is sanitised before use as a filename to prevent path
-    # traversal: only alphanumeric characters, hyphens, underscores, and dots
-    # are allowed; all other characters are replaced with underscores.
-    #
-    # @note This store is suitable for single-process use (development, CLI
-    #   tools, tests).  It is not safe for concurrent access across multiple
-    #   processes without external locking.
-    #
-    # @example
-    #   store = Phronomy::StateStore::File.new(dir: "tmp/workflow_states")
-    #   Phronomy::Workflow.define(MyContext, state_store: store) do
-    #     # ...
-    #   end
-    class File < Base
-      # @param dir [String] directory where state files are stored.
-      #   Created automatically if it does not exist.
-      def initialize(dir: ::File.join(::Dir.tmpdir, "phronomy_states"))
-        @dir = ::File.expand_path(dir)
-        ::FileUtils.mkdir_p(@dir)
-      end
-
-      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
-      # @return [self]
-      def save(state)
-        ::File.write(path(state.thread_id), serialize_state(state))
-        self
-      end
-
-      # @param thread_id [String]
-      # @return [Object, nil] state instance or nil if not found
-      def load(thread_id)
-        file = path(thread_id)
-        return nil unless ::File.exist?(file)
-
-        deserialize_state(::File.read(file))
-      end
-
-      # Removes the saved state file for the given thread_id.
-      # @param thread_id [String]
-      # @return [self]
-      def clear(thread_id)
-        file = path(thread_id)
-        ::File.delete(file) if ::File.exist?(file)
-        self
-      end
-
-      # Removes all state files managed by this store instance.
-      # @return [self]
-      def clear_all
-        ::Dir.glob(::File.join(@dir, "*.json")).each { |f| ::File.delete(f) }
-        self
-      end
-
-      # @return [String] the directory used by this store
-      def directory
-        @dir
-      end
-
-      private
-
-      # Converts a thread_id into a safe filename component.
-      # Characters outside [A-Za-z0-9._-] are replaced with underscores.
-      def sanitize(thread_id)
-        thread_id.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
-      end
-
-      def path(thread_id)
-        ::File.join(@dir, "#{sanitize(thread_id)}.json")
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/in_memory.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module StateStore
-    # In-memory state store backed by per-thread-id {Phronomy::Actor} instances
-    # from {Phronomy::ThreadActorRegistry}. Suitable for single-process use only.
-    class InMemory < Base
-      # Thread-local key for per-thread-id state data (namespaced by store
-      # instance object_id to support multiple independent InMemory stores).
-      THREAD_DATA_KEY = :phronomy_state_store_in_memory_data
-
-      def initialize
-      end
-
-      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
-      # @return [self]
-      def save(state)
-        store_id = object_id
-        Phronomy::ThreadActorRegistry.for(state.thread_id).call do
-          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id] = state
-        end
-        self
-      end
-
-      # @param thread_id [String]
-      # @return [Object, nil] state object or nil
-      def load(thread_id)
-        store_id = object_id
-        Phronomy::ThreadActorRegistry.for(thread_id).call do
-          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id]
-        end
-      end
-
-      # @param thread_id [String]
-      # @return [self]
-      def clear(thread_id)
-        store_id = object_id
-        Phronomy::ThreadActorRegistry.for(thread_id).call do
-          (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
-        end
-        self
-      end
-
-      def clear_all
-        store_id = object_id
-        Phronomy::ThreadActorRegistry.each_actor do |actor|
-          actor.call { (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id) }
-        end
-        self
-      end
-    end
-  end
-end

data/lib/phronomy/state_store/redis.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-
-module Phronomy
-  module StateStore
-    # Redis-backed state store.
-    # Persists graph state as a JSON string under the key
-    # "phronomy:state:<thread_id>" in Redis.
-    #
-    # The Redis client must be compatible with the redis-rb gem interface:
-    #   client.set(key, value)
-    #   client.get(key)
-    #   client.del(key)
-    #
-    # @example
-    #   require "redis"
-    #   redis = Redis.new(url: ENV["REDIS_URL"])
-    #   Phronomy.configure do |c|
-    #     c.default_state_store = Phronomy::StateStore::Redis.new(client: redis)
-    #   end
-    #
-    # @example with TTL
-    #   Phronomy::StateStore::Redis.new(client: redis, ttl: 3600)
-    class Redis < Base
-      KEY_PREFIX = "phronomy:state:"
-      private_constant :KEY_PREFIX
-
-      # @param client [#set, #get, #del] Redis-compatible client
-      # @param ttl    [Integer, nil] optional key expiry in seconds
-      def initialize(client:, ttl: nil)
-        @client = client
-        @ttl = ttl
-      end
-
-      # @param state [Object] includes Phronomy::WorkflowContext
-      # @return [self]
-      def save(state)
-        serialized = serialize_state(state)
-        if @ttl
-          @client.set(key(state.thread_id), serialized, ex: @ttl)
-        else
-          @client.set(key(state.thread_id), serialized)
-        end
-        self
-      end
-
-      # @param thread_id [String]
-      # @return [Object, nil] state instance or nil
-      def load(thread_id)
-        raw = @client.get(key(thread_id))
-        return nil unless raw
-
-        deserialize_state(raw)
-      end
-
-      # @return [self]
-      def clear(thread_id)
-        @client.del(key(thread_id))
-        self
-      end
-
-      private
-
-      def key(thread_id)
-        "#{KEY_PREFIX}#{thread_id}"
-      end
-    end
-  end
-end

data/lib/phronomy/state_store.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Namespace for state persistence backends.
-  # A StateStore saves and loads graph State objects keyed by thread_id.
-  # The thread_id is embedded in the State itself (state.thread_id).
-  module StateStore
-  end
-end

data/lib/phronomy/thread_actor_registry.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Global per-thread-id {Actor} registry.
-  #
-  # Maps the +:thread_id+ key from the +config:+ argument passed to
-  # {Phronomy::Agent::Base#invoke} to a {Phronomy::Actor} instance.
-  # Each thread_id gets exactly one Actor so that all operations for the same
-  # conversation are serialised automatically.
-  #
-  # @example
-  #   Phronomy::ThreadActorRegistry.for("user-42").call do
-  #     # runs sequentially on the Actor's thread
-  #   end
-  module ThreadActorRegistry
-    @actors = {}
-    @registry_actor = Actor.new
-
-    class << self
-      # Returns (or lazily creates) the {Actor} for +thread_id+.
-      #
-      # When +Phronomy.configuration.max_actors+ is set, the registry evicts the
-      # least-recently-used Actor (by stopping it) before inserting a new one.
-      # Accessing an existing Actor moves it to the most-recently-used position.
-      #
-      # @param thread_id [String]
-      # @return [Phronomy::Actor]
-      def for(thread_id)
-        @registry_actor.call do
-          if @actors.key?(thread_id)
-            # LRU touch: move to end (most-recently used)
-            actor = @actors.delete(thread_id)
-            @actors[thread_id] = actor
-          else
-            evict_lru_if_needed!
-            @actors[thread_id] = Actor.new
-          end
-          @actors[thread_id]
-        end
-      end
-
-      # Returns the current number of registered Actors.
-      #
-      # @return [Integer]
-      def actor_count
-        @registry_actor.call { @actors.size }
-      end
-
-      # Gracefully stops the Actor for +thread_id+ and removes it from the
-      # registry.  The next call to {.for} with the same id creates a fresh Actor.
-      #
-      # @param thread_id [String]
-      def stop(thread_id)
-        @registry_actor.call { @actors.delete(thread_id) }&.stop
-      end
-
-      # Stops and removes every registered Actor.
-      # Intended for test teardown and process shutdown.
-      def clear_all
-        actors = @registry_actor.call { @actors.values.tap { @actors.clear } }
-        actors.each(&:stop)
-      end
-
-      # Yields each currently registered Actor.
-      # A snapshot is taken so the registry cannot change while callers iterate.
-      #
-      # @yield [Phronomy::Actor]
-      def each_actor(&block)
-        @registry_actor.call { @actors.values.dup }.each(&block)
-      end
-
-      private
-
-      # Evicts the least-recently-used Actor when the registry is at capacity.
-      # Must be called from within @registry_actor.call { } to be thread-safe.
-      def evict_lru_if_needed!
-        max = Phronomy.configuration.max_actors
-        return unless max && @actors.size >= max
-
-        _lru_id, lru_actor = @actors.shift
-        lru_actor.stop
-      end
-    end
-  end
-end