vibe-sort 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57341544b7a583956dde5f307ad0705fd01f70994ea5fc634557ddc2ec045b55
-  data.tar.gz: 823b1d1d124ae00d2abaae240d74917df07452b6161619ec6e398362f266c8ea
+  metadata.gz: b152ab9be69894b49e7a1324253a4e0a4fe3d5a15ec61f50e8b67b3bd424e8ef
+  data.tar.gz: 7818eebe77421199fefeba102c3986da5e5665155cb7a916500377515a16b505
 SHA512:
-  metadata.gz: b0158f11c6899b503b183b50933d14485f19c4bcee3dbf75fb8e8ff3149eb279e8ec5af52a8bd6fea1cd15ca35255dde7a5884a1e0ec133b51d6c3de9f4fad36
-  data.tar.gz: d59a672c3b38922cf213ad0011bea552b02b0b66d79e600f42df37dd213e6683ef512f0d7413a98930b8f588e54942868dd3f421dec24e9d86c9f95a268ce9a2
+  metadata.gz: ce32c1524e7afaa485bf600e082fa1bceed852acb617570635c35c2a299a9472f5d8f08df883e76df6e047e1ca1c3e8ca6d3d5d492e8a7bbf104c6d5fb152cfe
+  data.tar.gz: 5b95ce876ce4a67bba1662344b2c46c05ff7d6328708458d571e60f3b2e6d347c7ddb442dfd97103c41699f3d7941d4e901894bb8f9fb29d9c70ab1a4248234a

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-07-10
+
+### Added
+
+- **Multi-Provider Support**: Sort via OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI (xAI) Grok
+- `provider:` option on `VibeSort::Client.new` (`:openai` default, `:anthropic`, `:gemini`, `:groq`, `:spacexai`)
+- `model:` option to override each provider's default model
+- `VibeSort::Providers::Base` adapter layer with per-provider subclasses
+- Anthropic adapter uses the Messages API with structured outputs (JSON schema), guaranteeing the response shape
+- Gemini adapter uses `generateContent` with JSON response mode
+- Groq and SpaceXAI adapters reuse the OpenAI-compatible Chat Completions wire format
+- Provider-specific test suites backed by WebMock
+
+### Changed
+
+- `VibeSort::Sorter` is now a thin dispatcher to the configured provider adapter
+- OpenAI default model updated from the deprecated `gpt-3.5-turbo-1106` to `gpt-4o-mini`
+- Error messages are prefixed with the provider name (e.g. "Anthropic API error: ...")
+- `temperature` is not sent to Anthropic (current Claude models reject the parameter)
+
+### Notes
+
+- Fully backward compatible: `VibeSort::Client.new(api_key: ...)` still defaults to OpenAI
+- Still zero runtime dependencies beyond Faraday — all providers are called over plain HTTPS
+
 ## [0.2.0] - 2025-10-16
 
 ### Added

data/README.md

@@ -1,8 +1,8 @@
 # 🌀 VibeSort
 
-> **AI-powered array sorting using OpenAI's GPT models**
+> **AI-powered array sorting using OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok**
 
