vibe-sort 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57341544b7a583956dde5f307ad0705fd01f70994ea5fc634557ddc2ec045b55
+  data.tar.gz: 823b1d1d124ae00d2abaae240d74917df07452b6161619ec6e398362f266c8ea
+SHA512:
+  metadata.gz: b0158f11c6899b503b183b50933d14485f19c4bcee3dbf75fb8e8ff3149eb279e8ec5af52a8bd6fea1cd15ca35255dde7a5884a1e0ec133b51d6c3de9f4fad36
+  data.tar.gz: d59a672c3b38922cf213ad0011bea552b02b0b66d79e600f42df37dd213e6683ef512f0d7413a98930b8f588e54942868dd3f421dec24e9d86c9f95a268ce9a2

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,27 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'bin/**/*'
+    - 'tmp/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2025-10-16
+
+### Added
+
+- **Mixed-Type Array Support**: Arrays can now contain integers, floats, AND strings
+- String sorting capability with case-sensitive alphabetical ordering
+- Mixed-type sorting with standard rules (numbers before strings)
+- Enhanced AI prompt to handle multiple data types intelligently
+- Updated examples in README and documentation for string and mixed-type arrays
+
+### Changed
+
+- Input validation now accepts `Numeric` or `String` types (previously `Numeric` only)
+- Error message updated to "Input must be an array of numbers or strings"
+- System prompt generalized to handle diverse array compositions
+- Output validation updated to accept numbers and strings
+- API documentation updated to reflect new capabilities
+
+### Documentation
+
+- Added string sorting examples to README
+- Added mixed-type array examples to README
+- Updated API reference with new sorting rules
+- Added sorting behavior section explaining number/string ordering
+- Updated error messages in documentation
+
+### Technical Details
+
+- `VibeSort::Client#valid_input?` now checks for `Numeric || String`
+- `VibeSort::Sorter#build_payload` uses generalized AI instructions
+- `VibeSort::Sorter#validate_sorted_array!` accepts both numeric and string values
+- All method signatures and documentation updated accordingly
+
+### Sorting Rules
+
+- **Numbers only**: Ascending numerical order
+- **Strings only**: Ascending alphabetical order (case-sensitive)
+- **Mixed arrays**: Numbers sorted first, then strings, each group sorted within itself
+
+## [0.1.0] - 2025-10-16
+
+### Added
+
+- Initial release of VibeSort gem
+- Core functionality: AI-powered array sorting using OpenAI API
+- `VibeSort::Client` - Main public interface for sorting arrays
+- `VibeSort::Configuration` - Configuration management for API key and temperature
+- `VibeSort::Sorter` - HTTP client for OpenAI API communication via Faraday
+- `VibeSort::ApiError` - Custom exception class for API errors
+- Comprehensive error handling with detailed error messages
+- Input validation for array types and numeric values
+- JSON mode support for reliable, structured API responses
+- Temperature configuration for controlling model behavior
+- Full test suite with RSpec
+- Complete documentation:
+  - README with usage examples and installation instructions
+  - Architecture documentation (`docs/architecture.md`)
+  - API reference (`docs/api_reference.md`)
+  - Development guide (`docs/development.md`)
+- Runtime dependencies:
+  - `faraday` (~> 2.0) for HTTP requests
+  - `faraday-json` (~> 1.0) for JSON middleware
+- Development dependencies:
+  - `rspec` (~> 3.0) for testing
+  - `pry` (~> 0.14) for debugging
+
+### Features
+
+- Sort arrays of integers, floats, or mixed numeric types
+- Configurable model temperature (default: 0.0 for deterministic results)
+- Consistent return format with success flag, sorted array, and error messages
+- Support for positive and negative numbers
+- Graceful error handling for invalid inputs and API failures
+- Thread-safe configuration per client instance
+
+### Documentation
+
+- Comprehensive README with examples and disclaimers
+- Architecture overview with component diagrams
+- Complete API reference for all public methods
+- Development guide with setup instructions and best practices
+- Code examples for common use cases
+- Performance considerations and cost analysis
+- Security best practices for API key management
+
+### Notes
+
+- This is a proof-of-concept gem for educational purposes
+- Not recommended for production use
+- Traditional sorting algorithms are faster, cheaper, and more reliable
+- Requires OpenAI API key and internet connection
+- Each sort operation incurs API costs (~$0.001-0.002 per request)

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Chayut Orapinpatipat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+# 🌀 VibeSort
+
+> **AI-powered array sorting using OpenAI's GPT models**
+
+VibeSort is a proof-of-concept Ruby gem that demonstrates sorting number arrays by leveraging the OpenAI Chat Completions API. Instead of using traditional sorting algorithms, it asks GPT to do the work!
+
+[![Gem Version](https://badge.fury.io/rb/vibe-sort.svg)](https://badge.fury.io/rb/vibe-sort)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ⚠️ Disclaimer
+
+This is a **proof-of-concept** and educational project. It is not intended for production use. Traditional sorting algorithms are far more efficient, reliable, and cost-effective. Use this gem to explore AI capabilities, not to sort arrays in real applications!
+
+## ✨ Features
+
+- 🤖 **AI-Powered Sorting**: Uses OpenAI's GPT models to sort arrays
+- 🎯 **Simple Interface**: Clean, intuitive API with a single `sort` method
+- 🔧 **Configurable**: Supports custom temperature settings for model behavior
+- 🛡️ **Error Handling**: Comprehensive error handling with clear error messages
+- 📊 **Structured Output**: Uses JSON mode for reliable, parsable responses
+- 🔍 **Type Validation**: Validates input and output to ensure data integrity
+- 📝 **Mixed-Type Support**: Sorts arrays containing integers, floats, and strings
+
+## ✅ Requirements
+
+- Ruby **3.0** or newer (MRI)
+- Bundler **2.0+**
+- An OpenAI API key with access to the Chat Completions API
+- Internet connectivity (each sort performs a remote API call)
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'vibe-sort'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install vibe-sort
+```
+
+## ⚡ Quick Start
+
+```bash
+export OPENAI_API_KEY="your-openai-api-key"
+bundle exec ruby -e "require 'vibe_sort'; client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY']); puts client.sort([34, 1, 'Apple', 8.5])"
+```
+
+Or fire up the bundled console for interactive experimentation:
+
+```bash
+OPENAI_API_KEY=your-openai-api-key bundle exec bin/console
+```
+
+```ruby
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+client.sort([34, 1, 'Apple', 8.5])
+# => { success: true, sorted_array: [1, 8.5, 34, "Apple"] }
+```
+
+## 🚀 Usage
+
+### Basic Usage
+
+```ruby
+require 'vibe_sort'
+
+# Initialize the client with your OpenAI API key
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+
+# Sort an array of numbers
+numbers = [34, 1, 99, 15, 8]
+result = client.sort(numbers)
+
+if result[:success]
+  puts "✅ Vibe Sort successful!"
+  puts "Original: #{numbers}"
+  puts "Sorted: #{result[:sorted_array]}"
+  # Output: [1, 8, 15, 34, 99]
+else
+  puts "❌ Vibe Sort failed: #{result[:error]}"
+end
+```
+
+### Sorting Strings
+
+```ruby
+# Sort an array of strings (case-sensitive)
+words = ["banana", "Apple", "cherry", "date"]
+result = client.sort(words)
+
+if result[:success]
+  puts "Sorted strings: #{result[:sorted_array]}"
+  # Output: ["Apple", "banana", "cherry", "date"]
+end
+```
+
+### Sorting Mixed Types
+
+```ruby
+# Sort arrays containing both numbers and strings
+mixed_items = [42, "hello", 8, "world", 15.5, "Apple"]
+result = client.sort(mixed_items)
+
+if result[:success]
+  puts "Sorted mixed array: #{result[:sorted_array]}"
+  # Output: [8, 15.5, 42, "Apple", "hello", "world"]
+  # Note: Numbers come before strings in the sorted output
+end
+```
+
+### Advanced Configuration
+
+You can customize the model's behavior using the `temperature` parameter:
+
+```ruby
+# Lower temperature (0.0) = more deterministic, consistent results
+client = VibeSort::Client.new(
+  api_key: ENV['OPENAI_API_KEY'],
+  temperature: 0.0
+)
+
+# Higher temperature = more creative/random (not recommended for sorting!)
+creative_client = VibeSort::Client.new(
+  api_key: ENV['OPENAI_API_KEY'],
+  temperature: 0.5
+)
+```
+
+### Error Handling
+
+VibeSort provides detailed error information:
+
+```ruby
+# Invalid input (unsupported types)
+result = client.sort([5, :symbol, 12])
+puts result[:error]
+# => "Input must be an array of numbers or strings"
+
+# Empty array
+result = client.sort([])
+puts result[:error]
+# => "Input must be an array of numbers or strings"
+
+# Invalid API key
+bad_client = VibeSort::Client.new(api_key: "invalid-key")
+result = bad_client.sort([1, 2, 3])
+puts result[:error]
+# => "OpenAI API error: Invalid API key"
+```
+
+### Return Value Structure
+
+The `sort` method always returns a hash with the following structure:
+
+```ruby
+{
+  success: true/false,      # Boolean indicating success or failure
+  sorted_array: [...],      # Array of sorted elements (empty on failure)
+  error: "..."              # Error message (only present on failure)
+}
+```
+
+### Sorting Behavior
+
+- **Numbers only**: Sorted in ascending numerical order
+- **Strings only**: Sorted in ascending alphabetical order (case-sensitive)
+- **Mixed types**: Numbers come before strings; each group sorted within itself
+
+## 🏗️ Architecture
+
+VibeSort follows a clean, modular architecture:
+
+- **`VibeSort::Client`**: Public interface for users
+- **`VibeSort::Configuration`**: Manages API key and settings
+- **`VibeSort::Sorter`**: Handles OpenAI API communication via Faraday
+- **`VibeSort::ApiError`**: Custom exception for API-related errors
+
+See the [Architecture Documentation](docs/architecture.md) for more details.
+
+## 📚 Documentation
+
+- [Architecture Overview](docs/architecture.md)
+- [API Reference](docs/api_reference.md)
+- [Development Guide](docs/development.md)
+
+## 🧪 Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run console for experimentation
+bin/console
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run with coverage
+bundle exec rspec --format documentation
+
+# Run specific test file
+bundle exec rspec spec/vibe/sort_spec.rb
+```
+
+## 🤔 Why Does This Exist?
+
+This gem was created as an educational exercise to:
+
+1. Explore the capabilities and limitations of LLMs for computational tasks
+2. Demonstrate how to integrate OpenAI's API into Ruby applications
+3. Provide a template for building Ruby gems with external API dependencies
+4. Spark conversations about appropriate use cases for AI
+
+**Please note**: This is intentionally inefficient and expensive compared to traditional sorting algorithms. It's a conversation starter, not a production solution!
+
+## ⚡ Performance Considerations
+
+- **Latency**: Each sort requires an API call (typically 1-3 seconds)
+- **Cost**: OpenAI API usage is metered and costs money
+- **Reliability**: Depends on API availability and internet connection
+- **Accuracy**: Generally accurate, but not guaranteed (unlike algorithmic sorting)
+- **Scale**: Not suitable for large arrays or high-frequency sorting
+
+Traditional sorting (e.g., Ruby's `Array#sort`) is:
+
+- ⚡ **10,000x faster** (microseconds vs seconds)
+- 💰 **Free** (no API costs)
+- 🎯 **100% reliable** (deterministic algorithm)
+- 📈 **Scalable** (handles millions of elements)
+
+## 🔑 Environment Variables
+
+Set your OpenAI API key as an environment variable:
+
+```bash
+export OPENAI_API_KEY='your-api-key-here'
+```
+
+Or use a `.env` file with the `dotenv` gem:
+
+```ruby
+# Gemfile
+gem 'dotenv'
+
+# In your code
+require 'dotenv/load'
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+```
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## 🙏 Acknowledgments
+
+- Built with [Faraday](https://lostisland.github.io/faraday/) for HTTP requests
+- Powered by [OpenAI](https://openai.com/) GPT models
+- Inspired by the absurdity and creativity of the AI era
+
+---
+
+**Remember**: With great AI power comes great responsibility (and API bills). Sort wisely! 🧙‍♂️

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]