little_ghost 0.2.1 → 0.4.0

data/lib/little_ghost/workflow.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
+require_relative "assembly"
+
 module LittleGhost
-  # Build agentic workflows with ordinary Ruby branching and local variables.
-  # A workflow composes several agents, consumes intermediate answers, and
-  # streams one final agent response.
+  # Coordinates Assembly participants with ordinary Ruby control flow.
+  #
+  # A workflow is an Assembly whose +perform+ method controls ordering,
+  # branching, parallel work, and local variables. Each participant may be an
+  # Agent or another coordinated Assembly. The workflow consumes intermediate
+  # answers and streams one final participant response.
   #
-  # A support workflow can route a difficult request through research before the
-  # responder writes the caller-visible answer:
+  # A support workflow can guarantee that research happens before the responder
+  # writes the caller-visible answer:
   #
   #   class ResponseWorkflow < LittleGhost::Workflow
   #     private
   #
   #     def perform
-  #       route = invoke(RouterAgent).output
-  #       return invoke(CustomerSupportAgent) unless route["research"]
-  #
   #       evidence = invoke(ResearchAgent).output
   #       invoke CustomerSupportAgent, input: <<~PROMPT
   #         #{input.text}
@@ -25,42 +27,45 @@ module LittleGhost
   #     end
   #   end
   #
-  #   run = runtime.build_run(
-  #     {message: "Why is transfer 481 pending?"},
-  #     agent_class: CustomerSupportAgent,
-  #     entrypoint_class: ResponseWorkflow
-  #   ).call
-  #   run.response # => "Transfer 481 is waiting for the receiving bank."
+  #   run = ResponseWorkflow.ask("Why is transfer 481 pending?")
+  #   run.response
+  #   # One possible response: Transfer 481 is waiting for the receiving bank.
+  #
+  # Call a named Workflow with
+  # ask[rdoc-ref:LittleGhost::Assembly.ask] for its final Run, or
+  # the streaming entrypoint[rdoc-ref:LittleGhost::Assembly.stream_ask] for live
+  # events.
   #
   # +invoke+ returns a lazy Workflow::Invocation. Reading +output+ consumes an
   # intermediate invocation and returns RunResult#output; +perform+ must return
   # its final invocation without consuming it so those events reach the caller.
   # Intermediate usage is added to the final result.
   #
-  # Every child inherits input, history, settings, cancellation, deadline,
-  # template paths, and trace parentage unless +invoke+ overrides its input.
-  # JSON-like context is copied for each child, preventing one intermediate agent
-  # from mutating a sibling's state. Non-JSON-like workflow context raises
-  # ArgumentError.
+  # A child receives the Workflow input unless +invoke+ supplies another one.
+  # It also inherits history, settings, cancellation, deadline, template paths,
+  # and the parent tracing relationship. JSON-like context is copied for each
+  # child, preventing one intermediate Agent from mutating a sibling's state.
+  # Non-JSON-like workflow context raises ArgumentError.
   #
-  # A workflow instance streams once. Returning the wrong value, returning an
-  # already consumed invocation, or consuming an invocation twice raises
-  # ProtocolError. Built agents close in reverse order, and the first cleanup
-  # failure is re-raised after every invocation has been given a chance to close.
-  # Composition errors emit an +invocation_error+ event and then re-raise.
-  class Workflow
-    # Hold one lazy agent call inside a workflow composition.
+  # A Workflow instance streams once. Returning the wrong value, returning an
+  # already consumed invocation, or consuming one twice raises ProtocolError.
+  # A composition error fails the owning top-level Run. Each child Assembly
+  # closes after its attempt, and a cleanup failure raises from that attempt.
+  class Workflow < Assembly
+    # Hold one lazy Assembly call inside a workflow composition.
     # Workflow implementations normally use only its output method or return the
     # object as the final invocation.
     class Invocation
       attr_reader :result # :nodoc:
 
-      def initialize(input:, history:, context:, build:, on_usage:) # :nodoc:
+      def initialize(reference:, participant:, input:, history:, context:, policies:, owner:) # :nodoc:
+        @reference = reference
+        @participant = participant
         @input = input
         @history = history
         @context = context
-        @build = build
-        @on_usage = on_usage
+        @policies = policies
+        @owner = owner
         @mutex = Mutex.new
         @consumed = false
         @closed = false
@@ -69,30 +74,29 @@ module LittleGhost
       def each(checkpoint: nil) # :nodoc:
         return enum_for(__method__, checkpoint:) unless block_given?
 
-        agent, options = @mutex.synchronize do
+        @mutex.synchronize do
           raise Error, "workflow invocation is already closed" if @closed
           raise ProtocolError, "workflow invocation was already consumed" if @consumed
 
           @consumed = true
-          @agent, options = @build.call
-          [@agent, options]
         end
-        begin
-          agent.stream(
-            @input,
-            history: @history,
-            context: @context,
-            **options,
-            checkpoint:
-          ).each do |event|
-            @result = event.data[:result] if event.type == :invocation_stop
-            @usage = event.data[:usage] if event.type == :invocation_error
-            yield event
-          end
-        ensure
-          report_usage if @intermediate
-          close
+        execution = @owner.send(
+          :execute_workflow_invocation,
+          reference: @reference,
+          participant: @participant,
+          input: @input,
+          history: @history,
+          context: @context,
+          policies: @policies,
+          checkpoint:
+        ) { |event| yield event }
+        @result = execution.result
+        @step = execution.step
+        @steps = execution.result.steps
+        execution.events.each do |event|
+          yield event
         end
+        @result
       end
 
       # Consumes this invocation when necessary and returns RunResult#output.
@@ -101,7 +105,12 @@ module LittleGhost
       # response text. Intermediate usage is recorded for the workflow total.
       def output
         @intermediate = true
-        each {} unless consumed?
+        unless consumed?
+          each do |event|
+            @owner.send(:emit_workflow_event, event) if event.type.to_s.start_with?("assembly_")
+          end
+          @owner.send(:record_workflow_steps, @steps)
+        end
         result&.output
       end
 
@@ -110,29 +119,21 @@ module LittleGhost
       end
 
       def close # :nodoc:
-        agent = @mutex.synchronize do
+        @mutex.synchronize do
           return if @closed
 
           @closed = true
-          @agent
         end
-        agent&.close
-      end
-
-      private
-
-      def report_usage
-        usage = result&.usage || @usage
-        @on_usage.call(usage) if usage
       end
     end
 
-    # Owning run and the runtime used to resolve workflow agents.
-    attr_reader :run, :runtime
+    # Run that owns this run-scoped Workflow.
+    attr_reader :run
+    # Runtime used to resolve child Assemblies.
+    attr_reader :runtime
 
-    def initialize(run:, runtime: run.runtime) # :nodoc:
-      @run = run
-      @runtime = runtime
+    def initialize(run: nil, runtime: nil) # :nodoc:
+      super(run:, runtime:, standalone: run.nil?)
       @mutex = Mutex.new
       @closed = false
       @started = false
@@ -162,6 +163,17 @@ module LittleGhost
     )
       raise ArgumentError, "input is required" if input.nil?
 
+      if standalone?
+        return build_run(entrypoint_payload(input, {
+          history:,
+          context:,
+          settings:,
+          template_paths:,
+          deadline_at: deadline,
+          cancellation_token:
+        }.compact)).each
+      end
+
       @mutex.synchronize do
         raise Error, "workflow is already closed" if @closed
         raise Error, "workflow instances can only be streamed once" if @started
@@ -178,11 +190,14 @@ module LittleGhost
         @parent_operation_id = parent_operation_id
         @checkpoint = checkpoint
         @intermediate_usage = Usage.new
