# Vibesorter
Sort arrays using LLMs with structured output
[](https://badge.fury.io/py/vibesorter)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## ✨ Features
- **One Simple Interface**: Just `vibesort()` for everything
- **Auto-Detection**: Automatically handles integers vs strings
- **LLM-Powered Sorting**: Use state-of-the-art language models
- **Structured Output**: Reliable, type-safe results using Pydantic models
- **Multiple Providers**: Support for OpenAI, Anthropic, and Google models
- **Custom Criteria**: Sort strings by length, alphabetically, or any criteria you want
- **Production Ready**: Comprehensive error handling and validation
- **Easy Setup**: Simple configuration with environment variables
## 🚀 Installation
```bash
pip install vibesorter
```
## 🔧 Setup
1. Copy the example environment file:
```bash
cp .env.example .env
```
2. Add your API key and preferred model to `.env`:
```env
VIBESORTER_MODEL_NAME=gpt-4o-mini
OPENAI_API_KEY=your_openai_api_key_here
```
Supported environment variables:
- `VIBESORTER_MODEL_NAME`: Model to use (default: `gpt-4o-mini`)
- `OPENAI_API_KEY`: For GPT models
- `ANTHROPIC_API_KEY`: For Claude models
- `GOOGLE_API_KEY`: For Gemini models
## 📖 Usage
### Sort Integers
```python
from vibesorter import vibesort
# Sort integers in ascending order
numbers = [64, 34, 25, 12, 22, 11, 90]
sorted_numbers = vibesort(numbers)
print(sorted_numbers) # [11, 12, 22, 25, 34, 64, 90]
# Sort in descending order
sorted_desc = vibesort(numbers, order="desc")
print(sorted_desc) # [90, 64, 34, 25, 22, 12, 11]
```
### Sort Strings
```python
from vibesorter import vibesort
# Sort strings alphabetically
words = ["python", "ai", "langchain", "sort"]
sorted_words = vibesort(words)
print(sorted_words) # ['ai', 'langchain', 'python', 'sort']
# Sort strings by length
sorted_by_length = vibesort(
words,
order="asc",
sort_criteria="by length"
)
print(sorted_by_length) # ["ai", "sort", "python", "langchain"]
# Sort numbers as strings numerically
numbers_as_strings = ["64", "34", "25", "12", "22", "11", "90"]
sorted_numerically = vibesort(
numbers_as_strings,
order="asc",
sort_criteria="numerically"
)
print(sorted_numerically) # ["11", "12", "22", "25", "34", "64", "90"]
```
### Error Handling
```python
from vibesorter import vibesort, APIKeyError, ModelError, VibesortError
try:
result = vibesort([3, 1, 4, 1, 5])
print(result)
except APIKeyError as e:
print(f"API key error: {e}")
except ModelError as e:
print(f"Model error: {e}")
except VibesortError as e:
print(f"Sorting error: {e}")
```
## 🔧 Configuration
### Supported Models
**OpenAI Models:**
- `gpt-4o-mini` (default, cleanest output)
- `gpt-4o`
- `gpt-4-turbo`
- `gpt-3.5-turbo`
**Anthropic Models:**
- `claude-3-sonnet-20240229`
- `claude-3-haiku-20240307`
- `claude-3-opus-20240229`
**Google Models:**
- `gemini-pro`
- `gemini-1.5-pro`
> **Note**: Google/Gemini models may show harmless schema warnings about `additionalProperties`. These don't affect functionality but for cleanest output, consider using OpenAI or Anthropic models.
### Environment Variables
The library automatically detects the provider based on your model name and available API keys:
```env
# For OpenAI models
VIBESORTER_MODEL_NAME=gpt-4o-mini
OPENAI_API_KEY=sk-...
# For Anthropic models
VIBESORTER_MODEL_NAME=claude-3-sonnet-20240229
ANTHROPIC_API_KEY=sk-ant-...
# For Google models
VIBESORTER_MODEL_NAME=gemini-pro
GOOGLE_API_KEY=AI...
```
## 🧪 Development
### Setup Development Environment
```bash
# Clone the repository
git clone https://github.com/Yazan-Hamdan/vibesorter.git
cd vibesorter
# Install development dependencies
pip install -e ".[dev]"
# Set up pre-commit hooks (optional)
pre-commit install
```
### Running Tests
```bash
pytest
```
### Code Formatting
```bash
black vibesorter/
isort vibesorter/
flake8 vibesorter/
```
### Type Checking
```bash
mypy vibesorter/
```
## 📋 API Reference
### `vibesort(array, order="asc", sort_criteria="")`
Sort an array of integers or strings using an LLM. Automatically detects the data type and uses the appropriate processing.
**Parameters:**
- `array` (List[int] | List[str]): List of integers or strings to sort
- `order` (Literal["asc", "desc"]): Sort order (default: "asc")
- `sort_criteria` (str): Optional criteria for string sorting (default: "", ignored for integers)
**Returns:**
- `List[int] | List[str]`: The sorted array (same type as input)
**Raises:**
- `VibesortError`: If sorting fails or array contains mixed types
- `APIKeyError`: If API key is not configured
- `ModelError`: If model initialization fails
**Examples:**
```python
# Sort integers
vibesort([3, 1, 4]) # → [1, 3, 4]
# Sort strings
vibesort(["c", "a", "b"]) # → ["a", "b", "c"]
# Sort strings with criteria
vibesort(["python", "ai"], sort_criteria="by length") # → ["ai", "python"]
```
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙋♂️ Support
If you have any questions or run into issues, please:
1. Check the [Issues](https://github.com/Yazan-Hamdan/vibesorter/issues) page
2. Create a new issue if your problem isn't already reported
3. Provide as much detail as possible, including:
- Python version
- Vibesorter version
- Error messages
- Sample code that reproduces the issue
Raw data
{
"_id": null,
"home_page": "https://github.com/Yazan-Hamdan/vibesorter",
"name": "vibesorter",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "llm, sorting, langchain, ai, structured-output",
"author": "Your Name",
"author_email": "Yazan Hamdan <yazanalatrash591@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/24/5c/720210e45e2cb2f162de5e7800c959c2f933de94a72189b7a2c7cf210e54/vibesorter-0.1.1.tar.gz",
"platform": null,
"description": "# Vibesorter\n\nSort arrays using LLMs with structured output\n\n[](https://badge.fury.io/py/vibesorter)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## \u2728 Features\n\n- **One Simple Interface**: Just `vibesort()` for everything\n- **Auto-Detection**: Automatically handles integers vs strings\n- **LLM-Powered Sorting**: Use state-of-the-art language models \n- **Structured Output**: Reliable, type-safe results using Pydantic models\n- **Multiple Providers**: Support for OpenAI, Anthropic, and Google models\n- **Custom Criteria**: Sort strings by length, alphabetically, or any criteria you want\n- **Production Ready**: Comprehensive error handling and validation\n- **Easy Setup**: Simple configuration with environment variables\n\n## \ud83d\ude80 Installation\n\n```bash\npip install vibesorter\n```\n\n## \ud83d\udd27 Setup\n\n1. Copy the example environment file:\n```bash\ncp .env.example .env\n```\n\n2. Add your API key and preferred model to `.env`:\n```env\nVIBESORTER_MODEL_NAME=gpt-4o-mini\nOPENAI_API_KEY=your_openai_api_key_here\n```\n\nSupported environment variables:\n- `VIBESORTER_MODEL_NAME`: Model to use (default: `gpt-4o-mini`)\n- `OPENAI_API_KEY`: For GPT models \n- `ANTHROPIC_API_KEY`: For Claude models\n- `GOOGLE_API_KEY`: For Gemini models\n\n## \ud83d\udcd6 Usage\n\n### Sort Integers\n\n```python\nfrom vibesorter import vibesort\n\n# Sort integers in ascending order\nnumbers = [64, 34, 25, 12, 22, 11, 90]\nsorted_numbers = vibesort(numbers)\nprint(sorted_numbers) # [11, 12, 22, 25, 34, 64, 90]\n\n# Sort in descending order\nsorted_desc = vibesort(numbers, order=\"desc\") \nprint(sorted_desc) # [90, 64, 34, 25, 22, 12, 11]\n```\n\n### Sort Strings\n\n```python\nfrom vibesorter import vibesort\n\n# Sort strings alphabetically \nwords = [\"python\", \"ai\", \"langchain\", \"sort\"]\nsorted_words = vibesort(words)\nprint(sorted_words) # ['ai', 'langchain', 'python', 'sort']\n\n# Sort strings by length\nsorted_by_length = vibesort(\n words, \n order=\"asc\",\n sort_criteria=\"by length\"\n)\nprint(sorted_by_length) # [\"ai\", \"sort\", \"python\", \"langchain\"]\n\n# Sort numbers as strings numerically\nnumbers_as_strings = [\"64\", \"34\", \"25\", \"12\", \"22\", \"11\", \"90\"]\nsorted_numerically = vibesort(\n numbers_as_strings,\n order=\"asc\", \n sort_criteria=\"numerically\"\n)\nprint(sorted_numerically) # [\"11\", \"12\", \"22\", \"25\", \"34\", \"64\", \"90\"]\n```\n\n### Error Handling\n\n```python\nfrom vibesorter import vibesort, APIKeyError, ModelError, VibesortError\n\ntry:\n result = vibesort([3, 1, 4, 1, 5])\n print(result)\nexcept APIKeyError as e:\n print(f\"API key error: {e}\")\nexcept ModelError as e:\n print(f\"Model error: {e}\") \nexcept VibesortError as e:\n print(f\"Sorting error: {e}\")\n```\n\n## \ud83d\udd27 Configuration\n\n### Supported Models\n\n**OpenAI Models:**\n- `gpt-4o-mini` (default, cleanest output)\n- `gpt-4o`\n- `gpt-4-turbo`\n- `gpt-3.5-turbo`\n\n**Anthropic Models:**\n- `claude-3-sonnet-20240229`\n- `claude-3-haiku-20240307`\n- `claude-3-opus-20240229`\n\n**Google Models:**\n- `gemini-pro`\n- `gemini-1.5-pro`\n\n> **Note**: Google/Gemini models may show harmless schema warnings about `additionalProperties`. These don't affect functionality but for cleanest output, consider using OpenAI or Anthropic models.\n\n### Environment Variables\n\nThe library automatically detects the provider based on your model name and available API keys:\n\n```env\n# For OpenAI models\nVIBESORTER_MODEL_NAME=gpt-4o-mini\nOPENAI_API_KEY=sk-...\n\n# For Anthropic models \nVIBESORTER_MODEL_NAME=claude-3-sonnet-20240229\nANTHROPIC_API_KEY=sk-ant-...\n\n# For Google models\nVIBESORTER_MODEL_NAME=gemini-pro\nGOOGLE_API_KEY=AI...\n```\n\n## \ud83e\uddea Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/Yazan-Hamdan/vibesorter.git\ncd vibesorter\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Set up pre-commit hooks (optional)\npre-commit install\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Formatting\n\n```bash\nblack vibesorter/\nisort vibesorter/\nflake8 vibesorter/\n```\n\n### Type Checking\n\n```bash\nmypy vibesorter/\n```\n\n## \ud83d\udccb API Reference\n\n### `vibesort(array, order=\"asc\", sort_criteria=\"\")`\n\nSort an array of integers or strings using an LLM. Automatically detects the data type and uses the appropriate processing.\n\n**Parameters:**\n- `array` (List[int] | List[str]): List of integers or strings to sort\n- `order` (Literal[\"asc\", \"desc\"]): Sort order (default: \"asc\")\n- `sort_criteria` (str): Optional criteria for string sorting (default: \"\", ignored for integers)\n\n**Returns:**\n- `List[int] | List[str]`: The sorted array (same type as input)\n\n**Raises:**\n- `VibesortError`: If sorting fails or array contains mixed types\n- `APIKeyError`: If API key is not configured\n- `ModelError`: If model initialization fails\n\n**Examples:**\n```python\n# Sort integers\nvibesort([3, 1, 4]) # \u2192 [1, 3, 4]\n\n# Sort strings\nvibesort([\"c\", \"a\", \"b\"]) # \u2192 [\"a\", \"b\", \"c\"] \n\n# Sort strings with criteria\nvibesort([\"python\", \"ai\"], sort_criteria=\"by length\") # \u2192 [\"ai\", \"python\"]\n```\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4b\u200d\u2642\ufe0f Support\n\nIf you have any questions or run into issues, please:\n\n1. Check the [Issues](https://github.com/Yazan-Hamdan/vibesorter/issues) page\n2. Create a new issue if your problem isn't already reported\n3. Provide as much detail as possible, including:\n - Python version\n - Vibesorter version \n - Error messages\n - Sample code that reproduces the issue\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Sort arrays using LLMs with structured output",
"version": "0.1.1",
"project_urls": {
"Bug Reports": "https://github.com/Yazan-Hamdan/vibesorter/issues",
"Documentation": "https://github.com/Yazan-Hamdan/vibesorter#readme",
"Homepage": "https://github.com/Yazan-Hamdan/vibesorter",
"Source": "https://github.com/Yazan-Hamdan/vibesorter"
},
"split_keywords": [
"llm",
" sorting",
" langchain",
" ai",
" structured-output"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15ddae288e1e54d55ec4183adc873ed159974751cd47e3d23549d04c90bd8b77",
"md5": "ad03dbecc869b33b03a8b7a8fce2605b",
"sha256": "7b3e136315a0c8a72d7bb34ff62082304616c1e08eb5537dda8569ae8e7f140a"
},
"downloads": -1,
"filename": "vibesorter-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad03dbecc869b33b03a8b7a8fce2605b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 4948,
"upload_time": "2025-08-30T19:06:07",
"upload_time_iso_8601": "2025-08-30T19:06:07.937870Z",
"url": "https://files.pythonhosted.org/packages/15/dd/ae288e1e54d55ec4183adc873ed159974751cd47e3d23549d04c90bd8b77/vibesorter-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "245c720210e45e2cb2f162de5e7800c959c2f933de94a72189b7a2c7cf210e54",
"md5": "b83255c4619854d4138bed4dcea82b16",
"sha256": "a7958700f68b2d6dc69141ca7f0acca71aa45bac8a43f8912e857deefccac55d"
},
"downloads": -1,
"filename": "vibesorter-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "b83255c4619854d4138bed4dcea82b16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 6018,
"upload_time": "2025-08-30T19:06:09",
"upload_time_iso_8601": "2025-08-30T19:06:09.373606Z",
"url": "https://files.pythonhosted.org/packages/24/5c/720210e45e2cb2f162de5e7800c959c2f933de94a72189b7a2c7cf210e54/vibesorter-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 19:06:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Yazan-Hamdan",
"github_project": "vibesorter",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "langchain",
"specs": [
[
">=",
"0.3.27"
]
]
},
{
"name": "langchain-core",
"specs": [
[
">=",
"0.3.17"
]
]
},
{
"name": "langchain-openai",
"specs": [
[
">=",
"0.3.32"
]
]
},
{
"name": "langchain-anthropic",
"specs": [
[
">=",
"0.3.19"
]
]
},
{
"name": "langchain-google-genai",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.5.0"
]
]
}
],
"lcname": "vibesorter"
}
JSON
