phronomy 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 138e6b7d6b59f34f827e39a43b86c6f30ea0dd80e936d11e326febad4d3217b0
-  data.tar.gz: fada502e034850a3162a488cb02fc195364fc93e72398e858a79058c005c2ad3
+  metadata.gz: f2129e4cbe20c3831530f0a8ef810abe272174195cbce5198207fec6bf255eff
+  data.tar.gz: f9a0152759518cb2d85126ee5fb7a57b96e00a0ed7b8acffd54c57de91ed0c18
 SHA512:
-  metadata.gz: 55526d56e69e328f9de38e75da98a9a1e0d206997f3463a18aa0481f18d978896f02567a0fefcb6ec4fe2a5f030d3829dde59c479305f6e3ce9d825b06222ce8
-  data.tar.gz: f58b275260866c5a7784c32c9846c9058cab815d6d294b92041dcf29525bbf76e1683c1151991c092eace65e5e55e41ad5390d6f6106f9306aa053bf42c5c0a8
+  metadata.gz: 0af940bc5279c64221d000e4c545c5e2696f2f14c405326785786b94cf9afc567619e94e79aefbfc68b0656d761ebe88b7604d1cbacf75e82ae3aca6d39b9e3f
+  data.tar.gz: 71d4ef2f73a4e914d4dd85fffef0643a1725857dc6bf51dce5c39e78f34a0bfdc69d2de59be574396175f3a2ea5841e502bde75d082ddb30f15ee30a1a598037

data/CHANGELOG.md

