llm_gateway 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98a42a5943a3b9797fa7ea4d782785e4932c65f7183eab6a452a86b2ca57e585
-  data.tar.gz: cbe9e03dc5d76ebfdc8ba911b6c077b803113922f3c470c67fdadcac1b779ff8
+  metadata.gz: 0fc0c0030bd149c9e3130d1f8e6fe2ccd0bfec5d87931534e4fc29d8808ad0c7
+  data.tar.gz: 1c9bf69153cfc502b41ef27305fcba114908a9debcdc34e9e2023fef257b4968
 SHA512:
-  metadata.gz: f58cb7936e3dcc9d643c1747f2d7404b2c1ca7474ad444f31178ce403351fba5ba1c981f91fabd1971097e7cb639b17709c9b62be9f784444d47d516801404b4
-  data.tar.gz: 45de5da177dbdd30d1490d1f5f2115a5b5d4e7adeb213d5a4a9c874bf99ed84d557e0e9988a77194bdcac2c491eb5903e4b66659d985284032bb6bfccba6cd1f
+  metadata.gz: 27ee426f1d8c3b97054e44b0d270d4eb8dd6d263fdf0717b1a47d655758ae634d1e25c12a850e468f4d360ca00beecfc430c9bfd3ed7a0a287bd0a48febcb110
+  data.tar.gz: fbc9b70052a776a99962b173842ede5016f4398504fca58d163a60f3eda52c58b2434c91d060bec3334c8c38e083c313692fb6b5442792943fcd3008ee44a08a

data/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 ## [Unreleased](https://github.com/Hyper-Unearthing/llm_gateway/tree/HEAD)
 
-[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.3...HEAD)
+
+**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:**
 
@@ -10,6 +28,10 @@
 - 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,183 +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/directory_bot/) 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
-
-You can combine the Prompt class with tools for more complex interactions:
-
-```ruby
-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
-    [{
-      name: 'get_weather',
-      description: 'Get current weather for a location',
-      input_schema: {
-        type: 'object',
-        properties: {
-          location: { type: 'string', description: 'City name' }
-        },
-        required: ['location']
-      }
-    }]
-  end
-end
+To run the sample:
 
-# Usage
-weather_prompt = WeatherAssistantPrompt.new('claude-sonnet-4-20250514', 'Singapore')
-result = weather_prompt.run
+```bash
+cd sample/directory_bot
+ruby run.rb
 ```
 
-### Tool Usage (Function Calling)
-
-```ruby
-# Define a 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']
-  }
-}
-
-# Use the tool
-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 = []
-  end
-
-  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

@@ -19,8 +19,17 @@ begin
     sh "git add CHANGELOG.md"
     sh "git commit -m 'Update changelog' || echo 'No changelog changes'"
 
+    # Ask for version bump type
+    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
+
     # Release
-    sh "gem bump --version patch --tag --push --release"
+    sh "gem bump --version #{version_type} --tag --push --release"
   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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module LlmGateway
+  class Tool
+      def initialize(*args)
+        # Empty constructor to allow subclasses to call super
+      end
+
+      def self.name(value = nil)
+        @name = value if value
+        @name
+      end
+
+      def self.description(value = nil)
+        @description = value if value
+        @description
+      end
+
+      def self.input_schema(value = nil)
+        @input_schema = value if value
+        @input_schema
+      end
+
+      def self.cache(value = nil)
+        @cache = value if value
+        @cache
+      end
+
+      def self.definition
+        {
+          name: @name,
+          description: @description,
+          input_schema: @input_schema,
+          cache_control: @cache ? { type: "ephemeral" } : nil
+        }.compact
+      end
+
+      def self.tool_name
+        definition[:name]
+      end
+
+      def execute(input, login)
+        raise NotImplementedError, "Subclasses must implement execute"
+      end
+  end
+end

data/lib/llm_gateway/version.rb

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

data/lib/llm_gateway.rb

@@ -7,6 +7,7 @@ require_relative "llm_gateway/fluent_mapper"
 require_relative "llm_gateway/base_client"
 require_relative "llm_gateway/client"
 require_relative "llm_gateway/prompt"
+require_relative "llm_gateway/tool"
 
 # Load adapters - order matters for inheritance
 require_relative "llm_gateway/adapters/claude/client"

data/sample/directory_bot/file_search_bot.rb

