tsikol 0.1.0

data/docs/cookbook/dynamic-tools.md

@@ -0,0 +1,970 @@
+# Dynamic Tools Recipe
+
+This recipe shows how to create and register tools dynamically at runtime, enabling flexible and adaptable MCP servers.
+
+## Basic Dynamic Tool Creation
+
+### Runtime Tool Registration
+
+```ruby
+class DynamicToolManager
+  def initialize(server)
+    @server = server
+    @dynamic_tools = {}
+  end
+  
+  def create_tool(name, description, parameters, &block)
+    # Create a new tool class dynamically
+    tool_class = Class.new(Tsikol::Tool) do
+      # Set description
+      class_eval { description description }
+      
+      # Define parameters
+      parameters.each do |param_name, param_config|
+        parameter param_name do
+          type param_config[:type]
+          param_config[:required] ? required : optional
+          default param_config[:default] if param_config[:default]
+          enum param_config[:enum] if param_config[:enum]
+          description param_config[:description]
+          
+          if param_config[:complete]
+            complete(&param_config[:complete])
+          end
+        end
+      end
+      
+      # Define execute method
+      define_method(:execute, &block)
+    end
+    
+    # Set the tool name
+    tool_class.define_singleton_method(:name) { name }
+    
+    # Register with server
+    @server.register_tool_class(tool_class)
+    @dynamic_tools[name] = tool_class
+    
+    log :info, "Dynamic tool created", name: name
+    
+    tool_class
+  end
+  
+  def remove_tool(name)
+    if @dynamic_tools[name]
+      @server.unregister_tool(name)
+      @dynamic_tools.delete(name)
+      log :info, "Dynamic tool removed", name: name
+      true
+    else
+      false
+    end
+  end
+  
+  def list_dynamic_tools
+    @dynamic_tools.keys
+  end
+end
+
+# Usage
+Tsikol.start(name: "dynamic-server") do
+  tool_manager = DynamicToolManager.new(self)
+  
+  # Create a dynamic tool
+  tool_manager.create_tool(
+    "custom_calculator",
+    "Performs custom calculations",
+    {
+      expression: {
+        type: :string,
+        required: true,
+        description: "Mathematical expression"
+      },
+      variables: {
+        type: :object,
+        required: false,
+        default: {},
+        description: "Variable values"
+      }
+    }
+  ) do |expression:, variables: {}|
+    # Tool implementation
+    evaluator = MathEvaluator.new(variables)
+    evaluator.evaluate(expression)
+  end
+  
+  # Store tool manager for later use
+  @tool_manager = tool_manager
+end
+```
+
+### Plugin-Based Tools
+
+```ruby
+class PluginSystem
+  def initialize(server, plugin_dir = "plugins")
+    @server = server
+    @plugin_dir = plugin_dir
+    @loaded_plugins = {}
+  end
+  
+  def load_plugins
+    Dir.glob(File.join(@plugin_dir, "*.rb")).each do |plugin_file|
+      load_plugin(plugin_file)
+    end
+  end
+  
+  def load_plugin(plugin_file)
+    plugin_name = File.basename(plugin_file, ".rb")
+    
+    begin
+      # Load plugin code
+      plugin_code = File.read(plugin_file)
+      plugin_module = Module.new
+      plugin_module.module_eval(plugin_code)
+      
+      # Find tool classes in the plugin
+      tool_classes = plugin_module.constants.select do |const|
+        klass = plugin_module.const_get(const)
+        klass.is_a?(Class) && klass < Tsikol::Tool
+      end
+      
+      # Register tools
+      tool_classes.each do |tool_const|
+        tool_class = plugin_module.const_get(tool_const)
+        @server.register_tool_class(tool_class)
+        
+        @loaded_plugins[plugin_name] ||= []
+        @loaded_plugins[plugin_name] << tool_class
+      end
+      
+      log :info, "Plugin loaded", 
+          name: plugin_name, 
+          tools: tool_classes.map(&:to_s)
+      
+      true
+      
+    rescue => e
+      log :error, "Failed to load plugin", 
+          name: plugin_name, 
+          error: e.message
+      false
+    end
+  end
+  
+  def unload_plugin(plugin_name)
+    if tools = @loaded_plugins[plugin_name]
+      tools.each do |tool_class|
+        @server.unregister_tool(tool_class.name)
+      end
+      
+      @loaded_plugins.delete(plugin_name)
+      log :info, "Plugin unloaded", name: plugin_name
+      true
+    else
+      false
+    end
+  end
+  
+  def reload_plugin(plugin_name)
+    unload_plugin(plugin_name)
+    load_plugin(File.join(@plugin_dir, "#{plugin_name}.rb"))
+  end
+end
+
+# Example plugin file: plugins/string_tools.rb
+class StringReverse < Tsikol::Tool
+  description "Reverses a string"
+  
+  parameter :text do
+    type :string
+    required
+    description "Text to reverse"
+  end
+  
+  def execute(text:)
+    text.reverse
+  end
+end
+
+class StringCapitalize < Tsikol::Tool
+  description "Capitalizes words in a string"
+  
+  parameter :text do
+    type :string
+    required
+    description "Text to capitalize"
+  end
+  
+  parameter :style do
+    type :string
+    optional
+    default "title"
+    enum ["title", "sentence", "all"]
+  end
+  
+  def execute(text:, style: "title")
+    case style
+    when "title"
+      text.split.map(&:capitalize).join(" ")
+    when "sentence"
+      text.capitalize
+    when "all"
+      text.upcase
+    end
+  end
+end
+```
+
+## Configuration-Based Tools
+
+### YAML Tool Definition
+
+```ruby
+class ConfigBasedToolLoader
+  def initialize(server)
+    @server = server
+  end
+  
+  def load_from_yaml(yaml_file)
+    config = YAML.load_file(yaml_file)
+    
+    config["tools"].each do |tool_config|
+      create_tool_from_config(tool_config)
+    end
+  end
+  
+  def create_tool_from_config(config)
+    tool_class = Class.new(Tsikol::Tool) do
+      description config["description"]
+      
+      # Define parameters
+      config["parameters"].each do |param|
+        parameter param["name"].to_sym do
+          type param["type"].to_sym
+          param["required"] ? required : optional
+          default param["default"] if param["default"]
+          enum param["enum"] if param["enum"]
+          description param["description"]
+        end
+      end
+      
+      # Define execute method based on type
+      case config["type"]
+      when "command"
+        define_method(:execute) do |**params|
+          execute_command(config["command"], params)
+        end
+      when "http"
+        define_method(:execute) do |**params|
+          execute_http_request(config["endpoint"], config["method"], params)
+        end
+      when "script"
+        define_method(:execute) do |**params|
+          execute_script(config["script"], params)
+        end
+      end
+    end
+    
+    # Set tool name
+    tool_class.define_singleton_method(:name) { config["name"] }
+    
+    # Add helper methods
+    tool_class.class_eval do
+      def execute_command(command_template, params)
+        command = substitute_params(command_template, params)
+        
+        log :info, "Executing command", command: command
+        
+        output = `#{command} 2>&1`
+        success = $?.success?
+        
+        if success
+          output
+        else
+          raise "Command failed: #{output}"
+        end
+      end
+      
+      def execute_http_request(endpoint_template, method, params)
+        require 'net/http'
+        require 'uri'
+        
+        endpoint = substitute_params(endpoint_template, params)
+        uri = URI.parse(endpoint)
+        
+        response = case method.upcase
+        when "GET"
+          Net::HTTP.get_response(uri)
+        when "POST"
+          Net::HTTP.post_form(uri, params)
+        else
+          raise "Unsupported HTTP method: #{method}"
+        end
+        
+        if response.is_a?(Net::HTTPSuccess)
+          response.body
+        else
+          raise "HTTP request failed: #{response.code} #{response.message}"
+        end
+      end
+      
+      def execute_script(script_template, params)
+        script = substitute_params(script_template, params)
+        eval(script)
+      end
+      
+      def substitute_params(template, params)
+        result = template.dup
+        params.each do |key, value|
+          result.gsub!("{{#{key}}}", value.to_s)
+        end
+        result
+      end
+    end
+    
+    @server.register_tool_class(tool_class)
+    
+    log :info, "Tool created from config", name: config["name"]
+  end
+end
+
+# Example YAML configuration: tools.yaml
+# tools:
+#   - name: disk_usage
+#     description: Check disk usage
+#     type: command
+#     command: "df -h {{path}}"
+#     parameters:
+#       - name: path
+#         type: string
+#         required: false
+#         default: "/"
+#         description: "Path to check"
+#
+#   - name: weather
+#     description: Get weather information
+#     type: http
+#     endpoint: "http://api.weather.com/v1/weather?city={{city}}"
+#     method: GET
+#     parameters:
+#       - name: city
+#         type: string
+#         required: true
+#         description: "City name"
+```
+
+### Database-Driven Tools
+
+```ruby
+class DatabaseToolManager
+  def initialize(server, database)
+    @server = server
+    @database = database
+    @loaded_tools = {}
+  end
+  
+  def load_tools
+    tools = @database[:tools].where(enabled: true).all
+    
+    tools.each do |tool_record|
+      create_tool_from_record(tool_record)
+    end
+  end
+  
+  def create_tool_from_record(record)
+    tool_class = Class.new(Tsikol::Tool) do
+      description record[:description]
+      
+      # Load parameters
+      parameters = JSON.parse(record[:parameters])
+      parameters.each do |param_name, param_config|
+        parameter param_name.to_sym do
+          type param_config["type"].to_sym
+          param_config["required"] ? required : optional
+          default param_config["default"] if param_config["default"]
+          description param_config["description"]
+        end
+      end
+      
+      # Define execute method
+      implementation = record[:implementation]
+      implementation_type = record[:implementation_type]
+      
+      case implementation_type
+      when "ruby"
+        # Direct Ruby code
+        class_eval <<~RUBY
+          def execute(**params)
+            #{implementation}
+          end
+        RUBY
+      when "sql"
+        # SQL query
+        define_method(:execute) do |**params|
+          execute_sql_query(implementation, params)
+        end
+      when "api"
+        # API call configuration
+        config = JSON.parse(implementation)
+        define_method(:execute) do |**params|
+          execute_api_call(config, params)
+        end
+      end
+    end
+    
+    # Set tool name
+    tool_class.define_singleton_method(:name) { record[:name] }
+    tool_class.define_singleton_method(:tool_id) { record[:id] }
+    
+    # Add database helper methods
+    tool_class.class_eval do
+      def execute_sql_query(query_template, params)
+        query = substitute_params(query_template, params)
+        
+        log :info, "Executing SQL", query: query
+        
+        results = @database.fetch(query).all
+        results.to_json
+      end
+      
+      def execute_api_call(config, params)
+        # Implementation for API calls
+        # Similar to HTTP implementation above
+      end
+    end
+    
+    @server.register_tool_class(tool_class)
+    @loaded_tools[record[:id]] = tool_class
+    
+    log :info, "Tool loaded from database", 
+        name: record[:name], 
+        id: record[:id]
+  end
+  
+  def reload_tool(tool_id)
+    # Remove old version
+    if old_tool = @loaded_tools[tool_id]
+      @server.unregister_tool(old_tool.name)
+      @loaded_tools.delete(tool_id)
+    end
+    
+    # Load new version
+    if record = @database[:tools].where(id: tool_id, enabled: true).first
+      create_tool_from_record(record)
+    end
+  end
+  
+  def sync_tools
+    # Get current tool IDs from database
+    db_tool_ids = @database[:tools].where(enabled: true).select_map(:id)
+    
+    # Remove tools that no longer exist
+    (@loaded_tools.keys - db_tool_ids).each do |tool_id|
+      if tool = @loaded_tools[tool_id]
+        @server.unregister_tool(tool.name)
+        @loaded_tools.delete(tool_id)
+      end
+    end
+    
+    # Add new tools
+    (db_tool_ids - @loaded_tools.keys).each do |tool_id|
+      if record = @database[:tools].where(id: tool_id).first
+        create_tool_from_record(record)
+      end
+    end
+    
+    # Reload modified tools
+    @loaded_tools.each do |tool_id, tool_class|
+      record = @database[:tools].where(id: tool_id).first
+      if record && record[:updated_at] > tool_class.loaded_at
+        reload_tool(tool_id)
+      end
+    end
+  end
+end
+```
+
+## Hot Reloading Tools
+
+### File Watcher System
+
+```ruby
+require 'listen'
+
+class HotReloadManager
+  def initialize(server, watch_dir = "app/tools")
+    @server = server
+    @watch_dir = watch_dir
+    @loaded_files = {}
+  end
+  
+  def start
+    @listener = Listen.to(@watch_dir) do |modified, added, removed|
+      handle_file_changes(modified, added, removed)
+    end
+    
+    # Load initial tools
+    load_all_tools
+    
+    # Start watching
+    @listener.start
+    
+    log :info, "Hot reload started", directory: @watch_dir
+  end
+  
+  def stop
+    @listener&.stop
+  end
+  
+  private
+  
+  def handle_file_changes(modified, added, removed)
+    (modified + added).each do |file|
+      reload_tool_file(file)
+    end
+    
+    removed.each do |file|
+      unload_tool_file(file)
+    end
+  end
+  
+  def load_all_tools
+    Dir.glob(File.join(@watch_dir, "**/*.rb")).each do |file|
+      load_tool_file(file)
+    end
+  end
+  
+  def reload_tool_file(file)
+    # Unload old version
+    unload_tool_file(file)
+    
+    # Load new version
+    load_tool_file(file)
+  end
+  
+  def load_tool_file(file)
+    begin
+      # Create isolated namespace
+      namespace = Module.new
+      
+      # Load file in namespace
+      namespace.module_eval(File.read(file), file)
+      
+      # Find tool classes
+      tool_classes = find_tool_classes(namespace)
+      
+      # Register tools
+      tool_classes.each do |tool_class|
+        @server.register_tool_class(tool_class)
+      end
+      
+      @loaded_files[file] = {
+        namespace: namespace,
+        tools: tool_classes
+      }
+      
+      log :info, "Tools loaded", 
+          file: file, 
+          count: tool_classes.size
+      
+    rescue => e
+      log :error, "Failed to load tool file", 
+          file: file, 
+          error: e.message
+    end
+  end
+  
+  def unload_tool_file(file)
+    if loaded = @loaded_files[file]
+      loaded[:tools].each do |tool_class|
+        @server.unregister_tool(tool_class.name)
+      end
+      
+      @loaded_files.delete(file)
+      
+      log :info, "Tools unloaded", file: file
+    end
+  end
+  
+  def find_tool_classes(namespace)
+    namespace.constants.map { |const|
+      namespace.const_get(const)
+    }.select { |const|
+      const.is_a?(Class) && const < Tsikol::Tool
+    }
+  end
+end
+
+# Usage
+Tsikol.start(name: "hot-reload-server") do
+  # Enable hot reloading in development
+  if ENV['RACK_ENV'] == 'development'
+    hot_reload = HotReloadManager.new(self)
+    hot_reload.start
+    
+    before_stop do
+      hot_reload.stop
+    end
+  else
+    # Load tools normally in production
+    Dir.glob('app/tools/**/*.rb').each { |f| require_relative f }
+  end
+end
+```
+
+## AI-Generated Tools
+
+### Tool Generation from Description
+
+```ruby
+class AiToolGenerator
+  def initialize(server)
+    @server = server
+  end
+  
+  def generate_tool(description, examples = [])
+    # Use sampling to generate tool implementation
+    prompt = build_generation_prompt(description, examples)
+    
+    response = @server.sample_text(
+      messages: [
+        {
+          role: "system",
+          content: {
+            type: "text",
+            text: SYSTEM_PROMPT
+          }
+        },
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: prompt
+          }
+        }
+      ],
+      temperature: 0.3,
+      max_tokens: 2000
+    )
+    
+    if response[:error]
+      raise "Failed to generate tool: #{response[:error]}"
+    end
+    
+    # Parse generated code
+    tool_code = extract_tool_code(response[:text])
+    
+    # Create and register tool
+    create_tool_from_code(tool_code)
+  end
+  
+  private
+  
+  SYSTEM_PROMPT = <<~PROMPT
+    You are an expert Ruby developer creating MCP tools.
+    Generate complete, working tool implementations following this pattern:
+    
+    class ToolName < Tsikol::Tool
+      description "Clear description"
+      
+      parameter :param_name do
+        type :string
+        required
+        description "Parameter description"
+      end
+      
+      def execute(param_name:)
+        # Implementation
+      end
+    end
+    
+    Ensure the code is safe, efficient, and handles errors properly.
+  PROMPT
+  
+  def build_generation_prompt(description, examples)
+    prompt = "Create a tool with the following requirements:\n\n"
+    prompt += "Description: #{description}\n\n"
+    
+    if examples.any?
+      prompt += "Examples:\n"
+      examples.each_with_index do |example, i|
+        prompt += "#{i + 1}. Input: #{example[:input]}\n"
+        prompt += "   Output: #{example[:output]}\n"
+      end
+    end
+    
+    prompt
+  end
+  
+  def extract_tool_code(response)
+    # Extract Ruby code from response
+    if match = response.match(/```ruby\n(.*?)```/m)
+      match[1]
+    else
+      response
+    end
+  end
+  
+  def create_tool_from_code(code)
+    # Create isolated namespace
+    namespace = Module.new
+    
+    # Evaluate code
+    namespace.module_eval(code)
+    
+    # Find tool class
+    tool_class = namespace.constants.map { |c|
+      namespace.const_get(c)
+    }.find { |c|
+      c.is_a?(Class) && c < Tsikol::Tool
+    }
+    
+    if tool_class
+      @server.register_tool_class(tool_class)
+      log :info, "AI-generated tool registered", name: tool_class.name
+      tool_class
+    else
+      raise "No valid tool class found in generated code"
+    end
+  end
+end
+
+# Usage
+generator = AiToolGenerator.new(server)
+
+tool = generator.generate_tool(
+  "Create a tool that converts between different units of measurement",
+  [
+    { input: { value: 100, from: "celsius", to: "fahrenheit" }, 
+      output: "212°F" },
+    { input: { value: 1, from: "mile", to: "kilometer" }, 
+      output: "1.60934 km" }
+  ]
+)
+```
+
+## Tool Composition
+
+### Composite Tools
+
+```ruby
+class CompositeToolBuilder
+  def initialize(server)
+    @server = server
+  end
+  
+  def build_composite(name, description, steps)
+    tool_class = Class.new(Tsikol::Tool) do
+      description description
+      
+      # Collect all parameters from component tools
+      all_params = {}
+      steps.each do |step|
+        tool = step[:tool]
+        step[:params].each do |param_name, source|
+          if source.is_a?(Symbol) && !all_params[source]
+            # This is an input parameter
+            all_params[source] = true
+          end
+        end
+      end
+      
+      # Define parameters
+      all_params.keys.each do |param|
+        parameter param do
+          type :string  # Default type
+          required
+          description "Input for #{param}"
+        end
+      end
+      
+      # Define execute method
+      define_method(:execute) do |**params|
+        results = {}
+        
+        steps.each_with_index do |step, index|
+          tool_name = step[:tool]
+          tool_params = {}
+          
+          # Build parameters for this tool
+          step[:params].each do |param_name, source|
+            tool_params[param_name] = if source.is_a?(Symbol)
+              # Reference to input parameter or previous result
+              results[source] || params[source]
+            else
+              # Literal value
+              source
+            end
+          end
+          
+          # Execute tool
+          log :debug, "Executing step #{index + 1}", 
+              tool: tool_name, 
+              params: tool_params
+          
+          result = @server.execute_tool(tool_name, tool_params)
+          
+          # Store result
+          results[step[:store_as] || :"step_#{index}"] = result
+        end
+        
+        # Return final result
+        final_step = steps.last
+        results[final_step[:store_as] || :"step_#{steps.size - 1}"]
+      end
+    end
+    
+    # Set tool name
+    tool_class.define_singleton_method(:name) { name }
+    
+    @server.register_tool_class(tool_class)
+    tool_class
+  end
+end
+
+# Usage
+builder = CompositeToolBuilder.new(server)
+
+# Create a composite tool that:
+# 1. Fetches data from an API
+# 2. Processes the data
+# 3. Generates a report
+builder.build_composite(
+  "data_pipeline",
+  "Fetches and processes data to generate a report",
+  [
+    {
+      tool: "http_request",
+      params: { 
+        url: :api_url,  # From input parameter
+        method: "GET"   # Literal value
+      },
+      store_as: :raw_data
+    },
+    {
+      tool: "json_parser",
+      params: { 
+        json: :raw_data  # From previous step
+      },
+      store_as: :parsed_data
+    },
+    {
+      tool: "report_generator",
+      params: {
+        data: :parsed_data,    # From previous step
+        format: :report_format # From input parameter
+      },
+      store_as: :report
+    }
+  ]
+)
+```
+
+## Testing Dynamic Tools
+
+```ruby
+require 'minitest/autorun'
+
+class DynamicToolTest < Minitest::Test
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @manager = DynamicToolManager.new(@server)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+  end
+  
+  def test_creates_dynamic_tool
+    @manager.create_tool(
+      "test_adder",
+      "Adds two numbers",
+      {
+        a: { type: :number, required: true, description: "First number" },
+        b: { type: :number, required: true, description: "Second number" }
+      }
+    ) do |a:, b:|
+      a + b
+    end
+    
+    response = @client.call_tool("test_adder", { "a" => 5, "b" => 3 })
+    
+    assert_successful_response(response)
+    assert_equal 8, response.dig(:result, :content, 0, :text)
+  end
+  
+  def test_removes_dynamic_tool
+    @manager.create_tool("temporary", "Temp tool", {}) { "temp" }
+    
+    # Tool exists
+    response = @client.call_tool("temporary", {})
+    assert_successful_response(response)
+    
+    # Remove tool
+    @manager.remove_tool("temporary")
+    
+    # Tool no longer exists
+    response = @client.call_tool("temporary", {})
+    assert_error_response(response, -32601)  # Method not found
+  end
+  
+  def test_hot_reload
+    # Create a temporary tool file
+    tool_file = "test_tool.rb"
+    File.write(tool_file, <<~RUBY)
+      class TestTool < Tsikol::Tool
+        description "Test tool v1"
+        
+        def execute
+          "Version 1"
+        end
+      end
+    RUBY
+    
+    # Load tool
+    loader = HotReloadManager.new(@server, ".")
+    loader.send(:load_tool_file, tool_file)
+    
+    response = @client.call_tool("test_tool", {})
+    assert_equal "Version 1", response.dig(:result, :content, 0, :text)
+    
+    # Modify tool
+    File.write(tool_file, <<~RUBY)
+      class TestTool < Tsikol::Tool
+        description "Test tool v2"
+        
+        def execute
+          "Version 2"
+        end
+      end
+    RUBY
+    
+    # Reload
+    loader.send(:reload_tool_file, tool_file)
+    
+    response = @client.call_tool("test_tool", {})
+    assert_equal "Version 2", response.dig(:result, :content, 0, :text)
+    
+  ensure
+    File.delete(tool_file) if File.exist?(tool_file)
+  end
+end
+```
+
+## Best Practices
+
+1. **Validate dynamic code** before execution
+2. **Sandbox untrusted code** for security
+3. **Version control** for dynamic tools
+4. **Monitor performance** of generated tools
+5. **Implement rollback** for tool updates
+6. **Test thoroughly** especially for AI-generated tools
+7. **Log all changes** for audit trail
+8. **Set resource limits** for dynamic tools
+9. **Use namespacing** to avoid conflicts
+10. **Cache compiled tools** for performance
+
+## Next Steps
+
+- Implement [Security](security.md) for dynamic code execution
+- Add [Monitoring](monitoring.md) for tool usage
+- Set up [Testing](../guides/testing.md) for dynamic tools
+- Review [Error Handling](error-handling.md) for tool failures