# Status Whimsy
A lightweight Python library that transforms boring status updates into delightful, whimsical messages using Claude Haiku 3.
## Features
- 🎨 Transform plain status messages into engaging updates
- 🎚️ Adjustable whimsy levels (1-10)
- 📏 Configurable output length (short, medium, long)
- 🚀 Simple API with both class-based and functional interfaces
- 🔧 Batch processing support
- 🌡️ Dynamic temperature scaling based on whimsy level
## Installation
```bash
pip install status-whimsy
```
## Quick Start
```python
from status_whimsy import StatusWhimsy
# Initialize with your Anthropic API key
whimsy = StatusWhimsy(api_key="your-api-key")
# Transform a boring status
result = whimsy.generate(
"Server is running",
whimsicalness=7,
length="short"
)
print(result)
# Output: "The server is dancing merrily in the digital clouds! 🎉"
```
## Usage
### Basic Usage
```python
from status_whimsy import StatusWhimsy
# Initialize the client
whimsy = StatusWhimsy() # Uses ANTHROPIC_API_KEY env variable
# Generate whimsical status updates
update = whimsy.generate("Database backup complete", whimsicalness=5)
```
### One-off Usage
```python
from status_whimsy import whimsify
# Quick transformation without creating a client
result = whimsify("User logged in", whimsicalness=8, length="medium")
```
### Batch Processing
```python
statuses = [
"Server is running",
"Database backup complete",
"User authentication failed"
]
whimsical_updates = whimsy.batch_generate(
statuses,
whimsicalness=6,
length="short"
)
```
## Configuration
### API Key
Set your Anthropic API key in one of two ways:
1. Environment variable:
```bash
export ANTHROPIC_API_KEY="your-api-key"
```
2. Pass directly to the constructor:
```python
whimsy = StatusWhimsy(api_key="your-api-key")
```
### Whimsy Levels
- **1**: Professional and straightforward
- **2**: Slightly friendly
- **3**: Casually friendly
- **4**: Lightly playful
- **5**: Moderately playful and fun
- **6**: Quite playful with personality
- **7**: Very whimsical and creative
- **8**: Highly whimsical with metaphors
- **9**: Extremely whimsical and imaginative
- **10**: Maximum whimsy with wild creativity
### Output Lengths
- **short**: 10-20 words
- **medium**: 20-40 words
- **long**: 40-60 words
## Examples
```python
from status_whimsy import StatusWhimsy
whimsy = StatusWhimsy()
# Professional (Level 1)
whimsy.generate("Server is running", whimsicalness=1)
# "Server operational and functioning normally."
# Moderate whimsy (Level 5)
whimsy.generate("Server is running", whimsicalness=5)
# "The server is humming along happily, serving requests with a smile!"
# Maximum whimsy (Level 10)
whimsy.generate("Server is running", whimsicalness=10)
# "The digital dragon awakens, breathing binary fire across the realm of electrons, ready to grant your computational wishes!"
```
## API Reference
### StatusWhimsy Class
#### `__init__(api_key: Optional[str] = None)`
Initialize the StatusWhimsy client.
#### `generate(status: str, whimsicalness: int = 5, length: Literal["short", "medium", "long"] = "short") -> str`
Generate a whimsical version of the given status.
#### `batch_generate(statuses: list[str], whimsicalness: int = 5, length: Literal["short", "medium", "long"] = "short") -> list[str]`
Generate whimsical versions for multiple status messages.
### Function
#### `whimsify(status: str, api_key: Optional[str] = None, whimsicalness: int = 5, length: Literal["short", "medium", "long"] = "short") -> str`
Quick function to whimsify a single status without creating a client.
## API Costs
This library uses Claude Haiku 3, which offers extremely affordable pricing:
### Claude Haiku 3 Pricing (as of January 2025)
- **Input tokens**: $0.25 per million tokens
- **Output tokens**: $1.25 per million tokens
### Cost Per Status Update
**Token Estimation:**
- Input tokens (your prompt + system instructions): ~150-200 tokens
- Output tokens (generated status):
- Short (10-20 words): ~15-30 tokens
- Medium (20-40 words): ~30-60 tokens
- Long (40-60 words): ~60-90 tokens
**Cost Calculation:**
Per single status update:
- Input cost: 200 tokens × $0.00000025 = $0.00005
- Output cost (short): 30 tokens × $0.00000125 = $0.0000375
- **Total per call: ~$0.00009** (less than 1/100th of a cent)
### Practical Examples
| Usage Volume | Approximate Cost |
|--------------|------------------|
| 100 status updates | $0.009 (less than 1¢) |
| 1,000 status updates | $0.09 (9¢) |
| 10,000 status updates | $0.90 (90¢) |
| 100,000 status updates | $9.00 |
### Example Monthly Cost
If your application generates 100 status updates per hour, 24/7:
- 100 × 24 × 30 = 72,000 updates/month
- **Cost: ~$6.48/month**
### Cost Optimization Tips
1. **Batch processing**: The `batch_generate()` method is more efficient for multiple statuses
2. **Shorter outputs**: Use `length="short"` to minimize output tokens
3. **Cache common statuses**: Store frequently used transformations locally
The library is extremely cost-effective due to Haiku's low pricing and the minimal token usage for status updates.
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/RichardAtCT/status-whimsy.git
cd status-whimsy
# Install in development mode
pip install -e ".[dev]"
```
### Running Tests
```bash
pytest
```
### Code Style
```bash
# Format code
black status_whimsy
# Sort imports
isort status_whimsy
# Type checking
mypy status_whimsy
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- Built with [Anthropic's Claude API](https://www.anthropic.com/)
- Inspired by the need for more joy in system status messages
## Support
If you encounter any issues or have questions, please [open an issue](https://github.com/RichardAtCT/status-whimsy/issues) on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "status-whimsy",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "status, whimsy, claude, anthropic, ai, creative-writing",
"author": "Richard Atkinson",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/ee/28ea2ef8ca96b1d2d0b54782938d7c203668afdb5a434cbf62ac0ef7229d/status_whimsy-0.1.0.tar.gz",
"platform": null,
"description": "# Status Whimsy\n\nA lightweight Python library that transforms boring status updates into delightful, whimsical messages using Claude Haiku 3.\n\n## Features\n\n- \ud83c\udfa8 Transform plain status messages into engaging updates\n- \ud83c\udf9a\ufe0f Adjustable whimsy levels (1-10)\n- \ud83d\udccf Configurable output length (short, medium, long)\n- \ud83d\ude80 Simple API with both class-based and functional interfaces\n- \ud83d\udd27 Batch processing support\n- \ud83c\udf21\ufe0f Dynamic temperature scaling based on whimsy level\n\n## Installation\n\n```bash\npip install status-whimsy\n```\n\n## Quick Start\n\n```python\nfrom status_whimsy import StatusWhimsy\n\n# Initialize with your Anthropic API key\nwhimsy = StatusWhimsy(api_key=\"your-api-key\")\n\n# Transform a boring status\nresult = whimsy.generate(\n \"Server is running\",\n whimsicalness=7,\n length=\"short\"\n)\nprint(result)\n# Output: \"The server is dancing merrily in the digital clouds! \ud83c\udf89\"\n```\n\n## Usage\n\n### Basic Usage\n\n```python\nfrom status_whimsy import StatusWhimsy\n\n# Initialize the client\nwhimsy = StatusWhimsy() # Uses ANTHROPIC_API_KEY env variable\n\n# Generate whimsical status updates\nupdate = whimsy.generate(\"Database backup complete\", whimsicalness=5)\n```\n\n### One-off Usage\n\n```python\nfrom status_whimsy import whimsify\n\n# Quick transformation without creating a client\nresult = whimsify(\"User logged in\", whimsicalness=8, length=\"medium\")\n```\n\n### Batch Processing\n\n```python\nstatuses = [\n \"Server is running\",\n \"Database backup complete\",\n \"User authentication failed\"\n]\n\nwhimsical_updates = whimsy.batch_generate(\n statuses,\n whimsicalness=6,\n length=\"short\"\n)\n```\n\n## Configuration\n\n### API Key\n\nSet your Anthropic API key in one of two ways:\n\n1. Environment variable:\n ```bash\n export ANTHROPIC_API_KEY=\"your-api-key\"\n ```\n\n2. Pass directly to the constructor:\n ```python\n whimsy = StatusWhimsy(api_key=\"your-api-key\")\n ```\n\n### Whimsy Levels\n\n- **1**: Professional and straightforward\n- **2**: Slightly friendly\n- **3**: Casually friendly\n- **4**: Lightly playful\n- **5**: Moderately playful and fun\n- **6**: Quite playful with personality\n- **7**: Very whimsical and creative\n- **8**: Highly whimsical with metaphors\n- **9**: Extremely whimsical and imaginative\n- **10**: Maximum whimsy with wild creativity\n\n### Output Lengths\n\n- **short**: 10-20 words\n- **medium**: 20-40 words\n- **long**: 40-60 words\n\n## Examples\n\n```python\nfrom status_whimsy import StatusWhimsy\n\nwhimsy = StatusWhimsy()\n\n# Professional (Level 1)\nwhimsy.generate(\"Server is running\", whimsicalness=1)\n# \"Server operational and functioning normally.\"\n\n# Moderate whimsy (Level 5)\nwhimsy.generate(\"Server is running\", whimsicalness=5)\n# \"The server is humming along happily, serving requests with a smile!\"\n\n# Maximum whimsy (Level 10)\nwhimsy.generate(\"Server is running\", whimsicalness=10)\n# \"The digital dragon awakens, breathing binary fire across the realm of electrons, ready to grant your computational wishes!\"\n```\n\n## API Reference\n\n### StatusWhimsy Class\n\n#### `__init__(api_key: Optional[str] = None)`\nInitialize the StatusWhimsy client.\n\n#### `generate(status: str, whimsicalness: int = 5, length: Literal[\"short\", \"medium\", \"long\"] = \"short\") -> str`\nGenerate a whimsical version of the given status.\n\n#### `batch_generate(statuses: list[str], whimsicalness: int = 5, length: Literal[\"short\", \"medium\", \"long\"] = \"short\") -> list[str]`\nGenerate whimsical versions for multiple status messages.\n\n### Function\n\n#### `whimsify(status: str, api_key: Optional[str] = None, whimsicalness: int = 5, length: Literal[\"short\", \"medium\", \"long\"] = \"short\") -> str`\nQuick function to whimsify a single status without creating a client.\n\n## API Costs\n\nThis library uses Claude Haiku 3, which offers extremely affordable pricing:\n\n### Claude Haiku 3 Pricing (as of January 2025)\n- **Input tokens**: $0.25 per million tokens\n- **Output tokens**: $1.25 per million tokens\n\n### Cost Per Status Update\n\n**Token Estimation:**\n- Input tokens (your prompt + system instructions): ~150-200 tokens\n- Output tokens (generated status):\n - Short (10-20 words): ~15-30 tokens\n - Medium (20-40 words): ~30-60 tokens\n - Long (40-60 words): ~60-90 tokens\n\n**Cost Calculation:**\nPer single status update:\n- Input cost: 200 tokens \u00d7 $0.00000025 = $0.00005\n- Output cost (short): 30 tokens \u00d7 $0.00000125 = $0.0000375\n- **Total per call: ~$0.00009** (less than 1/100th of a cent)\n\n### Practical Examples\n\n| Usage Volume | Approximate Cost |\n|--------------|------------------|\n| 100 status updates | $0.009 (less than 1\u00a2) |\n| 1,000 status updates | $0.09 (9\u00a2) |\n| 10,000 status updates | $0.90 (90\u00a2) |\n| 100,000 status updates | $9.00 |\n\n### Example Monthly Cost\nIf your application generates 100 status updates per hour, 24/7:\n- 100 \u00d7 24 \u00d7 30 = 72,000 updates/month\n- **Cost: ~$6.48/month**\n\n### Cost Optimization Tips\n1. **Batch processing**: The `batch_generate()` method is more efficient for multiple statuses\n2. **Shorter outputs**: Use `length=\"short\"` to minimize output tokens\n3. **Cache common statuses**: Store frequently used transformations locally\n\nThe library is extremely cost-effective due to Haiku's low pricing and the minimal token usage for status updates.\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/RichardAtCT/status-whimsy.git\ncd status-whimsy\n\n# Install in development mode\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Style\n\n```bash\n# Format code\nblack status_whimsy\n\n# Sort imports\nisort status_whimsy\n\n# Type checking\nmypy status_whimsy\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Anthropic's Claude API](https://www.anthropic.com/)\n- Inspired by the need for more joy in system status messages\n\n## Support\n\nIf you encounter any issues or have questions, please [open an issue](https://github.com/RichardAtCT/status-whimsy/issues) on GitHub.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight library for generating whimsical status updates using Claude Haiku 3",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/RichardAtCT/status-whimsy#readme",
"Homepage": "https://github.com/RichardAtCT/status-whimsy",
"Issues": "https://github.com/RichardAtCT/status-whimsy/issues",
"Repository": "https://github.com/RichardAtCT/status-whimsy"
},
"split_keywords": [
"status",
" whimsy",
" claude",
" anthropic",
" ai",
" creative-writing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ca062379fe6b58ff177a7a4e9c55030b01e8936af3a8e01cdb87d2a6e164e123",
"md5": "6218275de4cbffdcf283f63fe89b870a",
"sha256": "422e14b8280d05a96c6b358bc7139b32be4a4ec561e4193722e9fbf194201180"
},
"downloads": -1,
"filename": "status_whimsy-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6218275de4cbffdcf283f63fe89b870a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7136,
"upload_time": "2025-07-27T16:00:21",
"upload_time_iso_8601": "2025-07-27T16:00:21.096581Z",
"url": "https://files.pythonhosted.org/packages/ca/06/2379fe6b58ff177a7a4e9c55030b01e8936af3a8e01cdb87d2a6e164e123/status_whimsy-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "64ee28ea2ef8ca96b1d2d0b54782938d7c203668afdb5a434cbf62ac0ef7229d",
"md5": "92c5e8384e0fea838a4eef126c0ef375",
"sha256": "705511d3b39ae6d66b5253a938c8fc0f771eb0513c7dd0d0fdb53b77ad0c1611"
},
"downloads": -1,
"filename": "status_whimsy-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "92c5e8384e0fea838a4eef126c0ef375",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 8236,
"upload_time": "2025-07-27T16:00:22",
"upload_time_iso_8601": "2025-07-27T16:00:22.129865Z",
"url": "https://files.pythonhosted.org/packages/64/ee/28ea2ef8ca96b1d2d0b54782938d7c203668afdb5a434cbf62ac0ef7229d/status_whimsy-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 16:00:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RichardAtCT",
"github_project": "status-whimsy#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "anthropic",
"specs": [
[
">=",
"0.18.0"
]
]
}
],
"lcname": "status-whimsy"
}
JSON
