tsikol 0.1.0

data/docs/api/tool.md

@@ -0,0 +1,527 @@
+# Tool API Reference
+
+The `Tsikol::Tool` class provides the foundation for creating tools that AI assistants can call.
+
+## Class: Tsikol::Tool
+
+### Class Methods
+
+#### `.description(text = nil)`
+
+Set or get the tool description.
+
+```ruby
+class MyTool < Tsikol::Tool
+  description "Performs useful operations"
+end
+```
+
+#### `.parameter(name, &block)`
+
+Define a tool parameter with validation and completion.
+
+```ruby
+class FileTool < Tsikol::Tool
+  parameter :path do
+    type :string
+    required
+    description "File path"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*")
+    end
+  end
+  
+  parameter :options do
+    type :object
+    optional
+    default {}
+    description "Additional options"
+  end
+end
+```
+
+### Parameter DSL
+
+Parameters are defined using a DSL within the parameter block:
+
+#### `type(symbol)`
+
+Set the parameter type.
+
+```ruby
+parameter :count do
+  type :integer  # :string, :number, :integer, :boolean, :array, :object
+end
+```
+
+#### `required` / `optional`
+
+Specify if parameter is required.
+
+```ruby
+parameter :name do
+  type :string
+  required  # or optional
+end
+```
+
+#### `default(value)`
+
+Set default value for optional parameters.
+
+```ruby
+parameter :format do
+  type :string
+  optional
+  default "json"
+end
+```
+
+#### `description(text)`
+
+Describe the parameter's purpose.
+
+```ruby
+parameter :query do
+  type :string
+  required
+  description "Search query string"
+end
+```
+
+#### `enum(values)`
+
+Restrict parameter to specific values.
+
+```ruby
+parameter :operation do
+  type :string
+  required
+  enum ["read", "write", "delete"]
+  description "File operation"
+end
+```
+
+#### `complete(&block)`
+
+Define completion logic.
+
+```ruby
+parameter :language do
+  type :string
+  required
+  
+  complete do |partial|
+    languages = ["ruby", "python", "javascript", "go"]
+    languages.select { |lang| lang.start_with?(partial) }
+  end
+end
+```
+
+### Instance Methods
+
+#### `#execute(**params)`
+
+Main method to implement tool logic. Override in subclasses.
+
+```ruby
+class Calculator < Tsikol::Tool
+  parameter :a do
+    type :number
+    required
+  end
+  
+  parameter :b do
+    type :number
+    required
+  end
+  
+  parameter :operation do
+    type :string
+    required
+    enum ["add", "subtract", "multiply", "divide"]
+  end
+  
+  def execute(a:, b:, operation:)
+    case operation
+    when "add" then a + b
+    when "subtract" then a - b
+    when "multiply" then a * b
+    when "divide"
+      raise Tsikol::ValidationError, "Division by zero" if b == 0
+      a.to_f / b
+    end
+  end
+end
+```
+
+#### `#set_server(server)`
+
+Called when tool is registered with a server. Override to access server features.
+
+```ruby
+def set_server(server)
+  @server = server
+  
+  # Enable logging if server supports it
+  if @server.logging_enabled?
+    define_singleton_method(:log) do |level, message, data: nil|
+      @server.log(level, message, data: data)
+    end
+  end
+end
+```
+
+#### `#log(level, message, data: nil)`
+
+Log messages (only available after server registration with logging enabled).
+
+```ruby
+def execute(input:)
+  log :info, "Processing started", input_size: input.size
+  
+  result = process(input)
+  
+  log :info, "Processing complete", result_size: result.size
+  
+  result
+end
+```
+
+### Tool Registration
+
+Tools can be registered in several ways:
+
+#### Class Registration
+
+```ruby
+server.register_tool_class(MyTool)
+# or
+server.tool MyTool
+```
+
+#### Instance Registration
+
+```ruby
+tool = MyTool.new
+server.register_tool_instance(tool)
+```
+
+#### Inline Registration
+
+```ruby
+server.register_tool("simple_tool") do |param:|
+  "Result: #{param}"
+end
+# or
+server.tool "simple_tool" do |param:|
+  "Result: #{param}"
+end
+```
+
+### Parameter Validation
+
+Parameters are automatically validated:
+
+```ruby
+# Type validation
+parameter :age do
+  type :integer
+  required
+end
+# Validates that age is an integer
+
+# Enum validation
+parameter :color do
+  type :string
+  enum ["red", "green", "blue"]
+end
+# Validates color is one of the allowed values
+
+# Custom validation in execute
+def execute(email:)
+  unless email =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i
+    raise Tsikol::ValidationError, "Invalid email format"
+  end
+  
+  process_email(email)
+end
+```
+
+### Error Handling
+
+Tools should handle errors gracefully:
+
+```ruby
+class SafeTool < Tsikol::Tool
+  def execute(input:)
+    validate_input!(input)
+    result = process(input)
+    format_result(result)
+    
+  rescue ValidationError => e
+    # Return user-friendly error
+    "Validation failed: #{e.message}"
+    
+  rescue NetworkError => e
+    # Log and return error
+    log :error, "Network error", error: e.message
+    "Network error occurred. Please try again."
+    
+  rescue => e
+    # Unexpected errors
+    log :error, "Unexpected error", error: e.class.name, message: e.message
+    "An unexpected error occurred"
+  end
+end
+```
+
+### Async Operations
+
+Tools can perform async operations:
+
+```ruby
+class AsyncTool < Tsikol::Tool
+  def execute(data:)
+    job_id = SecureRandom.uuid
+    
+    # Start async processing
+    Thread.new do
+      begin
+        result = long_running_operation(data)
+        store_result(job_id, result)
+      rescue => e
+        store_error(job_id, e)
+      end
+    end
+    
+    # Return immediately
+    {
+      job_id: job_id,
+      status: "processing",
+      check_back_in: 60
+    }.to_json
+  end
+end
+```
+
+### Using Server Capabilities
+
+Tools can use server features when available:
+
+```ruby
+class AiTool < Tsikol::Tool
+  def execute(prompt:)
+    unless @server.sampling_enabled?
+      return "AI features not available"
+    end
+    
+    response = @server.sample_text(
+      messages: [
+        { role: "user", content: { type: "text", text: prompt } }
+      ],
+      temperature: 0.7
+    )
+    
+    if response[:error]
+      "AI error: #{response[:error]}"
+    else
+      response[:text]
+    end
+  end
+end
+```
+
+## Complete Example
+
+```ruby
+class FileManager < Tsikol::Tool
+  description "Manage files and directories"
+  
+  parameter :operation do
+    type :string
+    required
+    enum ["read", "write", "list", "delete", "info"]
+    description "Operation to perform"
+  end
+  
+  parameter :path do
+    type :string
+    required
+    description "File or directory path"
+    
+    complete do |partial|
+      Dir.glob("#{partial}*").map do |path|
+        File.directory?(path) ? "#{path}/" : path
+      end
+    end
+  end
+  
+  parameter :content do
+    type :string
+    optional
+    description "Content for write operations"
+  end
+  
+  parameter :options do
+    type :object
+    optional
+    default {}
+    description "Additional options (encoding, etc.)"
+  end
+  
+  def execute(operation:, path:, content: nil, options: {})
+    log :info, "File operation", operation: operation, path: path
+    
+    case operation
+    when "read"
+      read_file(path, options)
+    when "write"
+      write_file(path, content, options)
+    when "list"
+      list_directory(path)
+    when "delete"
+      delete_file(path)
+    when "info"
+      file_info(path)
+    end
+    
+  rescue Errno::ENOENT
+    raise Tsikol::ValidationError, "File not found: #{path}"
+  rescue Errno::EACCES
+    raise Tsikol::ValidationError, "Permission denied: #{path}"
+  rescue => e
+    log :error, "File operation failed", error: e.message
+    raise
+  end
+  
+  private
+  
+  def read_file(path, options)
+    encoding = options["encoding"] || "UTF-8"
+    File.read(path, encoding: encoding)
+  end
+  
+  def write_file(path, content, options)
+    raise Tsikol::ValidationError, "Content required for write" unless content
+    
+    mode = options["append"] ? "a" : "w"
+    File.open(path, mode) { |f| f.write(content) }
+    
+    "Wrote #{content.bytesize} bytes to #{path}"
+  end
+  
+  def list_directory(path)
+    unless File.directory?(path)
+      raise Tsikol::ValidationError, "Not a directory: #{path}"
+    end
+    
+    entries = Dir.entries(path).reject { |e| e.start_with?(".") }
+    entries.map do |entry|
+      full_path = File.join(path, entry)
+      {
+        name: entry,
+        type: File.directory?(full_path) ? "directory" : "file",
+        size: File.size(full_path)
+      }
+    end.to_json
+  end
+  
+  def delete_file(path)
+    if File.directory?(path)
+      Dir.rmdir(path)
+      "Deleted directory: #{path}"
+    else
+      File.delete(path)
+      "Deleted file: #{path}"
+    end
+  end
+  
+  def file_info(path)
+    stat = File.stat(path)
+    {
+      path: path,
+      type: stat.directory? ? "directory" : "file",
+      size: stat.size,
+      modified: stat.mtime.iso8601,
+      permissions: stat.mode.to_s(8)
+    }.to_json
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    if @server.logging_enabled?
+      define_singleton_method(:log) do |level, message, data: nil|
+        @server.log(level, message, data: data)
+      end
+    else
+      define_singleton_method(:log) do |*args|
+        # No-op if logging not enabled
+      end
+    end
+  end
+end
+```
+
+## Testing Tools
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class FileManagerTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.logging true
+    @server.register_tool_instance(FileManager.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_read_file
+    File.write("test.txt", "Hello, World!")
+    
+    response = @client.call_tool("file_manager", {
+      "operation" => "read",
+      "path" => "test.txt"
+    })
+    
+    assert_successful_response(response)
+    assert_equal "Hello, World!", response.dig(:result, :content, 0, :text)
+  ensure
+    File.delete("test.txt") if File.exist?("test.txt")
+  end
+  
+  def test_parameter_validation
+    response = @client.call_tool("file_manager", {
+      "operation" => "invalid_op",
+      "path" => "test.txt"
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /must be one of/, response[:error][:message]
+  end
+  
+  def test_completion
+    response = @client.complete(
+      { type: "ref/tool", name: "file_manager" },
+      { name: "path", value: "te" }
+    )
+    
+    assert_successful_response(response)
+    values = response.dig(:result, :completion, :values)
+    assert values.any? { |v| v.start_with?("te") }
+  end
+end
+```
+
+## See Also
+
+- [Tools Guide](../guides/tools.md)
+- [Server API](server.md)
+- [Testing Guide](../guides/testing.md)
+- [Error Handling](../cookbook/error-handling.md)