deepagents 0.1.0

data/lib/deepagents/state.rb

@@ -0,0 +1,139 @@
+require_relative 'errors'
+
+module DeepAgents
+  # Todo class for managing todos
+  class Todo
+    attr_accessor :content, :status
+    
+    def initialize(content, status = "pending")
+      raise ArgumentError, "Todo content cannot be nil or empty" if content.nil? || content.empty?
+      @content = content
+      @status = validate_status(status)
+    end
+    
+    def to_h
+      {
+        content: @content,
+        status: @status
+      }
+    end
+    
+    def self.from_h(hash)
+      content = hash[:content] || hash["content"]
+      status = hash[:status] || hash["status"] || "pending"
+      
+      raise ArgumentError, "Todo hash must contain content" if content.nil?
+      new(content, status)
+    end
+    
+    private
+    
+    def validate_status(status)
+      valid_statuses = ["pending", "in_progress", "completed"]
+      status = status.to_s.downcase
+      
+      unless valid_statuses.include?(status)
+        raise ArgumentError, "Invalid todo status: #{status}. Must be one of: #{valid_statuses.join(', ')}"
+      end
+      
+      status
+    end
+  end
+  
+  # Deep agent state class
+  class DeepAgentState
+    attr_reader :todos, :files, :messages
+    
+    def initialize
+      @todos = []
+      @files = {}
+      @messages = []
+    end
+    
+    def todos=(value)
+      @todos = validate_todos(value)
+    end
+    
+    def files=(value)
+      raise ArgumentError, "Files must be a hash" unless value.is_a?(Hash)
+      @files = value
+    end
+    
+    def messages=(value)
+      raise ArgumentError, "Messages must be an array" unless value.is_a?(Array)
+      @messages = value
+    end
+    
+    def get(key, default = nil)
+      case key.to_s
+      when "todos"
+        @todos
+      when "files"
+        @files
+      when "messages"
+        @messages
+      else
+        default
+      end
+    end
+    
+    def update(todos: nil, files: nil, messages: nil)
+      begin
+        if todos
+          @todos = validate_todos(todos)
+        end
+        
+        if files
+          raise ArgumentError, "Files must be a hash" unless files.is_a?(Hash)
+          @files.merge!(files)
+        end
+        
+        if messages
+          raise ArgumentError, "Messages must be an array" unless messages.is_a?(Array)
+          @messages += messages
+        end
+      rescue => e
+        raise StateError, "Failed to update state: #{e.message}"
+      end
+    end
+    
+    def [](key)
+      get(key)
+    end
+    
+    def []=(key, value)
+      case key.to_s
+      when "todos"
+        self.todos = value
+      when "files"
+        self.files = value
+      when "messages"
+        self.messages = value
+      else
+        raise ArgumentError, "Unknown state key: #{key}"
+      end
+    end
+    
+    def to_h
+      {
+        todos: @todos.map(&:to_h),
+        files: @files,
+        messages: @messages
+      }
+    end
+    
+    private
+    
+    def validate_todos(todos)
+      raise ArgumentError, "Todos must be an array" unless todos.is_a?(Array)
+      
+      todos.map do |todo|
+        if todo.is_a?(Todo)
+          todo
+        else
+          Todo.from_h(todo)
+        end
+      end
+    end
+  end
+end

data/lib/deepagents/sub_agent.rb

@@ -0,0 +1,130 @@
+require_relative 'errors'
+require_relative 'state'
+
+module DeepAgents
+  # SubAgent class for creating and managing sub-agents
+  class SubAgent
+    attr_reader :name, :instructions, :tools, :model, :state
+
+    def initialize(name, instructions, tools = [], model = nil)
+      raise ArgumentError, "Sub-agent name cannot be nil or empty" if name.nil? || name.empty?
+      raise ArgumentError, "Sub-agent instructions cannot be nil or empty" if instructions.nil? || instructions.empty?
+      
+      @name = name
+      @instructions = instructions
+      @tools = tools
+      @model = model
+      @state = DeepAgentState.new
+    end
+
+    def run(input, max_iterations = 10)
+      raise ArgumentError, "Model must be provided to run the sub-agent" unless @model
+      
+      prompt = build_prompt(input)
+      iterations = 0
+      messages = []
+      
+      while iterations < max_iterations
+        iterations += 1
+        
+        response = @model.generate(prompt, @tools)
+        
+        if response[:tool_calls] && !response[:tool_calls].empty?
+          tool_call = response[:tool_calls].first
+          tool_name = tool_call[:name]
+          tool_args = tool_call[:arguments]
+          
+          tool = find_tool(tool_name)
+          result = execute_tool(tool, tool_args)
+          
+          messages << { role: "assistant", content: "I'll use the #{tool_name} tool." }
+          messages << { role: "system", content: "Tool result: #{result}" }
+          
+          prompt = build_prompt(input, messages)
+        else
+          messages << { role: "assistant", content: response[:content] }
+          break
+        end
+      end
+      
+      if iterations >= max_iterations
+        raise MaxIterationsError.new(max_iterations)
+      end
+      
+      # Return the final response
+      messages.last[:content]
+    end
+
+    private
+
+    def build_prompt(input, messages = [])
+      prompt = "You are a sub-agent named #{@name} with the following instructions:\n\n"
+      prompt += "#{@instructions}\n\n"
+      
+      if @tools && !@tools.empty?
+        prompt += "You have access to the following tools:\n\n"
+        
+        @tools.each do |tool|
+          prompt += "#{tool.name}: #{tool.description}\n"
+          prompt += "Parameters: #{tool.parameters.join(', ')}\n\n"
+        end
+      end
+      
+      prompt += "Input: #{input}\n\n"
+      
+      if messages && !messages.empty?
+        prompt += "Previous messages:\n\n"
+        
+        messages.each do |message|
+          prompt += "#{message[:role]}: #{message[:content]}\n\n"
+        end
+      end
+      
+      prompt
+    end
+
+    def find_tool(name)
+      tool = @tools.find { |t| t.name == name }
+      raise ToolNotFoundError.new(name) unless tool
+      tool
+    end
+
+    def execute_tool(tool, args)
+      begin
+        if args.is_a?(Hash)
+          tool.call(**args)
+        else
+          tool.call(args)
+        end
+      rescue => e
+        "Error executing tool: #{e.message}"
+      end
+    end
+  end
+
+  # SubAgentRegistry class for managing sub-agents
+  class SubAgentRegistry
+    def initialize
+      @agents = {}
+    end
+
+    def register(agent)
+      raise ArgumentError, "Agent must be a SubAgent instance" unless agent.is_a?(SubAgent)
+      @agents[agent.name] = agent
+    end
+
+    def get(name)
+      agent = @agents[name]
+      raise SubAgentNotFoundError.new(name) unless agent
+      agent
+    end
+
+    def list
+      @agents.values
+    end
+
+    def names
+      @agents.keys
+    end
+  end
+end

data/lib/deepagents/tools.rb

@@ -0,0 +1,152 @@
+require_relative 'errors'
+
+module DeepAgents
+  # Tool class for defining tools that can be used by the agent
+  class Tool
+    attr_reader :name, :description, :parameters, :function
+
+    def initialize(name, description, parameters = [], &block)
+      raise ArgumentError, "Tool name cannot be nil or empty" if name.nil? || name.empty?
+      raise ArgumentError, "Tool description cannot be nil or empty" if description.nil? || description.empty?
+      raise ArgumentError, "Tool function block must be provided" unless block_given?
+
+      @name = name
+      @description = description
+      @parameters = parameters
+      @function = block
+    end
+
+    def call(*args, **kwargs)
+      begin
+        @function.call(*args, **kwargs)
+      rescue => e
+        raise ToolError.new(@name, e.message)
+      end
+    end
+
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        parameters: @parameters
+      }
+    end
+  end
+
+  # ToolRegistry class for managing tools
+  class ToolRegistry
+    def initialize
+      @tools = {}
+    end
+
+    def register(tool)
+      raise ArgumentError, "Tool must be a Tool instance" unless tool.is_a?(Tool)
+      @tools[tool.name] = tool
+    end
+
+    def get(name)
+      tool = @tools[name]
+      raise ToolNotFoundError.new(name) unless tool
+      tool
+    end
+
+    def list
+      @tools.values
+    end
+
+    def names
+      @tools.keys
+    end
+
+    def to_h
+      @tools.transform_values(&:to_h)
+    end
+  end
+
+  # FileSystem class for managing virtual files
+  class FileSystem
+    def initialize(initial_files = {})
+      @files = initial_files
+    end
+
+    def read(path)
+      file = @files[path]
+      raise FileNotFoundError.new(path) unless file
+      file
+    end
+
+    def write(path, content)
+      @files[path] = content
+    end
+
+    def delete(path)
+      raise FileNotFoundError.new(path) unless @files.key?(path)
+      @files.delete(path)
+    end
+
+    def list
+      @files.keys
+    end
+
+    def exists?(path)
+      @files.key?(path)
+    end
+
+    def to_h
+      @files
+    end
+  end
+
+  # Standard tools that can be used by the agent
+  module StandardTools
+    def self.file_system_tools(file_system)
+      [
+        Tool.new("read_file", "Read a file from the file system", ["path"]) do |path|
+          file_system.read(path)
+        end,
+        Tool.new("write_file", "Write content to a file in the file system", ["path", "content"]) do |path, content|
+          file_system.write(path, content)
+          "File written to #{path}"
+        end,
+        Tool.new("list_files", "List all files in the file system") do
+          file_system.list
+        end,
+        Tool.new("delete_file", "Delete a file from the file system", ["path"]) do |path|
+          file_system.delete(path)
+          "File deleted: #{path}"
+        end
+      ]
+    end
+
+    def self.todo_tools(state)
+      [
+        Tool.new("add_todo", "Add a new todo item", ["content"]) do |content|
+          todo = Todo.new(content)
+          state.todos << todo
+          "Todo added: #{content}"
+        end,
+        Tool.new("list_todos", "List all todo items") do
+          state.todos.map.with_index do |todo, index|
+            "#{index + 1}. [#{todo.status}] #{todo.content}"
+          end
+        end,
+        Tool.new("update_todo", "Update a todo item status", ["index", "status"]) do |index, status|
+          index = index.to_i - 1
+          if index < 0 || index >= state.todos.length
+            raise ArgumentError, "Invalid todo index: #{index + 1}"
+          end
+
+          todo = state.todos[index]
+          todo.status = status
+          "Todo updated: #{todo.content} - #{status}"
+        end
+      ]
+    end
+
+    def self.planning_tool
+      Tool.new("plan", "Create a plan for solving a task", ["task"]) do |task|
+        "Plan for #{task}:\n1. Analyze the requirements\n2. Break down into subtasks\n3. Implement each subtask\n4. Test the solution\n5. Refine as needed"
+      end
+    end
+  end
+end