+        @workflow_steps = []
+        @workflow_events = nil
       end
 
       Enumerator.new do |events|
         error_emitted = false
         observed_usage = nil
+        @workflow_events = events
         ensure_open!
         final_invocation = perform
         unless final_invocation.is_a?(Invocation) && !final_invocation.consumed?
@@ -197,6 +212,8 @@ module LittleGhost
             event.data.fetch(:result).usage
           when :invocation_error
             event.data[:usage] || observed_usage
+          when :assembly_step_error
+            event.data[:usage] || observed_usage
           else
             observed_usage
           end
@@ -212,10 +229,12 @@ module LittleGhost
           )
         end
         raise
+      ensure
+        @workflow_events = nil
       end
     end
 
-    # Closes all built agent invocations in reverse order.
+    # Closes all declared invocations in reverse order.
     #
     # The operation is idempotent, attempts every close, and raises the first
     # cleanup failure.
@@ -250,35 +269,32 @@ module LittleGhost
     end
 
     # :doc:
-    # Creates a lazy invocation for +agent_class_or_name+.
+    # Creates a lazy invocation for +assembly+.
     #
     # Intermediate calls may use +output+; the final call must be returned from
-    # +perform+ without being consumed.
-    def invoke(agent_class_or_name, input: self.input, history: self.history, context: self.context)
+    # +perform+ without being consumed. +as+ supplies the participant name used
+    # in steps and telemetry. Retries default to zero; a positive +retries+
+    # value requires explicit exception classes in +retry_on+.
+    def invoke(
+      assembly,
+      as: nil,
+      input: self.input,
+      history: self.history,
+      context: self.context,
+      timeout: nil,
+      retries: 0,
+      retry_on: nil,
+      retry_delay: 0
+    )
+      participant = as || assembly_identity(assembly)
       invocation = Invocation.new(
+        reference: assembly,
+        participant:,
         input:,
         history:,
         context: isolated_state(context),
-        build: lambda {
-          agent = runtime.build_agent(agent_class_or_name, run:)
-          begin
-            [
-              agent,
-              {
-                cancellation_token: @cancellation_token,
-                deadline: @deadline,
-                settings: @settings,
-                template_locals: template_locals_for(agent),
-                template_paths: @template_paths,
-                parent_operation_id: @parent_operation_id
-              }
-            ]
-          rescue
-            agent.close
-            raise
-          end
-        },
-        on_usage: ->(usage) { record_intermediate_usage(usage) }
+        policies: {timeout:, retries:, retry_on:, retry_delay:},
+        owner: self
       )
       @mutex.synchronize do
         raise Error, "workflow is already closed" if @closed
@@ -288,8 +304,116 @@ module LittleGhost
       invocation
     end
 
