autoflux 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4057f638e916ef5cca2980912c4daf1b0928cc929766156f7859ae93d2a596f6
-  data.tar.gz: a71fc9aaa77da24cb1c4dd9ea7dcd46b7386d640aaef737eb143d960bd1183c7
+  metadata.gz: bfba17b715db371a3388379b0d894f1cd7e02e5ddec7dc9e30545b009037195e
+  data.tar.gz: 768d96e08f58eac4516c03b6fb1ae13a6c4939ffa47702fa57de3c45cff8a831
 SHA512:
-  metadata.gz: 59926823b4d02b924f919f63df286be8e912e3a13921e8033ba7db333d21ff95ad0f5e4be669f604bf1bfea6c9c3ec90f4c2844375ad768c05dd835b9c9df2c6
-  data.tar.gz: 5ab23c20f3a229f5cc864b4814a08d8a25d3e38de97ef04c41ba77470c97ca0a9b1b297caaf86f8b01a54ef67ae69524d6b2deef91b10eb397b935879dc322ca
+  metadata.gz: fe2ee26a057d023a378eee32fead552d45312724a1a59b4dcf1a6681cef889ffda78030fcafac5b98ee41ae2c4a4d3b24d859fa1682aac86595ed82e58759226
+  data.tar.gz: dd3461bdffb1f07be326962f43b3ee661e901881eaea3a71c0225bb55047c559e13a5e62743e4426751a36af3447fdcf4084cddd238f155ce4529060f619802a

data/README.md

@@ -57,82 +57,110 @@ When receive "exit" from the user, the workflow transition to the stop state.
 
 ### Agent
 
-The agent is an adapter to the LLM model. You can inherit the `Autoflux::Agent` class to implement your own agent.
+The agent is an adapter to the LLM model.
 
 ```ruby
 # :nodoc:
-class OpenAIAgent < Autoflux::Agent
+class OpenAIAgent
   attr_reader :client, :model
 
-  def initialize(client:, tools: [], model: 'gpt-4o-mini')
+  def initialize(client:, model: 'gpt-4o-mini')
     super(tools: tools)
     @client = client
     @model = model
   end
 
   def call(memory:)
-    client.chat(
+    msg = client.chat(
       parameters: {
         model: model,
-        messages: memory.data,
-        tools: tools
+        messages: memory.data.map { |event| convert_message(event) },
       }
     ).dig('choices', 0, 'message')
+
+    convert_event(msg)
   end
 
-  def tools
-    @tools ||= @_tools.map do |tool|
-      {
-        type: :function,
-        function: {
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.parameters
-        }
-      }
+  # If allow to use the tool, return tool object implements `Autoflux::_Tool` interface
+  def tools?(name) = false
+  def tool(name) = nil
+
+  # Autoflux use a generic event object to represent the message, you have to convert it to the model's format
+  def convert_message(event)
+    {
+      role: event[:role],
+      content: event[:content]
+    }.tap do |evt|
+      evt[:tool_calls] = event[:invocations]&.map { |invocation| convert_tool_call(invocation) }
+      evt[:tool_call_id] = event[:invocation_id] if event[:invocation_id]
     end
   end
+
+  def convert_tool_call(invocation)
+    {
+      type: :function,
+      id: invocation[:id],
+      function: {
+        name: invocation[:name],
+        arguments: invocation[:args]
+      }
+    }
+  end
+
+  def convert_event(msg) # rubocop:disable Metrics/MethodLength
+    {
+      role: msg['role'],
+      content: msg['content'],
+      invocations: msg['tool_calls']&.map do |call|
+        {
+          id: call['id'],
+          name: call.dig('function', 'name'),
+          args: call.dig('function', 'arguments')
+        }
+      end
+    }
+  end
 end
 ```
 
-The memory is chat history which keep in the workflow. You can decide to use it or not.
+The memory is history which keep in the workflow. You can decide to use it or not.
 
 ### Tool
 
-The tool is a function that can be used in the agent's response. You can inherit the `Autoflux::Tool` class to implement your own tool.
+The tool is a function that can be used in the agent's response.
 
 ```ruby
 # :nodoc:
-class AddToCartTool < Autoflux::Tool
+class AddToCartTool
+  attr_reader :name, :description, :parameters
+
   def initialize # rubocop:disable Metrics/MethodLength
-    super(
-      name: 'add_to_cart',
-      description: 'Add the product to the cart',
-      parameters: {
-        type: 'object',
-        properties: {
-          name: { type: 'string', description: 'The name of the product' },
-          quantity: { type: 'number', description: 'The quantity of the product' }
-        }
+    @name = 'add_to_cart'
+    @description = 'Add the product to the cart'
+    @parameters = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'The name of the product' },
+        quantity: { type: 'number', description: 'The quantity of the product' }
       }
-    )
+    }
   end
 
-  def call(name:, quantity:, **)
-    { success: true, content: "Added #{quantity} #{name} to the cart" }
+  def call(workflow:, params:)
+    { success: true, content: "Added #{params[:quantity]} #{params[:name]} to the cart" }
   end
 end
 ```
 