-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!
+VibeSort is a proof-of-concept Ruby gem that demonstrates sorting arrays by leveraging LLM APIs. Instead of using traditional sorting algorithms, it asks an AI model to do the work! Supports the OpenAI Chat Completions API, the Anthropic Messages API, the Google Gemini API, and the OpenAI-compatible Groq and SpaceXAI (xAI) APIs — with zero dependencies beyond Faraday.
 
 [![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)
@@ -13,9 +13,10 @@ This is a **proof-of-concept** and educational project. It is not intended for p
 
 ## ✨ Features
 
-- 🤖 **AI-Powered Sorting**: Uses OpenAI's GPT models to sort arrays
+- 🤖 **AI-Powered Sorting**: Uses OpenAI, Anthropic Claude, Google Gemini, Groq, or SpaceXAI Grok models to sort arrays
+- 🔌 **Multi-Provider**: Switch providers with a single `provider:` option — no extra dependencies
 - 🎯 **Simple Interface**: Clean, intuitive API with a single `sort` method
-- 🔧 **Configurable**: Supports custom temperature settings for model behavior
+- 🔧 **Configurable**: Supports custom model and temperature settings
 - 🛡️ **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
@@ -25,7 +26,7 @@ This is a **proof-of-concept** and educational project. It is not intended for p
 
 - Ruby **3.0** or newer (MRI)
 - Bundler **2.0+**
-- An OpenAI API key with access to the Chat Completions API
+- An API key for at least one supported provider (OpenAI, Anthropic, or Google Gemini)
 - Internet connectivity (each sort performs a remote API call)
 
 ## 📦 Installation
@@ -118,6 +119,46 @@ if result[:success]
 end
 ```
 
+### Choosing a Provider
+
+VibeSort defaults to OpenAI, but any supported provider can be selected with the `provider:` option:
+
+```ruby
+# OpenAI (default)
+client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
+
+# Anthropic Claude
+client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
+
+# Google Gemini
+client = VibeSort::Client.new(provider: :gemini, api_key: ENV['GEMINI_API_KEY'])
+
+# Groq (fast open-model inference)
+client = VibeSort::Client.new(provider: :groq, api_key: ENV['GROQ_API_KEY'])
+
+# SpaceXAI (formerly xAI) Grok
+client = VibeSort::Client.new(provider: :spacexai, api_key: ENV['XAI_API_KEY'])
+```
+
+| Provider | API | Default model | Override with `model:` |
+|---|---|---|---|
+| `:openai` | Chat Completions | `gpt-4o-mini` | any chat model |
+| `:anthropic` | Messages | `claude-opus-4-8` | e.g. `claude-haiku-4-5` for cheaper sorts |
+| `:gemini` | generateContent | `gemini-2.5-flash` | e.g. `gemini-2.5-pro` |
+| `:groq` | Chat Completions (OpenAI-compatible) | `llama-3.3-70b-versatile` | any Groq-hosted model |
+| `:spacexai` | Chat Completions (OpenAI-compatible) | `grok-4` | e.g. `grok-4.5` |
+
+> **Groq ≠ Grok**: Groq is the independent fast-inference company (`api.groq.com`); Grok is SpaceXAI's model (`api.x.ai`). They are unrelated — VibeSort supports both.
+
+```ruby
+# Pick a specific model
+client = VibeSort::Client.new(
+  provider: :anthropic,
+  api_key: ENV['ANTHROPIC_API_KEY'],
+  model: 'claude-haiku-4-5'
+)
+```
+
 ### Advanced Configuration
 
 You can customize the model's behavior using the `temperature` parameter:
@@ -136,6 +177,8 @@ creative_client = VibeSort::Client.new(
 )
 ```
 
+> **Note**: current Anthropic Claude models no longer accept a `temperature` parameter, so it is ignored when `provider: :anthropic` is used.
+
 ### Error Handling
 
 VibeSort provides detailed error information:
@@ -181,8 +224,10 @@ The `sort` method always returns a hash with the following structure:
 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::Configuration`**: Manages provider, API key, model, and settings
+- **`VibeSort::Sorter`**: Dispatches to the configured provider adapter
+- **`VibeSort::Providers::Base`**: Shared prompt, HTTP plumbing (Faraday), and response validation
+- **`VibeSort::Providers::{OpenAI, Anthropic, Gemini}`**: Provider-specific request/response mapping
 - **`VibeSort::ApiError`**: Custom exception for API-related errors
 
 See the [Architecture Documentation](docs/architecture.md) for more details.
@@ -249,10 +294,14 @@ Traditional sorting (e.g., Ruby's `Array#sort`) is:
 
 ## 🔑 Environment Variables
 
-Set your OpenAI API key as an environment variable:
+Set the API key for your chosen provider as an environment variable:
 
 ```bash
-export OPENAI_API_KEY='your-api-key-here'
+export OPENAI_API_KEY='your-api-key-here'     # provider: :openai (default)
+export ANTHROPIC_API_KEY='your-api-key-here'  # provider: :anthropic
+export GEMINI_API_KEY='your-api-key-here'     # provider: :gemini
+export GROQ_API_KEY='your-api-key-here'       # provider: :groq
+export XAI_API_KEY='your-api-key-here'        # provider: :spacexai
 ```
 
 Or use a `.env` file with the `dotenv` gem:
@@ -273,7 +322,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 ## 🙏 Acknowledgments
 
 - Built with [Faraday](https://lostisland.github.io/faraday/) for HTTP requests
-- Powered by [OpenAI](https://openai.com/) GPT models
+- Powered by [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), and [Google Gemini](https://ai.google.dev/) models
 - Inspired by the absurdity and creativity of the AI era
 
 ---

data/docs/api_reference.md

@@ -6,30 +6,40 @@ The main public interface for the VibeSort gem.
 
 ### Class Methods
 
-#### `new(api_key:, temperature: 0.0)`
+#### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
 
 Creates a new VibeSort client instance.
 
 **Parameters:**
 
-- `api_key` (String, required): Your OpenAI API key
+- `api_key` (String, required): API key for the selected provider
 - `temperature` (Float, optional): Model temperature setting (default: 0.0)
   - Range: 0.0 to 2.0
   - Lower values (0.0-0.3): More deterministic and consistent
   - Higher values (0.7-2.0): More random and creative
+  - Ignored by providers whose current models do not accept it (Anthropic)
+- `provider` (Symbol or String, optional): LLM provider (default: `:openai`)
+  - Supported: `:openai`, `:anthropic`, `:gemini`, `:groq`, `:spacexai`
+- `model` (String, optional): Model ID override (default: the provider's default model)
 
 **Returns:** `VibeSort::Client` instance
 
 **Raises:**
 
-- `ArgumentError`: If api_key is nil or empty
+- `ArgumentError`: If api_key is nil or empty, or the provider is unknown
 
 **Example:**
 
 ```ruby
-# Basic initialization
+# Basic initialization (OpenAI, default provider)
 client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
 
+# Anthropic Claude
+client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
+
+# Google Gemini with a custom model
+client = VibeSort::Client.new(provider: :gemini, api_key: ENV['GEMINI_API_KEY'], model: 'gemini-2.5-pro')
+
 # With custom temperature
 client = VibeSort::Client.new(
   api_key: ENV['OPENAI_API_KEY'],
@@ -41,7 +51,7 @@ client = VibeSort::Client.new(
 
 #### `sort(array)`
 
-Sorts an array of numbers and/or strings using OpenAI's API.
+Sorts an array of numbers and/or strings using the configured provider's API.
 
 **Parameters:**
 
@@ -100,25 +110,28 @@ Configuration object for VibeSort. Usually not used directly by end users.
 
 ### Class Methods
 
-#### `new(api_key:, temperature: 0.0)`
+#### `new(api_key:, temperature: 0.0, provider: :openai, model: nil)`
 
 Creates a new configuration object.
 
 **Parameters:**
 
-- `api_key` (String, required): OpenAI API key
+- `api_key` (String, required): API key for the selected provider
 - `temperature` (Float, optional): Model temperature (default: 0.0)
+- `provider` (Symbol or String, optional): `:openai` (default), `:anthropic`, `:gemini`, `:groq`, or `:spacexai`
+- `model` (String, optional): Model ID override (nil uses the provider's default)
 
 **Raises:**
 
-- `ArgumentError`: If api_key is nil or empty
+- `ArgumentError`: If api_key is nil or empty, or the provider is unknown
 
 **Example:**
 
 ```ruby
 config = VibeSort::Configuration.new(
   api_key: "sk-...",
-  temperature: 0.0
+  provider: :anthropic,
+  model: "claude-haiku-4-5"
 )
 ```
 
@@ -136,11 +149,23 @@ Returns the configured temperature setting (read-only).
 
 **Returns:** Float
 
+#### `provider`
+
+Returns the configured provider (read-only).
+
+**Returns:** Symbol
+
+#### `model`
+
+Returns the configured model override, or nil when using the provider default (read-only).
+
+**Returns:** String or nil
+
 ---
 
 ## VibeSort::Sorter
 
-Internal class that handles API communication. Not intended for direct use.
+Internal class that dispatches the sorting operation to the configured provider adapter. Not intended for direct use.
 
 ### Class Methods
 
@@ -156,7 +181,7 @@ Creates a new sorter instance.
 
 #### `perform(array)`
 
-Performs the sorting operation via OpenAI API.
+Performs the sorting operation via the configured provider's API.
 
 **Parameters:**
 
@@ -170,17 +195,30 @@ Performs the sorting operation via OpenAI API.
 
 ### Constants
 
-#### `OPENAI_API_URL`
+#### `PROVIDER_CLASSES`
+
+Maps provider symbols to adapter classes.
+
+**Value:** `{ openai:, anthropic:, gemini:, groq:, spacexai: }`
+
+---
 
-The OpenAI API endpoint URL.
+## VibeSort::Providers
 
-**Value:** `"https://api.openai.com/v1/chat/completions"`
+Internal provider adapters. `Providers::Base` holds the shared prompt, Faraday HTTP plumbing, and response validation; each subclass maps one provider's request/response wire format.
 
-#### `DEFAULT_MODEL`
+| Adapter | Endpoint | `DEFAULT_MODEL` |
+|---|---|---|
+| `Providers::OpenAI` | `https://api.openai.com/v1/chat/completions` | `gpt-4o-mini` |
+| `Providers::Anthropic` | `https://api.anthropic.com/v1/messages` | `claude-opus-4-8` |
+| `Providers::Gemini` | `https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent` | `gemini-2.5-flash` |
+| `Providers::Groq` | `https://api.groq.com/openai/v1/chat/completions` | `llama-3.3-70b-versatile` |
+| `Providers::SpaceXAI` | `https://api.x.ai/v1/chat/completions` | `grok-4` |
 
-The default GPT model used for sorting.
+Notes:
 
-**Value:** `"gpt-3.5-turbo-1106"`
+- The Anthropic adapter uses structured outputs (JSON schema) and does not send `temperature` (rejected by current Claude models)
+- The Groq and SpaceXAI adapters subclass `Providers::OpenAI` (OpenAI-compatible APIs)
 
 ---
 
@@ -269,11 +307,13 @@ All sorting operations return a consistent hash structure:
 
 ### API Errors
 
+The `{Provider}` prefix names the configured provider (OpenAI, Anthropic, Gemini, Groq, or SpaceXAI):
+
 | Error Message Pattern | Cause | Solution |
 |----------------------|-------|----------|
-| "OpenAI API error: Invalid API key" | Invalid or missing API key | Check API key |
-| "OpenAI API error: Rate limit exceeded" | Too many requests | Wait and retry |
-| "OpenAI API error: HTTP {status}" | HTTP error | Check API status |
+| "{Provider} API error: Invalid API key" | Invalid or missing API key | Check API key |
+| "{Provider} API error: Rate limit exceeded" | Too many requests | Wait and retry |
+| "{Provider} API error: HTTP {status}" | HTTP error | Check API status |
 
 ### Response Parsing Errors
 
@@ -412,14 +452,14 @@ results = threads.map(&:value)
 
 ## Environment Variables
 
-### OPENAI_API_KEY
-
-Your OpenAI API key. Required for all operations.
-
-**Setup:**
+Set the API key for whichever provider you use:
 
 ```bash
-export OPENAI_API_KEY='sk-your-key-here'
+export OPENAI_API_KEY='sk-your-key-here'      # provider: :openai (default)
+export ANTHROPIC_API_KEY='your-key-here'      # provider: :anthropic
+export GEMINI_API_KEY='your-key-here'         # provider: :gemini
+export GROQ_API_KEY='your-key-here'           # provider: :groq
+export XAI_API_KEY='your-key-here'            # provider: :spacexai
 ```
 
 **Usage:**
@@ -432,9 +472,9 @@ client = VibeSort::Client.new(api_key: ENV['OPENAI_API_KEY'])
 
 ## Version
 
-Current version: `0.1.0`
+Current version: `0.3.0`
 
 ```ruby
 VibeSort::VERSION
-# => "0.1.0"
+# => "0.3.0"
 ```

data/docs/architecture.md

@@ -20,24 +20,36 @@ VibeSort follows a layered architecture with clear separation of concerns:
                   ▼
 ┌─────────────────────────────────────────┐
 │    VibeSort::Configuration              │
+│  - Provider selection                   │
 │  - API key management                   │
+│  - Model override                       │
 │  - Temperature settings                 │
 └─────────────────┬───────────────────────┘
                   │
                   ▼
 ┌─────────────────────────────────────────┐
-│      VibeSort::Sorter                   │
+│      VibeSort::Sorter (dispatcher)      │
+│  - Picks the provider adapter           │
+└─────────────────┬───────────────────────┘
+                  │
+                  ▼
+┌─────────────────────────────────────────┐
+│   VibeSort::Providers::Base             │
+│  - Shared prompt                        │
 │  - HTTP client (Faraday)                │
-│  - Request building                     │
-│  - Response parsing                     │
-│  - Validation                           │
+│  - Response parsing & validation        │
+├─────────────────────────────────────────┤
+│  OpenAI │ Anthropic │ Gemini │          │
+│  Groq   │ SpaceXAI                      │
+│  (request/response wire formats)        │
 └─────────────────┬───────────────────────┘
                   │
                   ▼
 ┌─────────────────────────────────────────┐
-│      OpenAI API                         │
-│  https://api.openai.com/v1/chat/       │
-│  completions                            │
+│      Provider API (HTTPS)               │
+│  api.openai.com │ api.anthropic.com     │
+│  generativelanguage.googleapis.com      │
+│  api.groq.com   │ api.x.ai              │
 └─────────────────────────────────────────┘
 ```
 
@@ -55,7 +67,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 - Return standardized response hashes
 
 **Key Methods**:
-- `initialize(api_key:, temperature: 0.0)`: Creates client with configuration
+- `initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)`: Creates client with configuration
 - `sort(array)`: Sorts array and returns result hash
 
 **Return Format**:
@@ -72,41 +84,46 @@ VibeSort follows a layered architecture with clear separation of concerns:
 **Purpose**: Encapsulates configuration settings.
 
 **Responsibilities**:
-- Store API key securely
-- Store temperature setting
-- Validate API key presence
+- Store provider selection and API key
+- Store model override and temperature setting
+- Validate API key presence and provider name
 
 **Key Methods**:
-- `initialize(api_key:, temperature:)`: Creates configuration
-- Raises `ArgumentError` if API key is nil or empty
+- `initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)`: Creates configuration
+- Raises `ArgumentError` if API key is nil/empty or provider is unknown
 
 **Attributes**:
-- `api_key`: OpenAI API key (String)
-- `temperature`: Model temperature (Float, 0.0-2.0)
+- `api_key`: Provider API key (String)
+- `provider`: `:openai`, `:anthropic`, `:gemini`, `:groq`, or `:spacexai` (Symbol)
+- `model`: Model ID override, or nil for the provider default (String or nil)
+- `temperature`: Model temperature (Float, 0.0-2.0; not sent to Anthropic)
 
 ### VibeSort::Sorter
 
-**Purpose**: Handles communication with OpenAI API.
-
-**Responsibilities**:
-- Build HTTP connection with Faraday
-- Construct API request payload
-- Send POST request to OpenAI
-- Parse and validate JSON responses
-- Extract sorted array from response
-- Raise `ApiError` on failures
+**Purpose**: Dispatches the sort to the configured provider adapter.
 
 **Key Methods**:
 - `initialize(config)`: Creates sorter with configuration
-- `perform(array)`: Executes sort via API
-- `build_payload(array)`: Private - constructs request
-- `handle_response(response)`: Private - processes response
-- `parse_sorted_array(response)`: Private - extracts result
-- `validate_sorted_array!(array)`: Private - validates output
+- `perform(array)`: Looks up the adapter in `PROVIDER_CLASSES` and delegates
 
-**Constants**:
-- `OPENAI_API_URL`: API endpoint
-- `DEFAULT_MODEL`: "gpt-3.5-turbo-1106" (supports JSON mode)
+### VibeSort::Providers
+
+**Purpose**: One adapter per LLM provider, all sharing a common base.
+
+**`Providers::Base` responsibilities**:
+- Hold the shared sorting prompt
+- Build the HTTP connection with Faraday
+- Parse and validate JSON responses (shared across providers)
+- Raise `ApiError` on failures
+
+**Adapter hooks** (implemented per provider): `provider_name`, `endpoint`, `headers`, `build_payload`, `extract_content`
+
+**Adapters and default models**:
+- `Providers::OpenAI` — Chat Completions, `gpt-4o-mini`
+- `Providers::Anthropic` — Messages API with structured outputs (JSON schema), `claude-opus-4-8`
+- `Providers::Gemini` — generateContent with JSON response mode, `gemini-2.5-flash`
+- `Providers::Groq` — OpenAI-compatible (subclasses `Providers::OpenAI`), `llama-3.3-70b-versatile`
+- `Providers::SpaceXAI` — OpenAI-compatible (subclasses `Providers::OpenAI`), `grok-4`
 
 ### VibeSort::ApiError
 
@@ -132,12 +149,12 @@ VibeSort follows a layered architecture with clear separation of concerns:
 
 3. **Client creates Sorter**
    - Passes Configuration object
-   - Sorter initializes Faraday connection
+   - Sorter picks the provider adapter, which initializes a Faraday connection
 
-4. **Sorter builds request payload**
+4. **Adapter builds the provider-specific request payload** (OpenAI example)
    ```json
    {
-     "model": "gpt-3.5-turbo-1106",
+     "model": "gpt-4o-mini",
      "temperature": 0.0,
      "response_format": { "type": "json_object" },
      "messages": [
@@ -153,16 +170,16 @@ VibeSort follows a layered architecture with clear separation of concerns:
    }
    ```
 
-5. **Sorter sends POST request**
-   - URL: `https://api.openai.com/v1/chat/completions`
-   - Headers: Authorization (Bearer token), Content-Type
+5. **Adapter sends POST request**
+   - URL: the adapter's endpoint (e.g. `https://api.openai.com/v1/chat/completions`)
+   - Headers: provider auth (Bearer token, `x-api-key`, or `x-goog-api-key`), Content-Type
    - Body: JSON payload
 
-6. **OpenAI processes request**
+6. **Provider processes request**
    - Model analyzes the array
    - Returns JSON with sorted array
 
-7. **Sorter parses response**
+7. **Adapter parses response** (OpenAI example)
    ```json
    {
      "choices": [{
@@ -227,8 +244,7 @@ VibeSort follows a layered architecture with clear separation of concerns:
 ## Dependencies
 
 ### Runtime
-- **faraday** (~> 2.0): HTTP client library
-- **faraday-json** (~> 1.0): JSON middleware for Faraday
+- **faraday** (~> 2.0): HTTP client library — the only runtime dependency; all providers are called over plain HTTPS
 
 ### Development
 - **rspec** (~> 3.0): Testing framework
@@ -236,8 +252,11 @@ VibeSort follows a layered architecture with clear separation of concerns:
 
 ## Design Decisions
 
-### Why JSON Mode?
-OpenAI's JSON mode (`response_format: { type: "json_object" }`) ensures the model always returns valid JSON, making parsing more reliable.
+### Why JSON Mode / Structured Outputs?
+Each adapter uses the strongest JSON guarantee its provider offers: OpenAI-compatible providers use JSON mode (`response_format: { type: "json_object" }`), Anthropic uses structured outputs with a JSON schema, and Gemini uses `responseMimeType: "application/json"`. This makes parsing reliable across providers.
+
+### Why Raw HTTP Instead of Provider SDKs?
+Three simple JSON POSTs don't justify three SDK dependencies. Keeping everything on Faraday keeps the gem lightweight and the adapters symmetric.
 
 ### Why Temperature 0.0 by Default?
 Lower temperature (0.0) produces deterministic, consistent results. Sorting should be predictable, not creative!
@@ -312,8 +331,7 @@ Potential improvements for future versions:
 
 1. **Batch Sorting**: Sort multiple arrays in one API call
 2. **Caching**: Cache results for identical inputs
-3. **Custom Models**: Allow users to specify different GPT models
-4. **Retry Logic**: Automatic retry on transient failures
+3. **Retry Logic**: Automatic retry on transient failures
 5. **Async Support**: Non-blocking API calls with callbacks
 6. **Metrics**: Track API usage, costs, and performance
 7. **Different Sort Orders**: Support descending order

data/lib/vibe/sort.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "sort/version"
-
-module Vibe
-  module Sort
-    class Error < StandardError; end
-    # Your code goes here...
-  end
-end
+# Compatibility shim: Bundler autorequires "vibe/sort" for a gem named
+# "vibe-sort", so `gem "vibe-sort"` in a Gemfile loads the real library
+# without needing an explicit `require "vibe_sort"`.
+require_relative "../vibe_sort"

data/lib/vibe_sort/client.rb

@@ -7,17 +7,26 @@ module VibeSort
 
     # 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
+    # @param api_key [String] API key for the selected provider
+    # @param temperature [Float] Temperature for the model (default: 0.0).
+    #   Ignored by providers whose current models do not accept it (Anthropic).
+    # @param provider [Symbol, String] LLM provider: :openai (default), :anthropic, or :gemini
+    # @param model [String, nil] Model ID override (nil uses the provider's default)
+    # @raise [ArgumentError] if api_key or provider is invalid
     #
-    # @example
+    # @example OpenAI (default provider)
     #   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)
+    #
+    # @example Anthropic Claude
+    #   client = VibeSort::Client.new(provider: :anthropic, api_key: ENV['ANTHROPIC_API_KEY'])
+    #
+    # @example Google Gemini with a custom model
+    #   client = VibeSort::Client.new(provider: :gemini, api_key: ENV['GEMINI_API_KEY'], model: 'gemini-2.5-pro')
+    def initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)
+      @config = Configuration.new(api_key: api_key, temperature: temperature, provider: provider, model: model)
     end
 
-    # Sort an array of numbers and/or strings using OpenAI API
+    # Sort an array of numbers and/or strings using the configured provider's API
     #
     # @param array [Array] Array of numbers and/or strings to sort
     # @return [Hash] Result hash with keys:
@@ -44,6 +53,7 @@ module VibeSort
     # @example API error
     #   result = client.sort([1, 2, 3]) # with invalid API key
     #   #=> { success: false, sorted_array: [], error: "OpenAI API error: Invalid API key" }
+    #   # The error prefix names the configured provider (OpenAI, Anthropic, or Gemini)
     def sort(array)
       # Validate input
       unless valid_input?(array)

data/lib/vibe_sort/configuration.rb

@@ -2,20 +2,29 @@
 
 module VibeSort
   # Configuration class for VibeSort
-  # Holds API key and temperature settings
+  # Holds provider, API key, model, and temperature settings
   class Configuration
-    attr_reader :api_key, :temperature
+    PROVIDERS = %i[openai anthropic gemini groq spacexai].freeze
+
+    attr_reader :api_key, :temperature, :provider, :model
 
     # 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)
+    # @param api_key [String] API key for the selected provider
+    # @param temperature [Float] Temperature for the model (0.0 to 2.0).
+    #   Ignored by providers whose current models do not accept it (Anthropic).
+    # @param provider [Symbol, String] LLM provider: :openai (default), :anthropic, :gemini, :groq, or :spacexai
+    # @param model [String, nil] Model ID override (nil uses the provider's default)
+    # @raise [ArgumentError] if api_key is nil or empty, or provider is unknown
+    def initialize(api_key:, temperature: 0.0, provider: :openai, model: nil)
       raise ArgumentError, "API key cannot be nil or empty" if api_key.nil? || api_key.empty?
 
+      @provider = provider.to_s.to_sym
+      raise ArgumentError, "Unknown provider: #{provider.inspect} (supported: #{PROVIDERS.join(", ")})" unless PROVIDERS.include?(@provider)
+
       @api_key = api_key
       @temperature = temperature
+      @model = model
     end
   end
 end

data/lib/vibe_sort/providers/anthropic.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Adapter for the Anthropic Messages API
+    #
+    # Uses structured outputs (output_config.format with a JSON schema) so the
+    # model is guaranteed to return the { "sorted_array": [...] } shape.
+    #
+    # Note: current Claude models (Opus 4.7+) reject the temperature parameter,
+    # so config.temperature is not forwarded to this provider.
+    class Anthropic < Base
+      ENDPOINT = "https://api.anthropic.com/v1/messages"
+      DEFAULT_MODEL = "claude-opus-4-8"
+      API_VERSION = "2023-06-01"
+      MAX_TOKENS = 4096
+
+      OUTPUT_SCHEMA = {
+        type: "object",
+        properties: {
+          sorted_array: {
+            type: "array",
+            items: { anyOf: [{ type: "number" }, { type: "string" }] }
+          }
+        },
+        required: ["sorted_array"],
+        additionalProperties: false
+      }.freeze
+
+      private
+
+      def provider_name
+        "Anthropic"
+      end
+
+      def endpoint
+        ENDPOINT
+      end
+
+      def headers
+        {
+          "x-api-key" => config.api_key,
+          "anthropic-version" => API_VERSION
+        }
+      end
+
+      def build_payload(array)
+        {
+          model: model,
+          max_tokens: MAX_TOKENS,
+          system: SYSTEM_PROMPT,
+          output_config: { format: { type: "json_schema", schema: OUTPUT_SCHEMA } },
+          messages: [
+            { role: "user", content: user_prompt(array) }
+          ]
+        }
+      end
+
+      def extract_content(response)
+        blocks = response.body["content"]
+        return nil unless blocks.is_a?(Array)
+
+        text_block = blocks.find { |block| block.is_a?(Hash) && block["type"] == "text" }
+        text_block && text_block["text"]
+      end
+    end
+  end
+end

data/lib/vibe_sort/providers/base.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Base class for LLM provider adapters.
+    #
+    # Holds everything that is provider-agnostic: the sorting prompt, the
+    # Faraday connection plumbing, and validation of the returned array.
+    # Subclasses implement the provider-specific hooks: +provider_name+,
+    # +endpoint+, +headers+, +build_payload+, and +extract_content+.
+    class Base
+      SYSTEM_PROMPT = "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."
+
+      attr_reader :config
+
+      # @param config [VibeSort::Configuration] Configuration object
+      def initialize(config)
+        @config = config
+      end
+
+      # Perform the sorting operation via the provider's API
+      #
+      # @param array [Array] Array of numbers and/or strings to sort
+      # @return [Hash] Result hash with :success and :sorted_array 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
+
+      # Model to use: explicit override from config, or the provider default
+      #
+      # @return [String] Model ID
+      def model
+        config.model || self.class::DEFAULT_MODEL
+      end
+
+      # @param array [Array] Array to sort
+      # @return [String] User prompt sent to the model
+      def user_prompt(array)
+        "Please sort this array: #{array.to_json}"
+      end
+
+      # @return [Faraday::Connection] Faraday connection object
+      def connection
+        @connection ||= Faraday.new(url: endpoint) do |f|
+          f.request :json  # Encodes request body as JSON
+          f.response :json # Decodes response body as JSON
+          headers.each { |name, value| f.headers[name] = value }
+          f.headers["Content-Type"] = "application/json"
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # @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("#{provider_name} API error: #{error_message}", response)
+        end
+
+        parse_sorted_array(response)
+      end
+
+      # Extract error message from failed response. Works for all three
+      # providers: OpenAI, Anthropic, and Gemini all return an "error"
+      # object with a "message" key on failure.
+      #
+      # @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 = extract_content(response)
+        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
+
+      # --- Provider-specific hooks ---
+
+      # @return [String] Human-readable provider name used in error messages
+      def provider_name
+        raise NotImplementedError
+      end
+
+      # @return [String] Full URL of the API endpoint
+      def endpoint
+        raise NotImplementedError
+      end
+
+      # @return [Hash] Provider-specific HTTP headers (auth etc.)
+      def headers
+        raise NotImplementedError
+      end
+
+      # @param array [Array] Array to sort
+      # @return [Hash] Provider-specific request payload
+      def build_payload(array)
+        raise NotImplementedError
+      end
+
+      # @param response [Faraday::Response] HTTP response
+      # @return [String, nil] Raw JSON text produced by the model
+      def extract_content(response)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/vibe_sort/providers/gemini.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Adapter for the Google Gemini API (generateContent)
+    class Gemini < Base
+      BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models"
+      DEFAULT_MODEL = "gemini-2.5-flash"
+
+      private
+
+      def provider_name
+        "Gemini"
+      end
+
+      # The Gemini endpoint embeds the model ID in the URL path
+      def endpoint
+        "#{BASE_URL}/#{model}:generateContent"
+      end
+
+      def headers
+        { "x-goog-api-key" => config.api_key }
+      end
+
+      def build_payload(array)
+        {
+          systemInstruction: { parts: [{ text: SYSTEM_PROMPT }] },
+          contents: [
+            { role: "user", parts: [{ text: user_prompt(array) }] }
+          ],
+          generationConfig: {
+            temperature: config.temperature,
+            responseMimeType: "application/json"
+          }
+        }
+      end
+
+      def extract_content(response)
+        response.body.dig("candidates", 0, "content", "parts", 0, "text")
+      end
+    end
+  end
+end

data/lib/vibe_sort/providers/groq.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Adapter for the Groq API (OpenAI-compatible Chat Completions)
+    class Groq < OpenAI
+      ENDPOINT = "https://api.groq.com/openai/v1/chat/completions"
+      DEFAULT_MODEL = "llama-3.3-70b-versatile"
+
+      private
+
+      def provider_name
+        "Groq"
+      end
+
+      def endpoint
+        ENDPOINT
+      end
+    end
+  end
+end

data/lib/vibe_sort/providers/openai.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Adapter for the OpenAI Chat Completions API
+    class OpenAI < Base
+      ENDPOINT = "https://api.openai.com/v1/chat/completions"
+      DEFAULT_MODEL = "gpt-4o-mini"
+
+      private
+
+      def provider_name
+        "OpenAI"
+      end
+
+      def endpoint
+        ENDPOINT
+      end
+
+      def headers
+        { "Authorization" => "Bearer #{config.api_key}" }
+      end
+
+      def build_payload(array)
+        {
+          model: model,
+          temperature: config.temperature,
+          response_format: { type: "json_object" },
+          messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: user_prompt(array) }
+          ]
+        }
+      end
+
+      def extract_content(response)
+        response.body.dig("choices", 0, "message", "content")
+      end
+    end
+  end
+end

data/lib/vibe_sort/providers/space_x_ai.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module VibeSort
+  module Providers
+    # Adapter for the SpaceXAI (xAI) Grok API (OpenAI-compatible Chat Completions)
+    class SpaceXAI < OpenAI
+      ENDPOINT = "https://api.x.ai/v1/chat/completions"
+      DEFAULT_MODEL = "grok-4"
+
+      private
+
+      def provider_name
+        "SpaceXAI"
+      end
+
+      def endpoint
+        ENDPOINT
+      end
+    end
+  end
+end

data/lib/vibe_sort/sorter.rb

@@ -1,10 +1,15 @@
 # frozen_string_literal: true
 
 module VibeSort
-  # Sorter class handles the API call to OpenAI
+  # Sorter dispatches the sorting operation to the configured provider adapter
   class Sorter
-    OPENAI_API_URL = "https://api.openai.com/v1/chat/completions"
-    DEFAULT_MODEL = "gpt-3.5-turbo-1106"
+    PROVIDER_CLASSES = {
+      openai: Providers::OpenAI,
+      anthropic: Providers::Anthropic,
+      gemini: Providers::Gemini,
+      groq: Providers::Groq,
+      spacexai: Providers::SpaceXAI
+    }.freeze
 
     attr_reader :config
 
@@ -15,111 +20,13 @@ module VibeSort
       @config = config
     end
 
-    # Perform the sorting operation via OpenAI API
+    # Perform the sorting operation via the configured provider's 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)"
+      PROVIDER_CLASSES.fetch(config.provider).new(config).perform(array)
     end
   end
 end

data/lib/vibe_sort/version.rb

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

data/lib/vibe_sort.rb

@@ -6,6 +6,12 @@ require "json"
 require_relative "vibe_sort/version"
 require_relative "vibe_sort/error"
 require_relative "vibe_sort/configuration"
+require_relative "vibe_sort/providers/base"
+require_relative "vibe_sort/providers/openai"
+require_relative "vibe_sort/providers/anthropic"
+require_relative "vibe_sort/providers/gemini"
+require_relative "vibe_sort/providers/groq"
+require_relative "vibe_sort/providers/space_x_ai"
 require_relative "vibe_sort/sorter"
 require_relative "vibe_sort/client"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: vibe-sort
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Chayut Orapinpatipat
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-10-16 00:00:00.000000000 Z
+date: 2026-07-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -24,8 +24,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-description: A proof-of-concept Ruby gem that sorts number arrays by leveraging the
-  OpenAI Chat Completions API. Demonstrates how AI can be used for computational tasks.
+description: A proof-of-concept Ruby gem that sorts arrays by leveraging LLM APIs
+  (OpenAI Chat Completions, Anthropic Messages, Google Gemini). Demonstrates how AI
+  can be used for computational tasks.
 email:
 - chayut_o@hotmail.com
 executables: []
@@ -45,14 +46,18 @@ files:
 - docs/development.md
 - docs/v0.2.0_UPDATE.md
 - lib/vibe/sort.rb
-- lib/vibe/sort/version.rb
 - lib/vibe_sort.rb
 - lib/vibe_sort/client.rb
 - lib/vibe_sort/configuration.rb
 - lib/vibe_sort/error.rb
+- lib/vibe_sort/providers/anthropic.rb
+- lib/vibe_sort/providers/base.rb
+- lib/vibe_sort/providers/gemini.rb
+- lib/vibe_sort/providers/groq.rb
+- lib/vibe_sort/providers/openai.rb
+- lib/vibe_sort/providers/space_x_ai.rb
 - lib/vibe_sort/sorter.rb
 - lib/vibe_sort/version.rb
-- sig/vibe/sort.rbs
 homepage: https://github.com/chayuto/vibe-sort
 licenses:
 - MIT
@@ -76,8 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: AI-powered array sorting using OpenAI's GPT models
+summary: AI-powered array sorting using OpenAI, Anthropic Claude, or Google Gemini
 test_files: []

data/lib/vibe/sort/version.rb

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

data/sig/vibe/sort.rbs

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