phronomy 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1da8f29678594e3b2c0b8db70e6485f3576ffe72bc19db0dd340abefbdc3118b
-  data.tar.gz: 8dbf2cacbca536c99b7552f3494edf208986b9e45c3817fac700da445d27d2c3
+  metadata.gz: ce5a4ac39be13ef17ca1c7cd5d812b0ccdd8ea8523fdf2e59ee8f7e78e2830fa
+  data.tar.gz: 3c943cd7b11ddd1bbe2e22fdd16f3855564361c3dba093d39f5f32d193850b5a
 SHA512:
-  metadata.gz: b513420381c3eb137470d834baca90938daded756b6d3e480eed295c592b9ada062f565eaf0a77c175075378fc747080aa7c8b6bf3ccd72da22dd0c4037e2608
-  data.tar.gz: 6cea982e98ef21605ff8b55de55a6693fd2b3c3002c0212c8c9c4912f68c5bbd74204669cea3658ec7c174f506e19bda5b5f1084cccee78fa49615b181863941
+  metadata.gz: e41fcf5aee7eaed49f3ef13c7399c787c281232909b07d1fa2a2e14b4a4d443222280ead723e885faeea0534e9173c036e16e90e6af04de4a440f0a76020e2c1
+  data.tar.gz: f0dbf8fa8947760cafbc530226a021b009acf3f0be37ddee08a5404087422b5508cd5df83ab50456b43fa8f1eb57a889f8a1974372d95b98edcad1752ddda562

data/README.md

@@ -91,6 +91,17 @@ task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks")
 result = task.wait_result   # top-level/external caller only
 ```
 
+A block listener receives Agent lifecycle events and is equivalent to `on_event:`:
+
+```ruby
+task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks") do |event|
+  puts event.type   # :done, :error, :tool_call, :tool_result, etc.
+end
+
+# on_event: keyword form is also accepted and behaves identically
+task = ResearchAgent.new.invoke_async("Research Ruby AI frameworks", on_event: listener)
+```
+
 ## Runtime model
 
 Phronomy uses one completion model with two execution mechanisms:

data/docs/getting-started.md

@@ -142,6 +142,19 @@ task = agent.invoke_async("Hello")
 result = task.wait_result
 ```
 
+Both `invoke` and `invoke_async` can receive public Agent events through either
+an `on_event:` listener or a block. A block is convenient when the listener is
+local to the call:
+
+```ruby
+task = agent.invoke_async("Hello") do |event|
+  puts event.payload[:output] if event.type == :done
+end
+```
+
+Use `on_event:` when the listener already exists as a callable. Do not provide
+both `on_event:` and a block to the same invocation.
+
 `Phronomy::Task` is the common caller-facing completion handle for asynchronous
 Phronomy work. Logical lifecycle progress is driven by EventLoop/FSMSession;
 synchronous work that must execute away from EventLoop is submitted to
@@ -159,13 +172,12 @@ end
 ```
 
 ```ruby
-task = agent.stream_async(
-  "Explain the design",
-  on_event: ->(event) { puts event.payload if event.type == :token }
-)
+task = agent.stream_async("Explain the design") do |event|
+  puts event.payload if event.type == :token
+end
 ```
 
-Streaming callbacks execute on EventLoop and therefore should return quickly.
+Agent event callbacks execute on EventLoop and therefore should return quickly.
 
 ## Human-in-the-loop approval
 
@@ -283,18 +295,15 @@ workflow = Phronomy::Workflow.define(AnswerContext) do
   entry :asking, ->(ctx) {
     thread_id = ctx.thread_id
 
-    my_agent.invoke_async(
-      ctx.question,
-      on_event: ->(event) {
-        next unless event.type == :done
-
-        workflow.signal(
-          thread_id: thread_id,
-          event: :answer_ready,
-          payload: {answer: event.payload[:output]}
-        )
-      }
-    )
+    my_agent.invoke_async(ctx.question) do |event|
+      next unless event.type == :done
+
+      workflow.signal(
+        thread_id: thread_id,
+        event: :answer_ready,
+        payload: {answer: event.payload[:output]}
+      )
+    end
 
     ctx
   }

data/examples/workflows/agent_event_mapping.rb

@@ -42,36 +42,33 @@ workflow = Phronomy::Workflow.define(GenerationContext) do
     request_id = context.generation_request_id
 
     # The Agent Task is intentionally not returned from the entry action.
-    # on_event is the application-level integration channel.
-    agent.invoke_async(
-      context.prompt,
-      on_event: ->(agent_event) {
-        workflow_event =
-          case agent_event.type
-          when :done
-            :generation_completed
-          when :error, :timeout, :cancelled, :approval_required
-            :generation_failed
-          end
-        next unless workflow_event
-
-        workflow.signal(
-          thread_id: context.thread_id,
-          event: workflow_event,
-          payload: {
-            generation_request_id: request_id,
-            agent_result: (
-              agent_event.payload if agent_event.type == :done
-            ),
-            error:
-              agent_event.payload[:error] ||
-              Phronomy::Error.new(
-                "Agent requested Tool approval"
-              )
-          }
-        )
-      }
-    )
+    # The block is the application-level integration channel.
+    agent.invoke_async(context.prompt) do |agent_event|
+      workflow_event =
+        case agent_event.type
+        when :done
+          :generation_completed
+        when :error, :timeout, :cancelled, :approval_required
+          :generation_failed
+        end
+      next unless workflow_event
+
+      workflow.signal(
+        thread_id: context.thread_id,
+        event: workflow_event,
+        payload: {
+          generation_request_id: request_id,
+          agent_result: (
+            agent_event.payload if agent_event.type == :done
+          ),
+          error:
+            agent_event.payload[:error] ||
+            Phronomy::Error.new(
+              "Agent requested Tool approval"
+            )
+        }
+      )
+    end
 
     context
   }

data/lib/phronomy/agent/async_event_api.rb

@@ -5,7 +5,15 @@ module Phronomy
     # Public Agent execution API. Agent instances are always stateful and all
     # operations are coordinated through Phronomy::Persistence.
     module AsyncEventApi
-      def invoke(input, thread_id: nil, config: {}, invocation_context: nil, on_event: nil)
+      def invoke(
+        input,
+        thread_id: nil,
+        config: {},
+        invocation_context: nil,
+        on_event: nil,
+        &block
+      )
+        listener = resolve_event_listener(on_event, block)
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
@@ -15,7 +23,7 @@ module Phronomy
             input,
             thread_id: thread_id,
             config: config,
-            on_event: on_event
+            on_event: listener
           ).wait_result
           [result, result[:usage]]
         end
@@ -27,8 +35,10 @@ module Phronomy
         config: {},
         invocation_context: nil,
         on_tool_approval_required: nil,
-        on_event: nil
+        on_event: nil,
+        &block
       )
+        listener = resolve_event_listener(on_event, block)
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
@@ -40,7 +50,7 @@ module Phronomy
           mode: :invoke,
           approval_policy: approval[:policy],
           approval_listener: approval[:listener],
-          on_event: on_event
+          on_event: listener
         )
       end
 

data/lib/phronomy/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Raizo T.C.S