phronomy 0.27.0 → 0.28.0

data/lib/phronomy/tracing/automatic.rb

@@ -19,9 +19,9 @@ module Phronomy
 
       def start(name, input: nil, **metadata)
         trace_pii = false
-        configuration = Phronomy.configuration
-        trace_pii = !!configuration.trace_pii
-        tracer = configuration.tracer
+        settings = Settings.current
+        trace_pii = !!settings.trace_pii
+        tracer = settings.tracer
         span = tracer.start_span(
           name,
           input: traced_payload(input, trace_pii: trace_pii),
@@ -47,7 +47,7 @@ module Phronomy
           error: traced_error(error, trace_pii: handle.trace_pii)
         }.freeze
 
-        if Phronomy::Runtime.in_event_loop_context?
+        if Phronomy::WaitPolicy.blocking_forbidden?
           submit_finish(handle, attributes)
         else
           finish_now(handle, attributes)
@@ -130,8 +130,13 @@ module Phronomy
       private_class_method :task_usage
 
       def submit_finish(handle, attributes)
-        Phronomy::Runtime.instance.offload.submit(on_full: :raise) do
+        Phronomy::Blocking.call_async do
           finish_now(handle, attributes)
+        end.on_complete do |_value, error|
+          if error
+            report_failure(:finish, handle.name, error,
+              include_message: handle.trace_pii)
+          end
         end
         nil
       rescue => error
@@ -164,7 +169,7 @@ module Phronomy
         message =
           "[Phronomy] automatic tracing #{stage} failed for " \
           "#{name}: #{error.class}#{detail}"
-        logger = Phronomy.configuration.logger
+        logger = Phronomy::RuntimeSettings.current.logger
         logger ? logger.warn(message) : Kernel.warn(message)
         nil
       rescue

data/lib/phronomy/tracing/base.rb

@@ -57,7 +57,7 @@ module Phronomy
       #
       # @param span [Object] the span returned by #start_span
       # @param output [Object, nil] successful output value
-      # @param usage [Phronomy::TokenUsage, nil] token usage for this span
+      # @param usage [Phronomy::LLMAdapter::TokenUsage, nil] token usage for this span
       # @param error [Exception, nil] exception if the block raised
       # @api public
       def finish_span(span, output: nil, usage: nil, error: nil)

data/lib/phronomy/tracing/observation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tracing
+    module Observation
+      # Convenience wrapper that delegates to the global tracer.
+      # Yields a span; the block must return [result, usage] where usage is a
+      # Phronomy::LLMAdapter::TokenUsage or nil. Returns only the result value.
+      #
+      # When +trace_pii+ is disabled, both the input and the output (LLM response,
+      # tool result) are replaced with the literal string "[REDACTED]" before being
+      # forwarded to the tracing backend. The actual result is still returned to
+      # the caller — only the copy sent to the tracer is redacted.
+      #
+      # @example
+      #   trace("my_chain", input: input) { [invoke(input), nil] }
+      # @api public
+      def self.trace(name, input: nil, **meta, &block)
+        traced_input = Settings.current.trace_pii ? input : "[REDACTED]"
+
+        if Settings.current.trace_pii
+          # PII recording is allowed: pass through unchanged.
+          Settings.current.tracer.trace(name, input: traced_input, **meta, &block)
+        else
+          # Redact both input (above) and output before forwarding to the tracer.
+          # Capture the real result so callers receive the unredacted value.
+          real_result = nil
+          Settings.current.tracer.trace(name, input: traced_input, **meta) do |span|
+            real_result, usage = block.call(span)
+            ["[REDACTED]", usage]
+          end
+          real_result
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/tracing/settings.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "../common/configuration_error"
+
+module Phronomy
+  module Tracing
+    # Tracing owns recording options; application composition selects the tracer.
+    # No concrete backend, execution resource or application facade belongs here.
+    # @api private
+    class Settings
+      def self.install_provider(&provider)
+        raise ArgumentError, "Tracing settings provider requires a block" unless provider
+
+        @provider = provider
+        nil
+      end
+
+      # Follow reset and scoped restoration only when a consumer already reads.
+      def self.current
+        settings = @provider&.call
+        unless settings.is_a?(Settings)
+          raise ConfigurationError, "Tracing settings provider must return Tracing::Settings"
+        end
+
+        settings
+      end
+
+      attr_accessor :tracer, :trace_pii
+
+      def initialize(tracer:)
+        @tracer = tracer
+        @trace_pii = false
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/{async_backend.rb → async/async_client.rb}