-    def record_intermediate_usage(usage)
-      @mutex.synchronize { @intermediate_usage += usage }
+    # :doc:
+    # Consumes independent invocations concurrently and returns their outputs in
+    # declaration order.
+    #
+    # +max_concurrency+ bounds active child executions. A child failure cancels
+    # siblings cooperatively before the error is raised.
+    def parallel(*invocations, max_concurrency: 8)
+      raise ArgumentError, "parallel requires at least one invocation" if invocations.empty?
+      unless invocations.all? { |invocation| invocation.is_a?(Invocation) && !invocation.consumed? }
+        raise ArgumentError, "parallel accepts unconsumed workflow invocations"
+      end
+
+      token = @cancellation_token.child
+      queue = SizedQueue.new(1_000)
+      worker = Thread.new do
+        results = Support::Executor.new(max_concurrency:).map(
+          invocations,
+          cancellation_token: token,
+          on_result: ->(_index, execution) { record_workflow_steps(execution.fetch(:steps)) }
+        ) do |invocation|
+          invocation.each do |event|
+            if event.type.to_s.start_with?("assembly_")
+              enqueue_assembly_event(queue, [:event, event], token)
+            end
+          end
+          {output: invocation.result&.output, steps: invocation.instance_variable_get(:@steps)}
+        end
+        enqueue_assembly_event(queue, [:done, results], token)
+      rescue => error
+        token.cancel
+        enqueue_assembly_terminal(queue, [:error, error])
+      end
+      executions = loop do
+        type, value = queue.pop
+        emit_workflow_event(value) if type == :event
+        raise value if type == :error
+        break value if type == :done
+      end
+      executions.map { |execution| execution.fetch(:output) }
+    ensure
+      token&.cancel
+      worker&.join
+    end
+
+    def execute_workflow_invocation(reference:, participant:, input:, history:, context:, policies:, checkpoint:)
+      step_id = SecureRandom.uuid
+      predecessor_id = @mutex.synchronize do
+        @workflow_steps.reverse.find { |step| step.parent_id.nil? }&.id
+      end
+      yield StreamEvent.build(
+        :assembly_step_start,
+        assembly_id: self.class.assembly_id,
+        assembly_kind: :workflow,
+        participant: participant.to_s,
+        step_id:
+      )
+      execution = execute_assembly_step(
+        reference:,
+        participant:,
+        input:,
+        history:,
+        context:,
+        cancellation_token: @cancellation_token,
+        deadline: @deadline,
+        settings: @settings,
+        template_locals: @template_locals,
+        template_paths: @template_paths,
+        parent_operation_id: @parent_operation_id,
+        policies:,
+        predecessor_ids: Array(predecessor_id),
+        checkpoint:,
+        step_id:
+      ) { |event| yield event }
+      yield StreamEvent.build(
+        :assembly_step_stop,
+        assembly_id: self.class.assembly_id,
+        assembly_kind: :workflow,
+        participant: participant.to_s,
+        step_id: execution.step.id,
+        usage: execution.step.usage
+      )
+      execution
+    end
+
+    def record_workflow_steps(steps)
+      @mutex.synchronize do
+        @workflow_steps.concat(steps)
+        @intermediate_usage += steps.first.usage
+      end
+    end
+
+    def emit_workflow_event(event)
+      sink = @mutex.synchronize do
+        if event.type == :assembly_step_error && event.data[:terminal] && event.data[:usage]
+          @intermediate_usage += event.data.fetch(:usage)
+        end
+        @workflow_events
+      end
+      sink << event if sink
+    end
+
+    def assembly_identity(reference)
+      case reference
+      when AssemblyBuilder, AssemblyDefinition
+        reference.assembly_id
+      when Class
+        (reference <= Assembly) ? reference.assembly_id : reference.to_s
+      else
+        reference.to_s
+      end
     end
 
     def aggregate_usage(event)
@@ -302,13 +426,19 @@ module LittleGhost
           usage: workflow_usage + result.usage,
           messages: result.messages,
           state: result.state,
-          structured_result: result.structured_result
+          structured_result: result.structured_result,
+          steps: workflow_steps + result.steps
         )
         StreamEvent.build(event.type, **event.data.merge(result: combined))
       when :invocation_error
         usage = event.data[:usage]
         return event unless usage
 
+        StreamEvent.build(event.type, **event.data.merge(usage: workflow_usage + usage))
+      when :assembly_step_error
+        usage = event.data[:usage]
+        return event unless usage
+
         StreamEvent.build(event.type, **event.data.merge(usage: workflow_usage + usage))
       else
         event
@@ -338,6 +468,10 @@ module LittleGhost
       @mutex.synchronize { @intermediate_usage }
     end
 
+    def workflow_steps
+      @mutex.synchronize { @workflow_steps.dup.freeze }
+    end
+
     def ensure_open!
       @mutex.synchronize { raise Error, "workflow is already closed" if @closed }
     end

data/lib/little_ghost.rb

@@ -4,6 +4,7 @@ require_relative "little_ghost/version"
 require_relative "little_ghost/errors"
 require_relative "little_ghost/execution_state"
 require_relative "little_ghost/support"
