tsikol 0.1.0

data/docs/api/prompt.md

@@ -0,0 +1,858 @@
+# Prompt API Reference
+
+The `Tsikol::Prompt` class provides the foundation for creating reusable AI assistant configurations with dynamic arguments.
+
+## Class: Tsikol::Prompt
+
+### Class Methods
+
+#### `.name(value = nil)`
+
+Set or get the prompt name.
+
+```ruby
+class CodeReviewer < Tsikol::Prompt
+  name "code_reviewer"
+end
+```
+
+#### `.description(text = nil)`
+
+Set or get the prompt description.
+
+```ruby
+class CodeReviewer < Tsikol::Prompt
+  name "code_reviewer"
+  description "AI code review assistant for various programming languages"
+end
+```
+
+#### `.argument(name, &block)`
+
+Define a prompt argument with validation and completion.
+
+```ruby
+class TranslationPrompt < Tsikol::Prompt
+  argument :text do
+    type :string
+    required
+    description "Text to translate"
+  end
+  
+  argument :target_language do
+    type :string
+    required
+    description "Target language for translation"
+    
+    complete do |partial|
+      languages = ["spanish", "french", "german", "italian", "portuguese"]
+      languages.select { |lang| lang.start_with?(partial.downcase) }
+    end
+  end
+  
+  argument :style do
+    type :string
+    optional
+    default "formal"
+    enum ["formal", "casual", "technical"]
+    description "Translation style"
+  end
+end
+```
+
+### Argument DSL
+
+Arguments use the same DSL as tool parameters:
+
+#### `type(symbol)`
+
+Set the argument type.
+
+```ruby
+argument :count do
+  type :integer  # :string, :number, :integer, :boolean, :array, :object
+end
+```
+
+#### `required` / `optional`
+
+Specify if argument is required.
+
+```ruby
+argument :topic do
+  type :string
+  required  # or optional
+end
+```
+
+#### `default(value)`
+
+Set default value for optional arguments.
+
+```ruby
+argument :temperature do
+  type :number
+  optional
+  default 0.7
+end
+```
+
+#### `description(text)`
+
+Describe the argument's purpose.
+
+```ruby
+argument :context do
+  type :string
+  required
+  description "Background context for the AI"
+end
+```
+
+#### `enum(values)`
+
+Restrict argument to specific values.
+
+```ruby
+argument :language do
+  type :string
+  required
+  enum ["ruby", "python", "javascript", "go"]
+  description "Programming language"
+end
+```
+
+#### `complete(&block)`
+
+Define completion logic.
+
+```ruby
+argument :file_path do
+  type :string
+  required
+  
+  complete do |partial|
+    Dir.glob("#{partial}*").select { |f| File.file?(f) }
+  end
+end
+```
+
+### Instance Methods
+
+#### `#get_messages(**args)`
+
+Main method to implement prompt logic. Must return an array of message objects.
+
+```ruby
+class SimplePrompt < Tsikol::Prompt
+  name "simple_prompt"
+  
+  argument :task do
+    type :string
+    required
+  end
+  
+  def get_messages(task:)
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: "You are a helpful assistant."
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: task
+        }
+      }
+    ]
+  end
+end
+```
+
+#### `#name`
+
+Get the prompt name (instance method).
+
+```ruby
+prompt = CodeReviewer.new
+prompt.name  # => "code_reviewer"
+```
+
+#### `#set_server(server)`
+
+Called when prompt is registered with a server. Override to access server features.
+
+```ruby
+def set_server(server)
+  @server = server
+  
+  # Access server resources if needed
+  if @server.resources["config"]
+    @config = JSON.parse(@server.resources["config"].read)
+  end
+end
+```
+
+### Prompt Registration
+
+Prompts can be registered in several ways:
+
+#### Class Registration
+
+```ruby
+server.register_prompt_class(CodeReviewer)
+# or
+server.prompt CodeReviewer
+```
+
+#### Instance Registration
+
+```ruby
+prompt = CodeReviewer.new
+server.register_prompt_instance(prompt)
+```
+
+#### Inline Registration
+
+```ruby
+server.register_prompt("simple") do |message:|
+  [
+    {
+      role: "user",
+      content: { type: "text", text: message }
+    }
+  ]
+end
+# or
+server.prompt "simple" do |message:|
+  [
+    {
+      role: "user",
+      content: { type: "text", text: message }
+    }
+  ]
+end
+```
+
+### Message Format
+
+Messages follow the OpenAI/Anthropic format:
+
+#### Basic Text Message
+
+```ruby
+{
+  role: "system",  # or "user", "assistant"
+  content: {
+    type: "text",
+    text: "The message content"
+  }
+}
+```
+
+#### Multiple Content Types
+
+```ruby
+{
+  role: "user",
+  content: [
+    {
+      type: "text",
+      text: "What's in this image?"
+    },
+    {
+      type: "image",
+      data: Base64.encode64(image_data),
+      mimeType: "image/png"
+    }
+  ]
+}
+```
+
+### Complex Prompt Examples
+
+#### Multi-Turn Conversation
+
+```ruby
+class ConversationalPrompt < Tsikol::Prompt
+  name "conversation"
+  description "Multi-turn conversational AI"
+  
+  argument :topic do
+    type :string
+    required
+    description "Conversation topic"
+  end
+  
+  argument :history do
+    type :array
+    optional
+    default []
+    description "Previous conversation messages"
+  end
+  
+  argument :personality do
+    type :string
+    optional
+    default "helpful"
+    enum ["helpful", "professional", "friendly", "concise"]
+  end
+  
+  def get_messages(topic:, history: [], personality: "helpful")
+    messages = []
+    
+    # System message with personality
+    messages << {
+      role: "system",
+      content: {
+        type: "text",
+        text: build_system_prompt(personality)
+      }
+    }
+    
+    # Include conversation history
+    history.each do |msg|
+      messages << format_history_message(msg)
+    end
+    
+    # Current user message
+    messages << {
+      role: "user",
+      content: {
+        type: "text",
+        text: topic
+      }
+    }
+    
+    messages
+  end
+  
+  private
+  
+  def build_system_prompt(personality)
+    base = "You are a conversational AI assistant."
+    
+    case personality
+    when "professional"
+      "#{base} Maintain a professional, business-appropriate tone."
+    when "friendly"
+      "#{base} Be warm, friendly, and conversational."
+    when "concise"
+      "#{base} Provide brief, direct responses."
+    else
+      "#{base} Be helpful and thorough in your responses."
+    end
+  end
+  
+  def format_history_message(msg)
+    {
+      role: msg["role"] || "user",
+      content: {
+        type: "text",
+        text: msg["content"] || msg["text"]
+      }
+    }
+  end
+end
+```
+
+#### Dynamic Context Loading
+
+```ruby
+class ContextAwarePrompt < Tsikol::Prompt
+  name "context_aware"
+  description "AI with dynamic context loading"
+  
+  argument :query do
+    type :string
+    required
+    description "User query"
+  end
+  
+  argument :context_sources do
+    type :array
+    optional
+    default ["docs", "code"]
+    description "Sources to load context from"
+  end
+  
+  argument :max_context_length do
+    type :integer
+    optional
+    default 2000
+    description "Maximum context length in tokens"
+  end
+  
+  def get_messages(query:, context_sources: ["docs", "code"], max_context_length: 2000)
+    messages = []
+    
+    # System message
+    messages << {
+      role: "system",
+      content: {
+        type: "text",
+        text: "You are an AI assistant with access to project documentation and code."
+      }
+    }
+    
+    # Load and add context
+    context_sources.each do |source|
+      context = load_context(source, query)
+      next if context.empty?
+      
+      messages << {
+        role: "system",
+        content: {
+          type: "text",
+          text: "Context from #{source}:\n#{truncate(context, max_context_length)}"
+        }
+      }
+    end
+    
+    # User query
+    messages << {
+      role: "user",
+      content: {
+        type: "text",
+        text: query
+      }
+    }
+    
+    messages
+  end
+  
+  private
+  
+  def load_context(source, query)
+    case source
+    when "docs"
+      load_documentation_context(query)
+    when "code"
+      load_code_context(query)
+    when "data"
+      load_data_context(query)
+    else
+      ""
+    end
+  end
+  
+  def load_documentation_context(query)
+    # Search documentation for relevant content
+    relevant_docs = search_docs(query)
+    relevant_docs.map { |doc| "#{doc[:title]}:\n#{doc[:content]}" }.join("\n\n")
+  end
+  
+  def load_code_context(query)
+    # Search codebase for relevant code
+    relevant_files = search_code(query)
+    relevant_files.map { |file| "File: #{file[:path]}\n```\n#{file[:content]}\n```" }.join("\n\n")
+  end
+  
+  def truncate(text, max_length)
+    return text if text.length <= max_length
+    text[0...max_length] + "... (truncated)"
+  end
+end
+```
+
+#### Template-Based Prompts
+
+```ruby
+class TemplatePrompt < Tsikol::Prompt
+  name "template"
+  description "Template-based prompt generation"
+  
+  argument :template_name do
+    type :string
+    required
+    enum ["bug_report", "feature_request", "code_review", "documentation"]
+    description "Template to use"
+  end
+  
+  argument :variables do
+    type :object
+    required
+    description "Variables to fill in the template"
+  end
+  
+  def get_messages(template_name:, variables:)
+    template = load_template(template_name)
+    filled_template = fill_template(template, variables)
+    
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: template[:system_prompt]
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: filled_template
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def load_template(name)
+    case name
+    when "bug_report"
+      {
+        system_prompt: "You are a software engineer analyzing bug reports. Provide detailed analysis and potential solutions.",
+        template: <<~TEMPLATE
+          Bug Report Analysis Request
+          
+          Title: {{title}}
+          Severity: {{severity}}
+          Component: {{component}}
+          
+          Description:
+          {{description}}
+          
+          Steps to Reproduce:
+          {{steps}}
+          
+          Expected Behavior:
+          {{expected}}
+          
+          Actual Behavior:
+          {{actual}}
+          
+          Environment:
+          {{environment}}
+        TEMPLATE
+      }
+    when "code_review"
+      {
+        system_prompt: "You are an experienced code reviewer. Provide constructive feedback on code quality, best practices, and potential improvements.",
+        template: <<~TEMPLATE
+          Code Review Request
+          
+          Language: {{language}}
+          Type: {{change_type}}
+          
+          Description of Changes:
+          {{description}}
+          
+          Code:
+          ```{{language}}
+          {{code}}
+          ```
+          
+          Specific Concerns:
+          {{concerns}}
+        TEMPLATE
+      }
+    # ... other templates
+    end
+  end
+  
+  def fill_template(template, variables)
+    result = template[:template].dup
+    
+    variables.each do |key, value|
+      result.gsub!("{{#{key}}}", value.to_s)
+    end
+    
+    # Check for missing variables
+    missing = result.scan(/\{\{(\w+)\}\}/).flatten
+    unless missing.empty?
+      raise Tsikol::ValidationError, "Missing template variables: #{missing.join(', ')}"
+    end
+    
+    result
+  end
+end
+```
+
+### Prompt Composition
+
+Combine multiple prompts or behaviors:
+
+```ruby
+class CompositePrompt < Tsikol::Prompt
+  name "composite"
+  description "Combines multiple AI behaviors"
+  
+  argument :task do
+    type :string
+    required
+  end
+  
+  argument :modes do
+    type :array
+    required
+    description "AI modes to activate"
+  end
+  
+  argument :context do
+    type :object
+    optional
+    default {}
+  end
+  
+  def get_messages(task:, modes:, context: {})
+    messages = []
+    
+    # Base system message
+    messages << {
+      role: "system",
+      content: {
+        type: "text",
+        text: "You are a multi-skilled AI assistant."
+      }
+    }
+    
+    # Add mode-specific instructions
+    modes.each do |mode|
+      mode_messages = get_mode_messages(mode, context)
+      messages.concat(mode_messages)
+    end
+    
+    # Add the task
+    messages << {
+      role: "user",
+      content: {
+        type: "text",
+        text: task
+      }
+    }
+    
+    messages
+  end
+  
+  private
+  
+  def get_mode_messages(mode, context)
+    case mode
+    when "researcher"
+      researcher_messages(context)
+    when "coder"
+      coder_messages(context)
+    when "analyst"
+      analyst_messages(context)
+    else
+      []
+    end
+  end
+  
+  def researcher_messages(context)
+    [{
+      role: "system",
+      content: {
+        type: "text",
+        text: <<~PROMPT
+          As a researcher:
+          - Gather information from multiple sources
+          - Verify facts and cite sources
+          - Present balanced viewpoints
+          - Highlight key findings
+        PROMPT
+      }
+    }]
+  end
+  
+  def coder_messages(context)
+    lang = context["language"] || "multiple languages"
+    [{
+      role: "system",
+      content: {
+        type: "text",
+        text: <<~PROMPT
+          As a coder working with #{lang}:
+          - Write clean, efficient code
+          - Follow best practices and conventions
+          - Include error handling
+          - Add helpful comments
+        PROMPT
+      }
+    }]
+  end
+end
+```
+
+## Testing Prompts
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+
+class PromptTest < Minitest::Test
+  include Tsikol::TestHelpers::Assertions
+  
+  def setup
+    @server = Tsikol::Server.new(name: "test")
+    @server.register_prompt_instance(CodeReviewer.new)
+    @client = Tsikol::TestHelpers::TestClient.new(@server)
+    @client.initialize_connection
+  end
+  
+  def test_basic_prompt
+    response = @client.get_prompt("code_reviewer", {
+      "code" => "def hello\n  puts 'Hello'\nend",
+      "language" => "ruby"
+    })
+    
+    assert_successful_response(response)
+    
+    messages = response.dig(:result, :messages)
+    assert messages.is_a?(Array)
+    assert messages.length >= 2
+    
+    # Verify system message
+    system_msg = messages.find { |m| m[:role] == "system" }
+    assert system_msg
+    assert_match /code review/i, system_msg[:content][:text]
+    
+    # Verify user message contains code
+    user_msg = messages.find { |m| m[:role] == "user" }
+    assert user_msg
+    assert_match /def hello/, user_msg[:content][:text]
+  end
+  
+  def test_argument_validation
+    # Missing required argument
+    response = @client.get_prompt("code_reviewer", {
+      "language" => "ruby"
+      # Missing "code" argument
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /code.*required/i, response[:error][:message]
+  end
+  
+  def test_enum_validation
+    response = @client.get_prompt("code_reviewer", {
+      "code" => "print('Hello')",
+      "language" => "cobol"  # Not in enum
+    })
+    
+    assert_error_response(response, -32602)
+    assert_match /must be one of/i, response[:error][:message]
+  end
+  
+  def test_optional_arguments_with_defaults
+    response = @client.get_prompt("code_reviewer", {
+      "code" => "console.log('Hello');",
+      "language" => "javascript"
+      # "style" will use default value
+    })
+    
+    assert_successful_response(response)
+    
+    # Should include default style in prompt
+    messages = response.dig(:result, :messages)
+    text = messages.map { |m| m[:content][:text] }.join(" ")
+    assert_match /standard/i, text  # Default style
+  end
+  
+  def test_completion
+    response = @client.complete(
+      { type: "ref/prompt", name: "code_reviewer" },
+      { name: "language", value: "ja" }
+    )
+    
+    assert_successful_response(response)
+    values = response.dig(:result, :completion, :values)
+    assert values.include?("javascript")
+    assert values.include?("java")
+  end
+end
+```
+
+## Best Practices
+
+### Clear System Prompts
+
+```ruby
+def get_messages(task:)
+  [
+    {
+      role: "system",
+      content: {
+        type: "text",
+        text: <<~PROMPT
+          You are an AI assistant specialized in #{specialty}.
+          
+          Your responsibilities:
+          1. Provide accurate information
+          2. Follow best practices
+          3. Explain your reasoning
+          
+          Constraints:
+          - Stay within your area of expertise
+          - Acknowledge when you're unsure
+          - Provide sources when possible
+        PROMPT
+      }
+    },
+    {
+      role: "user",
+      content: { type: "text", text: task }
+    }
+  ]
+end
+```
+
+### Dynamic Context
+
+```ruby
+def get_messages(query:, include_context: true)
+  messages = [base_system_message]
+  
+  if include_context
+    # Add relevant context
+    messages << context_message(query)
+  end
+  
+  # Add examples if helpful
+  if would_benefit_from_examples?(query)
+    messages.concat(example_messages)
+  end
+  
+  messages << user_message(query)
+  messages
+end
+```
+
+### Error Handling
+
+```ruby
+def get_messages(**args)
+  validate_arguments!(args)
+  
+  messages = build_messages(args)
+  
+  # Ensure valid message format
+  validate_messages!(messages)
+  
+  messages
+rescue => e
+  # Return minimal valid prompt on error
+  [
+    {
+      role: "user",
+      content: {
+        type: "text",
+        text: "Error building prompt: #{e.message}"
+      }
+    }
+  ]
+end
+```
+
+## See Also
+
+- [Prompts Guide](../guides/prompts.md)
+- [Server API](server.md)
+- [Testing Guide](../guides/testing.md)
+- [Sampling Guide](../guides/sampling.md)