@@ -2,21 +2,25 @@
 
 module Phronomy
   module VectorStore
-    # Framework-owned async convenience methods for VectorStore backends.
+    # Framework-owned asynchronous execution of a synchronous vector backend.
     #
-    # The backend extension contract is the synchronous interface defined by
-    # {VectorStore::Base}: add/search/remove/clear/size. These async convenience
-    # methods are inherited by backends and route that synchronous work through
-    # Phronomy's bounded {OffloadPool}. This keeps OS-thread creation, queue
-    # backpressure, submit timeout/cancellation, and completion semantics owned by
-    # the framework rather than by each backend.
+    # Backend authors implement only Base's synchronous operations. Applications
+    # use this client for asynchronous calls. Admission never waits for queue
+    # capacity; accepted calls return the pool's original TaskResult. Timeout
+    # includes queue wait and settles the result without interrupting running I/O.
+    # Construction does not start Runtime; the current default pool is resolved
+    # for each operation. An injected pool remains owned by its caller.
     #
-    # A future genuine native-async backend may adapt its completion into a
-    # {Phronomy::TaskResult} without an OffloadPool worker, but native async override is
-    # not part of the current backend SPI.
-    #
-    # @api private
-    module AsyncBackend
+    # @api public
+    class AsyncClient
+      # @param backend [VectorStore::Base] synchronous vector store
+      # @param pool [Concurrency::OffloadPool, nil] optional execution pool
+      # @api public
+      def initialize(backend:, pool: nil)
+        @backend = backend
+        @pool = pool
+      end
+
       # Async variant of {VectorStore::Base#add}.
       #
       # @param id                 [String]
@@ -27,12 +31,11 @@ module Phronomy
       # @return [Phronomy::TaskResult]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.offload.submit(
+        Phronomy::Execution.submit(pool: default_pool,
           timeout: timeout,
           cancellation_token: cancellation_token,
-          on_full: :raise
-        ) do
-          add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
+          on_full: :raise) do
+          @backend.add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
         end
       end
 
@@ -45,12 +48,11 @@ module Phronomy
       # @return [Phronomy::TaskResult]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.offload.submit(
+        Phronomy::Execution.submit(pool: default_pool,
           timeout: timeout,
           cancellation_token: cancellation_token,
-          on_full: :raise
-        ) do
-          search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
+          on_full: :raise) do
+          @backend.search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
         end
       end
 
@@ -62,12 +64,11 @@ module Phronomy
       # @return [Phronomy::TaskResult]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.offload.submit(
+        Phronomy::Execution.submit(pool: default_pool,
           timeout: timeout,
           cancellation_token: cancellation_token,
-          on_full: :raise
-        ) do
-          remove(id: id)
+          on_full: :raise) do
+          @backend.remove(id: id)
         end
       end
 
@@ -78,14 +79,19 @@ module Phronomy
       # @return [Phronomy::TaskResult]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.offload.submit(
+        Phronomy::Execution.submit(pool: default_pool,
           timeout: timeout,
           cancellation_token: cancellation_token,
-          on_full: :raise
-        ) do
-          clear
+          on_full: :raise) do
+          @backend.clear
         end
       end
+
+      private
+
+      def default_pool
+        @pool
+      end
     end
   end
 end

data/lib/phronomy/vector_store/{in_memory.rb → backends/in_memory.rb}

@@ -22,16 +22,16 @@ module Phronomy
         @expected_dimension = dimension
       end
 
+      protected
+
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
+      def perform_add(id:, embedding:, metadata: {}, cancellation_token: nil)
         # Establish expected dimension on first add, then validate.
         @expected_dimension ||= embedding.size
