rubycode 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8da87e3aaf4fd3001f396d9394df720eff277f65a2074ab639f5ca881490fb5f
-  data.tar.gz: b5ef26c288070a2b9a2a01914765b95e9778b71473a118e6d0cc7ec9084afafd
+  metadata.gz: 3de3303b47050cfd2d290e35fcbf834e57c5eeb53d85a6b697e0cd554a5b05c0
+  data.tar.gz: 3a60d16a0f7fc111e6ccf305b1d4d0427f8b9b42296e79455f9b3caae06ce2ee
 SHA512:
-  metadata.gz: 24f9e8016eb87418822608cfd72cdc158c45c3712767b6b18da41b4be52fa58bf49f402e4e0b9c3a5d761a0625eec0e90fb41301c340e51987201d467d4b51fb
-  data.tar.gz: 607b13e698d45693ef2041aa89095c91c9286e1939bbb800f823e1e1c64e9d2c8e538ddde11e9f41cbec56447ab12585ff2df5c0b0bc3df236ec0ce35654614c
+  metadata.gz: ca04ec8192747e4e97cef35c2a8ec6440e82b65a412e7c13a979f84a5d58de92c615e90e58cebe28b8761ae05d462f4a5e9a38bdeb0388005234b76bb02edc67
+  data.tar.gz: 84066bb9aa138c598eedad4a48472448d253f0eaeb1551ed1041a2bb4a3fc0087cabbc4c46dffeaf14ff83c1570096ff88db3c439537debbaea0f710eb01414c

data/.rubocop.yml

@@ -1,8 +1,16 @@
 AllCops:
   TargetRubyVersion: 3.1
+  NewCops: enable
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
 Style/StringLiteralsInInterpolation:
   EnforcedStyle: double_quotes
+
+# Metrics - reasonable limits for maintainability
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/MethodLength:
+  Max: 20

data/README.md

@@ -1,38 +1,107 @@
-# Rubycode
+# RubyCode
 
-TODO: Delete this and the text below, and describe your gem
+[![Gem Version](https://badge.fury.io/rb/rubycode.svg)](https://badge.fury.io/rb/rubycode)
+[![GitHub](https://img.shields.io/github/license/jonasmedeiros/rubycode)](https://github.com/jonasmedeiros/rubycode)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rubycode`. To experiment with that code, run `bin/console` for an interactive prompt.
+A Ruby-native AI coding assistant with pluggable LLM adapters. RubyCode provides an agent-based system that can explore codebases, search files, execute commands, and assist with coding tasks.
 
-## Installation
+**GitHub Repository**: [github.com/jonasmedeiros/rubycode](https://github.com/jonasmedeiros/rubycode)
+
+## Features
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+- **AI Agent Loop**: Autonomous task execution with tool calling
+- **Pluggable LLM Adapters**: Currently supports Ollama, easily extendable to other LLMs
+- **Built-in Tools**:
+  - `bash`: Execute safe bash commands for filesystem exploration
+  - `search`: Search file contents using grep with regex support
+  - `read`: Read files and directories with line numbers
+  - `done`: Signal task completion with final answer
+- **Conversation History**: Maintains context across interactions
+- **Environment Context**: Automatically provides Ruby version, platform, and working directory info
 
-Install the gem and add to the application's Gemfile by executing:
+## Installation
+
+Install the gem by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install rubycode
+```
+
+Or add it to your application's Gemfile:
+
+```ruby
+gem "rubycode"
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Then execute:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+### Basic Usage
+
+```ruby
+require "rubycode"
+
+# Configure the LLM adapter
+RubyCode.configure do |config|
+  config.adapter = :ollama
+  config.url = "http://localhost:11434"
+  config.model = "deepseek-v3.1:671b-cloud"
+  config.root_path = Dir.pwd
+  config.debug = false
+end
+
+# Create a client and ask a question
+client = RubyCode::Client.new
+response = client.ask(prompt: "Find the User model in the codebase")
+puts response
+```
+
+### Configuration Options
+
+```ruby
+RubyCode.configure do |config|
+  config.adapter = :ollama                    # LLM adapter to use
+  config.url = "http://localhost:11434"       # Ollama server URL
+  config.model = "deepseek-v3.1:671b-cloud"   # Model name
+  config.root_path = Dir.pwd                  # Project root directory
+  config.debug = false                        # Enable debug output
+  config.enable_tool_injection_workaround = true  # Force tool usage (enabled by default)
+end
+```
+
+### Available Tools
+
+The agent has access to four built-in tools:
+
+1. **bash**: Execute safe bash commands including:
+   - Directory exploration: `ls`, `pwd`, `find`, `tree`
+   - File inspection: `cat`, `head`, `tail`, `wc`, `file`
+   - Content search: `grep`, `rg` (ripgrep)
+   - Examples: `grep -rn "button" app/views`, `find . -name "*.rb"`
+2. **search**: Simplified search wrapper (use bash + grep for more control)
+3. **read**: Read files with line numbers or list directory contents
+4. **done**: Signal completion and provide the final answer
+
+**Note**: Tool schemas are externalized in `config/tools/*.json` for easy customization.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bundle install` to install dependencies.
+
+To install this gem onto your local machine, run:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bundle exec rake install
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rubycode.
+Bug reports and pull requests are welcome on GitHub at https://github.com/jonasmedeiros/rubycode.
 
 ## License
 

data/config/tools/bash.json

@@ -0,0 +1,17 @@
+{
+  "type": "function",
+  "function": {
+    "name": "bash",
+    "description": "Execute safe bash commands for exploring the filesystem and terminal operations.\n\nUse this for any command-line operations including:\n- Directory exploration: ls, find, tree\n- File inspection: cat, head, tail, wc, file\n- Content search: grep, rg (ripgrep)\n\nExamples:\n- grep -rn 'button' app/views\n- find . -name '*.rb' -type f\n- ls -la app/\n\nWhitelisted commands: ls, pwd, find, tree, cat, head, tail, wc, file, which, echo, grep, rg",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "The bash command to execute. Examples:\n- 'grep -rn \"button\" app/views' (search for text in files)\n- 'find . -name \"*.rb\"' (find files by name)\n- 'ls -la app/' (list directory contents)"
+        }
+      },
+      "required": ["command"]
+    }
+  }
+}

data/config/tools/done.json

@@ -0,0 +1,17 @@
+{
+  "type": "function",
+  "function": {
+    "name": "done",
+    "description": "Call this when you have found the code and are ready to provide your final answer. This signals you are finished exploring.",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "answer": {
+          "type": "string",
+          "description": "Your final answer showing the file, line number, current code, and suggested change"
+        }
+      },
+      "required": ["answer"]
+    }
+  }
+}

data/config/tools/read.json

@@ -0,0 +1,25 @@
+{
+  "type": "function",
+  "function": {
+    "name": "read",
+    "description": "Read a file or directory from the filesystem.\n\n- Use this when you know the file path and want to see its contents\n- Returns file contents with line numbers (format: 'line_number: content')\n- For directories, returns a listing of entries\n- Use the search tool to find specific content in files\n- Use bash with 'ls' or 'find' to discover what files exist",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "file_path": {
+          "type": "string",
+          "description": "Absolute or relative path to the file to read"
+        },
+        "offset": {
+          "type": "integer",
+          "description": "Line number to start reading from (1-indexed). Optional."
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Maximum number of lines to read. Default 2000. Optional."
+        }
+      },
+      "required": ["file_path"]
+    }
+  }
+}

data/config/tools/search.json

@@ -0,0 +1,29 @@
+{
+  "type": "function",
+  "function": {
+    "name": "search",
+    "description": "Search INSIDE file contents for patterns using grep. Returns matching lines with file paths and line numbers.\n\n- Searches file CONTENTS using regular expressions\n- Use this when you need to find WHERE specific text/code appears inside files\n- Returns file paths, line numbers, and the matching content\n- Example: search for 'button' to find files containing that text",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "pattern": {
+          "type": "string",
+          "description": "The pattern to search for (supports regex)"
+        },
+        "path": {
+          "type": "string",
+          "description": "Directory or file to search in. Defaults to '.' (current directory). Optional."
+        },
+        "include": {
+          "type": "string",
+          "description": "File pattern to include (e.g., '*.rb', '*.js'). Optional."
+        },
+        "case_insensitive": {
+          "type": "boolean",
+          "description": "Perform case-insensitive search. Optional."
+        }
+      },
+      "required": ["pattern"]
+    }
+  }
+}

data/lib/rubycode/adapters/base.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-module Rubycode
+module RubyCode
   module Adapters
+    # Base adapter class for LLM integrations
     class Base
       def initialize(config)
         @config = config

data/lib/rubycode/adapters/ollama.rb

@@ -3,55 +3,62 @@
 require "net/http"
 require "json"
 
-module Rubycode
+module RubyCode
   module Adapters
+    # Ollama adapter for local LLM integration
     class Ollama < Base
       def generate(messages:, system: nil, tools: nil)
         uri = URI("#{@config.url}/api/chat")
+        payload = build_payload(messages, system, tools)
+        request = build_request(uri, payload)
 
-        request = Net::HTTP::Post.new(uri)
-        request["Content-Type"] = "application/json"
+        debug_request(uri, payload) if @config.debug
+
+        body = send_request(uri, request)
 
-        payload = {
-          model: @config.model,
-          messages: messages,
-          stream: false
-        }
+        debug_response(body) if @config.debug
+
+        body
+      end
+
+      private
+
+      def build_payload(messages, system, tools)
+        payload = { model: @config.model, messages: messages, stream: false }
         payload[:system] = system if system
         payload[:tools] = tools if tools
+        payload
+      end
 
+      def build_request(uri, payload)
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
         request.body = payload.to_json
+        request
+      end
 
-        # DEBUG: Show request if debug mode enabled
-        if @config.debug
-          puts "\n" + "=" * 80
-          puts "📤 REQUEST TO LLM"
-          puts "=" * 80
-          puts "URL: #{uri}"
-          puts "Model: #{@config.model}"
-          puts "\nPayload:"
-          puts JSON.pretty_generate(payload)
-          puts "=" * 80
-        end
-
-        response = Net::HTTP.start(uri.hostname, uri.port) do |http|
-          http.request(request)
-        end
-
-        body = JSON.parse(response.body)
-
-        # DEBUG: Show response if debug mode enabled
-        if @config.debug
-          puts "\n" + "=" * 80
-          puts "📥 RESPONSE FROM LLM"
-          puts "=" * 80
-          puts JSON.pretty_generate(body)
-          puts "=" * 80 + "\n"
-        end
-
-        # /api/chat always returns this structure:
-        # { "message": { "role": "assistant", "content": "...", "tool_calls": [...] } }
-        body
+      def send_request(uri, request)
+        response = Net::HTTP.start(uri.hostname, uri.port) { |http| http.request(request) }
+        JSON.parse(response.body)
+      end
+
+      def debug_request(uri, payload)
+        puts "\n#{"=" * 80}"
+        puts "📤 REQUEST TO LLM"
+        puts "=" * 80
+        puts "URL: #{uri}"
+        puts "Model: #{@config.model}"
+        puts "\nPayload:"
+        puts JSON.pretty_generate(payload)
+        puts "=" * 80
+      end
+
+      def debug_response(body)
+        puts "\n#{"=" * 80}"
+        puts "📥 RESPONSE FROM LLM"
+        puts "=" * 80
+        puts JSON.pretty_generate(body)
+        puts "#{"=" * 80}\n"
       end
     end
   end

data/lib/rubycode/agent_loop.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require_relative "client/response_handler"
+require_relative "client/display_formatter"
+
+module RubyCode
+  # Manages the agent loop - iterates until task completion or limits reached
+  class AgentLoop
+    MAX_ITERATIONS = 25
+    MAX_TOOL_CALLS = 50
+
+    def initialize(adapter:, history:, config:, system_prompt:)
+      @adapter = adapter
+      @history = history
+      @config = config
+      @system_prompt = system_prompt
+      @response_handler = Client::ResponseHandler.new(history: @history, config: @config)
+      @display_formatter = Client::DisplayFormatter.new(config: @config)
+    end
+
+    def run
+      iteration = 0
+      total_tool_calls = 0
+
+      loop do
+        iteration += 1
+
+        return @response_handler.handle_max_iterations(iteration) if iteration > MAX_ITERATIONS
+
+        content, tool_calls = llm_response
+
+        if tool_calls.empty?
+          result = @response_handler.handle_empty_tool_calls(content, iteration, total_tool_calls)
+          return result if result
+
+          next # Continue loop for workaround case
+        end
+
+        total_tool_calls += tool_calls.length
+        return @response_handler.handle_max_tool_calls(content, total_tool_calls) if total_tool_calls > MAX_TOOL_CALLS
+
+        done_result = execute_tool_calls(tool_calls, iteration)
+        return @response_handler.finalize_response(done_result, iteration, total_tool_calls) if done_result
+      end
+    end
+
+    private
+
+    def llm_response
+      messages = @history.to_llm_format
+      response_body = @adapter.generate(
+        messages: messages,
+        system: @system_prompt,
+        tools: Tools.definitions
+      )
+
+      assistant_message = response_body["message"]
+      content = assistant_message["content"] || ""
+      tool_calls = assistant_message["tool_calls"] || []
+
+      @history.add_message(role: "assistant", content: content)
+      [content, tool_calls]
+    end
+
+    def execute_tool_calls(tool_calls, iteration)
+      puts "\n🤖 Iteration #{iteration}: Calling #{tool_calls.length} tool(s)..." unless @config.debug
+
+      done_result = nil
+      tool_calls.each do |tool_call|
+        result = execute_tool(tool_call)
+
+        if tool_call.dig("function", "name") == "done"
+          done_result = result
+          break
+        end
+      end
+      done_result
+    end
+
+    def execute_tool(tool_call)
+      tool_name = tool_call.dig("function", "name")
+      arguments = tool_call.dig("function", "arguments")
+
+      @display_formatter.display_tool_info(tool_name, arguments)
+
+      params = parse_arguments(arguments)
+      return nil unless params
+
+      result = run_tool(tool_name, params)
+      return nil unless result
+
+      @display_formatter.display_result(result)
+      add_tool_result_to_history(tool_name, result)
+      result
+    rescue ToolError, StandardError => e
+      # Handle all errors - add to history and continue
+      handle_tool_error(e)
+    end
+
+    def parse_arguments(arguments)
+      arguments.is_a?(Hash) ? arguments : JSON.parse(arguments)
+    rescue JSON::ParserError => e
+      error_msg = "Error parsing tool arguments: #{e.message}"
+      puts "   ✗ #{error_msg}"
+      @history.add_message(role: "user", content: error_msg)
+      nil
+    end
+
+    def run_tool(tool_name, params)
+      context = { root_path: @config.root_path }
+      Tools.execute(tool_name: tool_name, params: params, context: context)
+    rescue ToolError => e
+      # Re-raise tool errors to be caught by execute_tool
+      raise e
+    rescue StandardError => e
+      # Wrap unexpected errors
+      error_msg = "Error executing tool: #{e.message}"
+      puts "   ✗ #{error_msg}"
+      @history.add_message(role: "user", content: error_msg)
+      nil
+    end
+
+    def add_tool_result_to_history(tool_name, result)
+      @history.add_message(role: "user", content: "Tool '#{tool_name}' result:\n#{result}")
+    end
+
+    def handle_tool_error(error)
+      error_msg = "Error: #{error.message}"
+      puts "   ✗ #{error_msg}"
+      @history.add_message(role: "user", content: error_msg)
+      nil
+    end
+  end
+end

data/lib/rubycode/client/display_formatter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyCode
+  class Client
+    # Handles formatting and display of tool information and results
+    class DisplayFormatter
+      TOOL_ICONS = {
+        "bash" => ["💻", "command"],
+        "read" => ["📖", "file_path"],
+        "search" => ["🔍", "pattern"]
+      }.freeze
+
+      def initialize(config:)
+        @config = config
+      end
+
+      def display_tool_info(tool_name, arguments)
+        if @config.debug
+          puts "\n🔧 Tool: #{tool_name}"
+          puts "   Args: #{arguments.inspect}"
+        else
+          display_minimal_tool_info(tool_name, arguments)
+        end
+      end
+
+      def display_result(result)
+        return unless @config.debug
+
+        first_line = result.lines.first&.strip || "(empty)"
+        suffix = result.lines.count > 1 ? "... (#{result.lines.count} lines)" : ""
+        puts "   ✓ Result: #{first_line}#{suffix}"
+      end
+
+      private
+
+      def display_minimal_tool_info(tool_name, arguments)
+        return unless TOOL_ICONS.key?(tool_name)
+
+        icon, key = TOOL_ICONS[tool_name]
+        value = extract_argument_value(arguments, key)
+        puts "   #{icon} #{value}" if value
+      end
+
+      def extract_argument_value(arguments, key)
+        arguments.is_a?(Hash) ? arguments[key] : JSON.parse(arguments)[key]
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+end

data/lib/rubycode/client/response_handler.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module RubyCode
+  class Client
+    # Handles response scenarios (max iterations, empty tool calls, etc.)
+    class ResponseHandler
+      MAX_ITERATIONS = 25
+      MAX_TOOL_CALLS = 50
+
+      def initialize(history:, config:)
+        @history = history
+        @config = config
+      end
+
+      def handle_max_iterations(_iteration)
+        error_msg = "⚠️  Reached maximum iterations (#{MAX_ITERATIONS}). The agent may be stuck in a loop."
+        puts "\n#{error_msg}\n"
+        @history.add_message(role: "assistant", content: error_msg)
+        error_msg
+      end
+
+      def handle_empty_tool_calls(content, iteration, total_tool_calls)
+        if @config.enable_tool_injection_workaround && iteration < 10
+          inject_tool_reminder(iteration)
+          return nil
+        end
+
+        puts "\n✅ Agent finished (#{iteration} iterations, #{total_tool_calls} tool calls)\n" unless @config.debug
+        content
+      end
+
+      def handle_max_tool_calls(content, _total_tool_calls)
+        error_msg = "⚠️  Reached maximum tool calls (#{MAX_TOOL_CALLS}). Stopping to prevent excessive operations."
+        puts "\n#{error_msg}\n"
+        @history.add_message(role: "assistant", content: error_msg)
+        content.empty? ? error_msg : content
+      end
+
+      def finalize_response(done_result, iteration, total_tool_calls)
+        puts "\n✅ Agent finished (#{iteration} iterations, #{total_tool_calls + 1} tool calls)\n" unless @config.debug
+        done_result
+      end
+
+      private
+
+      def inject_tool_reminder(iteration)
+        puts "   ⚠️  No tool calls - injecting reminder (iteration #{iteration})" unless @config.debug
+        @history.add_message(
+          role: "user",
+          content: "You MUST call a tool. Do not respond with text. Call search, read, bash, or done tool now."
+        )
+      end
+    end
+  end
+end