phronomy 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04a7eceda662bfc638c3ec07ac161299b2bb08863e18e9ba03e7a3226165a921
-  data.tar.gz: 9938ace6e4a7250c08f733339af4de14c7d9ff62ff7c52a27eb954c0700d18f4
+  metadata.gz: d95954b46d12542673b5a319b338c7733d579b72105499a55dc4251628bc807f
+  data.tar.gz: 174341a0e329d861066d475b062260c3d78fac86da3d024ebc1594d7a37ec348
 SHA512:
-  metadata.gz: 1dc032c438a407a751b5c74fd76d172796e852a3add651c1ca6bb210991d20305a1cc609fe157e48026293084943714569219d359794c9bc7fde0dc396ed16d1
-  data.tar.gz: c1b52dcfa5196b92b72641f8d980856e5e827d61ff0e8afc61f5664f0556e0dbb0b047a7755d2f5f148525774c885ead4319510c32d7f2699fb4601c38d12ecd
+  metadata.gz: ee299b8d67fec8cb268683ffe672daab04a5c5b4794728dbeea3877e6c5216cefe91f292acac977d7293b837cd0b159445d58a87f925781a26f24438faecd010
+  data.tar.gz: 6da71943dc65b3671f5bd34ff18509a8ee2e0b12bfb5fcb206df77ba2c7345c9fd1b59dec90088dc3e8588e9327cb162046a803a9ac7cd405f4d30fc6712ebc3

data/lib/generators/phronomy/install/templates/create_phronomy_messages.rb.tt

@@ -3,7 +3,7 @@ class CreatePhronomyMessages < ActiveRecord::Migration[<%= ActiveRecord::Migrati
     create_table :phronomy_messages do |t|
       t.string :thread_id,       null: false
       t.string :role,            null: false
-      t.text   :content,         null: false
+      t.text   :content
       t.text   :tool_calls_json
       t.string :model_id
       t.timestamps

data/lib/phronomy/agent/base.rb

@@ -446,82 +446,88 @@ module Phronomy
       def stream(input, config: {}, &block)
         return invoke(input, config: config) unless block
 
-        run_input_guardrails!(input)
+        caller_meta = {}
+        caller_meta[:user_id] = config[:user_id] if config[:user_id]
+        caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
-        memory = config[:memory]
-        thread_id = config[:thread_id]
+        trace("agent.invoke", input: input, **caller_meta) do |_span|
+          run_input_guardrails!(input)
+
+          memory = config[:memory]
+          thread_id = config[:thread_id]
 
-        chat = build_chat
-        user_message = extract_message(input)
-        budget = build_token_budget
+          chat = build_chat
+          user_message = extract_message(input)
+          budget = build_token_budget
 
-        # Assemble context via Assembler (same as invoke_once).
-        assembler = Context::Assembler.new(budget: budget)
-        system_msg = build_instructions(input)
-        assembler.add_instruction(system_msg) if system_msg
+          # Assemble context via Assembler (same as invoke_once).
+          assembler = Context::Assembler.new(budget: budget)
+          system_msg = build_instructions(input)
+          assembler.add_instruction(system_msg) if system_msg
 
-        Array(config[:knowledge_sources]).each do |ks|
-          ks.fetch(query: user_message).each do |chunk|
-            assembler.add_knowledge(chunk[:content], type: chunk[:type], source: chunk[:source])
+          Array(config[:knowledge_sources]).each do |ks|
+            ks.fetch(query: user_message).each do |chunk|
+              assembler.add_knowledge(chunk[:content], type: chunk[:type], source: chunk[:source])
+            end
           end
-        end
 
-        if memory && thread_id
-          msgs = load_from_memory(memory, thread_id: thread_id, query: user_message)
-          message_elements = build_message_elements(msgs)
+          if memory && thread_id
+            msgs = load_from_memory(memory, thread_id: thread_id, query: user_message)
+            message_elements = build_message_elements(msgs)
 
-          # Run on_trim: app may call ctx.remove(seqs) to drop messages this turn.
-          if (trim_cb = self.class._on_trim_callback)
-            trim_ctx = Context::TrimContext.new(message_elements: message_elements, budget: budget)
-            trim_cb.call(trim_ctx)
-            message_elements = trim_ctx.message_elements
-          end
+            # Run on_trim: app may call ctx.remove(seqs) to drop messages this turn.
+            if (trim_cb = self.class._on_trim_callback)
+              trim_ctx = Context::TrimContext.new(message_elements: message_elements, budget: budget)
+              trim_cb.call(trim_ctx)
+              message_elements = trim_ctx.message_elements
+            end
 
-          # Run on_compaction_trigger → on_compact pipeline before calling the LLM.
-          if (trigger_cb = self.class._on_compaction_trigger_callback)
-            trigger_ctx = Context::TriggerContext.new(message_elements: message_elements, budget: budget)
-            if trigger_cb.call(trigger_ctx)
-              if (compact_cb = self.class._on_compact_callback)
-                compact_ctx = Context::CompactionContext.new(
-                  message_elements: message_elements,
-                  budget: budget,
-                  thread_id: thread_id,
-                  memory: memory
-                )
-                compact_cb.call(compact_ctx)
-                message_elements = build_message_elements(compact_ctx.result_messages)
+            # Run on_compaction_trigger → on_compact pipeline before calling the LLM.
+            if (trigger_cb = self.class._on_compaction_trigger_callback)
+              trigger_ctx = Context::TriggerContext.new(message_elements: message_elements, budget: budget)
+              if trigger_cb.call(trigger_ctx)
+                if (compact_cb = self.class._on_compact_callback)
+                  compact_ctx = Context::CompactionContext.new(
+                    message_elements: message_elements,
+                    budget: budget,
+                    thread_id: thread_id,
+                    memory: memory
+                  )
+                  compact_cb.call(compact_ctx)
+                  message_elements = build_message_elements(compact_ctx.result_messages)
+                end
               end
             end
-          end
 
-          assembler.add_messages(message_elements.map { |e| e[:message] })
-        end
+            assembler.add_messages(message_elements.map { |e| e[:message] })
+          end
 
-        context = assembler.build
-        apply_instructions(chat, context[:system]) if context[:system]
-        context[:messages].each { |msg| chat.messages << msg }
+          context = assembler.build
+          apply_instructions(chat, context[:system]) if context[:system]
+          context[:messages].each { |msg| chat.messages << msg }
 
-        # Wire per-event callbacks to yield StreamEvents.
-        chat.on_tool_call { |tool_call| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tool_call})) }
-        chat.on_tool_result { |tool_result| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tool_result})) }
+          # Wire per-event callbacks to yield StreamEvents.
+          chat.before_tool_call { |tool_call| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tool_call})) }
+          chat.after_tool_result { |tool_result| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tool_result})) }
 
