deepagents_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 942335db72adaeaf978062114daab11271909b68fb6e1c1323744a7c45d2593e
+  data.tar.gz: 3d78ea62b62e1ea92cd8c403d5044c091e68feeff9d0c7c0a6dc430dac3f28be
+SHA512:
+  metadata.gz: a536b7e86fdd1b388cfc1396348cd2b26883bad3d47d916c5699930264454016c71820e45af7980da97ec79ec0fe96f5b7f7470cb629e6937120193f74dda76b
+  data.tar.gz: 0fa9aa9200c7bc02f19228cdbc5a632120fe09f6da5e114022d587acad04e2d75387d3c42178e5fe1228188be84c921c91380935a3871f24875ee6d1eac77f8f

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Davis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,309 @@
+# DeepAgents for Rails
+
+DeepAgents Rails is a Ruby on Rails integration for the [DeepAgents](https://github.com/yourusername/deepagents) gem, providing easy setup and scaffolding for adding AI agent capabilities to your Rails applications.
+
+## Features
+
+- **Rails Integration**: Seamlessly integrate DeepAgents with your Rails application
+- **Generators**: Quickly scaffold agents, tools, models, controllers, and views
+- **UI Components**: Pre-built UI for agent conversations
+- **API Endpoints**: Ready-to-use API endpoints for agent interactions
+- **Database Models**: Store and retrieve conversation history
+- **File Handling**: Upload and process files with your agents
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'deepagents_rails'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install deepagents_rails
+```
+
+Then run the installation generator:
+
+```bash
+$ rails generate deepagents:install
+```
+
+This will:
+- Create a configuration file at `config/deepagents.yml`
+- Create an initializer at `config/initializers/deepagents.rb`
+- Mount the DeepAgents Rails engine in your routes
+- Add environment variable examples to `.env.example`
+
+## Configuration
+
+After installation, you can configure DeepAgents Rails in `config/initializers/deepagents.rb`:
+
+```ruby
+# config/initializers/deepagents.rb
+DeepagentsRails::Engine.config.deepagents.tap do |config|
+  config.api_key = ENV['DEEPAGENTS_API_KEY']
+  config.provider = ENV['DEEPAGENTS_PROVIDER']&.to_sym || :claude
+  config.model = ENV['DEEPAGENTS_MODEL'] || 'claude-3-sonnet-20240229'
+  config.temperature = ENV['DEEPAGENTS_TEMPERATURE']&.to_f || 0.7
+  config.max_tokens = ENV['DEEPAGENTS_MAX_TOKENS']&.to_i || 2000
+end
+```
+
+You can also use the YAML configuration file at `config/deepagents.yml`:
+
+```yaml
+# config/deepagents.yml
+default: &default
+  provider: claude
+  model: claude-3-sonnet-20240229
+  temperature: 0.7
+  max_tokens: 2000
+
+development:
+  <<: *default
+  api_key: <%= ENV['DEEPAGENTS_API_KEY'] %>
+
+test:
+  <<: *default
+  provider: mock
+  api_key: test_key
+
+production:
+  <<: *default
+  api_key: <%= ENV['DEEPAGENTS_API_KEY'] %>
+```
+
+## Usage
+
+### Creating an Agent
+
+Generate a new agent with:
+
+```bash
+$ rails generate deepagents:agent research
+```
+
+This will create:
+- An agent class at `app/deepagents/agents/research_agent.rb`
+- A controller at `app/controllers/researches_controller.rb`
+- Views at `app/views/researches/`
+- A test file at `spec/deepagents/agents/research_agent_spec.rb`
+- Routes for the agent
+
+You can then customize your agent:
+
+```ruby
+# app/deepagents/agents/research_agent.rb
+module Deepagents
+  module Agents
+    class ResearchAgent
+      def initialize(options = {})
+        @model = DeepAgents::Models::Claude.new(
+          api_key: DeepagentsRails::Engine.config.deepagents.api_key,
+          model: DeepagentsRails::Engine.config.deepagents.model
+        )
+        @agent = DeepAgents::Agent.new(@model)
+        setup_tools
+        setup_subagents
+      end
+
+      def setup_tools
+        # Add your tools here
+        @agent.add_tool(Deepagents::Tools::SearchTool.build)
+      end
+
+      def setup_subagents
+        # Add your subagents here
+      end
+
+      def run(input, context = {})
+        @agent.run(input, context)
+      end
+    end
+  end
+end
+```
+
+### Creating a Tool
+
+Generate a new tool with:
+
+```bash
+$ rails generate deepagents:tool search --description="Search for information" --parameters=query,limit
+```
+
+This will create:
+- A tool class at `app/deepagents/tools/search_tool.rb`
+- A test file at `spec/deepagents/tools/search_tool_spec.rb`
+
+You can then customize your tool:
+
+```ruby
+# app/deepagents/tools/search_tool.rb
+module Deepagents
+  module Tools
+    class SearchTool
+      def self.build
+        DeepAgents::Tool.new(
+          "search",
+          "Search for information"
+        ) do |query, limit|
+          # Implement your tool's functionality here
+          # This block will be called when the agent uses this tool
+          
+          begin
+            # Example implementation
+            "Found #{limit || 10} results for: #{query}"
+          rescue => e
+            "Error in search tool: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+### Creating Models for Conversation Storage
+
+Generate models for storing conversations:
+
+```bash
+$ rails generate deepagents:model chat
+```
+
+This will create:
+- Models at `app/models/deepagents/chat_conversation.rb`, `app/models/deepagents/chat_message.rb`, and `app/models/deepagents/chat_file.rb`
+- Migrations for creating the necessary tables
+
+Run the migrations:
+
+```bash
+$ rails db:migrate
+```
+
+You can then use these models to store and retrieve conversations:
+
+```ruby
+# Create a new conversation
+conversation = Deepagents::ChatConversation.create!(title: "My Chat")
+
+# Add a system message
+conversation.chat_messages.create!(role: "system", content: "You are a helpful assistant.")
+
+# Add a user message
+conversation.chat_messages.create!(role: "user", content: "Hello!")
+
+# Run the agent with the conversation context
+result = conversation.run_agent("Tell me about Ruby on Rails")
+
+# Access the assistant's response
+puts result[:message].content
+```
+
+### Creating API Endpoints
+
+Generate API controllers for your agents:
+
+```bash
+$ rails generate deepagents:controller chat --api_version=v1
+```
+
+This will create:
+- An API controller at `app/controllers/api/v1/chat_controller.rb`
+- Serializers at `app/serializers/chat_serializer.rb`
+- Routes for the API endpoints
+
+You can then use these endpoints to interact with your agents:
+
+```
+GET /api/v1/chats          # List conversations
+GET /api/v1/chats/:id      # Get a conversation
+POST /api/v1/chats         # Create a conversation
+POST /api/v1/chats/:id/run # Run the agent
+```
+
+### Creating UI Components
+
+Generate UI views for your agents:
+
+```bash
+$ rails generate deepagents:view chat
+```
+
+This will create:
+- Views at `app/views/chats/`
+- JavaScript at `app/javascript/chat_chat.js`
+- CSS at `app/assets/stylesheets/chat_chat.css`
+
+You can then access the UI at:
+
+```
+GET /chats          # List conversations
+GET /chats/:id      # View a conversation
+GET /chats/new      # Create a new conversation
+```
+
+## Service Integration
+
+You can use the DeepAgents Rails service to interact with your agents:
+
+```ruby
+# Get a service instance with the default agent
+service = DeepagentsRails.service
+
+# Get a service instance with a specific agent
+service = DeepagentsRails.service(:research)
+
+# Run the agent
+result = service.run("Tell me about Ruby on Rails")
+
+# Get available tools
+tools = service.available_tools
+
+# Get available agents
+agents = service.available_agents
+```
+
+## Testing
+
+DeepAgents Rails includes a mock provider for testing:
+
+```ruby
+# config/environments/test.rb
+config.deepagents.provider = :mock
+```
+
+You can then test your agents without making actual API calls:
+
+```ruby
+# spec/deepagents/agents/research_agent_spec.rb
+RSpec.describe Deepagents::Agents::ResearchAgent do
+  it "returns a response" do
+    agent = described_class.new
+    result = agent.run("Tell me about Ruby on Rails")
+    expect(result[:response]).to include("Ruby on Rails")
+  end
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/deepagents_rails/service.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module DeepagentsRails
+  # Service class for interacting with DeepAgents in a Rails application
+  class Service
+    attr_reader :agent, :config
+    
+    # Initialize a new DeepAgents service
+    # @param agent_name [Symbol, String] The name of the agent to use
+    # @param options [Hash] Additional options for the agent
+    def initialize(agent_name = nil, options = {})
+      @config = DeepagentsRails::Engine.config.deepagents
+      @agent_name = agent_name || :default
+      @options = options
+      
+      # Load the agent if specified
+      load_agent if @agent_name
+    end
+    
+    # Run the agent with the given input
+    # @param input [String] The input to send to the agent
+    # @param context [Hash] Additional context for the agent
+    # @return [Hash] The agent's response
+    def run(input, context = {})
+      ensure_agent_loaded
+      
+      # Run the agent
+      @agent.run(input, context)
+    end
+    
+    # Get a list of available tools
+    # @return [Array<DeepAgents::Tool>] The available tools
+    def available_tools
+      tools = []
+      
+      # Load tools from the Rails app
+      Dir[Rails.root.join('app/deepagents/tools/**/*_tool.rb')].each do |file|
+        require file
+        
+        # Extract the tool class name from the file path
+        tool_name = File.basename(file, '.rb').gsub('_tool', '')
+        tool_class_name = tool_name.camelize
+        
+        # Try to load the tool class
+        begin
+          tool_class = "Deepagents::Tools::#{tool_class_name}Tool".constantize
+          tools << tool_class.build if tool_class.respond_to?(:build)
+        rescue NameError => e
+          Rails.logger.warn("Could not load tool class for #{tool_name}: #{e.message}")
+        end
+      end
+      
+      tools
+    end
+    
+    # Get a list of available agents
+    # @return [Array<String>] The available agent names
+    def available_agents
+      agents = []
+      
+      # Load agents from the Rails app
+      Dir[Rails.root.join('app/deepagents/agents/**/*_agent.rb')].each do |file|
+        # Extract the agent name from the file path
+        agent_name = File.basename(file, '.rb').gsub('_agent', '')
+        agents << agent_name
+      end
+      
+      agents
+    end
+    
+    private
+    
+    # Load the specified agent
+    def load_agent
+      agent_class_name = @agent_name.to_s.camelize
+      
+      begin
+        agent_class = "Deepagents::Agents::#{agent_class_name}Agent".constantize
+        @agent = agent_class.new(@options)
+      rescue NameError => e
+        Rails.logger.error("Could not load agent class for #{@agent_name}: #{e.message}")
+        raise "Agent not found: #{@agent_name}"
+      end
+    end
+    
+    # Ensure that an agent is loaded
+    def ensure_agent_loaded
+      if @agent.nil?
+        raise "No agent loaded. Please specify an agent name when initializing the service."
+      end
+    end
+  end
+end

data/lib/deepagents_rails/version.rb

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

data/lib/deepagents_rails.rb

@@ -0,0 +1,31 @@
+require "deepagents_rails/version"
+require "deepagents_rails/service"
+require "deepagents"
+require "rails"
+
+module DeepagentsRails
+  class Engine < ::Rails::Engine
+    isolate_namespace DeepagentsRails
+    
+    config.deepagents = ActiveSupport::OrderedOptions.new
+    config.deepagents.api_key = nil
+    config.deepagents.model = "claude-3-sonnet-20240229"
+    config.deepagents.provider = :claude
+    
+    initializer "deepagents_rails.configure" do |app|
+      # Load configuration from config/initializers/deepagents.rb if it exists
+    end
+    
+    config.to_prepare do
+      # Load deepagents tools and agents when the Rails app boots
+      Dir.glob(Rails.root.join("app/deepagents/**/*.rb")).sort.each do |file|
+        require_dependency file
+      end
+    end
+  end
+  
+  # Helper method to create a new service instance
+  def self.service(agent_name = nil, options = {})
+    Service.new(agent_name, options)
+  end
+end

data/lib/generators/deepagents/agent/agent_generator.rb

@@ -0,0 +1,55 @@
+module Deepagents
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path('templates', __dir__)
+      
+      desc "Creates a new DeepAgents agent for your Rails application"
+      
+      class_option :tools, type: :array, default: [], desc: "Tools to include with this agent"
+      class_option :model, type: :string, desc: "Model to use for this agent (claude, openai, etc.)"
+      class_option :subagents, type: :array, default: [], desc: "Subagents to include with this agent"
+      
+      def create_agent_file
+        template "agent.rb", "app/deepagents/agents/#{file_name}_agent.rb"
+      end
+      
+      def create_agent_spec_file
+        template "agent_spec.rb", "spec/deepagents/agents/#{file_name}_agent_spec.rb"
+      end
+      
+      def create_agent_controller
+        template "controller.rb", "app/controllers/deepagents/#{file_name}_controller.rb"
+      end
+      
+      def create_agent_views
+        template "index.html.erb", "app/views/deepagents/#{file_name}/index.html.erb"
+        template "show.html.erb", "app/views/deepagents/#{file_name}/show.html.erb"
+      end
+      
+      def update_routes
+        route "namespace :deepagents do\n    resources :#{file_name}, only: [:index, :show, :create]\n  end"
+      end
+      
+      def display_next_steps
+        say "\n"
+        say "Agent #{file_name} has been created! 🤖", :green
+        say "\n"
+        say "Next steps:", :yellow
+        say "  1. Edit app/deepagents/agents/#{file_name}_agent.rb to customize your agent"
+        say "  2. Add any custom tools in app/deepagents/tools/"
+        say "  3. Access your agent at /deepagents/#{file_name}"
+        say "\n"
+      end
+      
+      private
+      
+      def model_name
+        options[:model] || "DeepagentsRails::Engine.config.deepagents.provider"
+      end
+      
+      def tools_list
+        options[:tools].empty? ? "[]" : options[:tools].map { |t| ":#{t}" }.join(", ")
+      end
+    end
+  end
+end

data/lib/generators/deepagents/agent/templates/agent.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Deepagents
+  module Agents
+    class <%= class_name %>Agent
+      attr_reader :model, :tools, :subagents
+      
+      def initialize(options = {})
+        # Initialize the model based on configuration
+        provider = options[:provider] || DeepagentsRails::Engine.config.deepagents.provider
+        model_name = options[:model] || DeepagentsRails::Engine.config.deepagents.model
+        api_key = options[:api_key] || DeepagentsRails::Engine.config.deepagents.api_key
+        
+        @model = case provider.to_sym
+                 when :claude
+                   DeepAgents::Models::Claude.new(api_key: api_key, model: model_name)
+                 when :openai
+                   DeepAgents::Models::OpenAI.new(api_key: api_key, model: model_name)
+                 else
+                   DeepAgents::Models::MockModel.new(model: model_name)
+                 end
+        
+        # Initialize tools
+        @tools = setup_tools(options[:tools] || [])
+        
+        # Initialize subagents
+        @subagents = setup_subagents(options[:subagents] || [])
+        
+        # Create the deep agent
+        @agent = create_agent
+      end
+      
+      def run(input, context = {})
+        # Run the agent with the given input and context
+        result = @agent.invoke({
+          messages: [{role: "user", content: input}],
+          files: context[:files] || {}
+        })
+        
+        # Return the result
+        {
+          response: result.messages.last[:content],
+          files: result.files
+        }
+      end
+      
+      private
+      
+      def setup_tools(tool_names)
+        tools = []
+        
+        # Add default tools
+        tools << DeepAgents::Tool.new(
+          "calculator",
+          "Perform mathematical calculations"
+        ) do |expression|
+          begin
+            eval(expression).to_s
+          rescue => e
+            "Error: #{e.message}"
+          end
+        end
+        
+        # Add custom tools based on tool_names
+        # Implement your custom tools here
+        
+        tools
+      end
+      
+      def setup_subagents(subagent_configs)
+        subagents = []
+        
+        # Add custom subagents based on subagent_configs
+        # Implement your custom subagents here
+        
+        subagents
+      end
+      
+      def create_agent
+        # Define the agent's instructions
+        instructions = <<~INSTRUCTIONS
+          You are a helpful assistant named <%= class_name %>.
+          
+          Your primary goal is to assist users with their questions and tasks.
+          
+          Please be concise, accurate, and helpful in your responses.
+        INSTRUCTIONS
+        
+        # Create and return the deep agent
+        DeepAgents.create_deep_agent(
+          @tools,
+          instructions,
+          model: @model,
+          subagents: @subagents
+        )
+      end
+    end
+  end
+end

data/lib/generators/deepagents/agent/templates/agent_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe Deepagents::Agents::<%= class_name %>Agent do
+  let(:agent) { described_class.new(provider: :mock) }
+  
+  describe '#initialize' do
+    it 'creates an agent with the correct model' do
+      expect(agent.model).to be_a(DeepAgents::Models::MockModel)
+    end
+    
+    it 'sets up the required tools' do
+      expect(agent.tools).not_to be_empty
+      expect(agent.tools.first).to be_a(DeepAgents::Tool)
+    end
+  end
+  
+  describe '#run' do
+    it 'returns a response when given input' do
+      result = agent.run('Hello, how are you?')
+      expect(result).to be_a(Hash)
+      expect(result[:response]).to be_a(String)
+    end
+    
+    it 'handles file context' do
+      result = agent.run('What is in the file?', files: { 'test.txt' => 'This is a test file.' })
+      expect(result).to be_a(Hash)
+      expect(result[:response]).to be_a(String)
+      expect(result[:files]).to be_a(Hash)
+    end
+  end
+end

data/lib/generators/deepagents/agent/templates/controller.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Deepagents
+  class <%= class_name %>Controller < ApplicationController
+    before_action :initialize_agent
+    
+    def index
+      # Display the agent interface
+    end
+    
+    def show
+      # Display a specific conversation
+      @conversation = Conversation.find(params[:id])
+    end
+    
+    def create
+      # Process user input and get agent response
+      @input = params[:input]
+      
+      # Get any file attachments
+      files = {}
+      if params[:files].present?
+        params[:files].each do |file|
+          files[file.original_filename] = file.read
+        end
+      end
+      
+      # Run the agent
+      result = @agent.run(@input, files: files)
+      
+      # Return the response
+      respond_to do |format|
+        format.html { redirect_to deepagents_<%= file_name %>_path, notice: "Response generated" }
+        format.json { render json: result }
+      end
+    end
+    
+    private
+    
+    def initialize_agent
+      @agent = Deepagents::Agents::<%= class_name %>Agent.new
+    end
+  end
+end