phronomy 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9bb874213c4687c9021be3c78d8972218ed56980cfff777a624311ce476d7314
-  data.tar.gz: ab3017e56357b057943d31a557e9e1cd12555ec13924fbee92c6f0f7791c9bd1
+  metadata.gz: 138e6b7d6b59f34f827e39a43b86c6f30ea0dd80e936d11e326febad4d3217b0
+  data.tar.gz: fada502e034850a3162a488cb02fc195364fc93e72398e858a79058c005c2ad3
 SHA512:
-  metadata.gz: e3d71a750858fda7910addd2ea8de1a3b907e746a247635d0b7467b4ffb5cf1ca970e74a08118b58e950c5843f756462d87a324331d23f50720067a83bb87590
-  data.tar.gz: 5ce1868de692cd6807c910f3d4669791307564c5f3dc58055c82c4c0737e3696c0d5b1050e7b85f1aba30b1e6309c11e66fcbf7ffc4f9f6c63f3970b5bce2d52
+  metadata.gz: 55526d56e69e328f9de38e75da98a9a1e0d206997f3463a18aa0481f18d978896f02567a0fefcb6ec4fe2a5f030d3829dde59c479305f6e3ce9d825b06222ce8
+  data.tar.gz: f58b275260866c5a7784c32c9846c9058cab815d6d294b92041dcf29525bbf76e1683c1151991c092eace65e5e55e41ad5390d6f6106f9306aa053bf42c5c0a8

data/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+
+- **`Phronomy::TrustPipeline` removed**: The `TrustPipeline` class and its inner
+  `TrustResult` value object have been deleted. Use `Phronomy::GeneratorVerifier`
+  instead, which provides the same generator-verifier pattern with a cleaner,
+  fully injectable API.
+
+### Added
+
+- **`Phronomy::GeneratorVerifier`** — Generator-Verifier coordination loop
+  (Anthropic blog, Pattern 1). Wraps a generator agent and a verifier agent with
+  fully injectable prompt builders, response parsers, a configurable iteration
+  limit, and an approval-outcome raise policy.
+- **`Phronomy::Agent::Orchestrator`** — Base class for orchestrator agents
+  (Anthropic blog, Pattern 2). Extends `Agent::Base` with a `subagent` DSL for
+  declarative subagent registration as LLM-callable tools, plus `dispatch_parallel`
+  and `fan_out` for programmatic parallel invocation.
+- **`Phronomy::Agent::TeamCoordinator`** — Agent teams coordination pattern
+  (Anthropic blog, Pattern 3). An LLM-powered coordinator with a shared task
+  queue and a pool of worker agents that carry conversation history across task
+  assignments. Adds `coordinator_provider` DSL for independent LLM routing.
+- **`Phronomy::Agent::SharedState`** — Shared-state coordination pattern
+  (Anthropic blog, Pattern 5). Peer agents collaborate via a `KnowledgeStore`;
+  the `member` DSL registers agents with per-agent instructions; `coordination`
+  sets the team protocol; `build_prompt` injects a tool-usage guide automatically.
+- **`Phronomy::LowConfidenceError`** — Exception raised by `GeneratorVerifier`
+  when `raise_policy: :raise` and verification fails after exhausting the
+  iteration limit.
+
+### Changed
+
+- **`Phronomy::Graph::StateGraph` event system refactored**: Per-node `advance`
+  events replaced with a unified `node_completed` event queue, reducing
+  event-handler registration overhead and simplifying listener registration.
+
+---
+
 ## [0.3.0] - 2026-05-18
 
 ### Removed

data/README.md

@@ -18,7 +18,10 @@ It provides composable building blocks — Workflows, Agents, Tools, Guardrails,
 | **Context Management** — Token budget calculation, estimation, and pruning | Stable |
 | **Knowledge/RAG** — Retrieval sources with pluggable loaders, splitters, and vector stores | Beta |
 | **Multi-agent** — Agent-as-Tool pattern and hub-and-spoke handoff routing | Beta |
-| **TrustPipeline** — Self-review loop and confidence gate (citations are LLM-self-reported) | Experimental |
+| **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::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 |
 | **Eval Framework** — Dataset-driven evaluation with multiple scorer types | Beta |
