tsikol 0.1.0

data/docs/guides/prompts.md

@@ -0,0 +1,920 @@
+# Prompts Guide
+
+Prompts enable MCP servers to provide reusable AI assistant configurations with dynamic arguments. They're perfect for creating specialized AI behaviors that clients can invoke.
+
+## Table of Contents
+
+1. [What are Prompts?](#what-are-prompts)
+2. [Creating Prompts](#creating-prompts)
+3. [Arguments](#arguments)
+4. [Message Formats](#message-formats)
+5. [Dynamic Content](#dynamic-content)
+6. [Advanced Patterns](#advanced-patterns)
+7. [Testing Prompts](#testing-prompts)
+
+## What are Prompts?
+
+Prompts are pre-configured message templates that:
+- Define AI assistant behaviors
+- Accept dynamic arguments
+- Return structured messages
+- Can include system prompts, examples, and context
+
+Think of prompts as reusable AI configurations.
+
+## Creating Prompts
+
+### Inline Prompts
+
+Simple prompts in server.rb:
+
+```ruby
+Tsikol.server "my-server" do
+  prompt "translator" do |language:, text:|
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a professional translator. Translate the text to #{language}."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: text
+        }
+      }
+    ]
+  end
+  
+  prompt "code_reviewer" do |code:, language: "auto"|
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are an expert code reviewer. Review the #{language} code for best practices, potential bugs, and improvements."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Review this code:\n\n```#{language}\n#{code}\n```"
+        }
+      }
+    ]
+  end
+end
+```
+
+### Class-Based Prompts
+
+For complex prompts:
+
+```ruby
+# app/prompts/sql_assistant.rb
+class SqlAssistant < Tsikol::Prompt
+  name "sql_assistant"
+  description "Expert SQL query assistant with database schema awareness"
+  
+  argument :query_description do
+    type :string
+    required
+    description "Natural language description of the desired query"
+  end
+  
+  argument :database_type do
+    type :string
+    optional
+    default "postgresql"
+    enum ["postgresql", "mysql", "sqlite", "oracle"]
+    description "Target database system"
+  end
+  
+  argument :include_schema do
+    type :boolean
+    optional
+    default true
+    description "Include database schema in context"
+  end
+  
+  def get_messages(query_description:, database_type: "postgresql", include_schema: true)
+    messages = []
+    
+    # System prompt
+    messages << {
+      role: "system",
+      content: {
+        type: "text",
+        text: build_system_prompt(database_type)
+      }
+    }
+    
+    # Include schema if requested
+    if include_schema
+      messages << {
+        role: "system",
+        content: {
+          type: "text",
+          text: "Database schema:\n#{fetch_schema}"
+        }
+      }
+    end
+    
+    # Add examples
+    messages.concat(example_messages(database_type))
+    
+    # User query
+    messages << {
+      role: "user",
+      content: {
+        type: "text",
+        text: query_description
+      }
+    }
+    
+    messages
+  end
+  
+  private
+  
+  def build_system_prompt(database_type)
+    <<~PROMPT
+      You are an expert SQL developer specializing in #{database_type}.
+      
+      Your responsibilities:
+      1. Write efficient, optimized SQL queries
+      2. Follow #{database_type} best practices
+      3. Include helpful comments
+      4. Explain complex queries
+      5. Suggest indexes when appropriate
+      
+      Always consider:
+      - Query performance
+      - Data integrity
+      - SQL injection prevention
+      - Database-specific features and syntax
+    PROMPT
+  end
+  
+  def fetch_schema
+    # In real implementation, fetch from database
+    <<~SCHEMA
+      -- Users table
+      CREATE TABLE users (
+        id SERIAL PRIMARY KEY,
+        email VARCHAR(255) UNIQUE NOT NULL,
+        name VARCHAR(255),
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
+      
+      -- Posts table
+      CREATE TABLE posts (
+        id SERIAL PRIMARY KEY,
+        user_id INTEGER REFERENCES users(id),
+        title VARCHAR(255) NOT NULL,
+        content TEXT,
+        published_at TIMESTAMP,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
+      
+      -- Comments table
+      CREATE TABLE comments (
+        id SERIAL PRIMARY KEY,
+        post_id INTEGER REFERENCES posts(id),
+        user_id INTEGER REFERENCES users(id),
+        content TEXT NOT NULL,
+        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+      );
+    SCHEMA
+  end
+  
+  def example_messages(database_type)
+    [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "Find all users who have posted in the last 30 days"
+        }
+      },
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: example_query_for(database_type)
+        }
+      }
+    ]
+  end
+  
+  def example_query_for(database_type)
+    case database_type
+    when "postgresql"
+      <<~SQL
+        -- Find users who have posted in the last 30 days
+        SELECT DISTINCT u.id, u.email, u.name
+        FROM users u
+        INNER JOIN posts p ON u.id = p.user_id
+        WHERE p.created_at >= CURRENT_DATE - INTERVAL '30 days'
+        ORDER BY u.name;
+      SQL
+    when "mysql"
+      <<~SQL
+        -- Find users who have posted in the last 30 days
+        SELECT DISTINCT u.id, u.email, u.name
+        FROM users u
+        INNER JOIN posts p ON u.id = p.user_id
+        WHERE p.created_at >= DATE_SUB(CURDATE(), INTERVAL 30 DAY)
+        ORDER BY u.name;
+      SQL
+    else
+      "-- Example query for #{database_type}"
+    end
+  end
+end
+```
+
+## Arguments
+
+### Basic Arguments
+
+```ruby
+argument :topic do
+  type :string
+  required
+  description "The topic to discuss"
+end
+
+argument :style do
+  type :string
+  optional
+  default "casual"
+  enum ["casual", "formal", "technical"]
+  description "Writing style"
+end
+```
+
+### Argument Types
+
+All supported argument types:
+
+```ruby
+# String arguments
+argument :name do
+  type :string
+  required
+end
+
+# Number arguments
+argument :temperature do
+  type :number
+  optional
+  default 0.7
+end
+
+# Boolean arguments
+argument :verbose do
+  type :boolean
+  optional
+  default false
+end
+
+# Array arguments
+argument :topics do
+  type :array
+  optional
+  default []
+end
+
+# Object arguments
+argument :config do
+  type :object
+  optional
+  default {}
+end
+```
+
+### Argument Completion
+
+Add autocomplete support:
+
+```ruby
+argument :programming_language do
+  type :string
+  required
+  
+  complete do |partial|
+    languages = ["ruby", "python", "javascript", "go", "rust", "java"]
+    languages.select { |lang| lang.start_with?(partial.downcase) }
+  end
+end
+
+argument :file_path do
+  type :string
+  required
+  
+  complete do |partial|
+    Dir.glob("#{partial}*").select { |f| File.file?(f) }
+  end
+end
+```
+
+## Message Formats
+
+### Basic Text Messages
+
+```ruby
+def get_messages(topic:)
+  [
+    {
+      role: "system",
+      content: {
+        type: "text",
+        text: "You are a helpful assistant."
+      }
+    },
+    {
+      role: "user", 
+      content: {
+        type: "text",
+        text: "Tell me about #{topic}"
+      }
+    }
+  ]
+end
+```
+
+### Multi-Modal Messages
+
+Including images or other content:
+
+```ruby
+def get_messages(image_path:, question:)
+  [
+    {
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: question
+        },
+        {
+          type: "image",
+          data: Base64.encode64(File.read(image_path, mode: "rb")),
+          mimeType: "image/png"
+        }
+      ]
+    }
+  ]
+end
+```
+
+### Conversation History
+
+Include previous exchanges:
+
+```ruby
+def get_messages(topic:, history: [])
+  messages = [
+    {
+      role: "system",
+      content: {
+        type: "text",
+        text: "You are a helpful tutor. Build on previous conversations."
+      }
+    }
+  ]
+  
+  # Add history
+  messages.concat(history)
+  
+  # Add new query
+  messages << {
+    role: "user",
+    content: {
+      type: "text",
+      text: "Continue explaining #{topic}"
+    }
+  }
+  
+  messages
+end
+```
+
+## Dynamic Content
+
+### Resource Integration
+
+Include data from resources:
+
+```ruby
+class DataAnalyst < Tsikol::Prompt
+  name "data_analyst"
+  description "Analyze data with current context"
+  
+  argument :query do
+    type :string
+    required
+  end
+  
+  def get_messages(query:)
+    # Fetch current data
+    current_metrics = fetch_current_metrics
+    
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a data analyst. Analyze the provided metrics."
+        }
+      },
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "Current metrics:\n#{current_metrics.to_json}"
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: query
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def fetch_current_metrics
+    # Fetch from resources or database
+    {
+      users_total: 1523,
+      active_today: 234,
+      revenue_mtd: 45_000,
+      conversion_rate: 2.3
+    }
+  end
+end
+```
+
+### Template Expansion
+
+Use templates for complex prompts:
+
+```ruby
+class DocumentGenerator < Tsikol::Prompt
+  name "document_generator"
+  description "Generate documents from templates"
+  
+  argument :document_type do
+    type :string
+    required
+    enum ["report", "proposal", "email", "article"]
+  end
+  
+  argument :data do
+    type :object
+    required
+    description "Data to fill the template"
+  end
+  
+  def get_messages(document_type:, data:)
+    template = load_template(document_type)
+    expanded = expand_template(template, data)
+    
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a professional document writer. Generate a #{document_type} based on the template."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: expanded
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def load_template(type)
+    # Load from file or database
+    case type
+    when "report"
+      <<~TEMPLATE
+        Generate a report with:
+        - Title: {{title}}
+        - Period: {{start_date}} to {{end_date}}
+        - Key metrics: {{metrics}}
+        - Recommendations based on the data
+      TEMPLATE
+    when "email"
+      <<~TEMPLATE
+        Write a professional email:
+        - To: {{recipient}}
+        - Subject: {{subject}}
+        - Main points: {{points}}
+        - Tone: {{tone}}
+      TEMPLATE
+    end
+  end
+  
+  def expand_template(template, data)
+    result = template.dup
+    data.each do |key, value|
+      result.gsub!("{{#{key}}}", value.to_s)
+    end
+    result
+  end
+end
+```
+
+## Advanced Patterns
+
+### Chained Prompts
+
+Build complex interactions:
+
+```ruby
+class InterviewAssistant < Tsikol::Prompt
+  name "interview_assistant"
+  description "Conduct structured interviews"
+  
+  argument :role do
+    type :string
+    required
+    description "Role being interviewed for"
+  end
+  
+  argument :stage do
+    type :string
+    required
+    enum ["intro", "technical", "behavioral", "closing"]
+  end
+  
+  argument :previous_answers do
+    type :array
+    optional
+    default []
+  end
+  
+  def get_messages(role:, stage:, previous_answers: [])
+    messages = base_messages(role)
+    
+    # Add context from previous stages
+    if previous_answers.any?
+      messages << {
+        role: "system",
+        content: {
+          type: "text",
+          text: "Previous answers:\n#{format_previous_answers(previous_answers)}"
+        }
+      }
+    end
+    
+    # Add stage-specific prompt
+    messages << stage_message(stage, role)
+    
+    messages
+  end
+  
+  private
+  
+  def base_messages(role)
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: <<~PROMPT
+            You are an experienced technical interviewer.
+            You're conducting an interview for a #{role} position.
+            Ask thoughtful questions and provide constructive feedback.
+            Maintain a professional but friendly tone.
+          PROMPT
+        }
+      }
+    ]
+  end
+  
+  def stage_message(stage, role)
+    content = case stage
+    when "intro"
+      "Start the interview. Introduce yourself and ask the candidate to tell you about themselves."
+    when "technical"
+      "Ask technical questions relevant to a #{role} position. Focus on practical problem-solving."
+    when "behavioral"
+      "Ask behavioral questions to assess culture fit and soft skills."
+    when "closing"
+      "Wrap up the interview. Ask if they have questions and explain next steps."
+    end
+    
+    {
+      role: "user",
+      content: {
+        type: "text",
+        text: content
+      }
+    }
+  end
+  
+  def format_previous_answers(answers)
+    answers.map.with_index do |answer, i|
+      "Q#{i + 1}: #{answer[:question]}\nA: #{answer[:answer]}"
+    end.join("\n\n")
+  end
+end
+```
+
+### Adaptive Prompts
+
+Adjust behavior based on context:
+
+```ruby
+class AdaptiveAssistant < Tsikol::Prompt
+  name "adaptive_assistant"
+  description "Adapts communication style based on user"
+  
+  argument :message do
+    type :string
+    required
+  end
+  
+  argument :user_profile do
+    type :object
+    optional
+    default {}
+  end
+  
+  def get_messages(message:, user_profile: {})
+    style = determine_style(user_profile)
+    expertise = user_profile["expertise_level"] || "intermediate"
+    
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: build_adaptive_prompt(style, expertise)
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: message
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def determine_style(profile)
+    return profile["preferred_style"] if profile["preferred_style"]
+    
+    # Infer from other attributes
+    if profile["role"] == "executive"
+      "concise"
+    elsif profile["technical_background"]
+      "detailed"
+    else
+      "balanced"
+    end
+  end
+  
+  def build_adaptive_prompt(style, expertise)
+    base = "You are an adaptive AI assistant."
+    
+    style_guide = case style
+    when "concise"
+      "Be very brief and to the point. Use bullet points."
+    when "detailed"
+      "Provide comprehensive explanations with examples."
+    when "balanced"
+      "Strike a balance between clarity and detail."
+    end
+    
+    expertise_guide = case expertise
+    when "beginner"
+      "Explain concepts simply, avoid jargon."
+    when "expert"
+      "Use technical terms freely, focus on advanced concepts."
+    else
+      "Adjust explanations to an intermediate level."
+    end
+    
+    "#{base}\n#{style_guide}\n#{expertise_guide}"
+  end
+end
+```
+
+### Prompt Composition
+
+Combine multiple prompts:
+
+```ruby
+class CompositePrompt < Tsikol::Prompt
+  name "composite_prompt"
+  description "Combines multiple specialized prompts"
+  
+  argument :task do
+    type :string
+    required
+  end
+  
+  argument :components do
+    type :array
+    required
+    description "Which components to include"
+  end
+  
+  def get_messages(task:, components:)
+    messages = []
+    
+    # Add base system message
+    messages << {
+      role: "system",
+      content: {
+        type: "text",
+        text: "You are a multi-skilled AI assistant."
+      }
+    }
+    
+    # Add component-specific instructions
+    components.each do |component|
+      messages.concat(component_messages(component))
+    end
+    
+    # Add user task
+    messages << {
+      role: "user",
+      content: {
+        type: "text",
+        text: task
+      }
+    }
+    
+    messages
+  end
+  
+  private
+  
+  def component_messages(component)
+    case component
+    when "coder"
+      coder_prompt_messages
+    when "writer"
+      writer_prompt_messages
+    when "analyst"
+      analyst_prompt_messages
+    else
+      []
+    end
+  end
+  
+  def coder_prompt_messages
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "For coding tasks: Write clean, efficient, well-documented code."
+        }
+      }
+    ]
+  end
+  
+  # Similar for other components...
+end
+```
+
+## Testing Prompts
+
+### Basic Prompt Test
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class SqlAssistantTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.register_prompt_instance(SqlAssistant.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_basic_query
+    response = @client.get_prompt("sql_assistant", {
+      "query_description" => "Find all users created this week"
+    })
+    
+    assert_successful_response(response)
+    
+    messages = response.dig(:result, :messages)
+    assert messages.is_a?(Array)
+    assert messages.length >= 2
+    
+    # Check system message
+    system_message = messages.find { |m| m[:role] == "system" }
+    assert system_message
+    assert_match /SQL developer/i, system_message[:content][:text]
+  end
+  
+  def test_database_type_variation
+    ["postgresql", "mysql", "sqlite"].each do |db_type|
+      response = @client.get_prompt("sql_assistant", {
+        "query_description" => "Create an index",
+        "database_type" => db_type
+      })
+      
+      assert_successful_response(response)
+      
+      # Verify database-specific content
+      content = response.dig(:result, :messages).map { |m| 
+        m[:content][:text] 
+      }.join(" ")
+      
+      assert_match db_type, content
+    end
+  end
+end
+```
+
+### Testing Dynamic Content
+
+```ruby
+class DataAnalystTest < Minitest::Test
+  def test_includes_current_metrics
+    # Mock metrics fetching
+    prompt = DataAnalyst.new
+    prompt.define_singleton_method(:fetch_current_metrics) do
+      { test_metric: 123 }
+    end
+    
+    messages = prompt.get_messages(query: "Analyze trends")
+    
+    # Find the metrics message
+    metrics_message = messages.find { |m| 
+      m[:content][:text].include?("test_metric")
+    }
+    
+    assert metrics_message
+    assert_match /"test_metric":123/, metrics_message[:content][:text]
+  end
+end
+```
+
+### Testing Argument Validation
+
+```ruby
+def test_required_arguments
+  # Missing required argument
+  response = @client.get_prompt("sql_assistant", {})
+  
+  assert_error_response(response)
+  assert_match /query_description.*required/i, response[:error][:message]
+end
+
+def test_enum_validation
+  response = @client.get_prompt("sql_assistant", {
+    "query_description" => "Test",
+    "database_type" => "invalid_db"
+  })
+  
+  assert_error_response(response)
+  assert_match /must be one of/i, response[:error][:message]
+end
+```
+
+## Best Practices
+
+1. **Clear Descriptions**: Help users understand what the prompt does
+2. **Validate Arguments**: Use enums and types to prevent errors
+3. **Provide Context**: Include relevant information in system messages
+4. **Use Examples**: Show the AI what you expect
+5. **Test Variations**: Ensure prompts work with different arguments
+6. **Keep Focused**: Each prompt should have a clear purpose
+7. **Document Behavior**: Explain what the prompt will generate
+
+## Next Steps
+
+- Learn about [Completion](completion.md)
+- Explore [Sampling](sampling.md) 
+- Add [Middleware](middleware.md)
+- Set up [Testing](testing.md)