phronomy 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a5d8907f1d87037c09f78f63dd8ddbd21605536b1aa53c2d43e52be4a6ab6791
-  data.tar.gz: 37260258f4ece53e6e5b748cb2236f9c99f6f7e5c754fb0c2d72c415b0137386
+  metadata.gz: 8ca63f10e2d505005a6011a8755135e0dea1c3d8e8013ae3b2ea1d3b5ecf13d3
+  data.tar.gz: 420ec691725b6450a0430cdce90372c13da4e73d7013a630b2aa33a7b72e496d
 SHA512:
-  metadata.gz: 1533e2e0d82283066bab5f80b6583497330b274396640b91a6b27b1706533e4d25842600eb023c0fd469c8da076101f43e5691218703faedce194cd74476c590
-  data.tar.gz: af0513115bfcd23f786dfbedb7bfa7947346bb36168cc62175bd900f8536d984789469afc1fd929de90fca9a6b8cd8496451a054ea3ca86af401ef142b1c3e95
+  metadata.gz: 300b155e482fe0b0015bba5d3985c8d37f2599828d9d87763cc5d9925c3bf399cbee46a658d48a79e152d9b410505609e35a89d3b02db632d51b85280938dc8c
+  data.tar.gz: 88184d595d04eb1ed1be8c6ec145476a5e1f7e6e02e52658f9d80ad3893a29fbcfc377c736b7c0de10deb14e6105bd9594d6b950bd2fb3afda800e770a2219c4

data/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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 thread-safety of `StdioTransport#rpc_call`** (#86): Concurrent calls
+  to the same `McpTool` instance could interleave JSON-RPC writes and reads,
+  corrupting request/response pairing. A `Mutex` is now held around each
+  write+read cycle. Also adds the missing `require "securerandom"`.
+
+### 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
+
+- **`Agent::Base#invoke` and `#stream` — `messages` and `thread_id` promoted to
+  top-level keyword arguments**:
+  Previously these values were passed inside the `config:` hash. They are now
+  explicit keyword arguments. The `config:` hash retains other runtime options
+  such as `:knowledge_sources`, `:user_id`, and `:session_id`.
+
+  **Before (v0.4.x)**:
+  ```ruby
+  agent.invoke(input, config: { messages: prior_msgs, thread_id: "t1" })
+  agent.stream(input, config: { messages: prior_msgs, thread_id: "t1" }) { |e| ... }
+  ```
+  **After (v0.5.0)**:
+  ```ruby
+  agent.invoke(input, messages: prior_msgs, thread_id: "t1")
+  agent.stream(input, messages: prior_msgs, thread_id: "t1") { |e| ... }
+  ```
+  Applications that only pass `:knowledge_sources`, `:user_id`, or `:session_id`
+  in `config:` require no changes.
+
+- **`Agent::Checkpoint#initialize` — `original_input:` is now a required keyword
+  argument**: Applications that construct `Checkpoint` instances directly must
+  add `original_input: input`. Checkpoints produced by `#invoke` already include
+  this field automatically.
+
+### Fixed
+
+- **`ReactAgent#step` — system instructions were never applied**: The first
+  iteration of the ReAct loop now calls `build_context` to assemble the system
+  prompt and history, matching the behaviour of `Agent::Base`. Subsequent
+  iterations re-apply instructions via `build_cached_system_text` before calling
+  `chat.complete`. Previously, all iterations silently omitted the system prompt.
+
+- **`Agent::Base#resume` — system instructions were not re-applied after
+  suspension**: Resuming from a `Checkpoint` now calls `build_cached_system_text`
+  using the original input stored in the checkpoint, so the LLM receives the
+  correct system prompt when the conversation continues. Previously, the LLM was
+  called without any system instructions on resume.
+
+---
+
 ## [0.4.0] - 2026-05-19
 
 ### Removed

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"
@@ -396,18 +393,19 @@ search_tool = Phronomy::Tool::McpTool.from_server(
 
 ### Conversation History — passing prior messages
 
-Phronomy does not manage conversation history internally. Instead, the application owns the
-message array and passes it in via `config[:messages]`:
+Phronomy does not manage conversation history internally. The application owns the
+message array and passes it in via the `messages:` keyword argument:
 
 ```ruby
 # First turn
-result1 = MyAgent.new.invoke("Hello! I'm Alice.", config: { thread_id: "session-1" })
+result1 = MyAgent.new.invoke("Hello! I'm Alice.", thread_id: "session-1")
 prior_messages = result1[:messages]   # Array<RubyLLM::Message>
 
 # Second turn — pass prior messages so the agent has context
 result2 = MyAgent.new.invoke(
   "What is my name?",
-  config: { messages: prior_messages, thread_id: "session-1" }
+  messages: prior_messages,
+  thread_id: "session-1"
 )
 puts result2[:output]   # => "Your name is Alice."
 ```
@@ -490,15 +488,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 |