+require_relative "little_ghost/data_map"
 require_relative "little_ghost/events"
 require_relative "little_ghost/instrumentation"
 require_relative "little_ghost/tracing/open_telemetry"
@@ -50,52 +51,53 @@ require_relative "little_ghost/structured_output"
 require_relative "little_ghost/prompt_resolver"
 require_relative "little_ghost/session_store"
 require_relative "little_ghost/session_stores/memory"
+require_relative "little_ghost/session_stores/filesystem"
 require_relative "little_ghost/session"
 require_relative "little_ghost/skills"
 require_relative "little_ghost/tools/write_todos"
 require_relative "little_ghost/run"
+require_relative "little_ghost/execution"
 require_relative "little_ghost/subagents/definition"
 require_relative "little_ghost/subagents/agent_path"
 require_relative "little_ghost/subagents/manager"
-require_relative "little_ghost/agent_interruptions"
+require_relative "little_ghost/agent_interjections"
+require_relative "little_ghost/assembly"
+require_relative "little_ghost/assembly_execution"
 require_relative "little_ghost/agent"
-require_relative "little_ghost/agent_builder"
 require_relative "little_ghost/workflow"
+require_relative "little_ghost/swarm"
+require_relative "little_ghost/graph"
+require_relative "little_ghost/assembly_builder"
+require_relative "little_ghost/agent_factory"
 require_relative "little_ghost/runtime/hook"
 require_relative "little_ghost/runtime"
 
-# Build AI features with reusable agents and agentic workflows. LittleGhost can
-# sit inside an existing Ruby system or support a dedicated AI service, keeping
-# models, prompts, tools, sessions, streaming, and instrumentation behind a
-# cohesive set of Ruby conventions.
+# LittleGhost is a Ruby library for building AI features with reusable agents
+# and composable assemblies. It can sit inside an existing Ruby system or
+# support a dedicated AI service.
 #
-# A customer support agent can answer directly, use an application tool, or ask a
-# specialist for research while the caller observes one run:
-#
-#   class ResearchAgent < LittleGhost::Agent
-#     description "Researches difficult support questions"
-#     model "openai:gpt-5.6-luna"
-#   end
+# Start with one model-driven behavior:
 #
 #   class CustomerSupportAgent < LittleGhost::Agent
 #     description "Handles support requests"
-#     model "openai:gpt-5.6-luna"
-#     tools AccountTool
-#     subagent ResearchAgent, kind: "research"
+#     model "openrouter:openai/gpt-5.6-luna"
+#     system_prompt "Answer customer questions clearly."
 #   end
 #
 #   run = CustomerSupportAgent.ask("Why is transfer 481 still pending?")
 #   run.completed? # => true
-#   run.response   # => "Transfer 481 is waiting for the receiving bank."
+#   run.response
+#   # One possible response: Transfer 481 is waiting for the receiving bank.
 #
-# Agent subclasses hold reusable behavior; Invocation objects carry one request,
-# and Run objects own execution and cleanup. Workflow subclasses can compose
-# several agents when ordinary Ruby branching is clearer than one agent loop.
+# Agent subclasses hold reusable behavior, Invocation objects carry one request,
+# and Run objects own execution and cleanup. When one model loop is not enough,
+# Assembly gives Agent, Workflow, Swarm, and Graph the same caller interface
+# while each type owns a different coordination policy.
 #
 # LittleGhost.configuration is process-wide unless LittleGhost.with_configuration
-# supplies an execution-scoped replacement. Configuration is loaded lazily and
-# snapshotted into a Runtime, so make application changes before the first agent
-# runtime is built.
+# supplies an execution-scoped replacement. The first standalone call lazily
+# builds one shared Runtime from that configuration, so make application changes
+# before invoking an Agent or Assembly.
 module LittleGhost
   class << self
     # The configuration active in the current execution context, falling back to
