tsikol 0.1.0

data/examples/advanced_features.rb

@@ -0,0 +1,129 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/tsikol'
+
+# Example showing advanced features: lifecycle hooks, health monitoring, error handling
+
+Tsikol.server "advanced-server" do
+  # Configure middleware with error handling
+  use Tsikol::ValidationMiddleware
+  use Tsikol::LoggingMiddleware, logger: self
+  
+  # Lifecycle hooks
+  before_start do
+    log :info, "Initializing server resources..."
+    # Initialize connections, load configs, etc.
+    @startup_time = Time.now
+  end
+  
+  after_start do
+    log :info, "Server ready to accept requests"
+    log :info, "Health endpoint available at: resource health"
+  end
+  
+  before_stop do
+    log :info, "Gracefully shutting down..."
+    # Close connections, save state, etc.
+  end
+  
+  after_stop do
+    uptime = Time.now - @startup_time
+    log :info, "Server stopped after #{uptime.round(2)} seconds"
+  end
+  
+  # Tool-specific hooks
+  before_tool "critical_operation" do |params|
+    log :warning, "Executing critical operation", data: params
+  end
+  
+  after_tool "critical_operation" do |params, result|
+    log :info, "Critical operation completed", data: { params: params, result: result }
+  end
+  
+  # General tool hooks for metrics
+  before_tool do |tool_name, params|
+    log :debug, "Calling tool: #{tool_name}"
+  end
+  
+  after_tool do |tool_name, params, result|
+    log :debug, "Tool #{tool_name} completed"
+  end
+  
+  # Tools with different error scenarios
+  tool "safe_operation" do |input:|
+    "Processed: #{input}"
+  end
+  
+  tool "risky_operation" do |should_fail: false|
+    raise "Simulated failure" if should_fail
+    "Operation successful"
+  end
+  
+  tool "critical_operation" do |data:, validate: true|
+    if validate && data.nil?
+      raise Tsikol::ValidationError, "Data cannot be nil"
+    end
+    
+    # Simulate some work
+    sleep(0.1)
+    "Critical operation completed for: #{data}"
+  end
+  
+  tool "slow_operation" do |timeout: 5|
+    log :info, "Starting slow operation", data: { timeout: timeout }
+    
+    # Simulate work that might timeout
+    timeout.times do |i|
+      sleep(1)
+      log :debug, "Progress: #{i + 1}/#{timeout}"
+    end
+    
+    "Completed after #{timeout} seconds"
+  end
+  
+  # Tool that demonstrates circuit breaker
+  tool "flaky_service" do
+    # This would fail randomly to demonstrate circuit breaker
+    if rand > 0.7
+      raise "Service temporarily unavailable"
+    end
+    "Service responded successfully"
+  end
+  
+  # Resource showing detailed metrics
+  resource "admin/metrics" do
+    {
+      server: {
+        name: @name,
+        version: @version,
+        uptime: Time.now - @startup_time,
+        health_status: health_status
+      },
+      metrics: @metrics.to_h,
+      error_handler: {
+        circuit_breakers: @error_handler.instance_variable_get(:@circuit_breakers).keys,
+        error_counts: @error_handler.instance_variable_get(:@error_counts)
+      }
+    }.to_json
+  end
+  
+  # Resource for testing error scenarios
+  resource "test/error" do
+    raise "This is a test error"
+  end
+  
+  # Prompt that tracks usage
+  prompt "analyze" do |data:, depth: "medium"|
+    @metrics.increment("prompts:analyze:usage")
+    "Analyze the following data with #{depth} depth analysis: #{data}"
+  end
+  
+  # Enable all capabilities
+  logging true
+  completion true
+  sampling true
+  
+  # Log server configuration
+  log :info, "Advanced server configured with lifecycle hooks and monitoring"
+end

