ruby_llm-docker 0.0.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05625b7756ab3721b9a1b6b5e91c798497ad16721628ad223145dcaa6f34891a
-  data.tar.gz: 2aa5e8fa18b3869e4ef03fb890382d784269245051f12b5242e16cb0fdd60b2a
+  metadata.gz: 17035d50b89aaa2e3cfd6409b1a827a3dc9d6e8cc6013e703105b1bce1d6a80e
+  data.tar.gz: aac7610a23113ca2b1cad98e1d7eaa88210d069cf7cf9eaedf28736c526b2599
 SHA512:
-  metadata.gz: 9919e675ec46e7905e4f9d76edba6d4006481de094ae38265e1091c2a4178f727591e270bb5940ac3adb98c12cdd78bdd57f8974a5e24ba45c4966e4eacbc574
-  data.tar.gz: 03edd42a7bc370cdef30b424a73178cc858b4865aa805cbfb19dc3d8512e8356507dc9d7fa19cdd3266a319dacfc0eba7dec83796a21799c4fd243eccd03acb7
+  metadata.gz: 152b3442d3130660f7aad1815a7d16918fe20c61a06579f7ab4815a97af25c49cb581c39103b5b08bcf352ad0052cd8e9c601b9e320e2a0606ba3a7ee5b096fa
+  data.tar.gz: 041ce68408938affab9523541f1adb283a6c279e69d3b8abdcc6842c47154da1d0441dcb8a44a05f71c1ed382e4624c5d3136d45f5340c17ed8e9b8a96533176

data/README.md

@@ -1,38 +1,282 @@
-# RubyLlm::Docker
+# RubyLLM Docker Tools
 