-        # Run before_completion hooks (global → class → instance) before the LLM call.
-        run_before_completion_hooks!(chat, config)
+          # Run before_completion hooks (global → class → instance) before the LLM call.
+          run_before_completion_hooks!(chat, config)
 
-        response = chat.ask(user_message) do |chunk|
-          block.call(StreamEvent.new(type: :token, payload: {content: chunk.content}))
-        end
+          response = chat.ask(user_message) do |chunk|
+            block.call(StreamEvent.new(type: :token, payload: {content: chunk.content}))
+          end
 
-        save_to_memory(memory, thread_id: thread_id, messages: chat.messages) if memory && thread_id
+          save_to_memory(memory, thread_id: thread_id, messages: chat.messages) if memory && thread_id
 
-        output = response.content
-        usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+          output = response.content
+          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
 
-        run_output_guardrails!(output)
+          run_output_guardrails!(output)
 
-        result = {output: output, messages: chat.messages, usage: usage}
-        block.call(StreamEvent.new(type: :done, payload: result))
-        result
+          result = {output: output, messages: chat.messages, usage: usage}
+          block.call(StreamEvent.new(type: :done, payload: result))
+          [result, usage]
+        end
       rescue => e
         block&.call(StreamEvent.new(type: :error, payload: {error: e}))
         raise

data/lib/phronomy/agent/handoff.rb

@@ -25,10 +25,10 @@ module Phronomy
       def initialize(target_agent:, description: nil)
         @target_agent = target_agent
         klass_name = target_agent.class.name&.split("::")&.last || "Agent"
-        @tool_name = "transfer_to_#{snake_case(klass_name)}"
-        @description = description || "Transfer the conversation to #{klass_name}."
         # Use a UUID so that two handoffs targeting the same class remain distinct.
         @uuid = SecureRandom.uuid
+        @tool_name = "transfer_to_#{snake_case(klass_name)}_#{@uuid.delete("-")[0, 8]}"
+        @description = description || "Transfer the conversation to #{klass_name}."
       end
 
       # Builds an anonymous Phronomy::Tool::Base subclass for this handoff.

data/lib/phronomy/agent/react_agent.rb

@@ -5,7 +5,11 @@ module Phronomy
     # ReAct pattern (Reasoning + Acting) agent.
     # Repeats the LLM <-> Tool loop until no more tool calls are made.
     class ReactAgent < Base
-      def invoke(input, config: {})
+      private
+
+      # Performs a single (non-retried) ReAct invocation.
+      # Overrides Base#invoke_once so that Base#invoke's retry loop is inherited.
+      def invoke_once(input, config: {})
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
@@ -43,7 +47,11 @@ module Phronomy
 
           save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
 
-          output = messages.last&.content
+          # Fall back to the last message that carries non-nil content. This
+          # guards against the case where the final message is a tool-call or
+          # tool-result message (content == nil) when max_iterations is
+          # exhausted before the model produces a text reply.
+          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
 
           # Run output guardrails before returning to the caller.
           run_output_guardrails!(output)
@@ -53,6 +61,8 @@ module Phronomy
         end
       end
 
+      public
+
       # Streaming version of #invoke for the ReAct loop.
       # Yields {Phronomy::Agent::StreamEvent} events while the LLM-tool loop runs.
       #
@@ -63,42 +73,50 @@ module Phronomy
       def stream(input, config: {}, &block)
         return invoke(input, config: config) unless block
 
-        run_input_guardrails!(input)
+        caller_meta = {}
+        caller_meta[:user_id] = config[:user_id] if config[:user_id]
+        caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
-        memory = config[:memory]
-        thread_id = config[:thread_id]
-        max_iter = self.class.max_iterations
+        trace("agent.invoke", input: input, **caller_meta) do |_span|
+          run_input_guardrails!(input)
 
-        initial_messages = if memory && thread_id
-          load_from_memory(memory, thread_id: thread_id, query: extract_message(input))
-        else
-          []
-        end
+          memory = config[:memory]
+          thread_id = config[:thread_id]
+          max_iter = self.class.max_iterations
 
-        messages = initial_messages.dup
-        user_asked = false
-        total_usage = Phronomy::TokenUsage.zero
-        iterations_exhausted = true
-
-        max_iter.times do
-          response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
-          user_asked = true
-          messages = response[:messages]
-          total_usage += response[:usage]
-          if response[:done]
-            iterations_exhausted = false
-            break
+          initial_messages = if memory && thread_id
+            load_from_memory(memory, thread_id: thread_id, query: extract_message(input))
+          else
+            []
           end
