vibe-sort 0.2.0

data/docs/v0.2.0_UPDATE.md

@@ -0,0 +1,377 @@
+# VibeSort v0.2.0 Update Summary
+
+## Overview
+
+VibeSort has been updated to **version 0.2.0** with support for sorting arrays containing **integers, floats, and strings**. This expands the gem's capabilities while maintaining the same clean API and architecture.
+
+---
+
+## 🎯 What Changed
+
+### Core Functionality
+
+#### Before (v0.1.0)
+- ✅ Sort arrays of numbers (integers and floats)
+- ❌ Strings not supported
+- ❌ Mixed-type arrays rejected
+
+#### After (v0.2.0)
+- ✅ Sort arrays of numbers (integers and floats)
+- ✅ Sort arrays of strings (case-sensitive)
+- ✅ Sort mixed-type arrays (numbers + strings)
+
+---
+
+## 📝 Technical Changes
+
+### 1. Input Validation (`VibeSort::Client`)
+
+**File:** `lib/vibe_sort/client.rb`
+
+**Before:**
+```ruby
+def valid_input?(array)
+  return false unless array.is_a?(Array)
+  return false if array.empty?
+  array.all? { |item| item.is_a?(Numeric) }
+end
+```
+
+**After:**
+```ruby
+def valid_input?(array)
+  return false unless array.is_a?(Array)
+  return false if array.empty?
+  array.all? { |item| item.is_a?(Numeric) || item.is_a?(String) }
+end
+```
+
+**Error Message Updated:**
+- Before: `"Input must be an array of numbers"`
+- After: `"Input must be an array of numbers or strings"`
+
+---
+
+### 2. AI Prompting (`VibeSort::Sorter`)
+
+**File:** `lib/vibe_sort/sorter.rb`
+
+**Before:**
+```ruby
+{
+  role: "system",
+  content: "You are an assistant that only sorts number arrays. 
+            Return a JSON object with a single key 'sorted_array' 
+            containing the numbers sorted in ascending order."
+}
+```
+
+**After:**
+```ruby
+{
+  role: "system",
+  content: "You are an assistant that only sorts arrays. 
+            The array may contain numbers and strings. 
+            Sort the array in ascending order. 
+            Follow standard sorting rules: numbers should come before strings, 
+            and string sorting should be case-sensitive. 
+            Return a JSON object with a single key 'sorted_array' 
+            containing the sorted elements."
+}
+```
+
+---
+
+### 3. Output Validation (`VibeSort::Sorter`)
+
+**File:** `lib/vibe_sort/sorter.rb`
+
+**Before:**
+```ruby
+def validate_sorted_array!(sorted_array)
+  unless sorted_array.is_a?(Array)
+    raise ApiError.new("Response does not contain a valid 'sorted_array'")
+  end
+  
+  unless sorted_array.all? { |item| item.is_a?(Numeric) }
+    raise ApiError.new("Sorted array contains non-numeric values")
+  end
+end
+```
+
+**After:**
+```ruby
+def validate_sorted_array!(sorted_array)
+  unless sorted_array.is_a?(Array)
+    raise ApiError.new("Response does not contain a valid 'sorted_array'")
+  end
+  
+  unless sorted_array.all? { |item| item.is_a?(Numeric) || item.is_a?(String) }
+    raise ApiError.new("Sorted array contains invalid values (must be numbers or strings)")
+  end
+end
+```
+
+---
+
+## 🚀 New Usage Examples
+
+### Sorting Strings
+
+```ruby
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+
+words = ["banana", "Apple", "cherry", "date"]
+result = client.sort(words)
+
+puts result[:sorted_array]
+# => ["Apple", "banana", "cherry", "date"]
+```
+
+### Sorting Mixed Types
+
+```ruby
+mixed_items = [42, "hello", 8, "world", 15.5, "Apple"]
+result = client.sort(mixed_items)
+
+puts result[:sorted_array]
+# => [8, 15.5, 42, "Apple", "hello", "world"]
+# Note: Numbers come before strings
+```
+
+---
+
+## 📋 Sorting Rules
+
+The AI follows these standard sorting conventions:
+
+1. **Numbers Only**: Ascending numerical order
+   - `[5, 2, 8, 1]` → `[1, 2, 5, 8]`
+
+2. **Strings Only**: Ascending alphabetical order (case-sensitive)
+   - `["banana", "Apple", "cherry"]` → `["Apple", "banana", "cherry"]`
+   - Capital letters come before lowercase in ASCII ordering
+
+3. **Mixed Types**: Numbers first, then strings
+   - `[42, "hello", 8, "world"]` → `[8, 42, "hello", "world"]`
+   - Each group is sorted within itself
+
+---
+
+## 📚 Documentation Updates
+
+### Updated Files
+
+1. **README.md**
+   - Added string sorting examples
+   - Added mixed-type sorting examples
+   - Updated features list
+   - Added sorting behavior section
+   - Updated error message examples
+
+2. **docs/api_reference.md**
+   - Updated method signatures
+   - Added sorting rules documentation
+   - Updated examples with strings and mixed types
+   - Updated error messages
+
+3. **CHANGELOG.md**
+   - Added v0.2.0 release notes
+   - Documented all changes
+   - Listed technical details
+
+4. **lib/vibe_sort/version.rb**
+   - Updated version to `0.2.0`
+
+---
+
+## ✅ Backward Compatibility
+
+**Good News:** This update is **fully backward compatible**!
+
+- All v0.1.0 code continues to work without changes
+- Number-only arrays still work exactly the same
+- No breaking changes to the API
+- Existing applications can upgrade without modification
+
+```ruby
+# This still works exactly as before
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+result = client.sort([5, 2, 8, 1, 9])
+# => { success: true, sorted_array: [1, 2, 5, 8, 9] }
+```
+
+---
+
+## 🧪 Testing Recommendations
+
+When upgrading to v0.2.0, test these scenarios:
+
+### 1. String Arrays
+```ruby
+client.sort(["zebra", "Apple", "banana", "cherry"])
+```
+
+### 2. Mixed Arrays
+```ruby
+client.sort([100, "test", 5, "alpha", 3.14])
+```
+
+### 3. Edge Cases
+```ruby
+# Empty strings
+client.sort(["", "hello", "world"])
+
+# Special characters
+client.sort(["@symbol", "123", "abc"])
+
+# Unicode
+client.sort(["café", "apple", "über"])
+```
+
+### 4. Invalid Input (should fail gracefully)
+```ruby
+client.sort([1, :symbol, "text"])  # Contains symbol
+client.sort([1, { key: "value" }]) # Contains hash
+```
+
+---
+
+## 🔍 Implementation Notes
+
+### Why These Changes?
+
+1. **Input Validation**: Extended to accept strings, maintaining type safety
+2. **AI Prompt**: Generalized to handle multiple data types while maintaining clear sorting rules
+3. **Output Validation**: Ensures API returns only expected types
+
+### AI Model Behavior
+
+The OpenAI GPT model (gpt-3.5-turbo-1106) handles mixed-type sorting intelligently:
+
+- Understands standard sorting conventions
+- Consistently places numbers before strings
+- Handles case-sensitive string sorting
+- Maintains JSON output format
+
+### Performance Considerations
+
+- No performance difference from v0.1.0
+- Same API latency (~1-3 seconds)
+- Same cost per request (~$0.001-0.002)
+- Same token usage (~100-200 tokens)
+
+---
+
+## 🎨 Architecture Remains Clean
+
+The core architecture is unchanged:
+
+```
+User Application
+      ↓
+VibeSort::Client (validates input)
+      ↓
+VibeSort::Configuration (stores settings)
+      ↓
+VibeSort::Sorter (communicates with OpenAI)
+      ↓
+OpenAI API (processes request)
+      ↓
+Sorted Array (returned to user)
+```
+
+---
+
+## 📦 Upgrade Instructions
+
+### Using Bundler
+
+Update your `Gemfile`:
+
+```ruby
+gem 'vibe-sort', '~> 0.2.0'
+```
+
+Then run:
+
+```bash
+bundle update vibe-sort
+```
+
+### Manual Installation
+
+```bash
+gem install vibe-sort -v 0.2.0
+```
+
+---
+
+## 🐛 Known Limitations
+
+Same limitations as v0.1.0:
+
+- Requires internet connection
+- Incurs API costs
+- Not suitable for production use
+- 1-3 second latency per request
+- Limited by OpenAI rate limits
+- Ascending order only (no descending option)
+
+**New considerations:**
+
+- String sorting is case-sensitive (ASCII order)
+- Unicode characters may sort unexpectedly
+- Very long strings may increase token usage
+
+---
+
+## 🔮 Future Enhancements
+
+Potential features for future versions:
+
+1. **Custom Sort Orders**
+   - Descending order option
+   - Case-insensitive string sorting
+   - Custom comparator functions
+
+2. **More Data Types**
+   - Date/time sorting
+   - Boolean values
+   - Custom object sorting
+
+3. **Advanced Features**
+   - Batch sorting
+   - Caching
+   - Retry logic
+   - Streaming responses
+
+---
+
+## 📞 Support
+
+- 🐛 [Report Issues](https://github.com/chayut/vibe-sort/issues)
+- 💡 [Feature Requests](https://github.com/chayut/vibe-sort/issues/new?labels=enhancement)
+- 📖 [Documentation](https://github.com/chayut/vibe-sort/tree/main/docs)
+
+---
+
+## ✨ Summary
+
+Version 0.2.0 expands VibeSort's capabilities while maintaining:
+
+- ✅ Same clean API
+- ✅ Same architecture
+- ✅ Full backward compatibility
+- ✅ Same performance characteristics
+- ✅ Comprehensive documentation
+
+The gem now handles a wider variety of data types, making it more versatile for educational purposes and demonstrations.
+
+**Happy Sorting!** 🌀
+
+---
+
+**Version:** 0.2.0  
+**Release Date:** October 16, 2025  
+**Status:** Stable

data/lib/vibe/sort/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Vibe
+  module Sort
+    VERSION = "0.1.0"
+  end
+end

data/lib/vibe/sort.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "sort/version"
+
+module Vibe
+  module Sort
+    class Error < StandardError; end
+    # Your code goes here...
+  end
+end

data/lib/vibe_sort/client.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module VibeSort
+  # Client is the main public interface for the VibeSort gem
+  class Client
+    attr_reader :config
+
+    # Initialize a new VibeSort client
+    #
+    # @param api_key [String] OpenAI API key
+    # @param temperature [Float] Temperature for the model (default: 0.0)
+    # @raise [ArgumentError] if api_key is invalid
+    #
+    # @example
+    #   client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+    def initialize(api_key:, temperature: 0.0)
+      @config = Configuration.new(api_key: api_key, temperature: temperature)
+    end
+
+    # Sort an array of numbers and/or strings using OpenAI API
+    #
+    # @param array [Array] Array of numbers and/or strings to sort
+    # @return [Hash] Result hash with keys:
+    #   - :success [Boolean] whether the operation succeeded
+    #   - :sorted_array [Array] the sorted array (empty on failure)
+    #   - :error [String] error message (only present on failure)
+    #
+    # @example Successful sort with numbers
+    #   result = client.sort([5, 2, 8, 1, 9])
+    #   #=> { success: true, sorted_array: [1, 2, 5, 8, 9] }
+    #
+    # @example Successful sort with strings
+    #   result = client.sort(["banana", "Apple", "cherry"])
+    #   #=> { success: true, sorted_array: ["Apple", "banana", "cherry"] }
+    #
+    # @example Successful sort with mixed types
+    #   result = client.sort([42, "hello", 8, "world"])
+    #   #=> { success: true, sorted_array: [8, 42, "hello", "world"] }
+    #
+    # @example Invalid input
+    #   result = client.sort([1, :symbol, 3])
+    #   #=> { success: false, sorted_array: [], error: "Input must be an array of numbers or strings" }
+    #
+    # @example API error
+    #   result = client.sort([1, 2, 3]) # with invalid API key
+    #   #=> { success: false, sorted_array: [], error: "OpenAI API error: Invalid API key" }
+    def sort(array)
+      # Validate input
+      unless valid_input?(array)
+        return {
+          success: false,
+          sorted_array: [],
+          error: "Input must be an array of numbers or strings"
+        }
+      end
+
+      # Perform the sort via API
+      sorter = Sorter.new(config)
+      sorter.perform(array)
+    rescue ApiError => e
+      {
+        success: false,
+        sorted_array: [],
+        error: e.message
+      }
+    rescue StandardError => e
+      {
+        success: false,
+        sorted_array: [],
+        error: "Unexpected error: #{e.message}"
+      }
+    end
+
+    private
+
+    # Validate that input is an array of numbers and/or strings
+    #
+    # @param array [Object] Input to validate
+    # @return [Boolean] true if valid, false otherwise
+    def valid_input?(array)
+      return false unless array.is_a?(Array)
+      return false if array.empty?
+
+      array.all? { |item| item.is_a?(Numeric) || item.is_a?(String) }
+    end
+  end
+end

data/lib/vibe_sort/configuration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VibeSort
+  # Configuration class for VibeSort
+  # Holds API key and temperature settings
+  class Configuration
+    attr_reader :api_key, :temperature
+
+    # Initialize a new Configuration
+    #
+    # @param api_key [String] OpenAI API key
+    # @param temperature [Float] Temperature for the model (0.0 to 2.0)
+    # @raise [ArgumentError] if api_key is nil or empty
+    def initialize(api_key:, temperature: 0.0)
+      raise ArgumentError, "API key cannot be nil or empty" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @temperature = temperature
+    end
+  end
+end

data/lib/vibe_sort/error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module VibeSort
+  # Custom error class for API-related errors
+  class ApiError < StandardError
+    attr_reader :response
+
+    # Initialize a new ApiError
+    #
+    # @param message [String] Error message
+    # @param response [Faraday::Response, nil] HTTP response object
+    def initialize(message, response = nil)
+      super(message)
+      @response = response
+    end
+  end
+end

data/lib/vibe_sort/sorter.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module VibeSort
+  # Sorter class handles the API call to OpenAI
+  class Sorter
+    OPENAI_API_URL = "https://api.openai.com/v1/chat/completions"
+    DEFAULT_MODEL = "gpt-3.5-turbo-1106"
+
+    attr_reader :config
+
+    # Initialize a new Sorter
+    #
+    # @param config [VibeSort::Configuration] Configuration object
+    def initialize(config)
+      @config = config
+    end
+
+    # Perform the sorting operation via OpenAI API
+    #
+    # @param array [Array] Array of numbers and/or strings to sort
+    # @return [Hash] Result hash with :success, :sorted_array, and optional :error keys
+    # @raise [VibeSort::ApiError] if the API request fails
+    def perform(array)
+      response = connection.post do |req|
+        req.body = build_payload(array)
+      end
+
+      handle_response(response)
+    end
+
+    private
+
+    # Build the connection to OpenAI API
+    #
+    # @return [Faraday::Connection] Faraday connection object
+    def connection
+      @connection ||= Faraday.new(url: OPENAI_API_URL) do |f|
+        f.request :json  # Encodes request body as JSON
+        f.response :json # Decodes response body as JSON
+        f.headers["Authorization"] = "Bearer #{config.api_key}"
+        f.headers["Content-Type"] = "application/json"
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    # Build the request payload for OpenAI API
+    #
+    # @param array [Array] Array to sort (numbers and/or strings)
+    # @return [Hash] Request payload
+    def build_payload(array)
+      {
+        model: DEFAULT_MODEL,
+        temperature: config.temperature,
+        response_format: { type: "json_object" },
+        messages: [
+          {
+            role: "system",
+            content: "You are an assistant that only sorts arrays. The array may contain numbers and strings. Sort the array in ascending order. Follow standard sorting rules: numbers should come before strings, and string sorting should be case-sensitive. Return a JSON object with a single key 'sorted_array' containing the sorted elements."
+          },
+          {
+            role: "user",
+            content: "Please sort this array: #{array.to_json}"
+          }
+        ]
+      }
+    end
+
+    # Handle the API response
+    #
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Result hash
+    # @raise [VibeSort::ApiError] if response is invalid or parsing fails
+    def handle_response(response)
+      unless response.success?
+        error_message = extract_error_message(response)
+        raise ApiError.new("OpenAI API error: #{error_message}", response)
+      end
+
+      parse_sorted_array(response)
+    end
+
+    # Extract error message from failed response
+    #
+    # @param response [Faraday::Response] HTTP response
+    # @return [String] Error message
+    def extract_error_message(response)
+      return "Unknown error" unless response.body.is_a?(Hash)
+
+      response.body.dig("error", "message") || "HTTP #{response.status}"
+    rescue StandardError
+      "HTTP #{response.status}"
+    end
+
+    # Parse the sorted array from the API response
+    #
+    # @param response [Faraday::Response] HTTP response
+    # @return [Hash] Success result with sorted array
+    # @raise [VibeSort::ApiError] if parsing fails or validation fails
+    def parse_sorted_array(response)
+      content = response.body.dig("choices", 0, "message", "content")
+      raise ApiError.new("Invalid response structure", response) if content.nil?
+
+      parsed_content = JSON.parse(content)
+      sorted_array = parsed_content["sorted_array"]
+
+      validate_sorted_array!(sorted_array)
+
+      { success: true, sorted_array: sorted_array }
+    rescue JSON::ParserError => e
+      raise ApiError.new("Failed to parse JSON response: #{e.message}", response)
+    end
+
+    # Validate that the sorted array is valid
+    #
+    # @param sorted_array [Object] Parsed sorted array
+    # @raise [VibeSort::ApiError] if validation fails
+    def validate_sorted_array!(sorted_array)
+      raise ApiError, "Response does not contain a valid 'sorted_array'" unless sorted_array.is_a?(Array)
+
+      return if sorted_array.all? { |item| item.is_a?(Numeric) || item.is_a?(String) }
+
+      raise ApiError, "Sorted array contains invalid values (must be numbers or strings)"
+    end
+  end
+end

data/lib/vibe_sort/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VibeSort
+  VERSION = "0.2.0"
+end

data/lib/vibe_sort.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+require_relative "vibe_sort/version"
+require_relative "vibe_sort/error"
+require_relative "vibe_sort/configuration"
+require_relative "vibe_sort/sorter"
+require_relative "vibe_sort/client"
+
+module VibeSort
+  class Error < StandardError; end
+end

data/sig/vibe/sort.rbs

@@ -0,0 +1,6 @@
+module Vibe
+  module Sort
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end