tsikol 0.1.0

data/docs/guides/completion.md

@@ -0,0 +1,472 @@
+# Completion Guide
+
+Completion (autocomplete) provides intelligent suggestions for tool parameters and prompt arguments, enhancing the user experience.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Basic Completion](#basic-completion)
+3. [Dynamic Completion](#dynamic-completion)
+4. [Advanced Patterns](#advanced-patterns)
+5. [CLI Generation](#cli-generation)
+6. [Best Practices](#best-practices)
+
+## Overview
+
+Completion helps users by:
+- Suggesting valid values for parameters
+- Reducing typing errors
+- Improving discoverability
+- Providing context-aware suggestions
+
+## Basic Completion
+
+### Tool Parameter Completion
+
+```ruby
+class FileManager < Tsikol::Tool
+  description "Manage files in the project"
+  
+  parameter :action do
+    type :string
+    required
+    description "Action to perform"
+    
+    # Static completion
+    complete do |partial|
+      actions = ["create", "delete", "rename", "copy", "move"]
+      actions.select { |a| a.start_with?(partial.downcase) }
+    end
+  end
+  
+  parameter :file_type do
+    type :string
+    optional
+    description "Type of file"
+    
+    # Filtered completion
+    complete do |partial|
+      types = ["ruby", "javascript", "python", "markdown", "json", "yaml"]
+      types.select { |t| t.include?(partial.downcase) }
+    end
+  end
+  
+  def execute(action:, file_type: nil)
+    "Performing #{action} on #{file_type || 'all'} files"
+  end
+end
+```
+
+### Prompt Argument Completion
+
+```ruby
+class CodeAssistant < Tsikol::Prompt
+  name "code_assistant"
+  description "AI coding assistant"
+  
+  argument :language do
+    type :string
+    required
+    
+    complete do |partial|
+      languages = [
+        "ruby", "python", "javascript", "typescript",
+        "go", "rust", "java", "c++", "swift"
+      ]
+      languages.select { |lang| lang.start_with?(partial.downcase) }
+    end
+  end
+  
+  argument :task do
+    type :string
+    required
+    
+    complete do |partial|
+      tasks = [
+        "debug", "refactor", "optimize", "document",
+        "test", "review", "explain", "convert"
+      ]
+      tasks.select { |task| task.include?(partial.downcase) }
+    end
+  end
+  
+  def get_messages(language:, task:)
+    [{
+      role: "user",
+      content: {
+        type: "text",
+        text: "Help me #{task} this #{language} code"
+      }
+    }]
+  end
+end
+```
+
+## Dynamic Completion
+
+### File System Completion
+
+```ruby
+class ProjectNavigator < Tsikol::Tool
+  description "Navigate project files"
+  
+  parameter :path do
+    type :string
+    required
+    
+    # Dynamic file system completion
+    complete do |partial|
+      # Expand home directory
+      expanded = partial.gsub('~', Dir.home)
+      
+      # Get directory and file pattern
+      if expanded.include?('/')
+        dir = File.dirname(expanded)
+        pattern = File.basename(expanded)
+      else
+        dir = '.'
+        pattern = expanded
+      end
+      
+      # Find matching files/directories
+      Dir.glob("#{dir}/#{pattern}*").map do |path|
+        # Add trailing slash for directories
+        File.directory?(path) ? "#{path}/" : path
+      end
+    end
+  end
+  
+  def execute(path:)
+    File.read(path)
+  end
+end
+```
+
+### Database-Driven Completion
+
+```ruby
+class DatabaseQuery < Tsikol::Tool
+  description "Query the database"
+  
+  parameter :table do
+    type :string
+    required
+    
+    # Complete from database schema
+    complete do |partial|
+      # In real app, query database for table names
+      tables = fetch_table_names
+      tables.select { |t| t.downcase.start_with?(partial.downcase) }
+    end
+  end
+  
+  parameter :column do
+    type :string
+    optional
+    
+    # Context-aware completion based on selected table
+    complete do |partial, context|
+      # Context contains previously entered parameters
+      table = context[:table]
+      return [] unless table
+      
+      columns = fetch_columns_for_table(table)
+      columns.select { |c| c.downcase.include?(partial.downcase) }
+    end
+  end
+  
+  private
+  
+  def fetch_table_names
+    # Mock implementation
+    ["users", "posts", "comments", "categories", "tags"]
+  end
+  
+  def fetch_columns_for_table(table)
+    # Mock implementation
+    case table
+    when "users"
+      ["id", "name", "email", "created_at", "updated_at"]
+    when "posts"
+      ["id", "title", "content", "user_id", "published_at"]
+    else
+      ["id", "created_at", "updated_at"]
+    end
+  end
+end
+```
+
+## Advanced Patterns
+
+### Hierarchical Completion
+
+```ruby
+class CloudManager < Tsikol::Tool
+  description "Manage cloud resources"
+  
+  parameter :provider do
+    type :string
+    required
+    
+    complete do |partial|
+      ["aws", "gcp", "azure", "digitalocean"].select { |p| 
+        p.start_with?(partial.downcase) 
+      }
+    end
+  end
+  
+  parameter :service do
+    type :string
+    required
+    
+    # Completion depends on provider
+    complete do |partial, context|
+      services = case context[:provider]
+      when "aws"
+        ["ec2", "s3", "lambda", "rds", "dynamodb"]
+      when "gcp"
+        ["compute", "storage", "functions", "sql", "firestore"]
+      when "azure"
+        ["vm", "blob", "functions", "sql", "cosmos"]
+      else
+        []
+      end
+      
+      services.select { |s| s.include?(partial.downcase) }
+    end
+  end
+  
+  parameter :action do
+    type :string
+    required
+    
+    # Multi-level context
+    complete do |partial, context|
+      actions = case [context[:provider], context[:service]]
+      when ["aws", "ec2"]
+        ["start", "stop", "reboot", "terminate", "describe"]
+      when ["aws", "s3"]
+        ["create-bucket", "delete-bucket", "upload", "download", "list"]
+      else
+        ["list", "describe", "create", "delete"]
+      end
+      
+      actions.select { |a| a.start_with?(partial.downcase) }
+    end
+  end
+end
+```
+
+### Async Completion
+
+```ruby
+class APIClient < Tsikol::Tool
+  description "Call external APIs"
+  
+  parameter :endpoint do
+    type :string
+    required
+    
+    # Async completion from API
+    complete do |partial|
+      begin
+        # Cache results for performance
+        @endpoints_cache ||= fetch_available_endpoints
+        @endpoints_cache.select { |e| e.include?(partial) }
+      rescue => e
+        log :error, "Failed to fetch endpoints", data: { error: e.message }
+        [] # Return empty array on error
+      end
+    end
+  end
+  
+  private
+  
+  def fetch_available_endpoints
+    # In real app, this might call an API
+    [
+      "/api/v1/users",
+      "/api/v1/posts",
+      "/api/v1/comments",
+      "/api/v2/graphql"
+    ]
+  end
+end
+```
+
+### Fuzzy Matching Completion
+
+```ruby
+class CommandRunner < Tsikol::Tool
+  description "Run project commands"
+  
+  parameter :command do
+    type :string
+    required
+    
+    complete do |partial|
+      commands = [
+        "build:development",
+        "build:production",
+        "test:unit",
+        "test:integration",
+        "deploy:staging",
+        "deploy:production"
+      ]
+      
+      # Fuzzy matching
+      commands.select do |cmd|
+        # Match if all characters in partial appear in order
+        pattern = partial.chars.join('.*')
+        cmd.match?(/#{pattern}/i)
+      end.sort_by do |cmd|
+        # Sort by similarity
+        levenshtein_distance(partial.downcase, cmd.downcase)
+      end
+    end
+  end
+  
+  private
+  
+  def levenshtein_distance(s, t)
+    # Simple implementation
+    m = s.length
+    n = t.length
+    return m if n == 0
+    return n if m == 0
+    
+    d = Array.new(m+1) { Array.new(n+1) }
+    
+    (0..m).each { |i| d[i][0] = i }
+    (0..n).each { |j| d[0][j] = j }
+    
+    (1..n).each do |j|
+      (1..m).each do |i|
+        cost = s[i-1] == t[j-1] ? 0 : 1
+        d[i][j] = [
+          d[i-1][j] + 1,
+          d[i][j-1] + 1,
+          d[i-1][j-1] + cost
+        ].min
+      end
+    end
+    
+    d[m][n]
+  end
+end
+```
+
+## CLI Generation
+
+When using the Tsikol CLI, completion hints are automatically added:
+
+```bash
+# Generate a tool with string parameters
+tsikol g tool file_manager action:string path:string
+
+# The generated file includes completion templates:
+parameter :action do
+  type :string
+  required
+  description "TODO: Add description for action"
+  
+  # Add completion for better UX
+  # complete do |partial|
+  #   # Return array of possible values
+  #   options = ["option1", "option2", "option3"]
+  #   options.select { |opt| opt.start_with?(partial) }
+  # end
+end
+```
+
+## Best Practices
+
+### 1. Performance
+
+```ruby
+# Cache expensive operations
+complete do |partial|
+  @cached_values ||= expensive_fetch_operation
+  @cached_values.select { |v| v.include?(partial) }
+end
+```
+
+### 2. Error Handling
+
+```ruby
+complete do |partial|
+  begin
+    fetch_suggestions(partial)
+  rescue => e
+    log :error, "Completion failed", data: { error: e.message }
+    [] # Always return array
+  end
+end
+```
+
+### 3. Limit Results
+
+```ruby
+complete do |partial|
+  all_suggestions = fetch_all_suggestions
+  filtered = all_suggestions.select { |s| s.include?(partial) }
+  filtered.first(20) # Limit to prevent UI overload
+end
+```
+
+### 4. Context Awareness
+
+```ruby
+# Use context for dependent completions
+complete do |partial, context|
+  # Access other parameter values
+  previous_value = context[:other_param]
+  
+  suggestions_for(previous_value, partial)
+end
+```
+
+### 5. User-Friendly Suggestions
+
+```ruby
+complete do |partial|
+  suggestions = fetch_suggestions
+  
+  # Sort by relevance
+  exact_matches = suggestions.select { |s| s.start_with?(partial) }
+  partial_matches = suggestions.select { |s| 
+    s.include?(partial) && !s.start_with?(partial) 
+  }
+  
+  # Exact matches first, then partial matches
+  (exact_matches + partial_matches).uniq
+end
+```
+
+## Testing Completions
+
+```ruby
+require 'tsikol/test_helpers'
+
+class CompletionTest < Minitest::Test
+  def test_tool_completion
+    client = Tsikol::TestHelpers::TestClient.new(server)
+    
+    # Test completion
+    response = client.complete(
+      { type: "ref/tool", name: "file_manager" },
+      { name: "action", value: "cr" }
+    )
+    
+    suggestions = response.dig(:result, :completion, :values)
+    assert_includes suggestions, "create"
+    assert_includes suggestions, "copy"
+  end
+end
+```
+
+## Next Steps
+
+- Learn about [Sampling](sampling.md) for AI assistance
+- Explore [Advanced Features](../advanced-features.md)
+- See [Complete Examples](../examples/)