-TODO: Delete this and the text below, and describe your gem
+A comprehensive Ruby gem that provides Docker management capabilities through [RubyLLM](https://github.com/afstanton/ruby_llm) tools. This library enables AI assistants and chatbots to interact with Docker containers, images, networks, and volumes programmatically using natural language.
 
-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/ruby_llm/docker`. To experiment with that code, run `bin/console` for an interactive prompt.
+**Note:** This gem is a port of the [DockerMCP](https://github.com/afstanton/docker_mcp) gem, adapted to work directly with RubyLLM tools instead of requiring an external MCP server.
 
-## Installation
+## ⚠️ Security Warning
+
+**This tool is inherently unsafe and should be used with extreme caution.**
+
+- **Arbitrary Code Execution**: The `exec_container` tool allows execution of arbitrary commands inside Docker containers
+- **File System Access**: The `copy_to_container` tool can copy files from the host system into containers
+- **Container Management**: Full container lifecycle management including creation, modification, and deletion
+- **Network & Volume Control**: Complete control over Docker networks and volumes
 
-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.
+**Recommendations:**
+- Only use in trusted environments
+- Ensure proper Docker daemon security configuration
+- Consider running with restricted Docker permissions
+- Monitor and audit all container operations
+- Be cautious when exposing these tools in production environments
+
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add ruby_llm-docker
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install ruby_llm-docker
 ```
 
+## Prerequisites
+
+- Docker Engine installed and running
+- Ruby 3.2+
+- Docker permissions for the user running the application
+- RubyLLM gem
+
 ## Usage
 
-TODO: Write usage instructions here
+### Basic Setup
+
+```ruby
+require 'ruby_llm/docker'
+
+# Create a new chat instance
+chat = RubyLLM::Chat.new(
+  api_key: 'your-openai-api-key',
+  model: 'gpt-4'
+)
+
+# Add all Docker tools to the chat
+RubyLLM::Docker.add_all_tools_to_chat(chat)
+
+# Or add individual tools
+chat.tools << RubyLLM::Docker::ListContainers.new
+chat.tools << RubyLLM::Docker::RunContainer.new
+# ... etc
+```
+
+### Interactive Command Line Tool
+
+This gem includes a ready-to-use interactive command line tool:
+
+```bash
+# Set your OpenAI API key
+export OPENAI_API_KEY='your-key-here'
+
+# Run the interactive Docker chat
+ruby -r 'ruby_llm/docker' -e "
+require_relative 'examples/docker_chat.rb'
+DockerChat.new.start
+"
+```
+
+Or use the included example script:
+
+```bash
+ruby examples/docker_chat.rb
+```
+
+### Example Usage
+
+Once configured, you can interact with Docker using natural language:
+
+```ruby
+# List all containers
+response = chat.ask("How many containers are currently running?")
+
+# Create and run a new container
+response = chat.ask("Create a new nginx container named 'my-web-server' and expose port 8080")
+
+# Execute commands in a container
+response = chat.ask("Check the nginx version in the my-web-server container")
+
+# Copy files to a container
+response = chat.ask("Copy my local config.txt file to /etc/nginx/ in the web server container")
+
+# View container logs
+response = chat.ask("Show me the logs for the my-web-server container")
+```
+
+## 🔨 Available Tools
+
+This gem provides 22 comprehensive Docker management tools organized by functionality:
+
+### Container Management
+
+- **`ListContainers`** - List all Docker containers (running and stopped) with detailed information
+- **`CreateContainer`** - Create a new container from an image without starting it
+- **`RunContainer`** - Create and immediately start a container from an image
+- **`StartContainer`** - Start an existing stopped container
+- **`StopContainer`** - Stop a running container gracefully
+- **`RemoveContainer`** - Delete a container (must be stopped first unless forced)
+- **`RecreateContainer`** - Stop, remove, and recreate a container with the same configuration
+- **`ExecContainer`** ⚠️ - Execute arbitrary commands inside a running container
+- **`FetchContainerLogs`** - Retrieve stdout/stderr logs from a container
+- **`CopyToContainer`** ⚠️ - Copy files or directories from host to container
+
+### Image Management
+
+- **`ListImages`** - List all Docker images available locally
+- **`PullImage`** - Download an image from a Docker registry
+- **`PushImage`** - Upload an image to a Docker registry
+- **`BuildImage`** - Build a new image from a Dockerfile
+- **`TagImage`** - Create a new tag for an existing image
+- **`RemoveImage`** - Delete an image from local storage
+
+### Network Management
+
+- **`ListNetworks`** - List all Docker networks
+- **`CreateNetwork`** - Create a new Docker network
+- **`RemoveNetwork`** - Delete a Docker network
+
+### Volume Management
+
+- **`ListVolumes`** - List all Docker volumes
+- **`CreateVolume`** - Create a new Docker volume for persistent data
+- **`RemoveVolume`** - Delete a Docker volume
+
+### Tool Parameters
+
+Most tools accept standard Docker parameters:
+- **Container ID/Name**: Can use either the full container ID, short ID, or container name
+- **Image**: Specify images using `name:tag` format (e.g., `nginx:latest`, `ubuntu:22.04`)
+- **Ports**: Use Docker port mapping syntax (e.g., `"8080:80"`)
+- **Volumes**: Use Docker volume mount syntax (e.g., `"/host/path:/container/path"`)
+- **Environment**: Set environment variables as comma-separated `KEY=VALUE` pairs (e.g., `"NODE_ENV=production,PORT=3000"`)
+
+## Common Use Cases
+
+### Development Environment Setup
+```ruby
+# Ask the AI to set up a development environment
+response = chat.ask("Pull the node:18-alpine image and create a development container
+  named 'dev-env' with port 3000 exposed and my current directory mounted as /app")
+
+# Install dependencies and start the application
+response = chat.ask("Run 'npm install' in the dev-env container")
+response = chat.ask("Start the application with 'npm start' in the dev-env container")
+```
+
+### Container Debugging
+```ruby
+# Check container status and debug issues
+response = chat.ask("Show me all containers and their current status")
+response = chat.ask("Get the logs for the problematic-container")
+response = chat.ask("Check the running processes in the problematic-container")
+response = chat.ask("Show disk usage in the problematic-container")
+```
+
+### File Management
+```ruby
+# Copy files to containers using natural language
+response = chat.ask("Copy my local nginx.conf file to /etc/nginx/ in the web-server container")
+response = chat.ask("Copy the entire src directory to /app/ in the app-container")
+```
+
+## Error Handling
+
+The tools provide detailed error messages for common issues:
+
+- **Container Not Found**: When referencing non-existent containers
+- **Image Not Available**: When trying to use images that aren't pulled locally
+- **Permission Denied**: When Docker daemon access is restricted
+- **Network Conflicts**: When creating networks with conflicting configurations
+- **Volume Mount Issues**: When specified paths don't exist or lack permissions
+
+All errors include descriptive messages to help diagnose and resolve issues.
+
+## Troubleshooting
+
+### Docker Daemon Connection Issues
+```bash
+# Check if Docker daemon is running
+docker info
+
+# Verify Docker permissions
+docker ps
+```
+
+### Container Operation Failures
+- Ensure container IDs/names are correct (ask the AI to list containers)
+- Check if containers are in the expected state (running/stopped)
+- Verify image availability (ask the AI to list available images)
+
+### Permission Issues
+- Ensure the user running the application has Docker permissions
+- Consider adding user to the `docker` group: `sudo usermod -aG docker $USER`
+- Verify Docker socket permissions: `ls -la /var/run/docker.sock`
+
+## Limitations
+
+- **Platform Specific**: Some container operations may behave differently across operating systems
+- **Docker API Version**: Requires compatible Docker Engine API version
+- **Resource Limits**: Large file copies and image operations may timeout
+- **Concurrent Operations**: Heavy concurrent usage may impact performance
+
+## Contributing
+
+We welcome contributions! Areas for improvement:
+
+- **Enhanced Security**: Additional safety checks and permission validation
+- **Better Error Handling**: More specific error messages and recovery suggestions
+- **Performance Optimization**: Streaming for large file operations
+- **Extended Functionality**: Support for Docker Compose, Swarm, etc.
+- **Testing**: Comprehensive test coverage for all tools
 
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-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).
+### Running Tests
+```bash
+# Install dependencies
+bundle install
 
-## Contributing
+# Run the test suite
+bundle exec rake spec
+
+# Run tests with coverage
+bundle exec rake spec COVERAGE=true
+```
+
+### Local Development Setup
+```bash
+# Clone the repository
+git clone https://github.com/afstanton/ruby_llm-docker.git
+cd ruby_llm-docker
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ruby_llm-docker.
+# Install dependencies
+bin/setup
+
+# Start development console
+bin/console
+
+# Build the gem locally
+bundle exec rake build
+
+# Install locally built gem
+bundle exec rake install
+```
+
+### Testing with RubyLLM
+```bash
+# Test the interactive chat tool
+export OPENAI_API_KEY='your-key-here'
+ruby examples/docker_chat.rb
+
+# Test tool loading without API calls
+ruby examples/test_chat.rb
+```
+
+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).
 
 ## License
 

