phronomy 0.6.0 → 0.7.1

data/lib/phronomy/invocation_context.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+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}.
+  #
+  # @example Build a context for a new agent invocation
+  #   ctx = Phronomy::InvocationContext.new(
+  #     thread_id:         "conv-123",
+  #     cancellation_token: Phronomy::CancellationToken.timeout_after(30),
+  #     max_parallel_tools: 5
+  #   )
+  #   agent.invoke("Hello", invocation_context: ctx)
+  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 [Integer] maximum simultaneous tool calls (default: 10)
+    attr_reader :max_parallel_tools
+
+    # @return [Object, nil] approval policy applied before write-scope tools
+    attr_reader :approval_policy
+
+    # @return [Object, nil] redaction policy applied to tool args / results
+    attr_reader :redaction_policy
+
+    # @return [Hash, nil] per-provider concurrency / rate-limit overrides
+    attr_reader :provider_limits
+
+    # @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
+
+    # @param thread_id [String, nil]
+    # @param session_id [String, nil]
+    # @param user_id [String, nil]
+    # @param cancellation_token [CancellationToken, nil]
+    # @param deadline [Deadline, nil]
+    # @param tracer_span [Object, nil]
+    # @param token_budget [Integer, nil]
+    # @param max_parallel_tools [Integer]
+    # @param approval_policy [Object, nil]
+    # @param redaction_policy [Object, nil]
+    # @param provider_limits [Hash, nil]
+    # @param task_id [String, nil]
+    # @param parent_task_id [String, nil]
+    # @api private
+    def initialize(
+      thread_id: nil,
+      session_id: nil,
+      user_id: nil,
+      cancellation_token: nil,
+      deadline: nil,
+      tracer_span: nil,
+      token_budget: nil,
+      max_parallel_tools: 10,
+      approval_policy: nil,
+      redaction_policy: nil,
+      provider_limits: nil,
+      task_id: nil,
+      parent_task_id: nil
+    )
+      @thread_id = thread_id
+      @session_id = session_id
+      @user_id = user_id
+      @cancellation_token = cancellation_token
+      @deadline = deadline
+      @tracer_span = tracer_span
+      @token_budget = token_budget
+      @max_parallel_tools = max_parallel_tools
+      @approval_policy = approval_policy
+      @redaction_policy = redaction_policy
+      @provider_limits = provider_limits
+      @task_id = task_id
+      @parent_task_id = parent_task_id
+    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(
+        thread_id: overrides.fetch(:thread_id, @thread_id),
+        session_id: overrides.fetch(:session_id, @session_id),
+        user_id: overrides.fetch(:user_id, @user_id),
+        cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
+        deadline: overrides.fetch(:deadline, @deadline),
+        tracer_span: overrides.fetch(:tracer_span, @tracer_span),
+        token_budget: overrides.fetch(:token_budget, @token_budget),
+        max_parallel_tools: overrides.fetch(:max_parallel_tools, @max_parallel_tools),
+        approval_policy: overrides.fetch(:approval_policy, @approval_policy),
+        redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
+        provider_limits: overrides.fetch(:provider_limits, @provider_limits),
+        task_id: overrides.fetch(:task_id, @task_id),
+        parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
+      )
+    end
+
+    # Convenience: returns the cancellation token or a new never-cancelled token.
+    # @return [CancellationToken]
+    # @api private
+    def effective_cancellation_token
+      @cancellation_token || 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]
+    # @api private
+    def effective_timeout_token
+      return @cancellation_token if @cancellation_token
+      return nil if @deadline.nil?
+
+      token = CancellationToken.new
+      @deadline.attach_to(token)
+      token
+    end
+  end
+end

data/lib/phronomy/knowledge_source/base.rb

@@ -11,12 +11,33 @@ module Phronomy
     class Base
       # Retrieve knowledge chunks relevant to the given query.
       #
-      # @param query [String, nil] the current user input used to select relevant chunks
+      # @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 }
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         raise NotImplementedError, "#{self.class}#fetch is not implemented"
       end
 
+      # Submits a {#fetch} call to {BlockingAdapterPool} and returns a
+      # {BlockingAdapterPool::PendingOperation}.
+      # Callers can fan out multiple fetches in parallel and await them all.
+      #
+      # @param query              [String, nil]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def fetch_async(query: nil, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          fetch(query: query, cancellation_token: cancellation_token)
+        end
+      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.
@@ -24,6 +45,7 @@ module Phronomy
       # Override in subclasses that return fixed content.
       #
       # @return [Boolean]