data/examples/basic-migrated/app/prompts/weather_chat.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class WeatherChat < Tsikol::Prompt
+  name "weather_chat"
+  description "Weather chat prompt"
+  
+  argument :city do
+    type :string
+    required
+    description "City to ask about weather"
+    
+    complete do |partial|
+      # List of cities for autocomplete
+      cities = [
+        "New York", "London", "Tokyo", "Paris", "Berlin",
+        "Sydney", "Toronto", "Mumbai", "Beijing", "Moscow",
+        "Los Angeles", "Chicago", "Houston", "Phoenix", "Philadelphia"
+      ]
+      
+      # Filter cities that start with the partial input (case-insensitive)
+      cities.select { |city| city.downcase.start_with?(partial.downcase) }
+    end
+  end
+  
+  def get_messages(city:)
+    [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "What's the weather like in #{city}? Please give me current conditions and a forecast."
+        }
+      }
+    ]
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    define_singleton_method(:log) do |level, message, data: nil, logger: nil|
+      @server.log(level, message, data: data, logger: logger)
+    end
+  end
+end

data/examples/basic-migrated/app/resources/weather_alerts.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+class WeatherAlerts < Tsikol::Resource
+  uri "weather/alerts"
+  description "Active weather alerts"
+  
+  def read
+    "No active weather alerts"
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    define_singleton_method(:log) do |level, message, data: nil, logger: nil|
+      @server.log(level, message, data: data, logger: logger)
+    end
+  end
+end

data/examples/basic-migrated/app/tools/get_current_weather.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class GetCurrentWeather < Tsikol::Tool
+  description "Get current weather for a location"
+  
+  parameter :location do
+    type :string
+    required
+    description "Location to get weather for"
+  end
+  
+  def execute(location:)
+    log :info, "Getting weather for #{location}" if respond_to?(:log)
+    
+    temps = { "New York" => 72, "London" => 61, "Tokyo" => 77 }
+    temp = temps[location] || 70
+    
+    if temps[location]
+      log :debug, "Found temperature in cache", data: { location: location, temp: temp } if respond_to?(:log)
+    else
+      log :warning, "Location not found, using default", data: { location: location } if respond_to?(:log)
+    end
+    
+    "Currently #{temp}°F in #{location}"
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    define_singleton_method(:log) do |level, message, data: nil, logger: nil|
+      @server.log(level, message, data: data, logger: logger)
+    end
+  end
+end

data/examples/basic-migrated/app/tools/get_forecast.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+class GetForecast < Tsikol::Tool
+  description "Get weather forecast for a location"
+  
+  parameter :location do
+    type :string
+    required
+    description "Location to get forecast for"
+  end
+  
+  parameter :days do
+    type :integer
+    optional
+    default 3
+    description "Number of days to forecast"
+  end
+  
+  def execute(location:, days: 3)
+    "#{days}-day forecast for #{location}: Mostly sunny"
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    define_singleton_method(:log) do |level, message, data: nil, logger: nil|
+      @server.log(level, message, data: data, logger: logger)
+    end
+  end
+end

data/examples/basic-migrated/app/tools/get_weather_by_coords.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class GetWeatherByCoords < Tsikol::Tool
+  description "Get weather by coordinates"
+  
+  parameter :latitude do
+    type :number
+    required
+    description "Latitude coordinate"
+  end
+  
+  parameter :longitude do
+    type :number
+    required
+    description "Longitude coordinate"
+  end
+  
+  parameter :location_name do
+    type :string
+    required
+    description "Name of the location"
+    
+    complete do |partial|
+      # In a real app, this might reverse geocode based on lat/long
+      locations = [
+        "Central Park, NYC",
+        "Times Square, NYC", 
+        "Brooklyn Bridge, NYC",
+        "Statue of Liberty, NYC",
+        "Empire State Building, NYC"
+      ]
+      
+      locations.select { |loc| loc.downcase.include?(partial.downcase) }
+    end
+  end
+  
+  def execute(latitude:, longitude:, location_name:)
+    "Weather at #{location_name} (#{latitude}, #{longitude}): Sunny, 75°F"
+  end
+  
+  def set_server(server)
+    @server = server
+    
+    define_singleton_method(:log) do |level, message, data: nil, logger: nil|
+      @server.log(level, message, data: data, logger: logger)
+    end
+  end
+end

data/examples/basic-migrated/server.rb