-        validate_embedding_dimension!(embedding, @expected_dimension)
         @documents[id] = {embedding: embedding, metadata: metadata}
         self
       end
@@ -46,11 +46,8 @@ module Phronomy
       #   (key always present); -r.fetch(:score) vs -r[:score] (key always present); snapshot = @documents
       #   vs .dup is equivalent in single-threaded tests (GVL makes Hash#dup atomic, no behaviour
       #   difference under test isolation)
-      def search(query_embedding:, k: 5, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        k = validate_k!(k)
+      def perform_search(query_embedding:, k: 5, cancellation_token: nil)
         # search never establishes dimension; validate only when dimension is known.
-        validate_embedding_dimension!(query_embedding, @expected_dimension)
         # Take an atomic snapshot before iterating.  Hash#dup is a C-level
         # call that completes without releasing the GVL, so it is atomic with
         # respect to any other Ruby thread.  Iterating the copy instead of
@@ -64,22 +61,27 @@ module Phronomy
         results.sort_by { |r| -r[:score] }.first(k)
       end
 
-      def remove(id:)
+      def perform_remove(id:)
         @documents.delete(id)
         self
       end
 
-      def clear
+      def perform_clear
         @documents.clear
         self
       end
 
       # @return [Integer] number of documents stored
       # @api public
-      def size
+      def perform_size
         @documents.size
       end
 
+      # @api public
+      def embedding_dimension
+        @expected_dimension
+      end
+
       private
 
       # mutant:disable - empty-vector early-return condition variants (if false, if nil, if a.empty?,

data/lib/phronomy/vector_store/{pgvector.rb → backends/pgvector.rb}

@@ -35,14 +35,14 @@ module Phronomy
         @dimension = dimension
       end
 
+      protected
+
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        validate_embedding_dimension!(embedding, @dimension)
+      def perform_add(id:, embedding:, metadata: {}, cancellation_token: nil)
         @model_class.upsert(
           {id: id, embedding: safe_vector(embedding), metadata: metadata.to_json},
           unique_by: :id
@@ -55,10 +55,7 @@ module Phronomy
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
       # @api public
-      def search(query_embedding:, k: 5, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
-        k_safe = validate_k!(k)
-        validate_embedding_dimension!(query_embedding, @dimension)
+      def perform_search(query_embedding:, k: 5, cancellation_token: nil)
         vec = safe_vector_literal(query_embedding)
         conn = @model_class.connection
         quoted_vec = "#{conn.quote(vec)}::vector"
@@ -66,48 +63,79 @@ module Phronomy
         @model_class
           .select("id, metadata, 1 - (embedding <=> #{quoted_vec}) AS score")
           .order("embedding <=> #{quoted_vec}")
-          .limit(k_safe)
+          .limit(k)
           .map do |r|
             {
-              id: r.id.to_s,
-              score: r.score.to_f,
+              id: parse_id(r.id),
+              score: parse_score(r.score),
               metadata: parse_metadata(r.metadata)
             }
           end
       end
 
-      def remove(id:)
+      def perform_remove(id:)
         @model_class.where(id: id).delete_all
         self
       end
 
-      def clear
+      def perform_clear
         @model_class.delete_all
         self
       end
 
       # Returns the number of documents in the backing table.
-      def size
+      def perform_size
         @model_class.count
       end
 
+      # @api public
+      def embedding_dimension
+        @dimension
+      end
+
       private
 
+      def parse_id(raw)
+        unless raw.is_a?(String) || raw.is_a?(Integer)
+          raise InvalidResultError, "Pgvector returned an invalid document id"
+        end
+        raw.to_s
+      end
+
+      def parse_score(raw)
+        valid = (raw.is_a?(String) && raw.match?(/\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/)) ||
+          (raw.is_a?(Numeric) && raw.real?)
+        value = Float(raw, exception: false) if valid
+        unless value&.finite?
+          raise InvalidResultError, "Pgvector requires a finite numeric score"
+        end
+        value
+      end
+
       # Parses a metadata value returned by the pg driver.
       # Handles NULL (nil), already-parsed Hash, and JSON string forms.
       def parse_metadata(raw)
         return {} if raw.nil?
         return symbolize_hash_keys(raw) if raw.is_a?(Hash)
 
-        parsed = JSON.parse(raw.to_s, symbolize_names: true)
-        parsed.is_a?(Hash) ? parsed : {}
+        unless raw.is_a?(String)
+          raise InvalidResultError, "Pgvector metadata must contain a JSON object"
+        end
+        parsed = JSON.parse(raw, symbolize_names: true)
+        unless parsed.is_a?(Hash)
+          raise InvalidResultError, "Pgvector metadata must contain a JSON object"
+        end
+        parsed
       rescue JSON::ParserError
-        {}
+        raise InvalidResultError, "Pgvector metadata contains invalid JSON"
       end
 
       # Recursively symbolizes keys for an already-parsed Hash.
       def symbolize_hash_keys(hash)
         hash.each_with_object({}) do |(k, v), h|
+          unless k.is_a?(String) || k.is_a?(Symbol)
+            raise InvalidResultError, "Pgvector metadata contains an invalid object key"
+          end
           h[k.to_sym] = v.is_a?(Hash) ? symbolize_hash_keys(v) : v
         end
       end

data/lib/phronomy/vector_store/{redis_search.rb → backends/redis_search.rb}

@@ -8,7 +8,7 @@ module Phronomy
     #
     # Requires:
     #   - The +redis+ gem (add to your Gemfile)
-    #   - A Redis server with the RediSearch (RedisSearch) module enabled
+    #   - A RESP2 Redis client and a server with the RediSearch module enabled
     #     (or Redis Stack which bundles RediSearch)
     #
     # Vectors are stored as FLOAT32 binary blobs in Redis Hash fields and
@@ -46,17 +46,17 @@ module Phronomy
         @mutex = Mutex.new
       end
 
+      protected
+
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
-      def add(id:, embedding:, metadata: {}, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
+      def perform_add(id:, embedding:, metadata: {}, cancellation_token: nil)
         # Establish expected dimension on first add (not race-free for concurrent
-        # first adds), then validate, then create/reuse the index.
+        # first adds), then create/reuse the index. Base has validated the input.
         @dimension ||= embedding.size
-        validate_embedding_dimension!(embedding, @dimension)
         ensure_index!(@dimension)
         @redis.call(
           "HSET", "#{DOC_PREFIX}#{id}",
@@ -71,20 +71,17 @@ module Phronomy
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] sorted by descending similarity score
       # @api public
-      def search(query_embedding:, k: 5, cancellation_token: nil)
-        cancellation_token&.raise_if_cancelled!
+      def perform_search(query_embedding:, k: 5, cancellation_token: nil)
         # search never establishes dimension.  If dimension is unknown and the
         # index has not been created yet, there are no documents to return.
         return [] if @dimension.nil? && !@index_created
 
-        validate_embedding_dimension!(query_embedding, @dimension)
         ensure_index!(@dimension)
-        k_safe = validate_k!(k)
         blob = pack_vector(query_embedding)
 
         raw = @redis.call(
           "FT.SEARCH", @index_name,
-          "*=>[KNN #{k_safe} @embedding $BLOB AS score]",
+          "*=>[KNN #{k} @embedding $BLOB AS score]",
           "PARAMS", 2, "BLOB", blob,
           "SORTBY", "score",
           "RETURN", 2, "score", "metadata",
@@ -94,26 +91,26 @@ module Phronomy
         parse_results(raw)
       end
 
-      def remove(id:)
+      def perform_remove(id:)
         @redis.call("DEL", "#{DOC_PREFIX}#{id}")
         self
       end
 
       # Returns the number of documents indexed.
       # Queries FT.INFO when the index has been created; returns 0 otherwise.
-      def size
+      def perform_size
         return 0 unless @index_created
 
-        raw = @redis.call("FT.INFO", @index_name)
-        return 0 unless raw.is_a?(Array)
-
-        idx = raw.index("num_docs")
-        idx ? raw[idx + 1].to_i : 0
-      rescue
-        0
+        fields = parse_fields(@redis.call("FT.INFO", @index_name), "FT.INFO")
+        count = fields["num_docs"]
+        count = Integer(count, 10) if count.is_a?(String) && count.match?(/\A\d+\z/)
+        unless count.is_a?(Integer) && count >= 0
+          raise InvalidResultError, "Redis FT.INFO requires a non-negative integer num_docs"
+        end
+        count
       end
 
-      def clear
+      def perform_clear
         @mutex.synchronize do
           begin
             @redis.call("FT.DROPINDEX", @index_name, "DD")
@@ -125,6 +122,11 @@ module Phronomy
         self
       end
 
+      # @api public
+      def embedding_dimension
+        @dimension
+      end
+
       private
 
       def ensure_index!(dim)
@@ -160,33 +162,68 @@ module Phronomy
       #
       # Redis FT.SEARCH returns: [count, key1, [field, value, ...], key2, ...]
       def parse_results(raw)
-        return [] if raw.nil? || !raw.is_a?(Array) || raw.size < 2
+        unless raw.is_a?(Array) && raw.size.odd? && raw.first.is_a?(Integer) &&
+            raw.first >= (raw.size - 1) / 2 && raw.first.zero? == (raw.size == 1)
+          raise InvalidResultError, "Redis FT.SEARCH requires a count and document/field pairs"
+        end
 
         results = []
-        i = 1
-        while i < raw.size
-          key = raw[i]
-          fields = raw[i + 1]
-          i += 2
-
-          next unless fields.is_a?(Array)
-
-          field_hash = fields.each_slice(2).to_h
-          score_str = field_hash["score"]
-          metadata_str = field_hash["metadata"]
-
-          next if score_str.nil?
+        raw.drop(1).each_slice(2) do |key, fields|
+          unless key.is_a?(String) && key.start_with?(DOC_PREFIX)
+            raise InvalidResultError, "Redis FT.SEARCH returned an invalid document key"
+          end
+          # Redis documents this null content when a key expires/is updated
+          # during the search. The key remains in the total count.
+          next if fields.nil?
 
-          id = key.to_s.delete_prefix(DOC_PREFIX)
+          field_hash = parse_fields(fields, "FT.SEARCH")
+          id = key.delete_prefix(DOC_PREFIX)
           # RediSearch returns cosine distance (0=identical, 2=opposite);
           # convert to cosine similarity for consistency with other backends.
-          score = 1.0 - score_str.to_f
-          metadata = metadata_str ? JSON.parse(metadata_str, symbolize_names: true) : {}
+          score = 1.0 - parse_distance(field_hash["score"])
+          metadata = parse_metadata(field_hash["metadata"])
 
           results << {id: id, score: score, metadata: metadata}
         end
         results
       end
+
+      # RESP2 field/value decoding belongs to this backend, not the Contract.
+      def parse_fields(raw, command)
+        unless raw.is_a?(Array) && raw.size.even?
+          raise InvalidResultError, "Redis #{command} requires field/value pairs"
+        end
+        raw.each_slice(2).each_with_object({}) do |(key, value), fields|
+          unless key.is_a?(String) && !fields.key?(key)
+            raise InvalidResultError, "Redis #{command} returned an invalid or duplicate field"
+          end
+          fields[key] = value
+        end
+      end
+
+      def parse_distance(raw)
+        valid = (raw.is_a?(String) && raw.match?(/\A[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?\z/)) ||
+          (raw.is_a?(Numeric) && raw.real?)
+        value = Float(raw, exception: false) if valid
+        unless value&.finite?
+          raise InvalidResultError, "Redis FT.SEARCH requires a finite numeric score"
+        end
+        value
+      end
+
+      def parse_metadata(raw)
+        return {} if raw.nil?
+        unless raw.is_a?(String)
+          raise InvalidResultError, "Redis metadata must contain a JSON object"
+        end
+        parsed = JSON.parse(raw, symbolize_names: true)
+        unless parsed.is_a?(Hash)
+          raise InvalidResultError, "Redis metadata must contain a JSON object"
+        end
+        parsed
+      rescue JSON::ParserError
+        raise InvalidResultError, "Redis metadata contains invalid JSON"
+      end
     end
   end
 end