llm_gateway 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21b3998df57de474c78626d8267db572418f80426ddaf82730cf8738e181d96c
-  data.tar.gz: 9a37ff5a3907a8b0d48dbd0fc83be2e50cd5757a60cacd051e93ff1dc63d734e
+  metadata.gz: 8e5e5bb04da32e9a1af4ad9dea6e8bf5af8785fc58d890fcb903739e89bc1a50
+  data.tar.gz: c23364222e72a72eaf2754bf775cff9709004db2007ab210c6440a0a2cb99cdc
 SHA512:
-  metadata.gz: 1be591a45a6fbee0b89846c679e0a9709e3a5493757eac3196be8194f8e592615b177c15f20d6763cf6a444bf8dbf3d899cf6e9fd9b11de7e2f02845f53ab1ff
-  data.tar.gz: ed5a981d3e7ff311d26fe4924760e286e7370da598464e4b00ad004c940015432d873be73afae7067d5fa659adbe7af701b5b6f4163432c10cdf7f950532d690
+  metadata.gz: 9f028198b6ed363a858dc0d409943d117d7c6c538ba81f21797a3dde55de4ada0fcf5e4814776873b5e35db0e3c3f87b938019cc9330fedcdae2469a746db1c4
+  data.tar.gz: df939b1f9dea8204e3ae87d1050056ea79014e29917475d4131dce7162dfec28f225f39bb5419c3327bf01f3a32d23634e612983d67c85fc581140c03da50697

data/CHANGELOG.md

@@ -1,16 +1,48 @@
 # Changelog
 
-## [Unreleased](https://github.com/Hyper-Unearthing/llm_gateway/tree/HEAD)
+## [v0.1.5](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.5) (2025-08-05)
 