@@ -0,0 +1,25 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../../lib/tsikol'
+
+# Option 1: Direct class references (requires explicit require)
+require_relative 'app/tools/get_current_weather'
+require_relative 'app/tools/get_forecast'
+require_relative 'app/tools/get_weather_by_coords'
+require_relative 'app/resources/weather_alerts'
+require_relative 'app/prompts/weather_chat'
+
+Tsikol.start(name: "weather-service") do
+  # Direct class references
+  tool GetCurrentWeather
+  tool GetForecast
+  tool GetWeatherByCoords
+  resource WeatherAlerts
+  prompt WeatherChat
+  
+  # Inline definition still works
+  resource "server/health" do
+    "Weather service is healthy"
+  end
+end

data/examples/basic.rb

@@ -0,0 +1,73 @@
+require_relative '../lib/tsikol'
+
+# NOTE: This example uses the original DSL-style API.
+# For the new Rails-like structure with separate files, see examples/basic-migrated/
+# or examples/weather-service/ for a more complete example.
+
+Tsikol.server "weather-service" do
+  # Declare server capabilities (optional - features auto-enable when used)
+  # capabilities do
+  #   logging      # Auto-enabled when using 'log'
+  #   completion   # Auto-enabled when using 'completion_for'
+  #   sampling     # Must be explicitly enabled
+  # end
+  
+  tool "get_current_weather" do |location:|
+    log :info, "Getting weather for #{location}"
+    
+    temps = { "New York" => 72, "London" => 61, "Tokyo" => 77 }
+    temp = temps[location] || 70
+    
+    if temps[location]
+      log :debug, "Found temperature in cache", data: { location: location, temp: temp }
+    else
+      log :warning, "Location not found, using default", data: { location: location }
+    end
+    
+    "Currently #{temp}°F in #{location}"
+  end
+  
+  tool "get_forecast" do |location:, days: 3|
+    "#{days}-day forecast for #{location}: Mostly sunny"
+  end
+  
+  resource "weather/alerts" do
+    "No active weather alerts"
+  end
+  
+  prompt "weather_chat" do |city:|
+    "What's the weather like in #{city}? Please give me current conditions and a forecast."
+  end
+  
+  # Define completions for the weather_chat prompt's city argument
+  completion_for "prompt", "weather_chat", "city" do |partial|
+    # List of cities for autocomplete
+    cities = [
+      "New York", "London", "Tokyo", "Paris", "Berlin",
+      "Sydney", "Toronto", "Mumbai", "Beijing", "Moscow",
+      "Los Angeles", "Chicago", "Houston", "Phoenix", "Philadelphia"
+    ]
+    
+    # Filter cities that start with the partial input (case-insensitive)
+    cities.select { |city| city.downcase.start_with?(partial.downcase) }
+  end
+  
+  # Tool for demonstrating location autocomplete
+  tool "get_weather_by_coords" do |latitude:, longitude:, location_name:|
+    "Weather at #{location_name} (#{latitude}, #{longitude}): Sunny, 75°F"
+  end
+  
+  # Completion for location names based on coordinates
+  completion_for "tool", "get_weather_by_coords", "location_name" do |partial|
+    # In a real app, this might reverse geocode based on lat/long
+    locations = [
+      "Central Park, NYC",
+      "Times Square, NYC", 
+      "Brooklyn Bridge, NYC",
+      "Statue of Liberty, NYC",
+      "Empire State Building, NYC"
+    ]
+    
+    locations.select { |loc| loc.downcase.include?(partial.downcase) }
+  end
+end

data/examples/full_featured.rb

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/tsikol'
+
+# Full-featured example showing all Tsikol capabilities
+
+# Custom middleware for API key validation
+class ApiKeyMiddleware < Tsikol::Middleware
+  def initialize(app, valid_keys: [])
+    super(app)
+    @valid_keys = valid_keys
+  end
+  
+  def before_request(message)
+    # Skip auth for certain methods
+    return message if %w[initialize tools/list].include?(message["method"])
+    
+    api_key = message.dig("metadata", "api_key")
+    unless @valid_keys.include?(api_key)
+      raise "Invalid API key"
+    end
+    
+    message
+  end
+end
+
+Tsikol.start(name: "full-featured-server") do
+  # Configure middleware stack
+  use Tsikol::ValidationMiddleware
+  use Tsikol::LoggingMiddleware
+  use ApiKeyMiddleware, valid_keys: ["demo-key-123", "test-key-456"]
+  use Tsikol::RateLimitMiddleware, max_requests: 100, window: 60
+  
+  # Enable all capabilities
+  logging true
+  completion true
+  
+  # Configure sampling with AI assistance
+  on_sampling do |request|
+    messages = request[:messages]
+    system_prompt = request[:system_prompt] || "You are a helpful assistant."
+    
+    # Log sampling request
+    log :info, "AI assistance requested", data: {
+      messages: messages.size,
+      system: system_prompt
+    }
+    
+    # Simulate AI response (in production, MCP client handles this)
+    {
+      role: "assistant",
+      content: {
+        type: "text",
+        text: "AI response would be generated by the MCP client (e.g., Claude Code)"
+      }
+    }
+  end
+  
+  # Advanced tool with parameter validation and completion
+  tool "data_processor" do |data:, format: "json", validate: true|
+    log :info, "Processing data", data: { format: format, validate: validate }
+    
+    begin
+      case format
+      when "json"
+        parsed = JSON.parse(data)
+        "Processed #{parsed.keys.size} fields"
+      when "csv"
+        lines = data.lines.count
+        "Processed #{lines} CSV rows"
+      when "xml"
+        "XML processing not implemented (demo)"
+      else
+        raise "Unsupported format: #{format}"
+      end
+    rescue => e
+      log :error, "Processing failed", data: { error: e.message }
+      "Error: #{e.message}"
+    end
+  end
+  
+  # Tool with completions
+  tool "query_database" do |table:, query_type: "select"|
+    "Executed #{query_type.upcase} on table: #{table}"
+  end
+  
+  # Define completions for database tool
+  completion_for "tool", "query_database", "table" do |partial|
+    tables = ["users", "orders", "products", "categories", "reviews"]
+    tables.select { |t| t.start_with?(partial.downcase) }
+  end
+  
+  completion_for "tool", "query_database", "query_type" do |partial|
+    types = ["select", "insert", "update", "delete", "count"]
+    types.select { |t| t.start_with?(partial.downcase) }
+  end
+  
+  # Resource with dynamic content
+  resource "system/status" do
+    {
+      server: "full-featured-server",
+      version: "1.0.0",
+      uptime: Time.now - $server_start_time,
+      capabilities: {
+        logging: true,
+        completion: true,
+        sampling: true,
+        middleware: true
+      },
+      stats: {
+        requests_handled: rand(1000..5000),
+        active_connections: rand(1..10),
+        memory_usage: "#{rand(50..200)}MB"
+      }
+    }.to_json
+  end
+  
+  # Advanced prompt with multiple arguments
+  prompt "code_review" do |language:, code:, focus: "general"|
+    prompt_text = "Please review this #{language} code"
+    prompt_text += " with focus on #{focus}" unless focus == "general"
+    prompt_text += ":\n\n```#{language}\n#{code}\n```"
+    prompt_text
+  end
+  
+  # Prompt completions
+  completion_for "prompt", "code_review", "language" do |partial|
+    languages = ["ruby", "python", "javascript", "typescript", "go", "rust", "java"]
+    languages.select { |l| l.start_with?(partial.downcase) }
+  end
+  
+  completion_for "prompt", "code_review", "focus" do |partial|
+    focuses = ["general", "performance", "security", "style", "bugs", "architecture"]
+    focuses.select { |f| f.include?(partial.downcase) }
+  end
+  
+  # Tool that uses sampling for enhanced functionality
+  tool "generate_documentation" do |code:, style: "markdown"|
+    log :info, "Generating documentation for code"
+    
+    # This would trigger sampling in a real implementation
+    <<~DOC
+    # Generated Documentation
+    
+    This documentation would be AI-generated based on the provided code.
+    Style: #{style}
+    
+    ## Overview
+    [AI would analyze and document the code here]
+    
+    ## Usage
+    [AI would provide usage examples]
+    
+    ## API Reference
+    [AI would document the API]
+    DOC
+  end
+  
+  # Resource showing middleware info
+  resource "debug/middleware" do
+    "Active middleware: Validation, Logging, ApiKey, RateLimit"
+  end
+  
+  # Admin tool protected by middleware
+  tool "admin/reset_stats" do
+    log :warning, "Stats reset requested"
+    "Statistics reset successfully (requires valid API key)"
+  end
+  
+  # Initialize server start time for uptime tracking
+  $server_start_time = Time.now
+  
+  log :info, "Full-featured server started with all capabilities enabled"
+end

data/examples/middleware_example.rb

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/tsikol'
+
+# Custom middleware example
+class TimingMiddleware < Tsikol::Middleware
+  def before_request(message)
+    message["_start_time"] = Time.now
+    message
+  end
+  
+  def after_response(response, original_message)
+    if original_message["_start_time"]
+      duration = Time.now - original_message["_start_time"]
+      puts "Request #{original_message['method']} took #{(duration * 1000).round(2)}ms"
+    end
+    response
+  end
+end
+
+# Audit middleware
+class AuditMiddleware < Tsikol::Middleware
+  def initialize(app, audit_file: "audit.log")
+    super(app)
+    @audit_file = audit_file
+  end
+  
+  def before_request(message)
+    File.open(@audit_file, "a") do |f|
+      f.puts "[#{Time.now}] REQUEST: #{message['method']} (id: #{message['id']})"
+      f.puts "  Params: #{message['params'].inspect}" if message['params']
+    end
+    message
+  end
+  
+  def after_response(response, original_message)
+    File.open(@audit_file, "a") do |f|
+      if response["error"]
+        f.puts "[#{Time.now}] ERROR: #{response['error']['message']}"
+      else
+        f.puts "[#{Time.now}] SUCCESS: #{original_message['method']}"
+      end
+      f.puts "-" * 50
+    end
+    response
+  end
+end
+
+# Create server with middleware
+Tsikol.server "middleware-demo" do
+  # Add middleware
+  use Tsikol::LoggingMiddleware
+  use TimingMiddleware
+  use AuditMiddleware, audit_file: "server_audit.log"
+  use Tsikol::RateLimitMiddleware, max_requests: 10, window: 60
+  
+  # Middleware for specific methods only
+  use Tsikol::AuthenticationMiddleware do |auth_info, message|
+    # Simple auth check - in production this would verify tokens, etc.
+    if message["method"] == "admin/shutdown"
+      auth_info["admin"] == true
+    else
+      true # Allow all other methods
+    end
+  end
+  
+  # Regular tools
+  tool "echo" do |message:|
+    "Echo: #{message}"
+  end
+  
+  tool "slow_operation" do |duration: 1|
+    sleep(duration.to_f)
+    "Operation completed after #{duration} seconds"
+  end
+  
+  tool "error_prone" do |should_fail: false|
+    raise "Intentional error" if should_fail
+    "Success!"
+  end
+  
+  # Admin tool (requires auth)
+  tool "admin/shutdown" do
+    "Server would shutdown (demo mode - not actually shutting down)"
+  end
+  
+  # Resource showing middleware info
+  resource "middleware/stack" do
+    {
+      middlewares: [
+        "LoggingMiddleware - Logs all requests and responses",
+        "TimingMiddleware - Measures request duration",
+        "AuditMiddleware - Writes audit log to file",
+        "RateLimitMiddleware - Limits to 10 requests per minute",
+        "AuthenticationMiddleware - Protects admin endpoints"
+      ],
+      benefits: [
+        "Cross-cutting concerns handled separately",
+        "Easy to add/remove functionality",
+        "Consistent request/response processing",
+        "Better debugging and monitoring"
+      ]
+    }.to_json
+  end
+  
+  # Enable logging for middleware demo
+  logging true
+  
+  # Set log level to debug to see middleware logs
+  log :info, "Server started with middleware stack"
+end