phronomy 0.20.0 → 0.22.0

data/lib/phronomy/engine/task.rb

@@ -3,20 +3,29 @@
 module Phronomy
   # A thread-free asynchronous completion handle.
   #
-  # Task no longer executes work. Execution belongs to EventLoop/FSMSession or
-  # OffloadPool. Task only represents completion, failure, cancellation,
-  # callbacks and a blocking wait for external callers.
+  # Task does not execute work. Execution belongs to EventLoop/FSMSession or
+  # OffloadPool. Task represents completion, failure, cancellation, callbacks,
+  # and a blocking wait for callers outside EventLoop.
+  #
+  # Framework components own Task settlement. Application code should observe a
+  # Task through {#wait_result}, {#on_complete}, {#map}, and state readers rather
+  # than calling {#complete}, {#fail}, or {#cancel!}. Operation-wide cancellation
+  # is supplied through the CancellationToken accepted by the API that created
+  # the Task.
   class Task
     STATES = %i[pending completed failed cancelled].freeze
     TERMINAL_STATES = %i[completed failed cancelled].freeze
     private_constant :TERMINAL_STATES
 
+    # Creates an unsettled completion handle for framework-owned execution.
+    # @api private
     def self.deferred(name: nil, parent: nil)
       new(name: name, parent: parent)
     end
 
     attr_reader :name, :parent
 
+    # @api private
     def initialize(name: nil, parent: nil)
       @name = name
       @parent = parent
@@ -30,20 +39,35 @@ module Phronomy
       parent&.register_child(self)
     end
 
+    # @return [Symbol] :pending, :completed, :failed, or :cancelled
+    # @api public
     def status
       @mutex.synchronize { @status }
     end
 
+    # @return [Boolean] whether the Task has reached a terminal state
+    # @api public
     def done?
       @mutex.synchronize { TERMINAL_STATES.include?(@status) }
     end
 
+    # @return [Boolean] whether the Task has not yet reached a terminal state
+    # @api public
     def alive?
       !done?
     end
 
-    # Blocks the calling thread until settlement. EventLoop is never allowed to
-    # wait for a Task; it must continue through explicit events instead.
+    # Blocks the calling thread until settlement.
+    #
+    # EventLoop is never allowed to wait for a Task; framework continuation must
+    # proceed through explicit events. The optional timeout is waiter-local: it
+    # does not settle or cancel the Task.
+    #
+    # @param timeout [Numeric, nil] maximum seconds this caller will block
+    # @return [Object] the completed value
+    # @raise [Phronomy::TimeoutError] when the waiter-local timeout expires
+    # @raise [Exception] the error that settled the Task
+    # @api public
     def wait_result(timeout: nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
@@ -71,8 +95,9 @@ module Phronomy
       value
     end
 
-    # Compatibility wait that does not re-raise the task error.
+    # Compatibility wait that does not re-raise the Task error.
     # Returns self when settled, nil on timeout.
+    # @api private
     def join(limit = nil)
       if Phronomy::Runtime.in_event_loop_context? && !done?
         raise Phronomy::EventLoopReentrancyError,
@@ -96,8 +121,15 @@ module Phronomy
 
     # Registers an independent completion notification.
     #
+    # The callback execution thread is not guaranteed. It may be the caller that
+    # registers after settlement, an OffloadPool worker, or a framework control
+    # thread. Callbacks must therefore be thread-safe and should complete quickly.
     # A callback failure is logged and does not suppress delivery to other
     # completion callbacks or change the Task's already-settled result.
+    #
+    # @yield [value, error]
+    # @return [self]
+    # @api public
     def on_complete(&callback)
       raise ArgumentError, "on_complete requires a block" unless callback
 
@@ -113,15 +145,25 @@ module Phronomy
       self
     end
 
+    # Settles this Task successfully. Framework-owned settlement API.
+    # @api private
     def complete(value = nil)
       settle!(:completed, value: value)
     end
 
+    # Settles this Task with a failure. Framework-owned settlement API.
+    # @api private
     def fail(error)
       raise ArgumentError, "error is required" unless error
       settle!(:failed, error: error)
     end
 
+    # Settles this Task as cancelled. Framework-owned settlement API.
+    #
+    # This method does not propagate backwards into a CancellationToken that may
+    # have been used to create the Task. Tokens can be shared across operations;
+    # operation-wide cancellation is owned by the creating API.
+    # @api private
     def cancel!(error = Phronomy::CancellationError.new("Task cancelled"))
       changed = settle!(:cancelled, error: error)
       if changed
@@ -131,6 +173,8 @@ module Phronomy
       self
     end
 
+    # Creates a derived Task by transforming this Task's successful result.
+    # @api public
     def map(&block)
       raise ArgumentError, "map requires a block" unless block
 

data/lib/phronomy/invocation_context.rb

@@ -3,10 +3,9 @@
 module Phronomy
   # Carries all per-invocation context values through the call stack.
   #
-  # +InvocationContext+ is a plain value object (struct-like, frozen on
-  # creation) that replaces ad-hoc +Thread.current[...]+ propagation.
-  # Pass it explicitly wherever context needs to cross a method boundary
-  # or be handed to a child {Task} / {TaskGroup}.
+  # +InvocationContext+ is a plain struct-like value carrier that replaces
+  # ad-hoc +Thread.current[...]+ propagation.
+  # Pass it explicitly wherever context needs to cross a method boundary.
   #
   # @example Build a context for a new agent invocation
   #   ctx = Phronomy::InvocationContext.new(
@@ -14,40 +13,12 @@ module Phronomy
   #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30)
   #   )
   #   agent.invoke("Hello", invocation_context: ctx)
+  #
+  # @api public
   class InvocationContext
-    # @return [String, nil] conversation / workflow thread identifier
-    attr_reader :thread_id
-
-    # @return [String, nil] session identifier (e.g. Rails session id)
-    attr_reader :session_id
-
-    # @return [String, nil] end-user identifier for tracing / audit
-    attr_reader :user_id
-
-    # @return [CancellationToken, nil]
-    attr_reader :cancellation_token
-
-    # @return [Deadline, nil]
-    attr_reader :deadline
-
-    # @return [Object, nil] OpenTelemetry / tracing span
-    attr_reader :tracer_span
-
-    # @return [Integer, nil] max tokens the agent may consume this invocation
-    attr_reader :token_budget
-
-    # @return [#call, nil] invocation-specific Tool approval policy. The callable
-    #   receives Phronomy::Agent::ApprovalEvaluationRequest.
-    attr_reader :approval_policy
-
-    # @return [Object, nil] redaction policy applied to tool args / results
-    attr_reader :redaction_policy
-
-    # @return [String, nil] unique identifier for this task in the trace tree
-    attr_reader :task_id
-
-    # @return [String, nil] task_id of the parent span / task
-    attr_reader :parent_task_id
+    attr_reader :thread_id, :session_id, :user_id, :cancellation_token,
+      :deadline, :tracer_span, :token_budget, :approval_policy,
+      :redaction_policy, :task_id, :parent_task_id
 
     # @param thread_id [String, nil]
     # @param session_id [String, nil]
@@ -56,11 +27,11 @@ module Phronomy
     # @param deadline [Deadline, nil]
     # @param tracer_span [Object, nil]
     # @param token_budget [Integer, nil]
-    # @param approval_policy [#call, nil] invocation-specific Tool approval policy
+    # @param approval_policy [#call, nil]
     # @param redaction_policy [Object, nil]
     # @param task_id [String, nil]
     # @param parent_task_id [String, nil]
-    # @api private
+    # @api public
     def initialize(
       thread_id: nil,
       session_id: nil,
@@ -88,10 +59,6 @@ module Phronomy
     end
 
     # Returns a new +InvocationContext+ with the given attributes merged in.
-    # All other attributes are carried over unchanged.
-    #
-    # @param overrides [Hash] keyword arguments to override
-    # @return [InvocationContext]
     # @api private
     def merge(**overrides)
       InvocationContext.new(
@@ -110,21 +77,13 @@ module Phronomy
     end
 
     # Convenience: returns the cancellation token or a new never-cancelled token.
-    # @return [CancellationToken]
     # @api private
     def effective_cancellation_token
       @cancellation_token || Phronomy::Concurrency::CancellationToken.new
     end
 
     # Returns the cancellation token to use for an invocation, taking both the
-    # explicit +cancellation_token+ and the +deadline+ into account.
-    #
-    # - When +cancellation_token+ is set, it is returned unchanged.
-    # - When only +deadline+ is set, a new {CancellationToken} is created and
-    #   the deadline is attached to it via {Deadline#attach_to}.
-    # - When neither is set, returns +nil+.
-    #
-    # @return [CancellationToken, nil]
+    # explicit cancellation_token and deadline into account.
     # @api private
     def effective_timeout_token
       return @cancellation_token if @cancellation_token

data/lib/phronomy/llm_adapter/base.rb

@@ -2,56 +2,57 @@
 
 module Phronomy
   module LLMAdapter
-    # Abstract base class for LLM adapters.
+    # Beta extension SPI for LLM call adapters.
     #
-    # Subclasses must implement {#complete} and {#stream}. The adapter or the
+    # External adapters implement {#complete} and {#stream}. The adapter or the
     # underlying provider client owns transport timeout, retry, backoff, and
-    # rate-limit behavior. Phronomy supplies cooperative cancellation and
-    # isolates synchronous provider calls in {OffloadPool}.
+    # rate-limit behavior. Phronomy owns cooperative cancellation and isolates
+    # synchronous provider calls in {OffloadPool}.
     #
-    # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
-    # those methods in an {OffloadPool} submission.
+    # The Agent pipeline calls the framework-owned {#complete_async} and
+    # {#stream_async} wrappers. Adapter implementers do not need to depend on
+    # EventLoop, FSMSession, OffloadPool, AgentInvocation, or ExecutionCoordinator.
+    #
+    # The current input to this SPI is the configured/materialized chat runtime
+    # object. Formalizing this SPI therefore does not imply a provider-neutral
+    # replacement for RubyLLMMaterializer.
+    #
+    # @api public
     class Base
       # Performs a blocking (non-streaming) LLM completion.
-      # Implementors must call +chat.ask(message)+ (or equivalent) and
-      # return the response object.
       #
-      # @param chat    [Object] the configured chat session object
-      # @param message [String] the user message
+      # Implementors call the configured chat/runtime client and return its
+      # response object. Transport/retry policy remains adapter-owned.
+      #
+      # @param chat    [Object] the configured/materialized chat runtime object
+      # @param message [String, nil] user message, or nil to continue without adding a new user turn
       # @param config  [Hash] invocation config (e.g. +:cancellation_token+)
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
-      # @api private
+      # @api public
       def complete(chat, message, config: {})
         raise NotImplementedError, "#{self.class}#complete is not implemented"
       end
 
       # Performs a blocking streaming LLM completion.
-      # Implementors must call +chat.ask(message) { |chunk| block.call(chunk) }+
-      # (or equivalent) and return the response object.
       #
-      # @param chat    [Object] the configured chat session object
-      # @param message [String] the user message
+      # @param chat    [Object] the configured/materialized chat runtime object
+      # @param message [String, nil] user message, or nil to continue without adding a new user turn
       # @param config  [Hash] invocation config
       # @yield [chunk] streaming chunk from the LLM
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
-      # @api private
+      # @api public
       def stream(chat, message, config: {}, &block)
         raise NotImplementedError, "#{self.class}#stream is not implemented"
       end
 
-      # Submits a non-streaming LLM call to {OffloadPool} and returns
-      # an {OffloadPool::PendingOperation}.
+      # Submits a non-streaming LLM call to {OffloadPool}.
       #
       # Transport timeout and retry remain the responsibility of the adapter or
       # provider client; Phronomy does not attach an additional operation timeout.
       #
-      # @param chat    [Object] configured chat session
-      # @param message [String] user message
-      # @param config  [Hash] invocation config
-      # @param pool    [OffloadPool] pool to submit to
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task] caller-facing completion handle
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
@@ -60,18 +61,14 @@ module Phronomy
         end
       end
 
-      # Submits a streaming LLM call to {OffloadPool} and returns
-      # an {OffloadPool::PendingOperation}.
-      #
-      # The block is invoked on an OffloadPool worker thread. Agent code must
-      # pass only a lightweight internal sink that posts a value to EventLoop;
-      # Application callbacks must never be passed directly to this method.
+      # Submits a streaming LLM call to {OffloadPool}.
       #
-      # Transport timeout and retry remain the responsibility of the adapter or
-      # provider client; Phronomy does not attach an additional operation timeout.
+      # The block is invoked on an OffloadPool worker thread. Agent code must pass
+      # only a lightweight internal sink that posts a value to EventLoop;
+      # application callbacks must never be passed directly to this method.
       #
       # @yield [chunk] streaming chunk on the worker thread
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task] caller-facing completion handle
       # @api private
       def stream_async(chat, message, config: {}, pool: default_pool, &block)
         raise ArgumentError, "stream_async requires a block" unless block

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -2,42 +2,43 @@
 
 module Phronomy
   module LLMAdapter
-    # LLM adapter that delegates to the RubyLLM blocking client.
+    # Default LLMAdapter SPI implementation backed by RubyLLM.
     #
-    # This is the default adapter used by Phronomy agents. It wraps
-    # +chat.ask+ (and its streaming variant) so that the synchronous provider
-    # call runs inside {OffloadPool} rather than on the EventLoop thread.
+    # The synchronous +chat.ask+ / +chat.complete+ calls are invoked through the
+    # framework-owned async bridge in {LLMAdapter::Base}, so adapter consumers do
+    # not need to manage OffloadPool themselves.
     #
     # @example Explicitly configuring this adapter
     #   Phronomy.configure do |c|
     #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
     #   end
+    #
+    # @api public
     class RubyLLM < Base
       # Delegates to +chat.ask(message)+ or +chat.complete+ when message is nil.
       #
       # Passing +nil+ for +message+ is used by the ReAct loop for continuation
       # turns where the user message has already been added to the chat history
-      # (e.g. after a tool result) and the LLM should continue without a new
-      # user turn.
+      # (for example after a Tool result).
       #
       # @param chat    [Object]      RubyLLM chat session
       # @param message [String, nil] user message, or nil to continue the chat
-      # @param config  [Hash]        invocation config (not used directly by this impl)
+      # @param config  [Hash]        invocation config (not used directly here)
       # @return [Object] RubyLLM response
-      # @api private
+      # @api public
       def complete(chat, message, config: {})
         message ? chat.ask(message) : chat.complete
       end
 
-      # Delegates to +chat.ask(message) { |chunk| block.call(chunk) }+ or
-      # +chat.complete(&block)+ when message is nil.
+      # Delegates to +chat.ask(message) { |chunk| ... }+ or +chat.complete(&block)+
+      # when message is nil.
       #
       # @param chat    [Object]      RubyLLM chat session
       # @param message [String, nil] user message, or nil to continue the chat
       # @param config  [Hash]        invocation config
-      # @yield [chunk] streaming chunk forwarded from +chat.ask+ / +chat.complete+
+      # @yield [chunk] streaming chunk forwarded from RubyLLM
       # @return [Object] RubyLLM response
-      # @api private
+      # @api public
       def stream(chat, message, config: {}, &block)
         message ? chat.ask(message, &block) : chat.complete(&block)
       end

data/lib/phronomy/llm_adapter.rb

@@ -1,20 +1,23 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Namespace for LLM adapter implementations.
+  # Namespace for LLM call adapters.
   #
-  # An LLMAdapter decouples Phronomy's agent pipeline from direct
-  # dependency on the RubyLLM blocking client. All LLM calls in
-  # {Agent::Base} are routed through the adapter so that:
+  # The public extension boundary is {LLMAdapter::Base#complete} and
+  # {LLMAdapter::Base#stream}. Those methods receive Phronomy's currently
+  # materialized chat/runtime object and perform the provider call. Phronomy owns
+  # the async/offload bridge around that synchronous contract.
   #
-  # - Synchronous provider work can be submitted to {OffloadPool} for bounded
-  #   off-EventLoop execution.
-  # - Alternative LLM clients can be swapped in without changing agent code.
+  # This SPI does not by itself make the complete input-materialization pipeline
+  # provider-neutral: the current Agent pipeline still materializes the canonical
+  # LLM input through RubyLLM-specific runtime objects before invoking the adapter.
   #
   # @example Configuring a custom adapter
   #   Phronomy.configure do |c|
   #     c.llm_adapter = MyCustomAdapter.new
   #   end
+  #
+  # @api public
   module LLMAdapter
   end
 end

data/lib/phronomy/output_parser/base.rb

@@ -14,7 +14,11 @@ module Phronomy
         parse(input.is_a?(String) ? input : input.to_s)
       end
 
-      # Implement in subclasses.
+      # Extension point implemented by custom parsers.
+      #
+      # @param text [String]
+      # @return [Object]
+      # @api public
       def parse(text)
         raise NotImplementedError, "#{self.class}#parse is not implemented"
       end

data/lib/phronomy/tool/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Public authoring façade for Phronomy Tools.
+    #
+    # This constant intentionally refers to the exact same Class object as
+    # {Phronomy::Agent::Context::Capability::Base}. The implementation namespace
+    # remains canonical internally so the existing Tool DSL state, inheritance,
+    # built-in Tools, and compatibility surface are not duplicated.
+    #
+    # @api public
+    Base = Phronomy::Agent::Context::Capability::Base
+  end
+end

data/lib/phronomy/tool.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Public authoring namespace for application-defined Tools.
+  #
+  # Concrete Tools supplied by Phronomy remain under {Phronomy::Tools}.
+  #
+  # @api public
+  module Tool
+  end
+end

data/lib/phronomy/vector_store/async_backend.rb

@@ -2,43 +2,29 @@
 
 module Phronomy
   module VectorStore
-    # Mixin that defines the async interface for VectorStore backends.
+    # Framework-owned async convenience methods for VectorStore backends.
     #
-    # Mixing this module into a VectorStore class provides three choices:
+    # 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.
     #
-    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
-    #    that route through {OffloadPool}.
+    # A future genuine native-async backend may adapt its completion into a
+    # {Phronomy::Task} without an OffloadPool worker, but native async override is
+    # not part of the current backend SPI.
     #
-    # 2. **Override selectively** — override only the async methods where the
-    #    backend has a native async driver, while the remaining methods fall back
-    #    to the pool.
-    #
-    # 3. **Implement all natively** — override all async methods to avoid pool
-    #    allocation entirely.
-    #
-    # @example Native async search (no pool worker thread allocated)
-    #   class MyFastStore < Phronomy::VectorStore::Base
-    #     include Phronomy::VectorStore::AsyncBackend
-    #
-    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-    #       # Returns a PendingOperation backed by a native async driver.
-    #       native_async_search(query_embedding, k)
-    #     end
-    #   end
-    #
-    # @api public
+    # @api private
     module AsyncBackend
       # Async variant of {VectorStore::Base#add}.
       #
-      # Submits the add call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param id                 [String]
       # @param embedding          [Array<Float>]
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -52,14 +38,11 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#search}.
       #
-      # Submits the search call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -73,13 +56,10 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#remove}.
       #
-      # Submits the remove call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param id                 [String]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -93,12 +73,9 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#clear}.
       #
-      # Submits the clear call to {OffloadPool} by default.
-      # Override to use a native async driver.
-      #
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [OffloadPool::PendingOperation]
+      # @return [Phronomy::Task]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/vector_store/base.rb

@@ -2,24 +2,22 @@
 
 module Phronomy
   module VectorStore
-    # Abstract interface for vector stores.
+    # Public extension SPI for vector stores.
     #
-    # Implementations manage a collection of (embedding, metadata) pairs and
-    # support similarity search.
+    # Backends implement the synchronous add/search/remove/clear/size contract.
+    # Phronomy supplies async convenience methods through {AsyncBackend}; blocking
+    # backend work is offloaded through the framework-owned bounded OffloadPool.
     #
-    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
-    # are provided by the {AsyncBackend} mixin which defaults to routing calls
-    # through {OffloadPool}. Backends with native async drivers may override
-    # individual async methods without touching the pool at all.
+    # @api public
     class Base
       include AsyncBackend
 
       # Add a document with its vector embedding.
       #
-      # @param id                 [String]                         unique document identifier
-      # @param embedding          [Array<Float>]                   vector embedding
-      # @param metadata           [Hash]                           arbitrary metadata (e.g. the original message object)
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param id                 [String] unique document identifier
+      # @param embedding          [Array<Float>] vector embedding
+      # @param metadata           [Hash] arbitrary metadata
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @api public
       def add(id:, embedding:, metadata: {}, cancellation_token: nil)
         cancellation_token&.raise_if_cancelled!
@@ -29,8 +27,8 @@ module Phronomy
       # Return the k most similar documents to the query embedding.
       #
       # @param query_embedding    [Array<Float>]
-      # @param k                  [Integer]                        number of results
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+      # @param k                  [Integer] number of results
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @return [Array<Hash>] each element: { id:, score:, metadata: }
       # @api public
       def search(query_embedding:, k: 5, cancellation_token: nil)
@@ -47,6 +45,7 @@ module Phronomy
       end
 
       # Remove all documents.
+      # @api public
       def clear
         raise NotImplementedError, "#{self.class}#clear is not implemented"
       end