+      # @api public
       def static?
         false
       end

data/lib/phronomy/knowledge_source/entity_knowledge.rb

@@ -43,6 +43,7 @@ module Phronomy
       # 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
@@ -54,9 +55,12 @@ module Phronomy
       # 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 query              [String, nil]                    unused — entity knowledge is always fully injected
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @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")
@@ -70,6 +74,7 @@ module Phronomy
       # Returns the current entity store (primarily for testing).
       #
       # @return [Hash]
+      # @api public
       def entities
         @entities.dup
       end

data/lib/phronomy/knowledge_source/rag_knowledge.rb

@@ -22,6 +22,7 @@ module Phronomy
       # @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
@@ -34,13 +35,16 @@ module Phronomy
       #
       # Returns an empty array when query is nil or blank.
       #
-      # @param query [String, nil]
+      # @param query              [String, nil]
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @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)
-        results = @store.search(query_embedding: vector, k: @k)
+        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]

data/lib/phronomy/knowledge_source/static_knowledge.rb

@@ -19,6 +19,7 @@ module Phronomy
       # @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
@@ -27,9 +28,12 @@ module Phronomy
 
       # Returns the fixed text as a single chunk, regardless of query.
       #
-      # @param query [String, nil] ignored for static knowledge
+      # @param query              [String, nil]                    ignored for static knowledge
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; raises CancellationError when cancelled
       # @return [Array<Hash>]
-      def fetch(query: nil)
+      # @api public
+      def fetch(query: nil, cancellation_token: nil)
+        cancellation_token&.raise_if_cancelled!
         return [] if @text.empty?
 
         chunk = {content: @text, type: @type}
@@ -39,6 +43,7 @@ module Phronomy
 
       # Static knowledge content never changes between invocations.
       # @return [true]
+      # @api public
       def static?
         true
       end

data/lib/phronomy/llm_adapter/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Abstract base class for LLM adapters.
+    #
+    # Subclasses must implement {#complete} and {#stream}.
+    # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
+    # those methods in a {BlockingAdapterPool} submission.
+    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
+      # @param config  [Hash]  the invocation config (e.g. +:cancellation_token+)
+      # @return [Object] LLM response object
+      # @raise [NotImplementedError]
+      # @api private
+      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 config  [Hash]  the invocation config
+      # @yield [chunk] streaming chunk from the LLM
+      # @return [Object] LLM response object
+      # @raise [NotImplementedError]
+      # @api private
+      def stream(chat, message, config: {}, &block)
+        raise NotImplementedError, "#{self.class}#stream is not implemented"
+      end
+
+      # Submits a non-streaming LLM call to {BlockingAdapterPool} and returns
+      # a {BlockingAdapterPool::PendingOperation}.
+      #
+      # @param chat    [Object] configured chat session
+      # @param message [String] user message
+      # @param config  [Hash]  invocation config
+      # @param pool    [BlockingAdapterPool] pool to submit to
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api private
+      def complete_async(chat, message, config: {}, pool: default_pool)
+        token = config[:cancellation_token]
+        timeout = config[:llm_timeout]
+        pool.submit(timeout: timeout, cancellation_token: token) do
+          complete(chat, message, config: config)
+        end
+      end
+
+      # Submits a streaming LLM call to {BlockingAdapterPool} and returns
+      # a {BlockingAdapterPool::PendingOperation}.
+      #
+      # When +enqueue_to:+ is given, streaming chunks are pushed into that
+      # {AsyncQueue} from the worker thread instead of being passed directly
+      # to the caller's block.  The queue is closed (via +ensure+) after the
+      # LLM call finishes so the consumer's drain loop terminates naturally.
+      # This keeps user-supplied blocks off the blocking-pool worker thread.
+      #
+      # When +enqueue_to:+ is nil and a block is given, the block is invoked
+      # directly from the worker thread (legacy behaviour, preserved for
+      # backward compatibility).
+      #
+      # @param chat       [Object] configured chat session
+      # @param message    [String] user message
+      # @param config     [Hash]   invocation config
+      # @param pool       [BlockingAdapterPool] pool to submit to
+      # @param enqueue_to [AsyncQueue, nil] when set, push chunks here instead of
+      #   calling the block on the worker thread
+      # @yield [chunk] streaming chunk — only used when +enqueue_to:+ is nil
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api private
+      def stream_async(chat, message, config: {}, pool: default_pool, enqueue_to: nil, &block)
+        token = config[:cancellation_token]
+        timeout = config[:llm_timeout]
+        if enqueue_to
+          pool.submit(timeout: timeout, cancellation_token: token) do
+            stream(chat, message, config: config) do |chunk|
+              enqueue_to.push(chunk)
+            end
+          ensure
+            enqueue_to.close
+          end
+        else
+          pool.submit(timeout: timeout, cancellation_token: token) do
+            stream(chat, message, config: config, &block)
+          end
+        end
+      end
+
+      private
+
+      def default_pool
+        Phronomy::Runtime.instance.blocking_io
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # LLM adapter that delegates to the RubyLLM blocking client.
+    #
+    # This is the default adapter used by Phronomy agents.  It wraps
+    # +chat.ask+ (and its streaming variant) so that the blocking HTTP
+    # call runs inside {BlockingAdapterPool} rather than on the EventLoop
+    # thread or the caller's thread directly.
+    #
+    # @example Explicitly configuring this adapter
+    #   Phronomy.configure do |c|
+    #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+    #   end
+    class RubyLLM < Base
+      # Delegates to +chat.ask(message)+.
+      #
+      # @param chat    [Object] RubyLLM chat session
+      # @param message [String] user message
+      # @param config  [Hash]   invocation config (not used directly by this impl)
+      # @return [Object] RubyLLM response
+      # @api private
+      def complete(chat, message, config: {})
+        chat.ask(message)
+      end
+
+      # Delegates to +chat.ask(message) { |chunk| block.call(chunk) }+.
+      #
+      # @param chat    [Object] RubyLLM chat session
+      # @param message [String] user message
+      # @param config  [Hash]   invocation config
+      # @yield [chunk] streaming chunk forwarded from +chat.ask+
+      # @return [Object] RubyLLM response
+      # @api private
+      def stream(chat, message, config: {}, &block)
+        chat.ask(message, &block)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Namespace for LLM adapter implementations.
+  #
+  # 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:
+  #
+  # - Blocking HTTP can be submitted to {BlockingAdapterPool} for bounded
+  #   concurrency and per-operation timeouts.
+  # - Alternative LLM clients can be swapped in without changing agent code.
+  #
+  # @example Configuring a custom adapter
+  #   Phronomy.configure do |c|
+  #     c.llm_adapter = MyCustomAdapter.new
+  #   end
+  module LLMAdapter
+  end
+end

data/lib/phronomy/loader/base.rb

@@ -16,6 +16,7 @@ module Phronomy
       # @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

data/lib/phronomy/loader/csv_loader.rb

@@ -20,6 +20,7 @@ module Phronomy
     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
@@ -28,6 +29,7 @@ module Phronomy
       # @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")
 

data/lib/phronomy/loader/markdown_loader.rb

@@ -24,6 +24,7 @@ module Phronomy
       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
@@ -31,6 +32,7 @@ module Phronomy
       # @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

data/lib/phronomy/loader/plain_text_loader.rb

@@ -12,6 +12,7 @@ module Phronomy
       # @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}}]

