phronomy 0.27.0 → 0.29.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

@@ -34,15 +34,44 @@ module Phronomy
       # @return [Object] the block's return value
       # @api public
       def trace(name, input: nil, **meta)
-        span = start_span(name, input: input, **meta)
-        result, usage = yield span
-        finish_span(span, output: result, usage: usage)
+        Base.trace_with(self, name, attributes: {input: input, **meta}) { |span| yield span }
+      end
+
+      # Use the public start/finish SPI, including duck-typed tracers.
+      # Start failures do not finish; finish is attempted once after execution.
+      # A secondary finish/reporting failure cannot replace the block's error.
+      # Set record_output: false for metadata-only operations.
+      # @api public
+      def self.trace_with(tracer, name, record_output: true, attributes: {})
+        span = tracer.start_span(name, **attributes)
+        begin
+          result, usage = yield span
+        rescue => primary
+          begin
+            tracer.finish_span(span, error: primary)
+          rescue => secondary
+            report_secondary(secondary)
+          end
+          raise
+        end
+        if record_output
+          tracer.finish_span(span, output: result, usage: usage)
+        else
+          tracer.finish_span(span)
+        end
         result
-      rescue => e
-        finish_span(span, error: e)
-        raise
       end
 
+      def self.report_secondary(error)
+        Phronomy::RuntimeSettings.current.logger&.warn(
+          "[Phronomy::Tracing] secondary finish failure: #{error.class}: #{error.message}"
+        )
+      rescue
+        # Diagnostics are best effort; preserve the primary business failure.
+        nil
+      end
+      private_class_method :report_secondary
+
       # Start a new span. Must return an object that will be passed to #finish_span.
       #
       # @param name [String]
@@ -57,7 +86,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/open_telemetry_tracer.rb

@@ -53,38 +53,13 @@ module Phronomy
         span.finish
       end
 
-      # Overrides Base#trace to use OTel +in_span+, which pushes the span onto
-      # the OTel Context stack while the block runs.  Nested +trace+ calls
-      # automatically inherit the current span as their parent, establishing the
-      # correct parent/child hierarchy in the trace tree.
-      #
-      # @param name [String] span name
-      # @param input [Object, nil] input to record as a span attribute
-      # @param meta [Hash] additional metadata (e.g. task_id, user_id)
-      # @yield [span] the active OTel span
-      # @return [Object] the block's return value
+      # Preserve the backend context while sharing C15's exactly-once finish
+      # and primary-error protection. Context affinity remains backend-owned.
       # @api private
       def trace(name, input: nil, **meta)
-        attrs = {}
-        attrs["phronomy.input"] = input.to_s if input
-        meta.each { |k, v| attrs["phronomy.#{k}"] = v.to_s unless v.nil? }
-
-        result = nil
-        @otel_tracer.in_span(name, attributes: attrs) do |span|
-          result, usage = yield span
-          span.set_attribute("phronomy.output", result.to_s) if result
-          if usage
-            span.set_attribute("llm.usage.input_tokens", usage.input)
-            span.set_attribute("llm.usage.output_tokens", usage.output)
-            total = (usage.input || 0) + (usage.output || 0)
-            span.set_attribute("llm.usage.total_tokens", total)
-          end
-        rescue => e
-          span.record_exception(e)
-          span.status = OpenTelemetry::Trace::Status.error(e.message)
-          raise
+        Base.trace_with(self, name, attributes: {input: input, **meta.compact}) do |span|
+          OpenTelemetry::Trace.with_span(span) { yield span }
         end
-        result
       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