@@ -0,0 +1,72 @@
+require_relative 'file_search_tool'
+require_relative 'file_search_prompt'
+require 'debug'
+
+# Bash File Search Assistant using LlmGateway architecture
+
+class FileSearchBot
+  def initialize(model, api_key)
+    @transcript = []
+    @model = model
+    @api_key = api_key
+  end
+
+  def query(input)
+    process_query(input)
+  end
+
+  private
+
+  def process_query(query)
+    # Add user message to transcript
+    @transcript << { role: 'user', content: [ { type: 'text', text: query } ] }
+
+    begin
+      prompt = FileSearchPrompt.new(@model, @transcript, @api_key)
+      result = prompt.post
+      process_response(result[:choices][0][:content])
+    rescue => e
+      puts "Error: #{e.message}"
+      puts "Backtrace: #{e.backtrace.join("\n")}"
+      puts "I give up as bot"
+    end
+  end
+
+  def process_response(response)
+    # Add assistant response to transcript
+    @transcript << { role: 'assistant', content: response }
+
+    response.each do |message|
+      if message[:type] == 'text'
+        puts "\nBot: #{message[:text]}\n"
+      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 tool result
+        follow_up_prompt = FileSearchPrompt.new(@model, @transcript, @api_key)
+        follow_up = follow_up_prompt.post
+
+        process_response(follow_up[:choices][0][:content]) if follow_up[:choices][0][:content]
+      end
+    end
+  end
+
+  def handle_tool_use(message)
+    if message[:name] == 'execute_bash_command'
+      tool = FileSearchTool.new
+      tool.execute(message[:input])
+    else
+      "Unknown tool: #{message[:name]}"
+    end
+  rescue StandardError => e
+    "Error executing tool: #{e.message}"
+  end
+end

data/sample/directory_bot/file_search_prompt.rb

@@ -0,0 +1,56 @@
+require_relative 'file_search_tool'
+
+class FileSearchPrompt < 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 a helpful assistant that can find things for them in directories.
+
+      # Bash File Search Assistant
+
+      You are a bash command-line assistant specialized in helping users find information in files and directories. Your role is to translate natural language queries into effective bash commands using search and file inspection tools.
+
+      ## Available Commands
+
+      You have access to these bash commands:
+      - `find` - Locate files and directories by name, type, size, date, etc.
+      - `grep` - Search for text patterns within files
+      - `cat` - Display entire file contents
+      - `head` - Show first lines of files
+      - `tail` - Show last lines of files
+      - `ls` - List directory contents with various options
+      - `wc` - Count lines, words, characters
+      - `sort` - Sort file contents
+      - `uniq` - Remove duplicate lines
+      - `awk` - Text processing and pattern extraction
+      - `sed` - Stream editing and text manipulation
+
+      ## Your Process
+
+      1. **Understand the Query**: Parse what the user is looking for
+      2. **Choose Strategy**: Determine the best combination of commands
+      3. **Execute Commands**: Use the execute_bash_command tool with exact bash commands
+      4. **Explain**: Briefly explain what each command does
+      5. **Suggest Refinements**: Offer ways to narrow or expand the search if needed
+
+      Always use the execute_bash_command tool to run commands rather than just suggesting them.
+    SYSTEM
+  end
+
+  def tools
+    [ FileSearchTool.definition ]
+  end
+
+  def post
+    LlmGateway::Client.chat(model, prompt, tools: tools, system: system_prompt, api_key: @api_key)
+  end
+end

data/sample/directory_bot/file_search_tool.rb

@@ -0,0 +1,32 @@
+
+class FileSearchTool < LlmGateway::Tool
+  name 'execute_bash_command'
+  description 'Execute bash commands for file searching and directory exploration'
+  input_schema({
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'The bash command to execute' },
+      explanation: { type: 'string', description: 'Explanation of what the command does' }
+    },
+    required: [ 'command', 'explanation' ]
+  })
+
+  def execute(input, login = nil)
+    command = input[:command]
+    explanation = input[:explanation]
+
+    puts "Executing: #{command}"
+    puts "Purpose: #{explanation}\n\n"
+
+    begin
+      result = `#{command} 2>&1`
+      if $?.success?
+        result.empty? ? "Command completed successfully (no output)" : result
+      else
+        "Error: #{result}"
+      end
+    rescue => e
+      "Error executing command: #{e.message}"
+    end
+  end
+end

data/sample/directory_bot/run.rb

@@ -0,0 +1,49 @@
+require 'tty-prompt'
+require_relative '../../lib/llm_gateway'
+require_relative 'file_search_bot'
+
+# Terminal Runner for FileSearchBot
+class FileSearchTerminalRunner
+  def initialize
+    @prompt = TTY::Prompt.new
+  end
+
+  def start
+    puts "File Search Assistant - I can help you find files and search through directories."
+    puts "First, let's configure your LLM settings:\n\n"
+
+    model, api_key = setup_configuration
+    bot = FileSearchBot.new(model, api_key)
+
+    puts "\nGreat! Now you can start searching."
+    puts "Type 'quit' or 'exit' to stop.\n\n"
+
+    loop do
+      user_input = @prompt.ask("What would you like to find?")
+
+      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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_gateway
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - billybonks
@@ -40,8 +40,13 @@ files:
 - lib/llm_gateway/errors.rb
 - lib/llm_gateway/fluent_mapper.rb
 - lib/llm_gateway/prompt.rb
+- lib/llm_gateway/tool.rb
 - lib/llm_gateway/utils.rb
 - lib/llm_gateway/version.rb
+- sample/directory_bot/file_search_bot.rb
+- sample/directory_bot/file_search_prompt.rb
+- sample/directory_bot/file_search_tool.rb
+- sample/directory_bot/run.rb
 - sig/llm_gateway.rbs
 homepage: https://github.com/Hyper-Unearthing/llm_gateway
 licenses: