phronomy 0.5.4 → 0.7.0

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/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/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

data/lib/phronomy/runnable.rb

@@ -25,13 +25,30 @@ module Phronomy
     # Yields a span; the block must return [result, usage] where usage is a
     # Phronomy::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 trace(name, input: nil, **meta, &block)
-      # Redact user input from spans when trace_pii is disabled to prevent
-      # accidental PII transmission to external tracing backends.
       traced_input = Phronomy.configuration.trace_pii ? input : "[REDACTED]"
-      Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
+
+      if Phronomy.configuration.trace_pii
+        # PII recording is allowed: pass through unchanged.
+        Phronomy.configuration.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
+        Phronomy.configuration.tracer.trace(name, input: traced_input, **meta) do |span|
+          real_result, usage = block.call(span)
+          ["[REDACTED]", usage]
+        end
+        real_result
+      end
     end
   end
 end

data/lib/phronomy/splitter/base.rb

@@ -18,6 +18,7 @@ module Phronomy
       #   returned by a Loader, or a plain String.
       # @return [Array<Hash>] array of <tt>{ text: String, metadata: Hash }</tt>
       # @raise [NotImplementedError] when not overridden by a subclass
+      # @api public
       def split(document)
         raise NotImplementedError, "#{self.class}#split is not implemented"
       end
@@ -26,6 +27,7 @@ module Phronomy
       #
       # @param documents [Array<Hash, String>]
       # @return [Array<Hash>]
+      # @api public
       def split_all(documents)
         documents.flat_map { |doc| split(doc) }
       end

data/lib/phronomy/splitter/fixed_size_splitter.rb

@@ -15,6 +15,7 @@ module Phronomy
       # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
       # @param chunk_overlap [Integer] characters to repeat at the start of each
       #   subsequent chunk (default: 200); must be less than chunk_size
+      # @api public
       def initialize(chunk_size: 1000, chunk_overlap: 200)
         raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
 
@@ -24,6 +25,7 @@ module Phronomy
 
       # @param document [Hash, String]
       # @return [Array<Hash>]
+      # @api public
       def split(document)
         doc = normalise(document)
         text = doc[:text]

data/lib/phronomy/splitter/recursive_splitter.rb

@@ -25,6 +25,7 @@ module Phronomy
       # @param chunk_size    [Integer] maximum characters per chunk (default: 1000)
       # @param chunk_overlap [Integer] overlap characters (default: 200)
       # @param separators    [Array<String>] separator list in priority order
+      # @api public
       def initialize(chunk_size: 1000, chunk_overlap: 200, separators: DEFAULT_SEPARATORS)
         raise ArgumentError, "chunk_overlap must be less than chunk_size" if chunk_overlap >= chunk_size
 
@@ -35,6 +36,7 @@ module Phronomy
 
       # @param document [Hash, String]
       # @return [Array<Hash>]
+      # @api public
       def split(document)
         doc = normalise(document)
         texts = recursive_split(doc[:text], @separators)

data/lib/phronomy/state_store/base.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module StateStore
+    # Abstract base class for workflow state persistence backends.
+    #
+    # Subclasses must implement {#load}, {#save}, and {#delete}.
+    # A snapshot is a plain +Hash+ with two keys:
+    #   +:fields+ — output of +context.to_h+
+    #   +:phase+  — +context.phase.to_s+
+    #
+    # @example Implementing a custom backend
+    #   class MyStore < Phronomy::StateStore::Base
+    #     def load(thread_id) = MyRecord.find_by(thread_id:)&.to_h
+    #     def save(thread_id, snapshot) = MyRecord.upsert(thread_id:, data: snapshot)
+    #     def delete(thread_id) = MyRecord.where(thread_id:).delete_all
+    #   end
+    class Base
+      # Load the stored snapshot for +thread_id+.
+      #
+      # @param thread_id [String]
+      # @return [Hash, nil] stored snapshot hash, or +nil+ if absent
+      # @api public
+      def load(thread_id)
+        raise NotImplementedError, "#{self.class}#load is not implemented"
+      end
+
+      # Persist +snapshot+ for +thread_id+. Overwrites any existing snapshot.
+      #
+      # @param thread_id [String]
+      # @param snapshot [Hash] serialisable hash of workflow state
+      # @return [void]
+      # @api public
+      def save(thread_id, snapshot)
+        raise NotImplementedError, "#{self.class}#save is not implemented"
+      end
+
+      # Delete the stored snapshot for +thread_id+. No-op if absent.
+      #
+      # @param thread_id [String]
+      # @return [void]
+      # @api public
+      def delete(thread_id)
+        raise NotImplementedError, "#{self.class}#delete is not implemented"
+      end
+    end
+  end
+end

data/lib/phronomy/state_store/in_memory.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module StateStore
+    # Thread-safe in-process state store backed by a plain Ruby Hash.
+    #
+    # Used as the recommended default for single-process applications and tests.
+    # State does not survive process restart.
+    #
+    # @example
+    #   store = Phronomy::StateStore::InMemory.new
+    #   store.save("t1", { fields: { count: 1 }, phase: "__end__" })
+    #   store.load("t1")   # => { fields: { count: 1 }, phase: "__end__" }
+    #   store.delete("t1")
+    #   store.load("t1")   # => nil
+    class InMemory < Base
+      def initialize
+        @data = {}
+        @mutex = Mutex.new
+      end
+
+      # @param thread_id [String]
+      # @return [Hash, nil]
+      # @api public
+      def load(thread_id)
+        @mutex.synchronize do
+          snap = @data[thread_id]
+          snap ? deep_dup(snap) : nil
+        end
+      end
+
+      # @param thread_id [String]
+      # @param snapshot [Hash]
+      # @return [void]
+      # @api public
+      def save(thread_id, snapshot)
+        @mutex.synchronize { @data[thread_id] = deep_dup(snapshot) }
+        nil
+      end
+
+      # @param thread_id [String]
+      # @return [void]
+      # @api public
+      def delete(thread_id)
+        @mutex.synchronize { @data.delete(thread_id) }
+        nil
+      end
+
+      private
+
+      # Recursively deep-duplicates a plain-data value (Hash, Array, or scalar).
+      # Sufficient for snapshot data which consists of JSON-compatible types.
+      def deep_dup(val)
+        case val
+        when Hash then val.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+        when Array then val.map { |v| deep_dup(v) }
+        else val.frozen? ? val : (val.dup rescue val) # rubocop:disable Style/RescueModifier
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/tool/agent_tool.rb

@@ -35,6 +35,7 @@ module Phronomy
         # @param description  [String, nil] description exposed to the LLM;
         #   defaults to "Delegates to <AgentClassName>"
         # @return [Class] an anonymous Phronomy::Tool::AgentTool subclass
+        # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)