-        end
 
-        save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
+          messages = initial_messages.dup
+          user_asked = false
+          total_usage = Phronomy::TokenUsage.zero
+          iterations_exhausted = true
+
+          max_iter.times do
+            response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
+            user_asked = true
+            messages = response[:messages]
+            total_usage += response[:usage]
+            if response[:done]
+              iterations_exhausted = false
+              break
+            end
+          end
 
-        output = messages.last&.content
-        run_output_guardrails!(output)
+          save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
 
-        result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
-        block.call(StreamEvent.new(type: :done, payload: result))
-        result
+          # Fall back to the last message that carries non-nil content (same as
+          # the non-streaming path above).
+          output = messages.reverse.find { |m| m.content && !m.content.empty? }&.content
+          run_output_guardrails!(output)
+
+          result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
+          block.call(StreamEvent.new(type: :done, payload: result))
+          [result, total_usage]
+        end
       rescue => e
         block&.call(StreamEvent.new(type: :error, payload: {error: e}))
         raise
@@ -136,8 +154,8 @@ module Phronomy
         chat = build_chat
         messages.each { |m| chat.add_message(m) }
 
-        chat.on_tool_call { |tc| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tc})) }
-        chat.on_tool_result { |tr| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tr})) }
+        chat.before_tool_call { |tc| block.call(StreamEvent.new(type: :tool_call, payload: {tool_call: tc})) }
+        chat.after_tool_result { |tr| block.call(StreamEvent.new(type: :tool_result, payload: {tool_result: tr})) }
 
         # Run before_completion hooks before each LLM call in the streaming loop.
         run_before_completion_hooks!(chat, config)

data/lib/phronomy/context/assembler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "cgi"
+
 module Phronomy
   module Context
     # Assembler collects all four context regions and produces the final
@@ -34,7 +36,7 @@ module Phronomy
       # @param trusted [Boolean]
       # @return [String]
       def self.xml_tag(text, type:, trusted: false)
-        "<context type=\"#{type}\" trusted=\"#{trusted}\">\n#{text}\n</context>"
+        "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
       end
 
       # @param budget [Phronomy::Context::TokenBudget, nil]
@@ -104,8 +106,8 @@ module Phronomy
       private
 
       def xml_context_tag(chunk)
-        src_attr = chunk[:source] ? " source=\"#{chunk[:source]}\"" : ""
-        "<context type=\"#{chunk[:type]}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{chunk[:text]}\n</context>"
+        src_attr = chunk[:source] ? " source=\"#{CGI.escapeHTML(chunk[:source].to_s)}\"" : ""
+        "<context type=\"#{CGI.escapeHTML(chunk[:type].to_s)}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{CGI.escapeHTML(chunk[:text].to_s)}\n</context>"
       end
 
       def trim_messages_to_budget(messages, system_text)
@@ -122,6 +124,12 @@ module Phronomy
           accumulated += tokens
           result.push(msg)
         end
+
+        if result.empty? && messages.any?
+          warn "[Phronomy::Assembler] All #{messages.length} conversation message(s) dropped: " \
+               "token budget exhausted by system context (budget=#{@budget.context_window}, used_by_system=#{used})"
+        end
+
         result.reverse
       end
     end

data/lib/phronomy/context/compaction_context.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Context
     # Context object passed to the +on_compact+ callback registered on an agent.
@@ -103,7 +101,7 @@ module Phronomy
         end
 
         remaining = (@message_elements[(last_idx + 1)..] || []).map { |e| e[:message] }
-        summary_msg = OpenStruct.new(role: :system, content: summary_text)
+        summary_msg = RubyLLM::Message.new(role: :system, content: summary_text)
         @result_messages = [summary_msg] + remaining
       end
     end

data/lib/phronomy/context/context_version_cache.rb

@@ -27,32 +27,46 @@ module Phronomy
       attr_reader :system_tokens
 
       def initialize
-        reset
+        @mutex = Mutex.new
+        @fingerprint = nil
+        @system_text = nil
+        @system_tokens = 0
       end
 
       # Returns true when the given fingerprint matches the stored one.
+      # The check is performed under a mutex so that a concurrent #update cannot
+      # expose a partially-written state where fingerprint is new but system_text
+      # is still nil (Issue #55).
       #
       # @param fingerprint [String] SHA-256 hex digest to compare
       # @return [Boolean]
       def valid?(fingerprint)
-        !@fingerprint.nil? && @fingerprint == fingerprint
+        @mutex.synchronize do
+          !@fingerprint.nil? && !@system_text.nil? && @fingerprint == fingerprint
+        end
       end
 
       # Update the cache with a new fingerprint and system text.
+      # All three assignments are performed atomically under a mutex so that
+      # concurrent readers never observe a partial state (Issue #55).
       #
       # @param fingerprint  [String] new SHA-256 hex digest
       # @param system_text  [String] fully assembled system prompt text
       def update(fingerprint:, system_text:)
-        @fingerprint = fingerprint
-        @system_text = system_text.to_s
-        @system_tokens = TokenEstimator.estimate(@system_text)
+        @mutex.synchronize do
+          @fingerprint = fingerprint
+          @system_text = system_text.to_s
+          @system_tokens = TokenEstimator.estimate(@system_text)
+        end
       end
 
       # Clear all cached values (used for testing and forced invalidation).
       def reset