data/lib/deepagents/version.rb

@@ -0,0 +1,3 @@
+module DeepAgents
+  VERSION = "0.1.0"
+end

data/lib/deepagents.rb

@@ -0,0 +1,61 @@
+require_relative "deepagents/version"
+require_relative "deepagents/errors"
+require_relative "deepagents/state"
+require_relative "deepagents/tools"
+require_relative "deepagents/sub_agent"
+require_relative "deepagents/models"
+require_relative "deepagents/graph"
+
+# External dependencies
+require "langchainrb"
+require "langgraph_rb"
+
+module DeepAgents
+  # Main entry point to create a deep agent
+  def self.create_deep_agent(tools, instructions, model: nil, subagents: nil, state_schema: nil)
+    begin
+      # Validate inputs
+      raise ArgumentError, "Tools must be an array" unless tools.is_a?(Array)
+      raise ArgumentError, "Instructions cannot be nil or empty" if instructions.nil? || instructions.empty?
+      
+      # If model is a string, try to create an appropriate model adapter
+      if model.is_a?(String)
+        if model.downcase.include?("claude")
+          model = Models::Claude.new(model: model)
+        elsif model.downcase.include?("gpt") || model.downcase.include?("openai")
+          model = Models::OpenAI.new(model: model)
+        else
+          # Default to Claude if we can't determine the model type
+          model = Models::Claude.new(model: model)
+        end
+      end
+      
+      Graph.create_deep_agent(tools, instructions, model: model, subagents: subagents, state_schema: state_schema)
+    rescue => e
+      # Wrap any errors in our own Error class
+      raise Error, "Failed to create deep agent: #{e.message}"
+    end
+  end
+  
+  # Convenience method to create a Claude model
+  def self.claude_model(api_key: nil, model: "claude-3-sonnet-20240229")
+    begin
+      Models::Claude.new(api_key: api_key, model: model)
+    rescue LoadError => e
+      raise Error, "Failed to create Claude model: The 'anthropic' gem is not installed. Please run 'gem install anthropic' or add it to your Gemfile."
+    rescue => e
+      raise Error, "Failed to create Claude model: #{e.message}"
+    end
+  end
+  
+  # Convenience method to create an OpenAI model
+  def self.openai_model(api_key: nil, model: "gpt-4o")
+    begin
+      Models::OpenAI.new(api_key: api_key, model: model)
+    rescue LoadError => e
+      raise Error, "Failed to create OpenAI model: The 'openai' gem is not installed. Please run 'gem install openai' or add it to your Gemfile."
+    rescue => e
+      raise Error, "Failed to create OpenAI model: #{e.message}"
+    end
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: deepagents
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Davis
+bindir: exe
+cert_chain: []
+date: 2025-08-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: langchainrb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: langgraph_rb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: anthropic
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+description: Ruby implementation of deepagents - a library for creating deep agents
+  with planning capabilities, sub-agent spawning, and a mock file system
+email:
+- chrisdavis179@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- LICENSE
+- README.md
+- Rakefile
+- examples/langchain_integration.rb
+- examples/research_agent.rb
+- lib/deepagents.rb
+- lib/deepagents/deepagentsrb/errors.rb
+- lib/deepagents/deepagentsrb/graph.rb
+- lib/deepagents/deepagentsrb/models.rb
+- lib/deepagents/deepagentsrb/state.rb
+- lib/deepagents/deepagentsrb/sub_agent.rb
+- lib/deepagents/deepagentsrb/tools.rb
+- lib/deepagents/deepagentsrb/version.rb
+- lib/deepagents/errors.rb
+- lib/deepagents/graph.rb
+- lib/deepagents/models.rb
+- lib/deepagents/state.rb
+- lib/deepagents/sub_agent.rb
+- lib/deepagents/tools.rb
+- lib/deepagents/version.rb
+homepage: https://github.com/cdaviis/deepagents
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/cdaviis/deepagents
+  source_code_uri: https://github.com/cdaviis/deepagents
+  changelog_uri: https://github.com/cdaviis/deepagents/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: General purpose 'deep agent' with sub-agent spawning, todo list capabilities,
+  and mock file system for Ruby
+test_files: []