-The tool is require the name and description. The parameters is optional.
+> You can define how to tell the agent to use the tool by adding `name` and `description` to the tool.
 
 ### IO
 
-The IO is an adapter to the input and output. You can inherit the `Autoflux::IO` class to implement your own IO.
+The IO is an adapter to the input and output.
 
 ```ruby
 # :nodoc:
-class ConsoleIO < Autoflux::IO
+class ConsoleIO
   def read
     print 'User: '
     gets.chomp
@@ -147,6 +175,8 @@ end
 The default `Autoflux::Stdio` implement the minimal Standard I/O support.
 
 ```ruby
+require 'autoflux/stdio'
+
 workflow = Autoflux::Workflow.new(
     agent: agent,
     io: Autoflux::Stdio.new(prompt: '> ')

data/lib/autoflux/memory.rb

@@ -15,9 +15,9 @@ module Autoflux
     # Push the data to the memory.
     #
     # @rbs data: Hash
-    def push(data)
-      puts JSON.pretty_generate(data) if verbose
-      @data.push(data)
+    def push(event)
+      puts JSON.pretty_generate(event) if verbose
+      @data.push(event)
     end
 
     # Get the last data from the memory.

data/lib/autoflux/stdio.rb

@@ -2,14 +2,12 @@
 
 module Autoflux
   # The Stdio is a class to represent the standard input/output.
-  class Stdio < IO
+  class Stdio
     attr_accessor :prompt
 
     # @rbs input: IO
     # @rbs output: IO
     def initialize(input: $stdin, output: $stdout, prompt: nil)
-      super()
-
       @input = input
       @output = output
       @prompt = prompt
@@ -18,12 +16,12 @@ module Autoflux
 
     def read
       print prompt if prompt
-      @input.gets.chomp
+      @input.gets&.chomp
     end
 
     # @rbs data: String
     def write(data)
-      @output.puts(data)
+      @output.puts(data) if data
     end
   end
 end

data/lib/autoflux/step/assistant.rb

@@ -3,15 +3,19 @@
 module Autoflux
   module Step
     # The Assistant state is used to call the agent.
-    class Assistant < Base
-      OUTPUT_ROLE_NAME = "assistant"
+    class Assistant
+      def to_s = self.class.name || "Assistant"
 
       def call(workflow:)
-        res = workflow.agent.call(memory: workflow.memory)
-        workflow.memory.push(res)
-        return Tool.new if res["tool_calls"]&.any?
+        event = workflow.agent.call(memory: workflow.memory)
+        workflow.memory.push(event)
 
-        workflow.io.write(res["content"]) if res["role"] == OUTPUT_ROLE_NAME
+        # @type var invocation_event: Autoflux::invocationEvent
+        invocation_event = event
+        return Tool.new if invocation_event[:invocations]&.any?
+
+        # @type var event: Autoflux::textEvent
+        workflow.io.write(event[:content]) if event[:role] == ROLE_ASSISTANT
 
         Command.new
       end

data/lib/autoflux/step/command.rb

@@ -3,14 +3,19 @@
 module Autoflux
   module Step
     # The Command step is used to get the user input.
-    class Command < Base
+    class Command
       EXIT_COMMAND = "exit"
 
+      def to_s = self.class.name || "Command"
+
       def call(workflow:)
         input = workflow.io.read
+        return Stop.new if input.nil?
         return Stop.new if input == EXIT_COMMAND
 
-        workflow.memory.push(role: :user, content: input)
+        # @type var event: Autoflux::event
+        event = { role: ROLE_USER, content: input }
+        workflow.memory.push(event)
         Assistant.new
       end
     end

data/lib/autoflux/step/start.rb

@@ -3,7 +3,8 @@
 module Autoflux
   module Step
     # The Start step is used to start the workflow.
-    class Start < Base
+    class Start
+      def to_s = self.class.name || "Start"
       def call(**) = Command.new
     end
   end

data/lib/autoflux/step/stop.rb

@@ -3,7 +3,8 @@
 module Autoflux
   module Step
     # The Stop step is used to stop the workflow.
-    class Stop < Base
+    class Stop
+      def to_s = self.class.name || "Stop"
       def call(**) = nil
     end
   end

data/lib/autoflux/step/tool.rb

@@ -3,14 +3,21 @@
 module Autoflux
   module Step
     # The Tool state is used to call the tools provided by the agent.
-    class Tool < Base
+    class Tool
+      def to_s = self.class.name || "Tool"
+
       def call(workflow:)
-        workflow.memory.last["tool_calls"]&.each do |tool|
-          workflow.memory.push(
-            role: :tool,
-            content: run(workflow: workflow, tool: tool).to_json,
-            tool_call_id: tool["id"]
-          )
+        # @type var event: Autoflux::invocationEvent
+        event = workflow.memory.last
+        event[:invocations]&.each do |invocation|
+          # @type: var invocation: Autoflux::invocation
+          # @type: var event: Autoflux::invocationResultEvent
+          event = {
+            role: ROLE_TOOL,
+            content: run(workflow: workflow, invocation: invocation).to_json,
+            invocation_id: invocation[:id]
+          }
+          workflow.memory.push(event)
         end
 
         Assistant.new
@@ -18,12 +25,12 @@ module Autoflux
 
       protected
 
-      def run(workflow:, tool:)
-        name = tool.dig("function", "name")
-        params = JSON.parse(tool.dig("function", "arguments"), symbolize_names: true)
+      def run(workflow:, invocation:)
+        name = invocation[:name]
+        params = JSON.parse(invocation[:args], symbolize_names: true)
         return { status: "error", message: "Tool not found" } unless workflow.agent.tool?(name)
 
-        workflow.agent.tool(name).call(**params) # steep:ignore
+        workflow.agent.tool(name)&.call(workflow: workflow, params: params)
       rescue JSON::ParserError
         { status: "error", message: "Invalid arguments" }
       end

data/lib/autoflux/step.rb

@@ -3,7 +3,6 @@
 module Autoflux
   # The Step means a state in the workflow
   module Step
-    require "autoflux/step/base"
     require "autoflux/step/start"
     require "autoflux/step/stop"
     require "autoflux/step/command"

data/lib/autoflux/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Autoflux
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/autoflux/workflow.rb

@@ -16,6 +16,8 @@ module Autoflux
       end
     end
 
+    include Enumerable
+
     attr_reader :id, :agent, :memory, :io
 
     # @rbs state: State
@@ -27,12 +29,27 @@ module Autoflux
       @memory = memory
     end
 
+    def each
+      return to_enum(:each) unless block_given?
+
+      yield self
+      while @step
+        @step = step.call(workflow: self)
+        yield self if @step
+      end
+    end
+
     # Run the workflow.
     #
     # @rbs system_prompt: String?
-    def run(system_prompt: nil)
-      memory.push(role: :system, content: system_prompt) unless system_prompt.nil?
-      @step = step.call(workflow: self) while @step
+    def run(system_prompt: nil, &block)
+      if system_prompt
+        # @type var event: Autoflux::event
+        event = { role: ROLE_SYSTEM, content: system_prompt }
+        memory.push(event)
+      end
+
+      each(&block || ->(_workflow) {})
     end
 
     # Stop the workflow.
@@ -51,7 +68,7 @@ module Autoflux
     def to_h
       {
         id: id,
-        step: step.name
+        step: step.to_s
       }
     end
   end

data/lib/autoflux.rb

@@ -6,9 +6,11 @@ require_relative "autoflux/version"
 module Autoflux
   class Error < StandardError; end
 
-  require_relative "autoflux/tool"
-  require_relative "autoflux/agent"
-  require_relative "autoflux/io"
+  ROLE_SYSTEM = "system"
+  ROLE_ASSISTANT = "assistant"
+  ROLE_TOOL = "tool"
+  ROLE_USER = "user"
+
   require_relative "autoflux/memory"
   require_relative "autoflux/step"
   require_relative "autoflux/workflow"

data/sig/autoflux/agent.rbs

@@ -3,14 +3,6 @@ module Autoflux
   interface _Agent
     def tool?: (String name) -> bool
     def tool: (String name) -> _Tool?
-    def call: (memory: _Memory) -> untyped
-  end
-
-  # The Agent is a abstract class to represent the adapter of the Language Model.
-  class Agent
-    include _Agent
-
-    @_tools: Array[_Tool]
-    def initialize: (?tools: Array[_Tool]?) -> void
+    def call: (memory: _Memory) -> event
   end
 end

data/sig/autoflux/event.rbs

@@ -0,0 +1,27 @@
+module Autoflux
+  type jsonString = String
+
+  type invocation = {
+    id: String,
+    name: String,
+    args: jsonString
+  }
+
+  type eventRole = "assistant" | "system" | "user" | "tool" | String
+  type baseEvent = {
+    role: eventRole,
+    agent_id?: String,
+    raw?: Hash[untyped, untyped]
+  }
+  type textEvent = baseEvent & {
+    content: String
+  }
+  type invocationEvent = baseEvent & {
+    invocations: Array[invocation]
+  }
+  type invocationResultEvent = textEvent & {
+    invocation_id: String
+  }
+
+  type event = textEvent | invocationEvent | invocationResultEvent
+end

data/sig/autoflux/io.rbs

@@ -1,11 +1,6 @@
 module Autoflux
   interface _IO
-    def read: () -> String
-    def write: (String data) -> String
-  end
-
-  # The IO is abstract class to represent the interface of the IO
-  class IO
-    include _IO
+    def read: () -> String?
+    def write: (String? data) -> untyped
   end
 end

data/sig/autoflux/memory.rbs

@@ -1,20 +1,20 @@
 module Autoflux
   interface _Memory
-    def data: () -> Array[untyped]
-    def push: (untyped data) -> untyped
-    def last: () -> untyped
+    def data: () -> Array[event]
+    def push: (event event) -> void
+    def last: () -> event
   end
 
   # The Memory is a class to store the memory of the workflow.
   class Memory
     include _Memory
 
-    @data: Array[untyped]
+    @data: Array[event]
     @verbose: bool
 
     attr_reader verbose: bool
 
     # @rbs data: Array[Hash]
-    def initialize: (?data: Array[untyped], ?verbose: bool) -> void
+    def initialize: (?data: Array[event], ?verbose: bool) -> void
   end
 end

data/sig/autoflux/stdio.rbs

@@ -1,21 +1,14 @@
 module Autoflux
   # The Stdio is a class to represent the standard input/output.
-  class Stdio < IO
-    @input: untyped
+  class Stdio
+    include _IO
 
-    @output: untyped
+    @input: ::IO
+    @output: ::IO
+    @prompt: String?
 
-    @prompt: untyped
+    attr_accessor prompt: String?
 
-    attr_accessor prompt: untyped
-
-    # @rbs input: IO
-    # @rbs output: IO
-    def initialize: (?input: untyped, ?output: untyped, ?prompt: untyped?) -> void
-
-    def read: () -> untyped
-
-    # @rbs data: String
-    def write: (untyped data) -> untyped
+    def initialize: (?input: IO, ?output: IO, ?prompt: String?) -> void
   end
 end

data/sig/autoflux/step.rbs

@@ -1,35 +1,35 @@
 module Autoflux
   interface _Step
-    def name: () -> String
+    def to_s: () -> String
     def call: (workflow: Workflow) -> untyped
   end
 
   module Step
-    # The Step::Base is abstract class to represent the interface of the state
-    class Base
-      include Autoflux::_Step
-    end
-
     # The Start step is used to start the workflow.
-    class Start < Base
+    class Start
+      include Autoflux::_Step
     end
 
     # The Stop step is used to stop the workflow.
-    class Stop < Base
+    class Stop
+      include Autoflux::_Step
     end
 
     # The Assistant state is used to call the agent.
-    class Assistant < Base
+    class Assistant
+      include Autoflux::_Step
       OUTPUT_ROLE_NAME: "assistant"
     end
 
     # The Tool state is used to call the tools provided by the agent.
-    class Tool < Base
-      def run: (workflow: Workflow, tool: untyped) -> untyped
+    class Tool
+      include Autoflux::_Step
+      def run: (workflow: Workflow, invocation: invocation) -> ::_ToJson
     end
 
     # The Command step is used to get the user input.
-    class Command < Base
+    class Command
+      include Autoflux::_Step
       EXIT_COMMAND: "exit"
     end
   end

data/sig/autoflux/tool.rbs

@@ -1,20 +1,5 @@
 module Autoflux
   interface _Tool
-    def name: () -> String
-    def description: () -> String
-    def parameters: () -> untyped
-
-    def call: (**untyped) -> untyped
-  end
-
-  # The Tool is a abstract class to represent the adapter of tools which can be used by the Language Model.
-  class Tool
-    include _Tool
-
-    @name: String
-    @description: String
-    @parameters: untyped
-
-    def initialize: (name: String, description: String, ?parameters: untyped?) -> void
+    def call: (workflow: Workflow, params: untyped) -> untyped
   end
 end

data/sig/autoflux/workflow.rbs

@@ -1,15 +1,14 @@
 module Autoflux
   # The workflow is a state machine to manage the flow of agentic AI.
   class Workflow
+    include Enumerable[Workflow]
+
     @id: String
     @agent: _Agent
     @io: _IO
     @step: _Step
     @memory: _Memory
 
-    # Generate a random UUID.
-    #
-    # @return [String]
     def self.next_id: () -> String
 
     attr_reader id: String
@@ -17,23 +16,11 @@ module Autoflux
     attr_reader memory: _Memory
     attr_reader io: _IO
 
-    # @rbs state: State
     def initialize: (agent: _Agent, io: _IO, ?id: String?, ?step: _Step, ?memory: _Memory) -> void
-
-    # Run the workflow.
-    #
-    # @rbs system_prompt: String?
-    def run: (?system_prompt: String?) -> void
-
-    # Stop the workflow.
+    def each: { (Workflow) -> void } -> void
+    def run: (?system_prompt: String?) ?{ (Workflow) -> void } -> void
     def stop: () -> void
-
-    # Get the current step. If the step is nil, return a Stop step.
     def step: () -> _Step
-
-    # Get the hash representation of the workflow.
-    #
-    # @return [Hash]
     def to_h: () -> { id: String, step: String }
   end
 end

data/sig/autoflux.rbs

@@ -1,6 +1,11 @@
 module Autoflux
   VERSION: String
 
+  ROLE_SYSTEM: eventRole & "system"
+  ROLE_USER: eventRole & "user"
+  ROLE_TOOL: eventRole & "tool"
+  ROLE_ASSISTANT: eventRole & "assistant"
+
   class Error < StandardError
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: autoflux
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Aotokitsuruya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-01-06 00:00:00.000000000 Z
+date: 2025-01-07 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight AI agent framework for Ruby
 email:
@@ -27,24 +27,21 @@ files:
 - Steepfile
 - commitlint.config.js
 - lib/autoflux.rb
-- lib/autoflux/agent.rb
-- lib/autoflux/io.rb
 - lib/autoflux/memory.rb
 - lib/autoflux/stdio.rb
 - lib/autoflux/step.rb
 - lib/autoflux/step/assistant.rb
-- lib/autoflux/step/base.rb
 - lib/autoflux/step/command.rb
 - lib/autoflux/step/start.rb
 - lib/autoflux/step/stop.rb
 - lib/autoflux/step/tool.rb
-- lib/autoflux/tool.rb
 - lib/autoflux/version.rb
 - lib/autoflux/workflow.rb
 - package-lock.json
 - package.json
 - sig/autoflux.rbs
 - sig/autoflux/agent.rbs
+- sig/autoflux/event.rbs
 - sig/autoflux/io.rbs
 - sig/autoflux/memory.rbs
 - sig/autoflux/stdio.rbs

data/lib/autoflux/agent.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-module Autoflux
-  # The Agent is a abstract class to represent the adapter of the Language Model.
-  class Agent
-    # @rbs tools: Array<Tool>
-    def initialize(tools: [])
-      @_tools = tools
-    end
-
-    # @rbs name: String
-    def tool?(name)
-      @_tools.any? { |tool| tool.name == name }
-    end
-
-    # @rbs name: String
-    def tool(name)
-      @_tools.find { |tool| tool.name == name }
-    end
-
-    # @rbs memory: Memory?
-    def call(**)
-      raise NotImplementedError
-    end
-  end
-end

data/lib/autoflux/io.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Autoflux
-  # The IO is abstract class to represent the interface of the IO
-  class IO
-    def read
-      raise NotImplementedError
-    end
-
-    # @rbs data: String
-    def write(_)
-      raise NotImplementedError
-    end
-  end
-end

data/lib/autoflux/step/base.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module Autoflux
-  module Step
-    # The Step::Base is abstract class to represent the interface of the state
-    class Base
-      # @rbs workflow: Workflow
-      def call(**)
-        raise NotImplementedError
-      end
-
-      def name
-        self.class.name || "Step"
-      end
-    end
-  end
-end

data/lib/autoflux/tool.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Autoflux
-  # The Tool is a abstract class to represent the adapter of tools which can be used by the Language Model.
-  class Tool
-    attr_reader :name, :description, :parameters
-
-    def initialize(name:, description:, parameters: nil)
-      @name = name
-      @description = description
-      @parameters = parameters
-      freeze
-    end
-
-    def call(**)
-      raise NotImplementedError
-    end
-  end
-end