data/lib/phronomy/metrics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Task-centric observability snapshot (Issue #276, extended in #307).
+  #
+  # Collects live metrics from the shared Runtime components
+  # (BlockingAdapterPool, EventLoop, and Runtime task registry) and returns
+  # them as a plain Hash so they can be forwarded to any monitoring backend
+  # (Prometheus, OpenTelemetry, StatsD, etc.).
+  #
+  # All metrics are read at the moment {.snapshot} is called; no
+  # persistent state is held here.
+  #
+  # @example Exporting to a metrics endpoint
+  #   data = Phronomy::Metrics.snapshot
+  #   # => { blocking_pool_active: 2, active_agent_tasks: 1, ... }
+  module Metrics
+    # Returns a Hash of current observability metrics.
+    #
+    # @return [Hash{Symbol => Numeric}]
+    # @api public
+    def self.snapshot
+      pool = Runtime.instance.blocking_io
+      el = EventLoop.instance
+      task_snap = Runtime.instance.task_snapshot
+
+      {
+        blocking_pool_active: pool.active_count,
+        blocking_pool_queue_length: pool.queue_depth,
+        blocking_pool_abandoned_total: pool.abandoned_count,
+        blocking_pool_size: pool.pool_size,
+        event_loop_lag_last_ms: (el.last_lag_seconds * 1000).round(3),
+        event_loop_lag_max_ms: (el.max_lag_seconds * 1000).round(3),
+        event_loop_lag_average_ms: (el.average_lag_seconds * 1000).round(3)
+      }.merge(task_snap)
+    end
+  end
+end

data/lib/phronomy/output_parser/base.rb

@@ -9,6 +9,7 @@ module Phronomy
 
       # @param input [String, #to_s] text to parse
       # @return [Object] parsed result
+      # @api public
       def invoke(input, config: {})
         parse(input.is_a?(String) ? input : input.to_s)
       end

data/lib/phronomy/output_parser/json_parser.rb

@@ -10,6 +10,7 @@ module Phronomy
       # @param text [String]
       # @return [Hash, Array] result parsed with symbolize_names: true
       # @raise [Phronomy::ParseError] raised when JSON parsing fails
+      # @api public
       def parse(text)
         json_str = extract_json(text)
         JSON.parse(json_str, symbolize_names: true)
@@ -19,10 +20,28 @@ module Phronomy
 
       private
 
-      # Extracts the inner content of a Markdown code fence if present;
-      # otherwise returns the text as-is.
+      # Extracts a JSON string from the LLM response text.
+      #
+      # Strategy (in order):
+      #   1. Try each ```json ... ``` or ``` ... ``` code fence in document order,
+      #      returning the content of the first one that parses as valid JSON.
+      #   2. Try the raw text stripped of leading/trailing whitespace.
+      #
+      # This handles:
+      #   - Single JSON code fence (common case)
+      #   - Multiple code fences — the first parseable JSON block wins
+      #   - No fence — LLM omitted the backticks but returned valid JSON
       def extract_json(text)
-        text.match(/```(?:json)?\s*\n?(.*?)\n?```/m)&.captures&.first || text.strip
+        text.scan(/```(?:json)?\s*\n?(.*?)\n?```/m).each do |captures|
+          candidate = captures.first.strip
+          JSON.parse(candidate)
+          return candidate
+        rescue JSON::ParserError
+          next
+        end
+
+        # Fallback: no valid fence found — try the raw text
+        text.strip
       end
     end
   end

data/lib/phronomy/output_parser/structured_parser.rb

@@ -9,6 +9,7 @@ module Phronomy
     #   parser.parse('{"name":"Alice","age":30}')  #=> #<struct PersonSchema name="Alice", age=30>
     class StructuredParser < Base
       # @param schema_class [Class] Struct with keyword_init: true or equivalent
+      # @api public
       def initialize(schema_class)
         @schema_class = schema_class
       end
@@ -16,6 +17,7 @@ module Phronomy
       # @param text [String]
       # @return [Object] instance of schema_class
       # @raise [Phronomy::ParseError] raised when JSON parsing or schema instantiation fails
+      # @api public
       def parse(text)
         data = JsonParser.new.parse(text)
         @schema_class.new(**data)

data/lib/phronomy/prompt_template.rb

@@ -27,6 +27,7 @@ module Phronomy
 
     # @param template        [String] human message template with {{var}} placeholders
     # @param system_template [String, nil] optional system message template
+    # @api public
     def initialize(template:, system_template: nil)
       @template = template
       @system_template = system_template
@@ -36,6 +37,7 @@ module Phronomy
     #
     # @param variables [Hash{Symbol => String}]
     # @return [String]
+    # @api public
     def format(**variables)
       substitute(@template, variables)
     end
@@ -45,6 +47,7 @@ module Phronomy
     #
     # @param variables [Hash{Symbol => String}]
     # @return [String, nil]
+    # @api public
     def format_system(**variables)
       @system_template && substitute(@system_template, variables)
     end
@@ -54,6 +57,7 @@ module Phronomy
     #
     # @param input  [Hash{Symbol => String}]
     # @return [Hash]
+    # @api public
     def invoke(input, config: {})
       vars = normalize_input(input)
       result = {prompt: format(**vars)}
@@ -65,6 +69,7 @@ module Phronomy
     # Returns the list of placeholder names found in both templates.
     #
     # @return [Array<Symbol>]
+    # @api public
     def variables
       names = @template.scan(PLACEHOLDER).flatten
       names += @system_template.scan(PLACEHOLDER).flatten if @system_template