@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.5.2] - 2026-05-20
+
+### Bug Fixes
+
+- **CHANGELOG correction for v0.5.1 MCP fix** (#90): The v0.5.1 entry
+  incorrectly stated that a `Mutex` was added to `StdioTransport#rpc_call`.
+  The actual fix was per-instance transport ownership (each `McpTool` instance
+  creates its own transport in `initialize`). Corrected the description.
+
+### Enhancements
+
+- **Add `McpTool#close`** (#92): Tool instances now expose a `close` method
+  that shuts down the underlying stdio child process (`StdioTransport`) or
+  releases the HTTP connection (`HttpTransport`). This gives callers a
+  deterministic way to clean up resources instead of relying on GC.
+
+### Maintenance
+
+- **Archive stale Rails integration design doc** (#91): Added an archived
+  notice to `spec/design/17_rails_integration.md` clarifying that Rails
+  integration was removed in v0.3.0–v0.5.1 and the document is for
+  historical reference only.
+
+- **Remove zombie `register_workflow_context` API** (#93): The
+  `Phronomy.register_workflow_context`, `workflow_context_registry`, and
+  `reset_workflow_context_registry!` methods (along with the backing
+  `@workflow_context_registry` and `@registry_mutex` module-level variables)
+  were removed from `lib/phronomy.rb`. These existed to support the
+  `StateStore` deserialization guard, which was removed in a prior release.
+  The API had no remaining callers in the codebase and was not listed in
+  the README stability table.
+
+---
+
+## [0.5.1] - 2026-05-21
+
+### Bug Fixes
+
+- **Remove broken Rails generator and Railtie** (#85): The generator template
+  referenced `Phronomy::ActiveRecord::ActsAs` which no longer exists, causing
+  `rails generate phronomy:install` to produce broken model files. Removed
+  `lib/generators/`, `lib/phronomy/railtie.rb`, and all references in
+  `lib/phronomy.rb`.
+
+- **Fix MCP transport ownership** (#86): `McpTool` no longer stores a shared
+  transport at class level. `from_server` now uses a short-lived transport only
+  to fetch tool metadata and calls `close` immediately after. Each tool instance
+  creates its own `StdioTransport` or `HttpTransport` in `initialize`, so
+  concurrent callers (e.g. via `Orchestrator#dispatch_parallel`) never share
+  stdio streams. No `Mutex` is needed. Also adds missing
+  `require "securerandom"` and a no-op `HttpTransport#close` for interface
+  consistency.
+
+### Documentation
+
+- **README corrections** (#87): Remove stale Rails generator installation
+  instructions. Clarify that `TeamCoordinator` worker state is local to a
+  single `invoke` call (not persistent across calls). Annotate app-level
+  examples (`09_rails_chat`, `15_rails_secure_chat`, `18_rails_agent_job`,
+  `19_trust_pipeline`) as requiring external infrastructure. Add scope note
+  to `Agent::Orchestrator` section.
+
+### Maintenance
+
+- **Add version guard to `ruby_llm_patches.rb`** (#88): The monkey-patch for
+  the upstream `handle_error_chunk` bug (ruby_llm <= 1.15.0) is now
+  gated behind a `Gem::Version` check so upgrading ruby_llm will
+  automatically disable the override.
+
+---
+
 ## [0.5.0] - 2026-05-20
 
 ### Breaking Changes

data/README.md

@@ -20,7 +20,7 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
 | **GeneratorVerifier** — Generator-Verifier loop with injectable prompt builders/parsers | Beta |
 | **Agent::Orchestrator** — Parallel subagent dispatch, fan-out, and `subagent` DSL | Beta |
-| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + persistent worker pool with task queue | Beta |
+| **Agent::TeamCoordinator** — Agent teams pattern: LLM coordinator + stateful worker pool with task queue (worker-local message history per run) | Beta |
 | **Agent::SharedState** — Shared state pattern: peer agents collaborate via a shared KnowledgeStore; `member` DSL with per-agent instructions and `coordination` team protocol | Experimental |
 | **Guardrails** — Input/output validation; built-in PII and prompt-injection detectors | Beta |
 | **Output Parser** — JSON and Struct-mapped parsers for structured LLM responses | Stable |
@@ -42,14 +42,6 @@ Then run:
 bundle install
 ```
 
-For Rails apps, run the install generator after bundling:
-
-```bash
-rails generate phronomy:install
-```
-
-This creates a configuration initializer.
-
 ## Quick Start
 
 ### Agent — ReAct tool-calling agent
@@ -279,6 +271,11 @@ end
 
 ### Agent::Orchestrator — Parallel subagent dispatch
 
+> **Note:** `dispatch_parallel` and `fan_out` use plain Ruby threads and are
+> intended for small-scale fan-out (a handful of subagents). For large-scale
+> parallel dispatch, manage concurrency (thread pools, rate limiting) at the
+> application level.
+
 ```ruby
 class ResearchOrchestrator < Phronomy::Agent::Orchestrator
   model "gpt-4o"
@@ -394,6 +391,13 @@ search_tool = Phronomy::Tool::McpTool.from_server(
 )
 ```
 
+Call `close` when the tool is no longer needed to shut down the underlying
+child process (stdio transport) or release the HTTP connection:
+
+```ruby
+search_tool.close
+```
+
 ### Conversation History — passing prior messages
 
 Phronomy does not manage conversation history internally. The application owns the
@@ -491,15 +495,21 @@ bundle exec ruby NN_example_name/run.rb
 | 06 | `06_guardrails/` | Input/output guardrails |
 | 07 | `07_tracing/` | Custom observability with Langfuse tracer |
 | 08 | `08_mcp_tool/` | MCP tool integration |
-| 09 | `09_rails_chat/` | Rails chat app with ActionCable streaming |
 | 10 | `10_context_management/` | Token budget and context pruning |
 | 11 | `11_agent_streaming/` | Streaming agent responses |
 | 12 | `12_prompt_template/` | Advanced prompt templates |
 | 13 | `13_mcp_http_tool/` | HTTP-based MCP tool server |
 | 14 | `14_code_review/` | Automated code review agent |
-| 15 | `15_rails_secure_chat/` | Rails chat with PII guardrails |
 | 16 | `16_before_completion_hook/` | Global/class/instance before_completion hooks |
 | 17 | `17_multi_agent_handoff/` | Hub-and-spoke agent routing via Runner |
+
+The following examples are **app-level demos** (Rails apps or advanced pipelines)
+that require additional infrastructure (a running Rails server, database, etc.):
+
+| # | Directory | What it demonstrates |
+|---|-----------|----------------------|
+| 09 | `09_rails_chat/` | Rails chat app with ActionCable streaming |
+| 15 | `15_rails_secure_chat/` | Rails chat with PII guardrails |
 | 18 | `18_rails_agent_job/` | Rails app with AgentJob + ActionCable streaming |
 | 19 | `19_trust_pipeline/` | Generator-Verifier pattern with citation tracking, self-review loop and confidence gate |
 

data/lib/phronomy/ruby_llm_patches.rb

@@ -3,18 +3,22 @@
 # Patches for upstream ruby_llm bugs that have not yet been released.
 # Remove each patch once the fix is available in a published gem version.
 
-module RubyLLM
-  module Streaming
-    private
+# Guard: apply monkey-patches only to affected ruby_llm versions so that
+# upgrading the gem does not silently keep dead overrides in place.
+if Gem::Version.new(RubyLLM::VERSION) <= Gem::Version.new("1.15.0")
+  module RubyLLM
+    module Streaming
+      private
 
-    # Upstream ruby_llm <= 1.15.0 assumes the SSE error chunk always has two
-    # lines ("event: error\ndata: {...}") and uses a fixed index [1], which
-    # raises NoMethodError when some providers (e.g. Qwen) return a single-line
-    # chunk ("data: {...}").  This patch finds the data line by content instead.
-    def handle_error_chunk(chunk, env)
-      data_line = chunk.split("\n").find { |l| l.start_with?("data: ") } || chunk.split("\n")[0]
-      error_data = data_line.delete_prefix("data: ")
-      parse_error_from_json(error_data, env, "Failed to parse error chunk")
+      # Upstream ruby_llm <= 1.15.0 assumes the SSE error chunk always has two
+      # lines ("event: error\ndata: {...}") and uses a fixed index [1], which
+      # raises NoMethodError when some providers (e.g. Qwen) return a single-line
+      # chunk ("data: {...}").  This patch finds the data line by content instead.
+      def handle_error_chunk(chunk, env)
+        data_line = chunk.split("\n").find { |l| l.start_with?("data: ") } || chunk.split("\n")[0]
+        error_data = data_line.delete_prefix("data: ")
+        parse_error_from_json(error_data, env, "Failed to parse error chunk")
+      end
     end
   end
 end

data/lib/phronomy/tool/mcp_tool.rb

@@ -3,6 +3,7 @@
 require "json"
 require "net/http"
 require "open3"
+require "securerandom"
 require "shellwords"
 require "uri"
 
@@ -36,9 +37,13 @@ module Phronomy
         # @param tool_name [String] the tool name as registered in the MCP server
         # @return [McpTool] a configured subclass instance ready for use with an Agent
         def from_server(server_uri, tool_name:)
+          # Use a short-lived transport only to query the tool definition,
+          # then close it.  Each McpTool instance creates its own transport
+          # so that concurrent callers never share IO streams.
           transport = build_transport(server_uri)
           tool_def = transport.fetch_tool(tool_name)
-          build_tool_class(tool_name, tool_def, transport).new
+          transport.close
+          build_tool_class(tool_name, server_uri, tool_def).new
         end
 
         private
@@ -55,10 +60,10 @@ module Phronomy
           end
         end
 
-        def build_tool_class(tool_name, tool_def, transport)
+        def build_tool_class(tool_name, server_uri, tool_def)
           klass = Class.new(McpTool)
           klass.instance_variable_set(:@mcp_tool_name, tool_name)
-          klass.instance_variable_set(:@mcp_transport, transport)
+          klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
           # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
@@ -66,10 +71,22 @@ module Phronomy
             klass.param(p[:name].to_sym, type: p[:type]&.to_sym || :string, desc: p[:description].to_s)
           end
 
-          # Define #execute to forward the call to the MCP server.
+          # Each instance creates its own transport so concurrent agent threads
+          # never share IO streams, eliminating the need for synchronisation.
+          klass.define_method(:initialize) do
+            uri = self.class.instance_variable_get(:@mcp_server_uri)
+            @mcp_transport = self.class.send(:build_transport, uri)
+          end
+
           klass.define_method(:execute) do |**args|
-            self.class.instance_variable_get(:@mcp_transport)
-              .call_tool(tool_name, args)
+            @mcp_transport.call_tool(tool_name, args)
+          end
+
+          # Allow callers to deterministically shut down the underlying child
+          # process (stdio) or release the HTTP connection.  For HttpTransport
+          # this is a no-op.  Calling execute after close raises an error.
+          klass.define_method(:close) do
+            @mcp_transport.close
           end
 
           klass
@@ -108,7 +125,6 @@ module Phronomy
           wait_thr = @wait_thr
           @stderr_thread = nil
           @wait_thr = nil
-          # Join outside the lock to avoid blocking on slow joins.
           stderr_thread&.join(1)
           wait_thr&.join(5)
         end
@@ -208,6 +224,11 @@ module Phronomy
           @read_timeout = read_timeout
         end
 
+        # HTTP connections are stateless; close is a no-op, defined so that
+        # both transport classes share the same interface as StdioTransport.
+        def close
+        end
+
         # Retrieve the tool definition from the server using MCP `tools/list`.
         # @param tool_name [String]
         # @return [Hash] { description:, parameters: }

data/lib/phronomy/version.rb

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

data/lib/phronomy.rb

@@ -5,7 +5,6 @@ require "ruby_llm"
 require_relative "phronomy/ruby_llm_patches"
 
 loader = Zeitwerk::Loader.for_gem
-loader.ignore(File.expand_path("generators", __dir__))
 # Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
 # ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
@@ -14,8 +13,6 @@ loader.setup
 require_relative "phronomy/version"
 require_relative "phronomy/token_usage"
 
-require "phronomy/railtie" if defined?(Rails::Railtie)
-
 module Phronomy
   # Exception hierarchy
   class Error < StandardError; end
@@ -53,42 +50,7 @@ module Phronomy
     end
   end
 
-  # Registry for WorkflowContext classes that may be serialized to external stores
-  # (Redis, DB). Call +register_workflow_context+ at application startup so that
-  # only known classes can be deserialized.
-  @workflow_context_registry = nil
-  @registry_mutex = Mutex.new
-
   class << self
-    # Register one or more WorkflowContext classes that are allowed to be
-    # deserialized by StateStore backends. When at least one class is registered,
-    # only registered classes will be accepted by
-    # +StateStore::Base#safe_state_class+.
-    #
-    # Call this once at application startup (e.g. in a Rails initializer).
-    #
-    # @param classes [Array<Class>] classes including Phronomy::WorkflowContext
-    # @example
-    #   Phronomy.register_workflow_context(ScanContext, OtherContext)
-    def register_workflow_context(*classes)
-      @registry_mutex.synchronize do
-        @workflow_context_registry ||= {}
-        classes.each do |klass|
-          raise ArgumentError, "#{klass.inspect} is not a Class" unless klass.is_a?(Class)
-          @workflow_context_registry[klass.name] = klass
-        end
-      end
-    end
-
-    # Returns the current registry Hash, or nil when no class has been registered.
-    # @return [Hash{String => Class}, nil]
-    attr_reader :workflow_context_registry
-
-    # Clears the registry. Primarily used in tests.
-    def reset_workflow_context_registry!
-      @registry_mutex.synchronize { @workflow_context_registry = nil }
-    end
-
     def configuration
       @configuration ||= Configuration.new
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-19 00:00:00.000000000 Z
+date: 2026-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,10 +64,6 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
-- lib/generators/phronomy/install/install_generator.rb
-- lib/generators/phronomy/install/templates/create_phronomy_messages.rb.tt
-- lib/generators/phronomy/install/templates/initializer.rb.tt
-- lib/generators/phronomy/install/templates/message_model.rb.tt
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
@@ -132,7 +128,6 @@ files:
 - lib/phronomy/output_parser/json_parser.rb
 - lib/phronomy/output_parser/structured_parser.rb
 - lib/phronomy/prompt_template.rb
-- lib/phronomy/railtie.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
 - lib/phronomy/splitter.rb

data/lib/generators/phronomy/install/install_generator.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-require "rails/generators"
-require "rails/generators/active_record"
-
-module Phronomy
-  module Generators
-    # Rails generator that installs Phronomy into a Rails app.
-    # Creates an initializer and database migrations:
-    #   - phronomy_messages (conversation history persistence)
-    #
-    # Usage:
-    #   rails generate phronomy:install
-    class InstallGenerator < ::Rails::Generators::Base
-      include ::Rails::Generators::Migration
-
-      source_root File.expand_path("templates", __dir__)
-
-      desc "Creates a Phronomy initializer and database migrations."
-
-      def self.next_migration_number(dirname)
-        ::ActiveRecord::Generators::Base.next_migration_number(dirname)
-      end
-
-      def copy_initializer
-        template "initializer.rb.tt", "config/initializers/phronomy.rb"
-      end
-
-      def create_messages_migration
-        migration_template(
-          "create_phronomy_messages.rb.tt",
-          "db/migrate/create_phronomy_messages.rb"
-        )
-      end
-
-      def create_message_model
-        template "message_model.rb.tt", "app/models/phronomy_message.rb"
-      end
-    end
-  end
-end

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

@@ -1,15 +0,0 @@
-class CreatePhronomyMessages < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
-  def change
-    create_table :phronomy_messages do |t|
-      t.string :thread_id,       null: false
-      t.string :role,            null: false
-      t.text   :content
-      t.text   :tool_calls_json
-      t.string :model_id
-      t.timestamps
-    end
-
-    add_index :phronomy_messages, :thread_id
-    add_index :phronomy_messages, [:thread_id, :created_at]
-  end
-end

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

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# Phronomy configuration initializer.
-# Customize LLM settings and agent defaults here.
-Phronomy.configure do |config|
-  # Default LLM model used when no model is specified on an agent or chain.
-  # config.default_model = "gpt-4o-mini"
-
-  # Maximum graph recursion depth (node steps per invoke).
-  # config.recursion_limit = 25
-end
-
-# RubyLLM provider credentials.
-# Prefer Rails credentials (config/credentials.yml.enc) over ENV vars.
-RubyLLM.configure do |c|
-  c.openai_api_key    = Rails.application.credentials.dig(:openai,    :api_key) || ENV["OPENAI_API_KEY"]
-  c.anthropic_api_key = Rails.application.credentials.dig(:anthropic, :api_key) || ENV["ANTHROPIC_API_KEY"]
-end

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

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-# Generated by `rails generate phronomy:install`.
-# Stores conversation messages keyed by thread_id.
-class PhronomyMessage < ApplicationRecord
-  include Phronomy::ActiveRecord::ActsAs
-  acts_as_phronomy_message
-end

data/lib/phronomy/railtie.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Railtie providing Rails integration for Phronomy.
-  # Loaded only when Rails is present.
-  class Railtie < ::Rails::Railtie
-    # Registers generator paths (rails generate phronomy:install).
-    generators do
-      require "generators/phronomy/install/install_generator"
-    end
-
-    # Fills in defaults not already set by a phronomy.rb initializer.
-    initializer "phronomy.configure_defaults" do
-      # Passes LLM API keys from Rails credentials to RubyLLM (only when present).
-      # Use ::Rails to avoid resolving to Phronomy::Rails by accident.
-      if ::Rails.application.credentials.respond_to?(:openai_api_key) &&
-          ::Rails.application.credentials.openai_api_key
-        RubyLLM.configure do |c|
-          c.openai_api_key = ::Rails.application.credentials.openai_api_key
-        end
-      end
-
-      if ::Rails.application.credentials.respond_to?(:anthropic_api_key) &&
-          ::Rails.application.credentials.anthropic_api_key
-        RubyLLM.configure do |c|
-          c.anthropic_api_key = ::Rails.application.credentials.anthropic_api_key
-        end
-      end
-    end
-
-    # Loads Phronomy::Rails::AgentJob when both ActionCable and ActiveJob are present.
-    initializer "phronomy.agent_job" do
-    end
-
-    # Loads Phronomy ActiveRecord extensions when ActiveRecord is available.
-    initializer "phronomy.active_record", after: "active_record.initialize_database" do
-    end
-  end
-end