@@ -107,15 +109,24 @@ module LittleGhost
     # Opens the active Configuration for application setup and returns it.
     #
     # Configuration files are loaded lazily when a runtime is first built, so
-    # make application-level changes before invoking an agent.
+    # make application-level changes before invoking an agent. Once the shared
+    # Runtime is ready, later mutations raise ConfigurationError.
     def configure(&block)
       configuration.configure(&block)
     end
 
+    # Returns the shared Runtime for the active Configuration.
+    #
+    # Most applications do not need to call this method. Standalone Agent and
+    # Assembly entrypoints use it automatically. Runtime construction is lazy,
+    # thread-safe, and locks the active Configuration after it succeeds.
+    def runtime = configuration.runtime
+
     # Returns the model resolver owned by the active process configuration.
     def model_resolver = configuration.model_resolver
 
-    # Makes +configuration+ current only while the block runs.
+    # Makes +configuration+ and its independent shared Runtime current only
+    # while the block runs.
     #
     # Execution state restores the previous configuration even when the block
     # raises. Other execution contexts continue to see their own configuration.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: little_ghost
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Matt Robinson
@@ -107,8 +107,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.9'
-description: Add agents, tools, and agentic workflows to existing Ruby systems or
-  dedicated AI services.
+description: Add agents, tools, workflows, swarms, and graphs to existing Ruby systems
+  or dedicated AI services.
 email:
 - robinson.matty@gmail.com
 executables: []
@@ -117,8 +117,11 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- docs/guides/assemblies.md
 - docs/guides/core_concepts.md
 - docs/guides/getting_started.md
+- docs/guides/production.md
+- docs/guides/prompt_views.md
 - lib/little_ghost.rb
 - lib/little_ghost/ag_ui.rb
 - lib/little_ghost/ag_ui/adapter.rb
@@ -128,13 +131,20 @@ files:
 - lib/little_ghost/agent/skills.rb
 - lib/little_ghost/agent/tool_loop.rb
 - lib/little_ghost/agent_builder.rb
-- lib/little_ghost/agent_interruptions.rb
+- lib/little_ghost/agent_factory.rb
+- lib/little_ghost/agent_interjections.rb
+- lib/little_ghost/assembly.rb
+- lib/little_ghost/assembly_builder.rb
+- lib/little_ghost/assembly_execution.rb
 - lib/little_ghost/configuration.rb
 - lib/little_ghost/content.rb
 - lib/little_ghost/data/model_catalog.json
+- lib/little_ghost/data_map.rb
 - lib/little_ghost/errors.rb
 - lib/little_ghost/events.rb
+- lib/little_ghost/execution.rb
 - lib/little_ghost/execution_state.rb
+- lib/little_ghost/graph.rb
 - lib/little_ghost/instrumentation.rb
 - lib/little_ghost/invocation.rb
 - lib/little_ghost/lookup.rb
@@ -182,6 +192,7 @@ files:
 - lib/little_ghost/session.rb
 - lib/little_ghost/session_store.rb
 - lib/little_ghost/session_stores/agent_core_memory.rb
+- lib/little_ghost/session_stores/filesystem.rb
 - lib/little_ghost/session_stores/memory.rb
 - lib/little_ghost/skills.rb
 - lib/little_ghost/skills/catalog.rb
@@ -203,6 +214,7 @@ files:
 - lib/little_ghost/support/output_truncation.rb
 - lib/little_ghost/support/redactor.rb
 - lib/little_ghost/support/sse_parser.rb
+- lib/little_ghost/swarm.rb
 - lib/little_ghost/tool.rb
 - lib/little_ghost/tool_execution.rb
 - lib/little_ghost/tool_registry.rb
@@ -242,5 +254,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.10
 specification_version: 4
-summary: A Ruby framework for AI features with agents and agentic workflows
+summary: A Ruby framework for AI features with agents and composable assemblies
 test_files: []