-        @fingerprint = nil
-        @system_text = nil
-        @system_tokens = 0
+        @mutex.synchronize do
+          @fingerprint = nil
+          @system_text = nil
+          @system_tokens = 0
+        end
       end
     end
   end

data/lib/phronomy/eval/runner.rb

@@ -22,24 +22,52 @@ module Phronomy
         @scorer = scorer
       end
 
-      # @param dataset  [Dataset]  collection of EvalCase objects
-      # @param callable [#call]    accepts a single String argument
+      # @param dataset     [Dataset]  collection of EvalCase objects
+      # @param callable    [#call]    accepts a single String argument
+      # @param concurrency [Integer]  number of parallel threads (default: 1, sequential)
       # @return [Array<EvalResult>]
-      def run(dataset, callable)
-        dataset.map do |eval_case|
-          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-          result = callable.call(eval_case.input)
-          latency_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - t0
+      def run(dataset, callable, concurrency: 1)
+        cases = dataset.to_a
+        return cases.map { |eval_case| run_one(eval_case, callable) } if concurrency <= 1
 
-          actual, usage = extract(result)
-          score, score_error = score_safely(@scorer, actual: actual, expected: eval_case.expected, input: eval_case.input)
-
-          EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms, error: score_error)
+        # Run cases in slices of +concurrency+ threads. Each slice is joined
+        # before the next starts, bounding peak thread count to +concurrency+.
+        # Writing to pre-allocated slots (one per thread) is safe because each
+        # thread writes to a unique index and all threads in a slice are joined
+        # before the next slice begins.
+        # Exceptions in worker threads are collected and re-raised after all
+        # threads in the slice are joined, preventing orphaned threads.
+        results = Array.new(cases.length)
+        cases.each_with_index.each_slice(concurrency) do |batch|
+          errors = []
+          errors_mu = Mutex.new
+          threads = batch.map do |eval_case, i|
+            Thread.new do
+              results[i] = run_one(eval_case, callable)
+            rescue => e
+              errors_mu.synchronize { errors << e }
+            end
+          end
+          threads.each(&:join)
+          raise errors.first if errors.any?
         end
+        results
       end
 
       private
 
+      # Evaluate a single EvalCase with the given callable and return an EvalResult.
+      def run_one(eval_case, callable)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+        result = callable.call(eval_case.input)
+        latency_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - t0
+
+        actual, usage = extract(result)
+        score, score_error = score_safely(@scorer, actual: actual, expected: eval_case.expected, input: eval_case.input)
+
+        EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms, error: score_error)
+      end
+
       # Normalises the callable's return value into [actual_string, usage_or_nil].
       def extract(result)
         if result.is_a?(Hash)

data/lib/phronomy/graph/compiled_graph.rb

@@ -169,7 +169,15 @@ module Phronomy
       def next_node(current, state)
         if (cond = @conditional_edges[current])
           result = cond[:condition].call(state)
-          return cond[:mapping] ? cond[:mapping][result] : result
+          if cond[:mapping]
+            unless cond[:mapping].key?(result)
+              raise ArgumentError,
+                "Conditional edge from #{current.inspect} returned #{result.inspect}, " \
+                "which is not present in the mapping (#{cond[:mapping].keys.inspect})"
+            end
+            return cond[:mapping][result]
+          end
+          return result
         end
 
         edges = @edges[current]

data/lib/phronomy/graph/state_graph.rb

@@ -113,7 +113,8 @@ module Phronomy
       def add_subgraph(name, subgraph, input_mapper: nil, output_mapper: nil)
         add_node(name) do |state|
           input = input_mapper ? input_mapper.call(state) : state.to_h
-          sub_state = subgraph.invoke(input, config: {thread_id: state.thread_id})
+          sub_thread_id = "#{state.thread_id}/#{name}"
+          sub_state = subgraph.invoke(input, config: {thread_id: sub_thread_id})
           output_mapper ? output_mapper.call(sub_state) : sub_state.to_h
         end
       end

data/lib/phronomy/guardrail/builtin/pii_pattern_detector.rb