@@ -226,23 +229,88 @@ end
 
 Hooks are called in order — global → class → instance — and deep-merged.
 
-### TrustPipeline — Trustworthy outputs with citations and review
+### GeneratorVerifier — Generator-Verifier loop with custom prompt builders
 
 ```ruby
-pipeline = Phronomy::TrustPipeline.new(
-  draft_agent:          PolicyDraftAgent,
-  review_agent:         PolicyReviewAgent,
+pipeline = Phronomy::GeneratorVerifier.new(
+  draft_agent:  PolicyDraftAgent,
+  review_agent: PolicyReviewAgent,
+
+  # Full control over the LLM dialogue — supply your own prompts.
+  draft_prompt_builder: ->(input, feedback) {
+    base = "Answer precisely: #{input}"
+    feedback ? "#{base}\n\nPrevious feedback: #{feedback}" : base
+  },
+  review_prompt_builder: ->(input, draft, citations) {
+    "Is this draft accurate? Draft: #{draft}"
+  },
+
   confidence_threshold: 0.7,
-  max_iterations:       3
+  max_iterations:       3,
+  raise_if_untrusted:   false   # set true to raise LowConfidenceError
 )
 
 result = pipeline.invoke("What is the refund policy?")
-puts result.output             # final answer
-puts result.trusted?           # true when confidence >= 0.7
-puts result.confidence         # Float 0.0–1.0
+puts result.output      # final answer
+puts result.trusted?    # true when confidence >= 0.7
+puts result.confidence  # Float 0.0–1.0
+result.citations.each { |c| puts "#{c[:source]}: #{c[:excerpt]}" }
+```
+
+Optionally inject a custom result parser to decode non-JSON LLM output:
+
+```ruby
+pipeline = Phronomy::GeneratorVerifier.new(
+  # ... (required params as shown above)
+  draft_result_parser:  ->(text) { my_custom_draft_parser(text) },
+  review_result_parser: ->(text) { my_custom_review_parser(text) }
+)
+```
 
-result.citations.each do |c|
-  puts "#{c[:source]}: #{c[:excerpt]}"
+Raise on low confidence:
+
+```ruby
+begin
+  result = pipeline.invoke("question")
+rescue Phronomy::LowConfidenceError => e
+  puts "Untrusted (confidence #{e.result.confidence}): #{e.result.output}"
+end
+```
+
+### Agent::Orchestrator — Parallel subagent dispatch
+
+```ruby
+class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+  model "gpt-4o"
+  instructions "Coordinate research tasks by dispatching to specialised agents."
+
+  # Each subagent is automatically exposed as an LLM-callable tool.
+  subagent :searcher,   SearchAgent
+  subagent :summarizer, SummaryAgent, on_error: :skip
+end
+
+result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
+```
+
+Programmatic parallel dispatch (no LLM loop):
+
+```ruby
+class MyOrchestrator < Phronomy::Agent::Orchestrator
+  model "gpt-4o"
+  instructions "Orchestrate."
+
+  def run(query)
+    # Heterogeneous agents in parallel
+    results = dispatch_parallel(
+      {agent: SearchAgent,   input: "topic A"},
+      {agent: AnalysisAgent, input: query}
+    )
+
+    # Fan-out — same agent, multiple inputs
+    translations = fan_out(agent: TranslationAgent, inputs: %w[Hello World])
+
+    results.map { |r| r[:output] }.join("\n")
+  end
 end
 ```
 
@@ -328,18 +396,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."
 ```
@@ -432,7 +501,7 @@ bundle exec ruby NN_example_name/run.rb
 | 16 | `16_before_completion_hook/` | Global/class/instance before_completion hooks |
 | 17 | `17_multi_agent_handoff/` | Hub-and-spoke agent routing via Runner |
 | 18 | `18_rails_agent_job/` | Rails app with AgentJob + ActionCable streaming |
-| 19 | `19_trust_pipeline/` | Trustworthy output via Citation Tracking + Self-Review + Confidence Gate |
+| 19 | `19_trust_pipeline/` | Generator-Verifier pattern with citation tracking, self-review loop and confidence gate |
 
 ## Development