data/Rakefile

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+require 'rubocop/rake_task'
 
 RuboCop::RakeTask.new
 

data/examples/docker_chat.rb

@@ -0,0 +1,269 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Docker Chat - Interactive command line tool for RubyLLM
+# A comprehensive chat interface with all Docker management tools available
+# through natural language interaction powered by OpenAI and RubyLLM
+#
+# Prerequisites:
+#   - Set OPENAI_API_KEY environment variable
+#   - Docker daemon running and accessible
+#
+# Usage:
+#   export OPENAI_API_KEY='your-key-here'
+#   ruby examples/docker_chat.rb
+#
+# Debug mode:
+#   ruby examples/docker_chat.rb --debug        # Enable debug output
+#   DOCKER_CHAT_DEBUG=true ruby examples/docker_chat.rb   # Via environment variable
+#
+# Commands:
+#   /exit      - Exit the chat
+#   /help      - Show available Docker tools
+#   /tools     - List all loaded tools
+#   /clear     - Clear the screen
+#   /debug     - Toggle debug mode on/off
+#   anything else - Send to OpenAI with Docker tools available
+
+require_relative '../lib/ruby_llm/docker'
+require 'io/console'
+
+# rubocop:disable Metrics/ClassLength
+
+# Interactive Docker chat interface using RubyLLM and OpenAI.
+# Provides natural language interaction with Docker containers, images, networks, and volumes.
+class DockerChat
+  def initialize
+    check_environment
+    configure_ruby_llm
+    setup_debug_mode
+    setup_chat
+    @running = true
+  end
+
+  def start
+    show_welcome
+    main_loop
+    show_goodbye
+  end
+
+  private
+
+  def check_environment
+    return if ENV['OPENAI_API_KEY']
+
+    puts '❌ Error: Please set OPENAI_API_KEY environment variable'
+    puts "Example: export OPENAI_API_KEY='your-api-key-here'"
+    exit 1
+  end
+
+  def configure_ruby_llm
+    RubyLLM.configure do |config|
+      config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+    end
+  end
+
+  def setup_debug_mode
+    # Check for debug mode via environment variable or command line argument
+    @debug_mode = ENV['DOCKER_CHAT_DEBUG'] == 'true' || ARGV.include?('--debug') || ARGV.include?('-d')
+    debug_puts '🐛 Debug mode enabled' if @debug_mode
+  end
+
+  def debug_puts(message)
+    puts message if @debug_mode
+  end
+
+  def setup_chat
+    # rubocop:disable Layout/BlockAlignment
+    # rubocop:disable Style/MultilineBlockChain
+    @chat = RubyLLM.chat(model: 'gpt-4')
+                   .on_tool_call do |tool_call|
+                      debug_puts "🔧 Calling tool: #{tool_call.name}"
+                      debug_puts "📝 Arguments: #{tool_call.arguments}"
+                    end
+                    .on_tool_result do |result|
+                      debug_puts "✅ Tool returned: #{result}"
+                    end
+    # rubocop:enable Layout/BlockAlignment
+    # rubocop:enable Style/MultilineBlockChain
+
+    # Add all Docker tools to the chat
+    RubyLLM::Docker.add_all_tools_to_chat(@chat)
+
+    puts '🔧 Loading Docker tools...'
+    puts "✅ Loaded #{RubyLLM::Docker.all_tools.size} Docker tools"
+  end
+
+  def show_welcome
+    puts "\n#{'=' * 60}"
+    puts '🐳 Welcome to Docker Chat!'
+    puts '   Interactive CLI with all Docker tools available'
+    puts '=' * 60
+    puts
+    puts '💡 You can ask questions about Docker containers, images, networks, and volumes.'
+    puts '   OpenAI has access to all Docker management tools on this system.'
+    puts
+    puts 'Commands:'
+    puts '  /exit  - Exit the chat'
+    puts '  /help  - Show available Docker tools'
+    puts '  /tools - List all loaded tools'
+    puts '  /clear - Clear the screen'
+    puts '  /debug - Toggle debug mode on/off'
+    puts
+    puts '🚀 Ready! Type your questions or commands...'
+    puts
+    debug_puts '🐛 Debug mode is currently enabled. Use /debug to toggle.'
+  end
+
+  def main_loop
+    while @running
+      print "\n🐳 > "
+
+      begin
+        input = gets&.chomp
+
+        # Handle Ctrl+C or EOF
+        if input.nil?
+          @running = false
+          break
+        end
+
+        process_input(input.strip)
+      rescue Interrupt
+        puts "\n\n👋 Received interrupt signal. Use /exit to quit cleanly."
+      rescue StandardError => e
+        puts "❌ Error: #{e.message}"
+        puts '   Please try again or type /exit to quit.'
+      end
+    end
+  end
+
+  def process_input(input)
+    return if input.empty?
+
+    case input.downcase
+    when '/exit', '/quit', '/q'
+      @running = false
+    when '/help', '/h'
+      show_help
+    when '/tools', '/t'
+      show_tools
+    when '/clear', '/c'
+      clear_screen
+    when '/debug', '/d'
+      toggle_debug_mode
+    when input.start_with?('/')
+      puts "❓ Unknown command: #{input}"
+      puts '   Type /help for available commands'
+    else
+      handle_chat_message(input)
+    end
+  end
+
+  def handle_chat_message(message)
+    puts "\n🤔 Thinking..."
+
+    begin
+      response = @chat.ask(message)
+
+      puts "\n🤖 OpenAI Response:"
+      puts '─' * 50
+      puts response.content
+      puts '─' * 50
+    rescue StandardError => e
+      puts "\n❌ Error communicating with OpenAI:"
+      puts "   #{e.class}: #{e.message}"
+      puts '   Please check your API key and network connection.'
+    end
+  end
+
+  def show_help
+    puts "\n📚 Available Docker Tools:"
+    puts '─' * 50
+
+    tools_by_category = {
+      'Container Management' => [
+        'ListContainers - List all Docker containers',
+        'CreateContainer - Create new containers',
+        'RunContainer - Create and start containers',
+        'StartContainer - Start stopped containers',
+        'StopContainer - Stop running containers',
+        'RemoveContainer - Delete containers',
+        'RecreateContainer - Recreate containers with same config',
+        'ExecContainer - Execute commands inside containers',
+        'CopyToContainer - Copy files to containers',
+        'FetchContainerLogs - Get container logs'
+      ],
+      'Image Management' => [
+        'ListImages - List available Docker images',
+        'PullImage - Download images from registries',
+        'BuildImage - Build images from Dockerfile',
+        'TagImage - Tag images with new names',
+        'PushImage - Upload images to registries',
+        'RemoveImage - Delete images'
+      ],
+      'Network Management' => [
+        'ListNetworks - List Docker networks',
+        'CreateNetwork - Create custom networks',
+        'RemoveNetwork - Delete networks'
+      ],
+      'Volume Management' => [
+        'ListVolumes - List Docker volumes',
+        'CreateVolume - Create persistent volumes',
+        'RemoveVolume - Delete volumes'
+      ]
+    }
+
+    tools_by_category.each do |category, tools|
+      puts "\n#{category}:"
+      tools.each { |tool| puts "  • #{tool}" }
+    end
+
+    puts "\n💡 Example questions you can ask:"
+    puts "  • 'How many containers are running?'"
+    puts "  • 'Show me all Docker images'"
+    puts "  • 'Create a new nginx container named web-server'"
+    puts "  • 'What networks are available?'"
+    puts "  • 'Pull the latest Ubuntu image'"
+  end
+
+  def show_tools
+    puts "\n🔧 Loaded Tools (#{RubyLLM::Docker.all_tools.size}):"
+    puts '─' * 30
+
+    RubyLLM::Docker.all_tools.each_with_index do |tool_class, index|
+      tool_name = tool_class.name.split('::').last
+      puts "#{(index + 1).to_s.rjust(2)}. #{tool_name}"
+    end
+  end
+
+  def clear_screen
+    system('clear') || system('cls')
+    puts '🐳 Docker Chat - Screen cleared'
+  end
+
+  def toggle_debug_mode
+    @debug_mode = !@debug_mode
+    status = @debug_mode ? 'enabled' : 'disabled'
+    puts "🐛 Debug mode #{status}"
+    debug_puts 'Debug output will now be shown for tool calls and results' if @debug_mode
+  end
+
+  def show_goodbye
+    puts "\n👋 Thanks for using Docker Chat!"
+    puts '   Hope you found it helpful for managing your Docker environment.'
+    puts
+  end
+end
+# rubocop:enable Metrics/ClassLength
+
+# Start the chat if this file is run directly
+if __FILE__ == $PROGRAM_NAME
+  begin
+    DockerChat.new.start
+  rescue StandardError => e
+    puts "\n💥 Fatal error: #{e.class} - #{e.message}"
+    puts '   Please check your setup and try again.'
+    exit 1
+  end
+end

data/examples/list_containers.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Using RubyLLM with Docker ListContainers tool
+# This script creates a chat with OpenAI and asks about Docker containers
+
+require_relative '../lib/ruby_llm/docker'
+
+# Check if OpenAI API key is configured
+unless ENV['OPENAI_API_KEY']
+  puts 'Error: Please set OPENAI_API_KEY environment variable'
+  puts "Example: export OPENAI_API_KEY='your-api-key-here'"
+  exit 1
+end
+
+RubyLLM.configure do |config|
+  config.openai_api_key = ENV.fetch('OPENAI_API_KEY', nil)
+end
+
+begin
+  # Create a new RubyLLM chat instance
+  chat = RubyLLM.chat(model: 'gpt-4')
+
+  # Add the ListContainers tool
+  chat.with_tool(RubyLLM::Docker::ListContainers)
+
+  # Ask OpenAI how many containers there are
+  puts 'Asking OpenAI about Docker containers...'
+  response = chat.ask('How many Docker containers are currently on this system?')
+
+  puts "\nOpenAI Response:"
+  puts response.content
+rescue StandardError => e
+  puts "Error: #{e.class} - #{e.message}"
+  puts 'This helps us see what needs to be fixed in the ListContainers tool'
+end