@@ -25,14 +25,20 @@ module Phronomy
         # Recognised PII categories and their detection patterns.
         PATTERNS = {
           # Japanese My Number: 12 consecutive or grouped digits (4-4-4).
+          # Matched candidates are additionally validated with the official check-digit
+          # algorithm (JIS X 0076) to eliminate false positives from arbitrary 12-digit strings.
           my_number: {
             pattern: /(?<!\d)(?<!\d[- ])\d{4}[- ]?\d{4}[- ]?\d{4}(?![- ]?\d)/,
-            label: "My Number"
+            label: "My Number",
+            validate_my_number: true
           },
           # Credit / debit card: 16 digits, optionally separated by spaces or hyphens.
+          # Matched candidates are additionally validated with the Luhn algorithm
+          # to eliminate false positives from arbitrary 16-digit sequences.
           credit_card: {
             pattern: /\b(?:\d{4}[- ]?){3}\d{4}\b/,
-            label: "credit card number"
+            label: "credit card number",
+            validate_luhn: true
           },
           # Email address (simplified RFC 5322).
           email: {
@@ -64,9 +70,47 @@ module Phronomy
         def check(value)
           text = value.to_s
           @active_patterns.each do |entry|
-            fail!("PII detected in input: #{entry[:label]}") if text.match?(entry[:pattern])
+            detected = if entry[:validate_luhn]
+              # Scan for all candidates then filter by Luhn check-digit validation.
+              # This avoids false positives on arbitrary 16-digit strings (e.g. internal IDs).
+              text.scan(entry[:pattern]).any? { |m| luhn_valid?(m.gsub(/[- ]/, "")) }
+            elsif entry[:validate_my_number]
+              # Scan for all candidates then apply the JIS X 0076 check-digit algorithm.
+              # This avoids false positives on arbitrary 12-digit strings.
+              text.scan(entry[:pattern]).any? { |m| my_number_valid?(m.gsub(/[- ]/, "")) }
+            else
+              text.match?(entry[:pattern])
+            end
+            fail!("PII detected in input: #{entry[:label]}") if detected
           end
         end
+
+        private
+
+        # Returns true when +digits+ (a 12-character string of decimal digits) satisfies
+        # the Japanese My Number check-digit algorithm defined in JIS X 0076.
+        # The check digit is the 12th digit.
+        def my_number_valid?(digits)
+          weights = [6, 5, 4, 3, 2, 7, 6, 5, 4, 3, 2]
+          total = weights.each_with_index.sum { |w, i| w * digits[i].to_i }
+          remainder = total % 11
+          check = (remainder <= 1) ? 0 : 11 - remainder
+          check == digits[11].to_i
+        end
+
+        # Returns true when +digits+ (a string of decimal digits) satisfies the
+        # Luhn check-digit algorithm used by payment card networks.
+        def luhn_valid?(digits)
+          digits.chars.reverse.each_with_index.sum do |d, i|
+            n = d.to_i
+            if i.odd?
+              doubled = n * 2
+              (doubled > 9) ? (doubled - 9) : doubled
+            else
+              n
+            end
+          end % 10 == 0
+        end
       end
     end
   end

data/lib/phronomy/memory/compression/summary.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -64,6 +62,9 @@ module Phronomy
           else
             {messages: messages, compaction: nil}
           end
+        rescue => e
+          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
+          {messages: messages, compaction: nil}
         end
 
         private
@@ -98,7 +99,7 @@ module Phronomy
             #{text}
             </context>
           CONTEXT
-          OpenStruct.new(role: :system, content: content)
+          RubyLLM::Message.new(role: :system, content: content)
         end
       end
     end

data/lib/phronomy/memory/compression/tool_output_pruner.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Memory
     module Compression
@@ -25,6 +23,11 @@ module Phronomy
       class ToolOutputPruner < Base
         TRUNCATION_NOTE = "\n[... output truncated ...]"
 
+        # Internal value object for cloned messages.
+        # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
+        ClonedMessage = Struct.new(:role, :content, :tool_calls, :model_id, keyword_init: true)
+        private_constant :ClonedMessage
+
         # @param max_chars [Integer] maximum character length for tool-result content
         def initialize(max_chars: 4000)
           @max_chars = max_chars
@@ -51,10 +54,12 @@ module Phronomy
         private
 
         def clone_message(original, new_content)
-          attrs = {role: original.role, content: new_content}
-          attrs[:tool_calls] = original.tool_calls if original.respond_to?(:tool_calls)
-          attrs[:model_id] = original.model_id if original.respond_to?(:model_id)
-          OpenStruct.new(attrs)
+          ClonedMessage.new(
+            role: original.role,
+            content: new_content,
+            tool_calls: (original.tool_calls if original.respond_to?(:tool_calls)),
+            model_id: (original.model_id if original.respond_to?(:model_id))
+          )
         end
       end
     end

data/lib/phronomy/memory/conversation_manager.rb

@@ -48,7 +48,16 @@ module Phronomy
         @retrieval = retrieval
         @compression = compression
         @ttl = ttl
-        @append_mutex = Mutex.new
+        # Per-thread mutexes allow concurrent saves for different thread_ids while
+        # preventing races (duplicate compaction records) within the same thread_id.
+        @thread_mutexes = {}
+        @thread_mutexes_mutex = Mutex.new
+        # Tracks the monotonically increasing next-seq per thread so that TTL
+        # purges (which reduce raw.length) do not reset the sequence counter.
+        # Protected by a dedicated mutex so concurrent saves for distinct
+        # thread_ids do not race on the shared Hash (Issue #60).
+        @raw_seq_hwm = {}
+        @raw_seq_hwm_mutex = Mutex.new
       end
 
       # Load conversation messages for a thread, applying retrieval selection.
@@ -83,8 +92,10 @@ module Phronomy
       # @param thread_id [String]
       # @param messages  [Array] full conversation history up to this point
       def save(thread_id:, messages:)
-        append_new_messages(thread_id: thread_id, messages: messages)
-        compress_and_save(thread_id: thread_id, messages: messages)
+        thread_mutex(thread_id).synchronize do
+          append_new_messages_unlocked(thread_id: thread_id, messages: messages)
+          compress_and_save(thread_id: thread_id, messages: messages)
+        end
         @retrieval.index(thread_id: thread_id, messages: messages) if @retrieval.respond_to?(:index)
       end
 
@@ -124,22 +135,44 @@ module Phronomy
 
       private
 
+      # Returns (or lazily creates) the per-thread mutex for +thread_id+.
+      # The outer @thread_mutexes_mutex protects the hash from concurrent creation.
+      def thread_mutex(thread_id)
+        @thread_mutexes_mutex.synchronize do
+          @thread_mutexes[thread_id] ||= Mutex.new
+        end
+      end
+
       # Append messages that are new since the last save to the raw history.
+      # Must be called while holding the per-thread mutex (via thread_mutex).
       # Messages are append-only; existing raw entries are never modified.
-      def append_new_messages(thread_id:, messages:)
-        # Synchronize load + append to prevent seq number collisions when two
-        # threads save the same thread_id concurrently.
-        @append_mutex.synchronize do
-          raw = @storage.load_raw(thread_id: thread_id)
-          starting_seq = raw.length
-          new_messages = messages[starting_seq..]
-          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: starting_seq) if new_messages&.any?
+      #
+      # Uses a per-thread high-water-mark (HWM) to determine the next seq number.
+      # The HWM is the maximum of:
+      #   - The highest seq stored in the raw store (correct after normal appends)
+      #   - The in-memory HWM (correct after TTL purge empties the raw store)
+      # This prevents seq number collisions when TTL purge reduces raw.length.
+      def append_new_messages_unlocked(thread_id:, messages:)
+        raw = @storage.load_raw(thread_id: thread_id)
+        # Derive the next seq from the raw store's high-water-mark seq when
+        # entries are present. Fall back to the in-memory HWM when the raw
+        # store has been partially or fully purged by TTL expiry.
+        stored_next_seq = raw.any? ? raw.map { |e| e[:seq] }.max + 1 : nil
+        hwm = @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] }
+        next_seq = [stored_next_seq, hwm].compact.max || 0
+        new_messages = messages[next_seq..]
+        if new_messages&.any?
+          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: next_seq)
+          @raw_seq_hwm_mutex.synchronize { @raw_seq_hwm[thread_id] = next_seq + new_messages.length }
         end
       end
 
       # Apply the configured compression strategy and persist the result.
       # When no strategy is configured, saves messages directly to the legacy store.
       # When compression fires, also persists the compaction record.
+      # If the compression strategy raises (e.g. LLM timeout), we fall back to
+      # saving the messages without compaction so the conversation is never lost
+      # due to a transient summarization failure (Issue #58).
       def compress_and_save(thread_id:, messages:)
         unless @compression
           @storage.save(thread_id: thread_id, messages: messages)
@@ -151,11 +184,16 @@ module Phronomy
         all_raw = @storage.load_raw(thread_id: thread_id)
         uncompacted = all_raw.select { |r| r[:seq] >= uncompacted_start_seq }.map { |r| r[:message] }
 
-        result = @compression.compress(
-          thread_id: thread_id,
-          messages: uncompacted,
-          seq_offset: uncompacted_start_seq
-        )
+        result = begin
+          @compression.compress(
+            thread_id: thread_id,
+            messages: uncompacted,
+            seq_offset: uncompacted_start_seq
+          )
+        rescue => e
+          warn "[Phronomy] Compression failed (#{e.class}: #{e.message}); saving without compaction."
+          {messages: messages, compaction: nil}
+        end
 
         if result[:compaction]
           @storage.save_compaction(

data/lib/phronomy/memory/retrieval/semantic.rb

@@ -29,21 +29,36 @@ module Phronomy
           @counter = 0
           @max_index_size = max_index_size
           @mutex = Mutex.new
+          @indexed_object_ids = {}  # thread_id => { object_id => true }
         end
 
         # Index a new batch of messages so they are searchable on future #select calls.
         # Called by ConversationManager#save.
         #
+        # Messages are deduplicated by object identity: if a message object has already
+        # been indexed for the given thread_id, it is skipped (no duplicate embed call).
+        #
         # @param thread_id [String]
         # @param messages  [Array]
         def index(thread_id:, messages:)
           messages.each do |msg|
+            # Fast path: skip already-indexed messages without calling embed.
+            already_indexed = @mutex.synchronize do
+              (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
+            end
+            next if already_indexed
+
             embedding = @embeddings.embed(msg.content.to_s)
             @mutex.synchronize do
+              # Re-check inside lock to handle concurrent callers for the same thread.
+              indexed = (@indexed_object_ids[thread_id] ||= {})
+              next if indexed[msg.object_id]
+
               id = "#{thread_id}:#{@counter}"
               @counter += 1
               @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
               @index[id] = msg
+              indexed[msg.object_id] = true
               evict_oldest! if @max_index_size && @index.size > @max_index_size
             end
           end
@@ -59,6 +74,7 @@ module Phronomy
               @index.delete(id)
               @store.remove(id: id)
             end
+            @indexed_object_ids.delete(thread_id)
           end
         end
 
@@ -71,7 +87,7 @@ module Phronomy
         def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
-            results = @store.search(query_embedding: query_embedding, k: @k * 3)
+            results = @mutex.synchronize { @store.search(query_embedding: query_embedding, k: @k * 3) }
             results
               .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
               .first(@k)

data/lib/phronomy/memory/storage/active_record.rb

@@ -75,7 +75,7 @@ module Phronomy
               @model_class.create!(
                 thread_id: thread_id,
                 role: msg.role.to_s,
-                content: msg.content.to_s,
+                content: msg.content,
                 tool_calls_json: serialize_tool_calls(msg),
                 model_id: (msg.model_id if msg.respond_to?(:model_id))
               )
@@ -100,15 +100,17 @@ module Phronomy
         def append_raw(thread_id:, messages:, starting_seq:)
           return unless @raw_model_class
 
-          messages.each_with_index do |msg, i|
-            @raw_model_class.create!(
-              thread_id: thread_id,
-              seq: starting_seq + i,
-              role: msg.role.to_s,
-              content: msg.content.to_s,
-              tool_calls_json: serialize_tool_calls(msg),
-              model_id: (msg.model_id if msg.respond_to?(:model_id))
-            )
+          @raw_model_class.transaction do
+            messages.each_with_index do |msg, i|
+              @raw_model_class.create!(
+                thread_id: thread_id,
+                seq: starting_seq + i,
+                role: msg.role.to_s,
+                content: msg.content,
+                tool_calls_json: serialize_tool_calls(msg),
+                model_id: (msg.model_id if msg.respond_to?(:model_id))
+              )
+            end
           end
         end
 

data/lib/phronomy/state_store/in_memory.rb

@@ -8,30 +8,31 @@ module Phronomy
     class InMemory < Base
       def initialize
         @store = {}
+        @mutex = Mutex.new
       end
 
       # @param state [Object] includes Phronomy::Graph::State; must have a non-nil thread_id
       # @return [self]
       def save(state)
-        @store[state.thread_id] = state
+        @mutex.synchronize { @store[state.thread_id] = state }
         self
       end
 
       # @param thread_id [String]
       # @return [Object, nil] state object or nil
       def load(thread_id)
-        @store[thread_id]
+        @mutex.synchronize { @store[thread_id] }
       end
 
       # @param thread_id [String]
       # @return [self]
       def clear(thread_id)
-        @store.delete(thread_id)
+        @mutex.synchronize { @store.delete(thread_id) }
         self
       end
 
       def clear_all
-        @store.clear
+        @mutex.synchronize { @store.clear }
         self
       end
     end

data/lib/phronomy/tool/base.rb

@@ -157,7 +157,14 @@ module Phronomy
           key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
           next unless properties[key]
 
-          properties[key]["enum"] = values.map(&:to_s)
+          param_type = properties[key]["type"]
+          properties[key]["enum"] = values.map do |v|
+            case param_type
+            when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
+            when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
+            else v.to_s
+            end
+          end
         end
 
         schema

data/lib/phronomy/tool/mcp_tool.rb

@@ -90,6 +90,9 @@ module Phronomy
           @mutex = Mutex.new
           @stdin = nil
           @stdout = nil
+          @stderr = nil
+          @wait_thr = nil
+          @stderr_thread = nil
         end
 
         # Shut down the child process and close its IO streams.
@@ -97,9 +100,17 @@ module Phronomy
           @mutex.synchronize do
             @stdin&.close
             @stdout&.close
+            @stderr&.close
             @stdin = nil
             @stdout = nil
+            @stderr = nil
           end
+          # Join the stderr drain thread and the child process outside the mutex
+          # to avoid holding the lock during potentially slow joins.
+          @stderr_thread&.join(1)
+          @wait_thr&.join(5)
+          @stderr_thread = nil
+          @wait_thr = nil
         end
 
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
@@ -144,7 +155,15 @@ module Phronomy
         def ensure_started!
           return if @stdin && !@stdin.closed?
 
-          @stdin, @stdout, _stderr, _wait_thr = Open3.popen3(*@command)
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*@command)
+          # Drain stderr asynchronously to prevent the pipe buffer from filling
+          # and deadlocking the child process. Errors inside the drain thread are
+          # silently ignored since stderr content is diagnostics-only.
+          @stderr_thread = Thread.new do
+            @stderr.read
+          rescue
+            nil
+          end
         end
 
         def rpc_call(method, params)
@@ -212,6 +231,10 @@ module Phronomy
         # @return [Object] the tool result
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
+          if response["error"]
+            err_msg = response.dig("error", "message") || response["error"].to_s
+            raise Phronomy::ToolError, "MCP HTTP server returned error: #{err_msg}"
+          end
           content = response.dig("result", "content")
 
           if content.is_a?(Array)

data/lib/phronomy/tracing/base.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Tracing
     # Abstract tracer.

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -35,6 +35,8 @@ module Phronomy
         @public_key = public_key
         @secret_key = secret_key
         @host = host.chomp("/")
+        @http = nil
+        @http_mutex = Mutex.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -78,21 +80,37 @@ module Phronomy
       private
 
       # Sends a batch of events to the Langfuse ingestion endpoint.
+      # The Net::HTTP connection is cached and reused across calls to avoid
+      # per-span TCP + TLS handshake overhead (Issue #61).
       # Errors are rescued and ignored to keep the tracer non-disruptive.
       def ingest(events)
         uri = URI.parse("#{@host}/api/public/ingestion")
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-        http.open_timeout = 3
-        http.read_timeout = 5
         req = Net::HTTP::Post.new(uri.request_uri)
         req["Content-Type"] = "application/json"
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
-        http.request(req)
-      rescue
+
+        @http_mutex.synchronize do
+          @http ||= build_http(uri)
+          @http.request(req)
+        end
+      rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
+        # Connection was reset; drop the cached connection and warn.
+        @http_mutex.synchronize { @http = nil }
+        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
+        nil
+      rescue => e
+        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
         nil
       end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 3
+        http.read_timeout = 5
+        http
+      end
     end
   end
 end

data/lib/phronomy/tracing/null_tracer.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Tracing
     # No-op tracer used as the default. All calls succeed silently.
@@ -10,8 +8,13 @@ module Phronomy
     #
     #   Phronomy.configure { |c| c.tracer = MyRealTracer.new }
     class NullTracer < Base
+      # Internal value object for span handles returned by #start_span.
+      # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
+      SpanStruct = Struct.new(:name)
+      private_constant :SpanStruct
+
       # Returns a minimal span object with the given name.
-      def start_span(name, **) = OpenStruct.new(name: name)
+      def start_span(name, **) = SpanStruct.new(name)
 
       # Does nothing.
       def finish_span(span, **) = nil

data/lib/phronomy/trust_pipeline.rb

@@ -75,13 +75,20 @@ module Phronomy
     # @param review_agent         [Class]   subclass of Phronomy::Agent::Base
     # @param confidence_threshold [Float]   answers below this are retried (default: 0.7)
     # @param max_iterations       [Integer] maximum draft-review cycles (default: 3)
+    # @param input_delimiter      [Array<String>, nil] optional two-element array
+    #   [start_tag, end_tag] used to wrap user input in prompts, e.g.
+    #   ["<user_input>", "</user_input>"] or
+    #   ["=== user input start ===", "=== user input end ==="].
+    #   When nil (default), input is embedded as-is for backward compatibility.
     def initialize(draft_agent:, review_agent:,
       confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
-      max_iterations: DEFAULT_MAX_ITERATIONS)
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      input_delimiter: nil)
       @draft_agent_class = draft_agent
       @review_agent_class = review_agent
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
+      @input_delimiter = input_delimiter
       @graph_mutex = Mutex.new
       @compiled_graph = nil
     end
@@ -173,6 +180,15 @@ module Phronomy
       graph
     end
 
+    # Wraps +input+ with the configured delimiter pair when +input_delimiter+ is set.
+    # When no delimiter is configured the input is returned unchanged.
+    def wrap_input(input)
+      return input unless @input_delimiter
+
+      start_tag, end_tag = @input_delimiter
+      "#{start_tag}\n#{input}\n#{end_tag}"
+    end
+
     # Builds the prompt sent to the DraftAgent for each iteration.
     def draft_prompt(input, feedback)
       lines = [
@@ -186,7 +202,7 @@ module Phronomy
       end
       lines += [
         "",
-        "Question: #{input}",
+        "Question: #{wrap_input(input)}",
         "",
         "RESPOND ONLY WITH VALID JSON (no text outside the JSON block):",
         '{"answer":"<full answer>","confidence":<0.0-1.0>,' \
@@ -205,7 +221,7 @@ module Phronomy
       [
         "You are a rigorous quality reviewer. Evaluate the draft answer below.",
         "",
-        "Question: #{input}",
+        "Question: #{wrap_input(input)}",
         "",
         "Draft answer:",
         draft.to_s,

data/lib/phronomy/vector_store/in_memory.rb

@@ -14,13 +14,14 @@ module Phronomy
     class InMemory < Base
       def initialize
         @documents = {}
+        @mutex = Mutex.new
       end
 
       # @param id        [String]
       # @param embedding [Array<Float>]
       # @param metadata  [Hash]
       def add(id:, embedding:, metadata: {})
-        @documents[id] = {embedding: embedding, metadata: metadata}
+        @mutex.synchronize { @documents[id] = {embedding: embedding, metadata: metadata} }
         self
       end
 
@@ -28,7 +29,8 @@ module Phronomy
       # @param k               [Integer]
       # @return [Array<Hash>] sorted by descending score
       def search(query_embedding:, k: 5)
-        results = @documents.map do |id, doc|
+        snapshot = @mutex.synchronize { @documents.dup }
+        results = snapshot.map do |id, doc|
           score = cosine_similarity(query_embedding, doc[:embedding])
           {id: id, score: score, metadata: doc[:metadata]}
         end
@@ -36,18 +38,18 @@ module Phronomy
       end
 
       def remove(id:)
-        @documents.delete(id)
+        @mutex.synchronize { @documents.delete(id) }
         self
       end
 
       def clear
-        @documents.clear
+        @mutex.synchronize { @documents.clear }
         self
       end
 
       # @return [Integer] number of documents stored
       def size
-        @documents.size
+        @mutex.synchronize { @documents.size }
       end
 
       private

data/lib/phronomy/vector_store/redis_search.rb

@@ -38,6 +38,7 @@ module Phronomy
         @index_name = index_name
         @dimension = dimension
         @index_created = false
+        @mutex = Mutex.new
       end
 
       # @param id        [String]
@@ -79,37 +80,43 @@ module Phronomy
       end
 
       def clear
-        begin
-          @redis.call("FT.DROPINDEX", @index_name, "DD")
-        rescue => e
-          raise unless e.message.to_s.include?("Unknown Index name")
+        @mutex.synchronize do
+          begin
+            @redis.call("FT.DROPINDEX", @index_name, "DD")
+          rescue => e
+            raise unless e.message.to_s.include?("Unknown Index name")
+          end
+          @index_created = false
         end
-        @index_created = false
         self
       end
 
       private
 
       def ensure_index!(dim)
-        return if @index_created
-
-        @dimension ||= dim
-        begin
-          @redis.call(
-            "FT.CREATE", @index_name,
-            "ON", "HASH",
-            "PREFIX", 1, DOC_PREFIX,
-            "SCHEMA",
-            "embedding", "VECTOR", "FLAT", 6,
-            "TYPE", "FLOAT32",
-            "DIM", @dimension,
-            "DISTANCE_METRIC", "COSINE",
-            "metadata", "TEXT"
-          )
-        rescue => e
-          raise unless e.message.to_s.include?("Index already exists")
+        return if @index_created # fast path outside lock
+
+        @mutex.synchronize do
+          return if @index_created # re-check inside lock
+
+          @dimension ||= dim
+          begin
+            @redis.call(
+              "FT.CREATE", @index_name,
+              "ON", "HASH",
+              "PREFIX", 1, DOC_PREFIX,
+              "SCHEMA",
+              "embedding", "VECTOR", "FLAT", 6,
+              "TYPE", "FLOAT32",
+              "DIM", @dimension,
+              "DISTANCE_METRIC", "COSINE",
+              "metadata", "TEXT"
+            )
+          rescue => e
+            raise unless e.message.to_s.include?("Index already exists")
+          end
+          @index_created = true
         end
-        @index_created = true
       end
 
       # Pack a Float array as a FLOAT32 binary string for RediSearch.

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-10 00:00:00.000000000 Z
+date: 2026-05-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm