tsikol 0.1.0

data/docs/examples/weather-service.md

@@ -0,0 +1,822 @@
+# Weather Service Example
+
+A comprehensive MCP server providing weather information with caching, rate limiting, and multiple data sources.
+
+## Overview
+
+This example demonstrates:
+- External API integration
+- Caching strategies
+- Rate limiting
+- Error handling and fallbacks
+- Resource implementation
+- Prompt templates
+- Testing with mocked APIs
+
+## Implementation
+
+### server.rb
+
+```ruby
+#!/usr/bin/env ruby
+
+require 'tsikol'
+require 'net/http'
+require 'json'
+require 'redis'
+
+# Weather API client
+class WeatherClient
+  API_KEY = ENV['OPENWEATHER_API_KEY']
+  BASE_URL = 'https://api.openweathermap.org/data/2.5'
+  
+  def initialize
+    @cache = {}
+  end
+  
+  def current_weather(city)
+    fetch_data("weather", { q: city })
+  end
+  
+  def forecast(city, days = 5)
+    data = fetch_data("forecast", { q: city, cnt: days * 8 })
+    parse_forecast(data)
+  end
+  
+  private
+  
+  def fetch_data(endpoint, params)
+    params[:appid] = API_KEY
+    params[:units] = 'metric'
+    
+    uri = URI("#{BASE_URL}/#{endpoint}")
+    uri.query = URI.encode_www_form(params)
+    
+    response = Net::HTTP.get_response(uri)
+    
+    unless response.is_a?(Net::HTTPSuccess)
+      raise "Weather API error: #{response.code} #{response.message}"
+    end
+    
+    JSON.parse(response.body)
+  end
+  
+  def parse_forecast(data)
+    # Group forecast by day
+    daily_forecast = data['list'].group_by do |item|
+      Time.at(item['dt']).strftime('%Y-%m-%d')
+    end
+    
+    daily_forecast.map do |date, items|
+      temps = items.map { |i| i['main']['temp'] }
+      {
+        date: date,
+        temp_min: temps.min,
+        temp_max: temps.max,
+        temp_avg: (temps.sum / temps.size).round(1),
+        conditions: items.map { |i| i['weather'][0]['main'] }.uniq
+      }
+    end
+  end
+end
+
+# Current weather tool
+class CurrentWeatherTool < Tsikol::Tool
+  name "current_weather"
+  description "Get current weather for a city"
+  
+  parameter :city do
+    type :string
+    required
+    description "City name (e.g., 'London', 'New York')"
+    
+    complete do |partial|
+      # Suggest popular cities
+      cities = [
+        "London", "New York", "Tokyo", "Paris", "Sydney",
+        "Los Angeles", "Chicago", "Toronto", "Berlin", "Madrid"
+      ]
+      cities.select { |c| c.downcase.start_with?(partial.downcase) }
+    end
+  end
+  
+  parameter :units do
+    type :string
+    optional
+    default "celsius"
+    enum ["celsius", "fahrenheit"]
+    description "Temperature units"
+  end
+  
+  def execute(city:, units: "celsius")
+    # Check cache first
+    cache_key = "weather:current:#{city.downcase}"
+    
+    data = with_cache(cache_key, ttl: 600) do
+      weather_client.current_weather(city)
+    end
+    
+    format_current_weather(data, units)
+  rescue => e
+    log :error, "Weather fetch failed", city: city, error: e.message
+    "Unable to fetch weather for #{city}: #{e.message}"
+  end
+  
+  private
+  
+  def format_current_weather(data, units)
+    temp = data['main']['temp']
+    feels_like = data['main']['feels_like']
+    
+    if units == "fahrenheit"
+      temp = celsius_to_fahrenheit(temp)
+      feels_like = celsius_to_fahrenheit(feels_like)
+      unit_symbol = "�F"
+    else
+      unit_symbol = "�C"
+    end
+    
+    <<~WEATHER
+      Weather in #{data['name']}, #{data['sys']['country']}:
+      
+      Conditions: #{data['weather'][0]['description'].capitalize}
+      Temperature: #{temp.round(1)}#{unit_symbol}
+      Feels like: #{feels_like.round(1)}#{unit_symbol}
+      Humidity: #{data['main']['humidity']}%
+      Wind: #{data['wind']['speed']} m/s
+      Pressure: #{data['main']['pressure']} hPa
+      
+      Last updated: #{Time.at(data['dt']).strftime('%Y-%m-%d %H:%M')}
+    WEATHER
+  end
+  
+  def celsius_to_fahrenheit(celsius)
+    (celsius * 9/5) + 32
+  end
+  
+  def weather_client
+    @weather_client ||= WeatherClient.new
+  end
+end
+
+# Weather forecast tool
+class WeatherForecastTool < Tsikol::Tool
+  name "weather_forecast"
+  description "Get weather forecast for a city"
+  
+  parameter :city do
+    type :string
+    required
+    description "City name"
+  end
+  
+  parameter :days do
+    type :number
+    optional
+    default 5
+    description "Number of days (1-5)"
+  end
+  
+  def execute(city:, days: 5)
+    days = [[1, days].max, 5].min  # Clamp between 1 and 5
+    
+    cache_key = "weather:forecast:#{city.downcase}:#{days}"
+    
+    forecast = with_cache(cache_key, ttl: 3600) do
+      weather_client.forecast(city, days)
+    end
+    
+    format_forecast(city, forecast)
+  rescue => e
+    log :error, "Forecast fetch failed", city: city, error: e.message
+    "Unable to fetch forecast for #{city}: #{e.message}"
+  end
+  
+  private
+  
+  def format_forecast(city, forecast)
+    lines = ["#{days}-day forecast for #{city}:", ""]
+    
+    forecast.each do |day|
+      date = Date.parse(day[:date]).strftime('%A, %B %d')
+      temps = "#{day[:temp_min]}�C - #{day[:temp_max]}�C (avg: #{day[:temp_avg]}�C)"
+      conditions = day[:conditions].join(", ")
+      
+      lines << "#{date}:"
+      lines << "  Temperature: #{temps}"
+      lines << "  Conditions: #{conditions}"
+      lines << ""
+    end
+    
+    lines.join("\n")
+  end
+  
+  def weather_client
+    @weather_client ||= WeatherClient.new
+  end
+end
+
+# Weather alerts resource
+class WeatherAlertsResource < Tsikol::Resource
+  uri "weather/alerts/:region?"
+  description "Active weather alerts for a region"
+  
+  def read
+    region = params[:region] || "global"
+    
+    # In a real implementation, this would fetch from a weather alerts API
+    alerts = fetch_alerts(region)
+    
+    {
+      region: region,
+      alerts: alerts,
+      last_updated: Time.now.iso8601,
+      severity_levels: ["info", "warning", "severe", "extreme"]
+    }.to_json
+  end
+  
+  private
+  
+  def fetch_alerts(region)
+    # Mock implementation - replace with real API
+    case region.downcase
+    when "california"
+      [
+        {
+          id: "CA-001",
+          type: "fire_weather",
+          severity: "warning",
+          title: "Red Flag Warning",
+          description: "High winds and low humidity",
+          areas: ["Los Angeles County", "Ventura County"],
+          valid_until: (Time.now + 86400).iso8601
+        }
+      ]
+    when "florida"
+      [
+        {
+          id: "FL-001",
+          type: "thunderstorm",
+          severity: "warning",
+          title: "Severe Thunderstorm Warning",
+          description: "Possible tornadoes and damaging winds",
+          areas: ["Miami-Dade County"],
+          valid_until: (Time.now + 7200).iso8601
+        }
+      ]
+    else
+      []
+    end
+  end
+end
+
+# Historical weather data resource
+class HistoricalWeatherResource < Tsikol::Resource
+  uri "weather/history/:city/:date?"
+  description "Historical weather data for a city"
+  
+  def read
+    city = params[:city]
+    date = params[:date] || Date.today.to_s
+    
+    # Check if date is valid and not in future
+    begin
+      parsed_date = Date.parse(date)
+      if parsed_date > Date.today
+        return error_response("Cannot get historical data for future dates")
+      end
+    rescue
+      return error_response("Invalid date format. Use YYYY-MM-DD")
+    end
+    
+    # Fetch from cache or API
+    cache_key = "weather:history:#{city}:#{date}"
+    data = with_cache(cache_key, ttl: 86400) do  # Cache for 24 hours
+      fetch_historical_data(city, parsed_date)
+    end
+    
+    format_historical_data(city, date, data)
+  end
+  
+  private
+  
+  def fetch_historical_data(city, date)
+    # Mock implementation - replace with real historical weather API
+    {
+      temp_min: 10 + rand(5),
+      temp_max: 20 + rand(10),
+      temp_avg: 15 + rand(5),
+      precipitation: rand(20),
+      humidity: 50 + rand(30),
+      conditions: ["Partly Cloudy", "Sunny", "Overcast"].sample
+    }
+  end
+  
+  def format_historical_data(city, date, data)
+    {
+      city: city,
+      date: date,
+      temperature: {
+        min: "#{data[:temp_min]}�C",
+        max: "#{data[:temp_max]}�C",
+        average: "#{data[:temp_avg]}�C"
+      },
+      precipitation: "#{data[:precipitation]}mm",
+      humidity: "#{data[:humidity]}%",
+      conditions: data[:conditions]
+    }.to_json
+  end
+  
+  def error_response(message)
+    { error: message }.to_json
+  end
+end
+
+# Weather assistant prompt
+class WeatherAssistantPrompt < Tsikol::Prompt
+  name "weather_assistant"
+  description "Expert weather assistant with comprehensive knowledge"
+  
+  argument :focus do
+    type :string
+    optional
+    enum ["current", "forecast", "alerts", "travel", "activities"]
+    description "Specific focus area for the assistant"
+  end
+  
+  argument :location do
+    type :string
+    optional
+    description "Default location for weather queries"
+  end
+  
+  def get_messages(focus: nil, location: nil)
+    system_message = build_system_message(focus, location)
+    
+    [
+      {
+        role: "system",
+        content: {
+          type: "text",
+          text: system_message
+        }
+      },
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: "You are now active and ready to help with weather information."
+        }
+      },
+      {
+        role: "assistant",
+        content: {
+          type: "text",
+          text: "I'm ready to help you with weather information#{location ? " for #{location}" : ''}. I can provide current conditions, forecasts, weather alerts, and recommendations for weather-related activities. What would you like to know?"
+        }
+      }
+    ]
+  end
+  
+  private
+  
+  def build_system_message(focus, location)
+    base = <<~SYSTEM
+      You are an expert weather assistant with access to comprehensive weather data and tools.
+      
+      Available tools:
+      - current_weather: Get current weather conditions for any city
+      - weather_forecast: Get multi-day weather forecasts
+      
+      Available resources:
+      - weather/alerts/{region}: Check active weather alerts
+      - weather/history/{city}/{date}: Access historical weather data
+      
+      Key capabilities:
+      1. Provide accurate, up-to-date weather information
+      2. Interpret weather data in user-friendly terms
+      3. Give weather-based recommendations for activities
+      4. Explain weather patterns and phenomena
+      5. Provide travel weather advisories
+    SYSTEM
+    
+    if focus
+      base += "\n\nSpecial focus: #{focus_description(focus)}"
+    end
+    
+    if location
+      base += "\n\nDefault location: #{location} (but assist with any location requested)"
+    end
+    
+    base
+  end
+  
+  def focus_description(focus)
+    case focus
+    when "current"
+      "Emphasize current weather conditions and immediate concerns"
+    when "forecast"
+      "Focus on weather predictions and trends"
+    when "alerts"
+      "Prioritize weather warnings and safety information"
+    when "travel"
+      "Provide weather information relevant to travel planning"
+    when "activities"
+      "Suggest weather-appropriate activities and timing"
+    end
+  end
+end
+
+# Caching mixin
+module Cacheable
+  def with_cache(key, ttl: 300)
+    if redis_available?
+      cached = redis.get(key)
+      return JSON.parse(cached) if cached
+      
+      result = yield
+      redis.setex(key, ttl, result.to_json)
+      result
+    else
+      # Fallback to in-memory cache
+      @memory_cache ||= {}
+      if cached = @memory_cache[key]
+        return cached[:data] if Time.now < cached[:expires_at]
+      end
+      
+      result = yield
+      @memory_cache[key] = {
+        data: result,
+        expires_at: Time.now + ttl
+      }
+      result
+    end
+  end
+  
+  private
+  
+  def redis
+    @redis ||= Redis.new
+  end
+  
+  def redis_available?
+    return @redis_available if defined?(@redis_available)
+    @redis_available = begin
+      redis.ping == "PONG"
+    rescue
+      false
+    end
+  end
+end
+
+# Include caching in tools and resources
+[CurrentWeatherTool, WeatherForecastTool, HistoricalWeatherResource].each do |klass|
+  klass.include Cacheable
+end
+
+# Start the server
+Tsikol.start(
+  name: "weather-service",
+  version: "1.0.0",
+  description: "Comprehensive weather information service"
+) do
+  # Enable capabilities
+  logging true
+  prompts true
+  
+  # Middleware stack
+  use Tsikol::LoggingMiddleware, level: :info
+  use Tsikol::RateLimitMiddleware, 
+      max_requests: 60,
+      window_seconds: 60
+  use Tsikol::CachingMiddleware,
+      cacheable_methods: ["resources/read"]
+  
+  # Register components
+  tool CurrentWeatherTool
+  tool WeatherForecastTool
+  resource WeatherAlertsResource
+  resource HistoricalWeatherResource
+  prompt WeatherAssistantPrompt
+  
+  # Service status resource
+  resource "status" do
+    description "Weather service status"
+    
+    def read
+      {
+        status: "operational",
+        api_key_configured: !ENV['OPENWEATHER_API_KEY'].nil?,
+        cache_available: redis_available?,
+        components: {
+          current_weather: "operational",
+          forecast: "operational",
+          alerts: "operational",
+          historical: "operational"
+        },
+        rate_limits: {
+          requests_per_minute: 60,
+          burst_capacity: 10
+        }
+      }.to_json
+    end
+    
+    def redis_available?
+      Redis.new.ping == "PONG" rescue false
+    end
+  end
+end
+```
+
+### config.yml
+
+```yaml
+# Weather service configuration
+weather_service:
+  # API configuration
+  openweather:
+    api_key: ${OPENWEATHER_API_KEY}
+    timeout: 10
+    retry_attempts: 3
+  
+  # Caching
+  cache:
+    redis_url: ${REDIS_URL:-redis://localhost:6379}
+    ttl:
+      current_weather: 600      # 10 minutes
+      forecast: 3600           # 1 hour
+      alerts: 300              # 5 minutes
+      historical: 86400        # 24 hours
+  
+  # Rate limiting per tier
+  rate_limits:
+    free:
+      requests_per_minute: 10
+      burst: 5
+    premium:
+      requests_per_minute: 60
+      burst: 20
+    enterprise:
+      requests_per_minute: 600
+      burst: 100
+  
+  # Supported regions for alerts
+  alert_regions:
+    - global
+    - usa
+    - europe
+    - asia
+    - california
+    - florida
+    - texas
+```
+
+### Testing
+
+```ruby
+require 'minitest/autorun'
+require 'tsikol/test_helpers'
+require 'webmock/minitest'
+
+class WeatherServiceTest < Minitest::Test
+  include Tsikol::TestHelpers
+  
+  def setup
+    @server = create_test_server
+    @client = TestClient.new(@server)
+    
+    # Mock weather API responses
+    stub_weather_api
+  end
+  
+  def test_current_weather
+    response = @client.call_tool("current_weather", {
+      "city" => "London"
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /Weather in London/, result
+    assert_match /Temperature:/, result
+    assert_match /Humidity:/, result
+  end
+  
+  def test_weather_forecast
+    response = @client.call_tool("weather_forecast", {
+      "city" => "New York",
+      "days" => 3
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /3-day forecast for New York/, result
+  end
+  
+  def test_temperature_conversion
+    response = @client.call_tool("current_weather", {
+      "city" => "Miami",
+      "units" => "fahrenheit"
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /�F/, result
+  end
+  
+  def test_weather_alerts
+    response = @client.read_resource("weather/alerts/california")
+    
+    assert_successful_response(response)
+    data = JSON.parse(response.dig(:result, :contents, 0, :text))
+    assert_equal "california", data["region"]
+    assert_kind_of Array, data["alerts"]
+  end
+  
+  def test_caching
+    # First request
+    response1 = @client.call_tool("current_weather", { "city" => "Paris" })
+    assert_successful_response(response1)
+    
+    # Second request (should be cached)
+    response2 = @client.call_tool("current_weather", { "city" => "Paris" })
+    assert_successful_response(response2)
+    
+    # Results should be identical
+    assert_equal response1[:result], response2[:result]
+  end
+  
+  def test_error_handling
+    # Stub API error
+    stub_request(:get, /api.openweathermap.org/)
+      .to_return(status: 404, body: '{"message": "city not found"}')
+    
+    response = @client.call_tool("current_weather", {
+      "city" => "InvalidCityName"
+    })
+    
+    assert_successful_response(response)
+    result = response.dig(:result, :content, 0, :text)
+    assert_match /Unable to fetch weather/, result
+  end
+  
+  private
+  
+  def stub_weather_api
+    # Current weather
+    stub_request(:get, /api.openweathermap.org\/data\/2.5\/weather/)
+      .to_return(status: 200, body: {
+        name: "London",
+        sys: { country: "GB" },
+        main: {
+          temp: 15.5,
+          feels_like: 14.2,
+          humidity: 72,
+          pressure: 1013
+        },
+        weather: [{ description: "partly cloudy" }],
+        wind: { speed: 3.5 },
+        dt: Time.now.to_i
+      }.to_json)
+    
+    # Forecast
+    stub_request(:get, /api.openweathermap.org\/data\/2.5\/forecast/)
+      .to_return(status: 200, body: {
+        list: Array.new(24) do |i|
+          {
+            dt: Time.now.to_i + (i * 3600 * 3),
+            main: { temp: 15 + rand(10) },
+            weather: [{ main: ["Clear", "Clouds", "Rain"].sample }]
+          }
+        end
+      }.to_json)
+  end
+  
+  def create_test_server
+    # Create server without starting it
+    server = Tsikol::Server.new(name: "test-weather") do
+      tool CurrentWeatherTool
+      tool WeatherForecastTool
+      resource WeatherAlertsResource
+      resource HistoricalWeatherResource
+    end
+    
+    # Inject test weather client
+    server.instance_eval do
+      @weather_client = MockWeatherClient.new
+    end
+    
+    server
+  end
+end
+
+class MockWeatherClient < WeatherClient
+  def initialize
+    @responses = {}
+  end
+  
+  def set_response(method, response)
+    @responses[method] = response
+  end
+  
+  def current_weather(city)
+    @responses[:current] || super
+  end
+  
+  def forecast(city, days)
+    @responses[:forecast] || super
+  end
+end
+```
+
+## Deployment
+
+### Docker Setup
+
+```dockerfile
+FROM ruby:3.2-slim
+
+WORKDIR /app
+
+# Install dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    redis-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy application
+COPY Gemfile Gemfile.lock ./
+RUN bundle install
+
+COPY . .
+
+# Environment
+ENV REDIS_URL=redis://redis:6379
+
+# Run server
+CMD ["ruby", "server.rb"]
+```
+
+### docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  weather-service:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - OPENWEATHER_API_KEY=${OPENWEATHER_API_KEY}
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - redis
+    restart: unless-stopped
+  
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+    restart: unless-stopped
+
+volumes:
+  redis_data:
+```
+
+## Best Practices Demonstrated
+
+1. **External API Integration** with proper error handling
+2. **Multi-level Caching** (Redis + in-memory fallback)
+3. **Rate Limiting** to prevent API abuse
+4. **Comprehensive Testing** with mocked APIs
+5. **Configuration Management** with environment variables
+6. **Docker Deployment** ready for production
+7. **Graceful Degradation** when services are unavailable
+8. **Structured Logging** for debugging
+9. **Resource Organization** with clear URI patterns
+10. **Prompt Engineering** for AI assistance
+
+## Performance Optimizations
+
+1. Cache API responses to reduce external calls
+2. Use Redis for distributed caching
+3. Implement request batching for multiple cities
+4. Add connection pooling for HTTP requests
+5. Use async processing for non-critical updates
+
+## Security Considerations
+
+1. Never expose API keys in logs or responses
+2. Validate and sanitize city names
+3. Implement rate limiting per API key
+4. Use HTTPS for all external API calls
+5. Rotate API keys regularly
+
+## Next Steps
+
+- Add more weather data sources for redundancy
+- Implement weather maps and visualizations
+- Add severe weather notifications
+- Create mobile app integration
+- Add machine learning for weather predictions
+- Implement webhook support for alerts