-[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.0...HEAD)
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.4...v0.1.5)
+
+**Merged pull requests:**
+
+- burn: login from tool base class [\#11](https://github.com/Hyper-Unearthing/llm_gateway/pull/11) ([billybonks](https://github.com/billybonks))
+- improve sample [\#10](https://github.com/Hyper-Unearthing/llm_gateway/pull/10) ([billybonks](https://github.com/billybonks))
+- ci: mark latest change log as a version [\#9](https://github.com/Hyper-Unearthing/llm_gateway/pull/9) ([billybonks](https://github.com/billybonks))
+- ci: improve rake release task, so i get burnt less [\#8](https://github.com/Hyper-Unearthing/llm_gateway/pull/8) ([billybonks](https://github.com/billybonks))
+
+## [v0.1.4](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.4) (2025-08-04)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.3...v0.1.4)
+
+**Merged pull requests:**
+
+- ci: release should ask me what version i want to bump [\#7](https://github.com/Hyper-Unearthing/llm_gateway/pull/7) ([billybonks](https://github.com/billybonks))
+- docs: create an real world example that does something interesting [\#6](https://github.com/Hyper-Unearthing/llm_gateway/pull/6) ([billybonks](https://github.com/billybonks))
+- feat: there was no way to pass api\_key to gateway besides env [\#5](https://github.com/Hyper-Unearthing/llm_gateway/pull/5) ([billybonks](https://github.com/billybonks))
+
+## [v0.1.3](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.3) (2025-08-04)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.2...v0.1.3)
 
 **Merged pull requests:**
 
 - feat: add tool base class [\#4](https://github.com/Hyper-Unearthing/llm_gateway/pull/4) ([billybonks](https://github.com/billybonks))
+
+## [v0.1.2](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.2) (2025-08-04)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.1...v0.1.2)
+
+**Merged pull requests:**
+
 - feat: add prompt base class [\#3](https://github.com/Hyper-Unearthing/llm_gateway/pull/3) ([billybonks](https://github.com/billybonks))
 - lint files and add coverage [\#2](https://github.com/Hyper-Unearthing/llm_gateway/pull/2) ([billybonks](https://github.com/billybonks))
 - test: vcr lookup was not working when using different commands [\#1](https://github.com/Hyper-Unearthing/llm_gateway/pull/1) ([billybonks](https://github.com/billybonks))
 
+## [v0.1.1](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.1) (2025-08-04)
+
+[Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/v0.1.0...v0.1.1)
+
 ## [v0.1.0](https://github.com/Hyper-Unearthing/llm_gateway/tree/v0.1.0) (2025-08-04)
 
 [Full Changelog](https://github.com/Hyper-Unearthing/llm_gateway/compare/505c78116a2e778b23f319a380cd4bf6e300db89...v0.1.0)

data/README.md

@@ -43,221 +43,21 @@ result = LlmGateway::Client.chat(
 )
 ```
 
-### Prompt Class
+### Sample Application
 
-You can also create reusable prompt classes by subclassing `LlmGateway::Prompt`:
+See the [file search bot example](sample/claude_code_clone/) for a complete working application that demonstrates:
+- Creating reusable Prompt and Tool classes
+- Handling conversation transcripts with tool execution
+- Building an interactive terminal interface
 
-```ruby
-# Simple text completion with prompt class
-class GeographyQuestionPrompt < LlmGateway::Prompt
-  def initialize(model, question)
-    super(model)
-    @question = question
-  end
-
-  def prompt
-    @question
-  end
-end
-
-# Usage
-geography_prompt = GeographyQuestionPrompt.new('claude-sonnet-4-20250514', 'What is the capital of France?')
-result = geography_prompt.run
-
-# With system message
-class GeographyTeacherPrompt < LlmGateway::Prompt
-  def initialize(model, question)
-    super(model)
-    @question = question
-  end
-
-  def prompt
-    @question
-  end
-
-  def system_prompt
-    'You are a helpful geography teacher.'
-  end
-end
-
-# Usage
-teacher_prompt = GeographyTeacherPrompt.new('gpt-4', 'What is the capital of France?')
-result = teacher_prompt.run
-```
-
-### Using Prompt with Tools
+To run the sample:
 
-You can combine the Prompt class with tools for more complex interactions:
-
-```ruby
-# Define a tool class
-class GetWeatherTool < LlmGateway::Tool
-  name 'get_weather'
-  description 'Get current weather for a location'
-  input_schema({
-    type: 'object',
-    properties: {
-      location: { type: 'string', description: 'City name' }
-    },
-    required: ['location']
-  })
-
-  def execute(input, login = nil)
-    # Your weather API implementation here
-    "The weather in #{input['location']} is sunny and 25°C"
-  end
-end
-
-class WeatherAssistantPrompt < LlmGateway::Prompt
-  def initialize(model, location)
-    super(model)
-    @location = location
-  end
-
-  def prompt
-    "What's the weather like in #{@location}?"
-  end
-
-  def system_prompt
-    'You are a helpful weather assistant.'
-  end
-
-  def tools
-    [GetWeatherTool]
-  end
-end
-
-# Usage
-weather_prompt = WeatherAssistantPrompt.new('claude-sonnet-4-20250514', 'Singapore')
-result = weather_prompt.run
+```bash
+cd sample/claude_code_clone
+ruby run.rb
 ```
 
-### Tool Usage (Function Calling)
-
-```ruby
-# Define a tool class
-class GetWeatherTool < LlmGateway::Tool
-  name 'get_weather'
-  description 'Get current weather for a location'
-  input_schema({
-    type: 'object',
-    properties: {
-      location: { type: 'string', description: 'City name' }
-    },
-    required: ['location']
-  })
-
-  def execute(input, login = nil)
-    # Your weather API implementation here
-    "The weather in #{input['location']} is sunny and 25°C"
-  end
-end
-
-# Use the tool
-weather_tool = {
-  name: 'get_weather',
-  description: 'Get current weather for a location',
-  input_schema: {
-    type: 'object',
-    properties: {
-      location: { type: 'string', description: 'City name' }
-    },
-    required: ['location']
-  }
-}
-
-result = LlmGateway::Client.chat(
-  'claude-sonnet-4-20250514',
-  'What\'s the weather in Singapore?',
-  tools: [weather_tool],
-  system: 'You are a helpful weather assistant.'
-)
-
-# Note: Tools are not automatically executed. The LLM will indicate when a tool should be called,
-# but it's up to you to find the appropriate tool and execute it based on the response.
-
-# Example of handling tool execution with conversation transcript:
-class WeatherAssistant
-  def initialize
-    @transcript = []
-    @weather_tool = {
-      name: 'get_weather',
-      description: 'Get current weather for a location',
-      input_schema: {
-        type: 'object',
-        properties: {
-          location: { type: 'string', description: 'City name' }
-        },
-        required: ['location']
-      }
-    }
-  end
-
-  attr_reader :weather_tool
-
-  def process_message(content)
-    # Add user message to transcript
-    @transcript << { role: 'user', content: [{ type: 'text', text: content }] }
-
-    result = LlmGateway::Client.chat(
-      'claude-sonnet-4-20250514',
-      @transcript,
-      tools: [@weather_tool],
-      system: 'You are a helpful weather assistant.'
-    )
-
-    process_response(result[:choices][0][:content])
-  end
-
-  private
-
-  def process_response(response)
-    # Add assistant response to transcript
-    @transcript << { role: 'assistant', content: response }
-
-    response.each do |message|
-      if message[:type] == 'text'
-        puts message[:text]
-      elsif message[:type] == 'tool_use'
-        result = handle_tool_use(message)
-
-        # Add tool result to transcript
-        tool_result = {
-          type: 'tool_result',
-          tool_use_id: message[:id],
-          content: result
-        }
-        @transcript << { role: 'user', content: [tool_result] }
-
-        # Continue conversation with full transcript context
-        follow_up = LlmGateway::Client.chat(
-          'claude-sonnet-4-20250514',
-          @transcript,
-          tools: [@weather_tool],
-          system: 'You are a helpful weather assistant.'
-        )
-
-        process_response(follow_up[:choices][0][:content])
-      end
-    end
-  end
-
-  def handle_tool_use(message)
-    tool_class = WeatherAssistantPrompt.find_tool(message[:name])
-    raise "Unknown tool: #{message[:name]}" unless tool_class
-
-    # Execute the tool with the provided input
-    tool_instance = tool_class.new
-    tool_instance.execute(message[:input])
-  rescue StandardError => e
-    "Error executing tool: #{e.message}"
-  end
-end
-
-# Usage
-assistant = WeatherAssistant.new
-assistant.process_message("What's the weather in Singapore?")
-```
+The bot will prompt for your model and API key, then allow you to ask natural language questions about finding files and searching directories.
 
 ### Response Format
 

data/Rakefile

@@ -14,13 +14,60 @@ begin
 
   desc "Release with changelog"
   task :gem_release do
-    # Generate changelog first
-    sh "bundle exec github_changelog_generator  -u Hyper-Unearthing -p llm_gateway"
-    sh "git add CHANGELOG.md"
-    sh "git commit -m 'Update changelog' || echo 'No changelog changes'"
+    # Safety checks: ensure we're on main and up-to-date
+    current_branch = `git branch --show-current`.strip
+    unless current_branch == "main"
+      puts "Error: You must be on the main branch to release. Current branch: #{current_branch}"
+      exit 1
+    end
 
-    # Release
-    sh "gem bump --version patch --tag --push --release"
+    # Check if branch is up-to-date with remote
+    sh "git fetch origin"
+    local_commit = `git rev-parse HEAD`.strip
+    remote_commit = `git rev-parse origin/main`.strip
+    unless local_commit == remote_commit
+      puts "Error: Your main branch is not in sync with origin/main. Please pull the latest changes."
+      exit 1
+    end
+
+    # Check for uncommitted changes
+    unless `git status --porcelain`.strip.empty?
+      puts "Error: You have uncommitted changes. Please commit or stash them before releasing."
+      exit 1
+    end
+
+    # Ask for version bump type first
+    print "What type of version bump? (major/minor/patch): "
+    version_type = $stdin.gets.chomp.downcase
+
+    unless %w[major minor patch].include?(version_type)
+      puts "Invalid version type. Please use major, minor, or patch."
+      exit 1
+    end
+
+    # Bump version without committing yet to get new version
+    sh "gem bump --version #{version_type} --no-commit"
+
+    # Get the new version
+    new_version = `ruby -e "puts Gem::Specification.load('llm_gateway.gemspec').version"`.strip
+
+    # Generate changelog with proper version
+    sh "bundle exec github_changelog_generator " \
+       "-u Hyper-Unearthing -p llm_gateway --future-release v#{new_version}"
+
+    # Bundle to update Gemfile.lock
+    sh "bundle"
+
+    # Add all changes and commit in one go
+    sh "git add ."
+    sh "git commit -m 'Bump llm_gateway to $(ruby -e \"puts Gem::Specification.load('llm_gateway.gemspec').version\")'"
+
+    # Tag and push
+    sh "git tag v$(ruby -e \"puts Gem::Specification.load('llm_gateway.gemspec').version\")"
+    sh "git push origin main --tags"
+
+    # Release the gem
+    sh "gem push $(gem build llm_gateway.gemspec | grep 'File:' | awk '{print $2}')"
   end
 rescue LoadError
   # gem-release not available in this environment

data/lib/llm_gateway/client.rb

@@ -2,9 +2,11 @@
 
 module LlmGateway
   class Client
-    def self.chat(model, message, response_format: "text", tools: nil, system: nil)
+    def self.chat(model, message, response_format: "text", tools: nil, system: nil, api_key: nil)
       client_klass = client_class(model)
-      client = client_klass.new(model_key: model)
+      client_options = { model_key: model }
+      client_options[:api_key] = api_key if api_key
+      client = client_klass.new(**client_options)
 
       input_mapper = input_mapper_for_client(client)
       normalized_input = input_mapper.map({

data/lib/llm_gateway/tool.rb

@@ -39,7 +39,7 @@ module LlmGateway
         definition[:name]
       end
 
-      def execute(input, login)
+      def execute(input)
         raise NotImplementedError, "Subclasses must implement execute"
       end
   end

data/lib/llm_gateway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LlmGateway
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

data/sample/claude_code_clone/agent.rb

@@ -0,0 +1,65 @@
+class Agent
+  def initialize(prompt_class, model, api_key)
+    @prompt_class = prompt_class
+    @model = model
+    @api_key = api_key
+    @transcript = []
+  end
+
+  def run(user_input, &block)
+    @transcript << { role: 'user', content: [ { type: 'text', text: user_input } ] }
+
+    begin
+      prompt = @prompt_class.new(@model, @transcript, @api_key)
+      result = prompt.post
+      process_response(result[:choices][0][:content], &block)
+    rescue => e
+      yield({ type: 'error', message: e.message }) if block_given?
+      raise e
+    end
+  end
+
+  private
+
+  def process_response(response, &block)
+    @transcript << { role: 'assistant', content: response }
+
+    response.each do |message|
+      yield(message) if block_given?
+
+      if message[:type] == 'text'
+        # Text response processed
+      elsif message[:type] == 'tool_use'
+        result = handle_tool_use(message)
+
+        tool_result = {
+          type: 'tool_result',
+          tool_use_id: message[:id],
+          content: result
+        }
+        @transcript << { role: 'user', content: [ tool_result ] }
+
+        yield(tool_result) if block_given?
+
+        follow_up_prompt = @prompt_class.new(@model, @transcript, @api_key)
+        follow_up = follow_up_prompt.post
+
+        process_response(follow_up[:choices][0][:content], &block) if follow_up[:choices][0][:content]
+      end
+    end
+
+    response
+  end
+
+  def handle_tool_use(message)
+    tool_class = @prompt_class.find_tool(message[:name])
+    if tool_class
+      tool = tool_class.new
+      tool.execute(message[:input])
+    else
+      "Unknown tool: #{message[:name]}"
+    end
+  rescue StandardError => e
+    "Error executing tool: #{e.message}"
+  end
+end

data/sample/claude_code_clone/claude_code_clone.rb

@@ -0,0 +1,40 @@
+require_relative 'prompt'
+require_relative 'agent'
+require 'debug'
+
+# Bash File Search Assistant using LlmGateway architecture
+
+class ClaudeCloneClone
+  def initialize(model, api_key)
+    @agent = Agent.new(Prompt, model, api_key)
+  end
+
+  def query(input)
+    begin
+      @agent.run(input) do |message|
+        case message[:type]
+        when 'text'
+          puts "\n\e[32m•\e[0m #{message[:text]}"
+        when 'tool_use'
+          puts "\n\e[33m•\e[0m \e[36m#{message[:name]}\e[0m"
+          if message[:input] && !message[:input].empty?
+            puts "  \e[90m#{message[:input]}\e[0m"
+          end
+        when 'tool_result'
+          if message[:content] && !message[:content].empty?
+            content_preview = message[:content].to_s.split("\n").first(3).join("\n")
+            if content_preview.length > 100
+              content_preview = content_preview[0..97] + "..."
+            end
+            puts "  \e[90m#{content_preview}\e[0m"
+          end
+        when 'error'
+          puts "\n\e[31m•\e[0m \e[91mError: #{message[:message]}\e[0m"
+        end
+      end
+    rescue => e
+      puts "\n\e[31m•\e[0m \e[91mError: #{e.message}\e[0m"
+      puts "\e[90m  #{e.backtrace.first}\e[0m" if e.backtrace&.first
+    end
+  end
+end

data/sample/claude_code_clone/prompt.rb

@@ -0,0 +1,79 @@
+require_relative 'tools/edit_tool'
+require_relative 'tools/read_tool'
+require_relative 'tools/todowrite_tool'
+require_relative 'tools/bash_tool'
+require_relative 'tools/grep_tool'
+
+class Prompt < LlmGateway::Prompt
+  def initialize(model, transcript, api_key)
+    super(model)
+    @transcript = transcript
+    @api_key = api_key
+  end
+
+  def prompt
+    @transcript
+  end
+
+  def system_prompt
+    <<~SYSTEM
+      You are Claude Code Clone, an interactive CLI tool that assists with software engineering tasks.
+
+      # Core Capabilities
+
+      I provide assistance with:
+      - Code analysis and debugging
+      - Feature implementation
+      - File editing and creation
+      - Running tests and builds
+      - Git operations
+      - Web browsing and research
+      - Task planning and management
+
+      ## Available Tools
+
+      You have access to these specialized tools:
+      - `Edit` - Modify existing files by replacing specific text strings
+      - `Read` - Read file contents with optional pagination
+      - `TodoWrite` - Create and manage structured task lists
+      - `Bash` - Execute shell commands with timeout support
+      - `Grep` - Search for patterns in files using regex
+
+      ## Core Instructions
+
+      I am designed to:
+      - Be concise and direct (minimize output tokens)
+      - Follow existing code conventions and patterns
+      - Use defensive security practices only
+      - Plan tasks with the TodoWrite tool for complex work
+      - Run linting/typechecking after making changes
+      - Never commit unless explicitly asked
+
+      ## Process
+
+      1. **Understand the Request**: Parse what the user needs accomplished
+      2. **Plan if Complex**: Use TodoWrite for multi-step tasks
+      3. **Execute Tools**: Use appropriate tools to complete the work
+      4. **Validate**: Run tests/linting when applicable
+      5. **Report**: Provide concise status updates
+
+      Always use the available tools to perform actions rather than just suggesting commands.
+
+      Before starting any task, build a todo list of what you need to do, ensuring each item is actionable and prioritized. Then, execute the tasks one by one, using the TodoWrite tool to track progress and completion.
+
+      After completing each task, update the TodoWrite list to reflect the status and any necessary follow-up actions.
+    SYSTEM
+  end
+
+  def self.tools
+    [ EditTool, ReadTool, TodoWriteTool, BashTool, GrepTool ]
+  end
+
+  def tools
+    self.class.tools.map(&:definition)
+  end
+
+  def post
+    LlmGateway::Client.chat(model, prompt, tools: tools, system: system_prompt, api_key: @api_key)
+  end
+end

data/sample/claude_code_clone/run.rb

@@ -0,0 +1,47 @@
+require 'tty-prompt'
+require_relative '../../lib/llm_gateway'
+require_relative 'claude_code_clone.rb'
+
+# Terminal Runner for FileSearchBot
+class FileSearchTerminalRunner
+  def initialize
+    @prompt = TTY::Prompt.new
+  end
+
+  def start
+    puts "First, let's configure your LLM settings:\n\n"
+
+    model, api_key = setup_configuration
+    bot = ClaudeCloneClone.new(model, api_key)
+
+    puts "Type 'quit' or 'exit' to stop.\n\n"
+
+    loop do
+      user_input = @prompt.ask("What can i do for you?")
+
+      break if [ 'quit', 'exit' ].include?(user_input.downcase)
+
+      bot.query(user_input)
+    end
+  end
+
+  private
+
+  def setup_configuration
+    model = @prompt.ask("Enter model (default: claude-3-7-sonnet-20250219):") do |q|
+      q.default 'claude-3-7-sonnet-20250219'
+    end
+
+    api_key = @prompt.mask("Enter your API key:") do |q|
+      q.required true
+    end
+
+    [ model, api_key ]
+  end
+end
+
+# Start the bot
+if __FILE__ == $0
+  runner = FileSearchTerminalRunner.new
+  runner.start
+end

data/sample/claude_code_clone/tools/bash_tool.rb

@@ -0,0 +1,54 @@
+class BashTool < LlmGateway::Tool
+  name 'Bash'
+  description 'Execute shell commands'
+  input_schema({
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'Shell command to execute' },
+      description: { type: 'string', description: 'Human-readable description' },
+      timeout: { type: 'integer', description: 'Timeout in milliseconds' }
+    },
+    required: [ 'command' ]
+  })
+
+  def execute(input)
+    command = input[:command]
+    description = input[:description]
+    timeout = input[:timeout] || 120000 # Default 2 minutes
+
+    if description
+      puts "Executing: #{command}"
+      puts "Description: #{description}\n\n"
+    else
+      puts "Executing: #{command}\n\n"
+    end
+
+    begin
+      # Convert timeout from milliseconds to seconds
+      timeout_seconds = timeout / 1000.0
+
+      # Use timeout command if available, otherwise use Ruby's timeout
+      if system('which timeout > /dev/null 2>&1')
+        result = `timeout #{timeout_seconds}s #{command} 2>&1`
+        exit_status = $?
+      else
+        require 'timeout'
+        result = Timeout.timeout(timeout_seconds) do
+          `#{command} 2>&1`
+        end
+        exit_status = $?
+      end
+
+      if exit_status.success?
+        result.empty? ? "Command completed successfully (no output)" : result
+      else
+        "Command failed with exit code #{exit_status.exitstatus}:\n#{result}"
+      end
+
+    rescue Timeout::Error
+      "Command timed out after #{timeout_seconds} seconds"
+    rescue => e
+      "Error executing command: #{e.message}"
+    end
+  end
+end

data/sample/claude_code_clone/tools/edit_tool.rb

@@ -0,0 +1,61 @@
+class EditTool < LlmGateway::Tool
+  name 'Edit'
+  description 'Modify existing files by replacing specific text strings'
+  input_schema({
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: 'Absolute path to file to modify' },
+      old_string: { type: 'string', description: 'Exact text to replace' },
+      new_string: { type: 'string', description: 'Replacement text' },
+      replace_all: { type: 'boolean', description: 'Replace all occurrences (default: false)' }
+    },
+    required: [ 'file_path', 'old_string', 'new_string' ]
+  })
+
+  def execute(input)
+    file_path = input[:file_path]
+    old_string = input[:old_string]
+    new_string = input[:new_string]
+    replace_all = input[:replace_all] || false
+
+    # Validate file exists
+    unless File.exist?(file_path)
+      return "Error: File not found at #{file_path}"
+    end
+
+    # Read file content
+    begin
+      content = File.read(file_path)
+    rescue => e
+      return "Error reading file: #{e.message}"
+    end
+
+    # Check if old_string exists in file
+    unless content.include?(old_string)
+      return "Error: Text '#{old_string}' not found in file"
+    end
+
+    # Perform replacement
+    if replace_all
+      updated_content = content.gsub(old_string, new_string)
+      occurrences = content.scan(old_string).length
+    else
+      # Replace only first occurrence
+      updated_content = content.sub(old_string, new_string)
+      occurrences = 1
+    end
+
+    # Check if replacement would result in same content
+    if content == updated_content
+      return "Error: old_string and new_string are identical, no changes made"
+    end
+
+    # Write updated content back to file
+    begin
+      File.write(file_path, updated_content)
+      "Successfully replaced #{occurrences} occurrence(s) in #{file_path}"
+    rescue => e
+      "Error writing file: #{e.message}"
+    end
+  end
+end

data/sample/claude_code_clone/tools/grep_tool.rb

@@ -0,0 +1,113 @@
+class GrepTool < LlmGateway::Tool
+  name 'Grep'
+  description 'Search for patterns in files using regex'
+  input_schema({
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Regex pattern to search for' },
+      path: { type: 'string', description: 'File or directory path' },
+      output_mode: {
+        type: 'string',
+        enum: [ 'content', 'files_with_matches', 'count' ],
+        description: 'Output mode: content, files_with_matches, or count'
+      },
+      glob: { type: 'string', description: 'File pattern filter (e.g., "*.rb")' },
+      '-n': { type: 'boolean', description: 'Show line numbers' },
+      '-i': { type: 'boolean', description: 'Case insensitive search' },
+      '-C': { type: 'integer', description: 'Context lines around matches' }
+    },
+    required: [ 'pattern' ]
+  })
+
+  def execute(input)
+    pattern = input[:pattern]
+    path = input[:path] || '.'
+    output_mode = input[:output_mode] || 'files_with_matches'
+    glob = input[:glob]
+    show_line_numbers = input['-n'] || false
+    case_insensitive = input['-i'] || false
+    context_lines = input['-C'] || 0
+
+    # Build grep command
+    cmd_parts = [ 'grep' ]
+
+    # Add flags
+    cmd_parts << '-r' unless File.file?(path) # Recursive for directories
+    cmd_parts << '-n' if show_line_numbers && output_mode == 'content'
+    cmd_parts << '-i' if case_insensitive
+    cmd_parts << "-C#{context_lines}" if context_lines > 0 && output_mode == 'content'
+
+    # Output mode flags
+    case output_mode
+    when 'files_with_matches'
+      cmd_parts << '-l'
+    when 'count'
+      cmd_parts << '-c'
+    end
+
+    # Add pattern and path
+    cmd_parts << "'#{pattern}'"
+
+    # Handle glob pattern
+    if glob
+      if File.directory?(path)
+        cmd_parts << "#{path}/**/*"
+        # Use shell globbing with find for better glob support
+        find_cmd = "find #{path} -name '#{glob}' -type f"
+        files_result = `#{find_cmd} 2>/dev/null`
+        if files_result.empty?
+          return "No files found matching pattern '#{glob}' in #{path}"
+        end
+
+        # Run grep on each matching file
+        files = files_result.strip.split("\n")
+        results = []
+
+        files.each do |file|
+          grep_cmd = cmd_parts[0..-2].join(' ') + " '#{pattern}' '#{file}'"
+          result = `#{grep_cmd} 2>/dev/null`
+          results << result unless result.empty?
+        end
+
+        return results.empty? ? "No matches found" : results.join("\n")
+      else
+        cmd_parts << path
+      end
+    else
+      cmd_parts << path
+    end
+
+    command = cmd_parts.join(' ')
+
+    begin
+      puts "Executing: #{command}"
+      result = `#{command} 2>&1`
+      exit_status = $?
+
+      if exit_status.success?
+        if result.empty?
+          "No matches found"
+        else
+          case output_mode
+          when 'content'
+            result
+          when 'files_with_matches'
+            result
+          when 'count'
+            result
+          else
+            result
+          end
+        end
+      elsif exit_status.exitstatus == 1
+        # grep returns 1 when no matches found, which is normal
+        "No matches found"
+      else
+        "Error: #{result}"
+      end
+
+    rescue => e
+      "Error executing grep: #{e.message}"
+    end
+  end
+end

data/sample/claude_code_clone/tools/read_tool.rb

@@ -0,0 +1,61 @@
+class ReadTool < LlmGateway::Tool
+  name 'Read'
+  description 'Read file contents with optional pagination'
+  input_schema({
+    type: 'object',
+    properties: {
+      file_path: { type: 'string', description: 'Absolute path to file' },
+      limit: { type: 'integer', description: 'Number of lines to read' },
+      offset: { type: 'integer', description: 'Starting line number' }
+    },
+    required: [ 'file_path' ]
+  })
+
+  def execute(input)
+    file_path = input[:file_path]
+    limit = input[:limit]
+    offset = input[:offset] || 0
+
+    # Validate file exists
+    unless File.exist?(file_path)
+      return "Error: File not found at #{file_path}"
+    end
+
+    # Check if it's a directory
+    if File.directory?(file_path)
+      return "Error: #{file_path} is a directory, not a file"
+    end
+
+    begin
+      lines = File.readlines(file_path, chomp: true)
+
+      # Apply offset
+      if offset > 0
+        if offset >= lines.length
+          return "Error: Offset #{offset} exceeds file length (#{lines.length} lines)"
+        end
+        lines = lines[offset..-1]
+      end
+
+      # Apply limit
+      if limit && limit > 0
+        lines = lines[0, limit]
+      end
+
+      # Format output with line numbers (similar to cat -n)
+      output = lines.each_with_index.map do |line, index|
+        line_number = offset + index + 1
+        "#{line_number.to_s.rjust(6)}→#{line}"
+      end
+
+      if output.empty?
+        "File is empty or no lines in specified range"
+      else
+        output.join("\n")
+      end
+
+    rescue => e
+      "Error reading file: #{e.message}"
+    end
+  end
+end

data/sample/claude_code_clone/tools/todowrite_tool.rb

@@ -0,0 +1,98 @@
+require 'json'
+
+class TodoWriteTool < LlmGateway::Tool
+  name 'TodoWrite'
+  description 'Create and manage structured task lists'
+  input_schema({
+    type: 'object',
+    properties: {
+      todos: {
+        type: 'array',
+        description: 'Array of todo objects',
+        items: {
+          type: 'object',
+          properties: {
+            id: { type: 'string', description: 'Unique identifier' },
+            content: { type: 'string', description: 'Task description' },
+            status: {
+              type: 'string',
+              enum: [ 'pending', 'in_progress', 'completed' ],
+              description: 'Task status'
+            },
+            priority: {
+              type: 'string',
+              enum: [ 'high', 'medium', 'low' ],
+              description: 'Task priority'
+            }
+          },
+          required: [ 'id', 'content', 'status', 'priority' ]
+        }
+      }
+    },
+    required: [ 'todos' ]
+  })
+
+  def execute(input)
+    todos = input[:todos]
+
+    # Validate todos structure
+    todos.each_with_index do |todo, index|
+      unless todo.is_a?(Hash)
+        return "Error: Todo at index #{index} is not a hash"
+      end
+
+      required_fields = [ 'id', 'content', 'status', 'priority' ]
+      missing_fields = required_fields - todo.keys.map(&:to_s)
+      unless missing_fields.empty?
+        return "Error: Todo at index #{index} missing required fields: #{missing_fields.join(', ')}"
+      end
+
+      valid_statuses = [ 'pending', 'in_progress', 'completed' ]
+      unless valid_statuses.include?(todo['status'])
+        return "Error: Invalid status '#{todo['status']}' in todo #{todo['id']}. Must be one of: #{valid_statuses.join(', ')}"
+      end
+
+      valid_priorities = [ 'high', 'medium', 'low' ]
+      unless valid_priorities.include?(todo['priority'])
+        return "Error: Invalid priority '#{todo['priority']}' in todo #{todo['id']}. Must be one of: #{valid_priorities.join(', ')}"
+      end
+    end
+
+    # Store todos (in practice, this might be saved to a file or database)
+    @todos = todos
+
+    # Generate summary
+    total = todos.length
+    pending = todos.count { |t| t['status'] == 'pending' }
+    in_progress = todos.count { |t| t['status'] == 'in_progress' }
+    completed = todos.count { |t| t['status'] == 'completed' }
+
+    summary = "Todo list updated successfully:\n"
+    summary += "Total tasks: #{total}\n"
+    summary += "Pending: #{pending}, In Progress: #{in_progress}, Completed: #{completed}\n\n"
+
+    # List current todos
+    summary += "Current tasks:\n"
+    todos.each do |todo|
+      status_icon = case todo['status']
+      when 'pending' then '⏳'
+      when 'in_progress' then '🔄'
+      when 'completed' then '✅'
+      end
+
+      priority_icon = case todo['priority']
+      when 'high' then '🔴'
+      when 'medium' then '🟡'
+      when 'low' then '🟢'
+      end
+
+      summary += "#{status_icon} #{priority_icon} [#{todo['id']}] #{todo['content']}\n"
+    end
+
+    summary
+  end
+
+  def self.current_todos
+    @todos || []
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: llm_gateway
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - billybonks
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-04 00:00:00.000000000 Z
+date: 2025-08-05 00:00:00.000000000 Z
 dependencies: []
 description: LlmGateway provides a consistent Ruby interface for multiple LLM providers
   including Claude, OpenAI, and Groq. Features include unified response formatting,
@@ -43,6 +43,15 @@ files:
 - lib/llm_gateway/tool.rb
 - lib/llm_gateway/utils.rb
 - lib/llm_gateway/version.rb
+- sample/claude_code_clone/agent.rb
+- sample/claude_code_clone/claude_code_clone.rb
+- sample/claude_code_clone/prompt.rb
+- sample/claude_code_clone/run.rb
+- sample/claude_code_clone/tools/bash_tool.rb
+- sample/claude_code_clone/tools/edit_tool.rb
+- sample/claude_code_clone/tools/grep_tool.rb
+- sample/claude_code_clone/tools/read_tool.rb
+- sample/claude_code_clone/tools/todowrite_tool.rb
 - sig/llm_gateway.rbs
 homepage: https://github.com/Hyper-Unearthing/llm_gateway
 licenses: