eclips-blossom-ai 0.5.3

🌸 Beautiful and simple AI generation library for images, text, and audio

🌸 Blossom AI

🚀 Quick Start • 📚 Documentation • 🖥️ CLI Interface • 💡 Examples • 📝 Changelog

---

✨ Features

🖼️ HD Image Generation Create stunning images from text HD quality up to 2048x2048 Advanced controls (guidance, quality) Direct URL generation	💬 Advanced Text Generation Multiple AI models (OpenAI, Gemini, etc.) Real-time streaming Function calling & tools JSON mode	👁️ Vision & Multimodal Analyze images with AI Multiple image support Local & URL images High-quality analysis
🖥️ CLI Interface Interactive terminal menu Quick command-line access No code required Shell automation	🚀 Production Ready Sync & async support Connection pooling Smart caching Comprehensive tests	⚡ Fast & Secure Token in headers only SSL verification enforced Optimized performance No memory leaks

🆕 What's New in v0.5.0

👁️ Vision Support (NEW!)

Analyze images with AI:

• 🔍 Image analysis from URLs or local files
• 🎨 Multiple images in one request
• 📊 Adjustable detail levels (low/auto/high)
• 🤖 Works with vision-capable models

from blossom_ai import Blossom, MessageBuilder

with Blossom(api_token="token") as client:
    messages = [
        MessageBuilder.image(
            role="user",
            text="What's in this image?",
            image_url="https://example.com/image.jpg",
            detail="high"
        )
    ]
    
    response = client.text.chat(messages, model="openai")
    print(response)

📚 Full Vision Documentation →

🎨 Enhanced Image Generation

Advanced image controls:

• 🎯 Quality levels: low, medium, high, hd
• 🎨 Guidance scale control (1.0-20.0)
• 🚫 Negative prompts for better control
• 🌈 Transparent background support
• 🖼️ Image-to-image transformation
• ⚡ Fast URL generation (no download needed)

with Blossom(api_token="token") as client:
    # HD quality with advanced controls
    image = client.image.generate(
        "majestic dragon",
        quality="hd",
        guidance_scale=7.5,
        negative_prompt="blurry, low quality",
        width=1920,
        height=1080
    )

📝 Advanced Text Features

Powerful text generation:

• 🛠️ Function calling / Tool use
• 📋 Structured JSON output
• ⚙️ Advanced parameters: max_tokens, frequency_penalty, presence_penalty, top_p
• 🌊 Improved streaming with SSE
• 🌡️ Extended temperature range (0-2)
• 💬 Multi-turn conversations

with Blossom(api_token="token") as client:
    response = client.text.generate(
        "Explain quantum computing",
        max_tokens=500,
        temperature=0.8,
        frequency_penalty=0.5,
        json_mode=True
    )

🚀 Quick Start

📦 Installation

pip install eclips-blossom-ai

🖥️ CLI Interface

Perfect for quick testing and learning:

# Launch interactive menu
python -m blossom_ai.utils.cli

# Quick commands
python -m blossom_ai.utils.cli --image "a beautiful sunset" --output sunset.png
python -m blossom_ai.utils.cli --text "Explain quantum computing"

# Set API token (optional for some features)
export POLLINATIONS_API_KEY="your_token"
python -m blossom_ai.utils.cli

Interactive Menu:

╔════════════════════════════════════════╗
║        🌸 BLOSSOM AI CLI 🌸            ║
║  Simple interface for AI generation    ║
╚════════════════════════════════════════╝

1. 🖼️  Generate Image
2. 💬 Generate Text
3. 👁️  Analyze Image (Vision)
4. ℹ️  Show Available Models
5. 🚪 Exit

📚 Full CLI Documentation →

⚡ Python Library

from blossom_ai import Blossom
import os
api_token = os.getenv('POLLINATIONS_API_KEY')
# Simple usage
with Blossom(api_token=api_token) as ai:
    # Generate image URL 
    url = ai.image.generate_url("a beautiful sunset")
    print(url)
    
    # Save image directly
    ai.image.save("a serene lake at dawn", "lake.jpg")
    
    # Generate text
    response = ai.text.generate("Explain quantum computing")
    print(response)
    
    # Stream text in real-time
    for chunk in ai.text.generate("Tell me a story", stream=True):
        print(chunk, end='', flush=True)

🎯 With API Token (Advanced Features)

import os
from blossom_ai import Blossom

# ✅ Best practice: Use environment variables
api_token = os.getenv('POLLINATIONS_API_KEY')

with Blossom(api_token=api_token) as client:
    # HD image with advanced controls
    image = client.image.generate(
        "majestic dragon",
        quality="hd",
        guidance_scale=7.5,
        negative_prompt="blurry, low quality",
        width=1920,
        height=1080
    )
    
    # Advanced text generation
    response = client.text.generate(
        "Explain AI",
        max_tokens=200,
        frequency_penalty=0.5,
        temperature=0.8
    )
    
    # Vision analysis (requires token)
    from blossom_ai import MessageBuilder
    
    messages = [
        MessageBuilder.image(
            role="user",
            text="Describe this image",
            image_url="https://example.com/photo.jpg"
        )
    ]
    
    analysis = client.text.chat(messages, model="openai")
    print(analysis)

# Automatic cleanup - no resource leaks!

📊 Why Blossom AI?

┌─────────────────────────────────────────────────────────────┐
│  ✓ CLI Interface for quick terminal access                 │
│  ✓ Vision & multimodal support (images + text)             │
│  ✓ HD image generation with advanced controls              │
│  ✓ Function calling and structured outputs                 │
│  ✓ Both sync and async support out of the box              │
│  ✓ Clean, modern Python with type hints                    │
│  ✓ Production-ready with comprehensive testing             │
│  ✓ Smart caching and optimization utilities                │
│  ✓ Secure: tokens in headers only, SSL enforced            │
│  ✓ Active development and community support                │
└─────────────────────────────────────────────────────────────┘

🎯 Choose Your Style

🖥️ CLI (Terminal) Perfect for: ✅ Quick testing ✅ Learning the API ✅ Shell automation ✅ No code required python -m blossom_ai.utils.cli \ --image "sunset" \ --output sunset.png

📚 Library (Python) Perfect for: ✅ Production apps ✅ Complex workflows ✅ Integration ✅ Advanced features from blossom_ai import Blossom with Blossom() as ai: ai.image.save("sunset", "sunset.png")

📚 Documentation

Resource	Description
📖 Getting Started	Complete guide to using Blossom AI
🖥️ CLI Interface	Terminal interface documentation
👁️ Vision Guide	Vision and multimodal features
🎨 Image Generation	HD images with advanced controls
💬 Text Generation	Advanced text generation features
⚙️ Installation	Setup and configuration
💡 Examples	Practical code examples
🌐 Web Apps	Build FastAPI/Flask applications
📝 Changelog	Version history and updates
🔒 Security	Security best practices

🌟 Showcase

🎨 Image Generation Examples

CLI:

# Quick generation
python -m blossom_ai.utils.cli --image "cyberpunk city" --output city.png

# HD quality with custom size
python -m blossom_ai.utils.cli \
  --image "mountain landscape" \
  --width 1920 \
  --height 1080 \
  --quality hd \
  --output landscape.png

Python:

# Simple and fast
with Blossom() as ai:
    ai.image.save("a cyberpunk city at night", "cyberpunk.jpg")
    ai.image.save("watercolor painting of mountains", "mountains.jpg")

# HD quality with advanced controls
with Blossom(api_token="token") as ai:
    image = ai.image.generate(
        "majestic dragon breathing fire",
        quality="hd",
        guidance_scale=7.5,
        negative_prompt="blurry, low quality, distorted",
        width=1920,
        height=1080,
        seed=42  # Reproducible results
    )

💬 Text Generation Examples

CLI:

# Quick text generation
python -m blossom_ai.utils.cli --text "Write a haiku about AI"

# With streaming for real-time output
python -m blossom_ai.utils.cli --text "Tell me a story" --stream

Python:

# Creative writing
story = ai.text.generate("Write a short sci-fi story about time travel")

# Code generation
code = ai.text.generate("Create a Python function to sort a list")

# Advanced controls
response = ai.text.generate(
    "Explain quantum computing for beginners",
    max_tokens=500,
    temperature=0.8,
    frequency_penalty=0.5,
    stream=True  # Real-time streaming
)

# Structured JSON output
json_data = ai.text.generate(
    "List 5 programming languages with their use cases",
    json_mode=True
)

👁️ Vision Analysis Examples (NEW!)

Python:

from blossom_ai import Blossom, MessageBuilder

with Blossom(api_token="token") as ai:
    # Analyze image from URL
    messages = [
        MessageBuilder.image(
            role="user",
            text="What's in this image? Describe in detail.",
            image_url="https://example.com/photo.jpg",
            detail="high"
        )
    ]
    
    analysis = ai.text.chat(messages, model="openai")
    print(analysis)
    
    # Analyze local image
    messages = [
        MessageBuilder.image(
            role="user",
            text="Identify the objects in this image",
            image_path="/path/to/image.jpg",
            detail="auto"
        )
    ]
    
    result = ai.text.chat(messages, model="openai")
    
    # Compare multiple images
    messages = [
        MessageBuilder.image(
            role="user",
            text="Compare these two images",
            image_url="https://example.com/image1.jpg"
        ),
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "And this second image:"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://example.com/image2.jpg",
                        "detail": "high"
                    }
                }
            ]
        }
    ]
    
    comparison = ai.text.chat(messages, model="openai")

🔧 Shell Automation Examples

#!/bin/bash

# Generate multiple images in parallel
for i in {1..5}; do
    python -m blossom_ai.utils.cli \
        --image "abstract art style $i" \
        --output "art_$i.png" &
done
wait

# Batch text processing
questions=(
    "What is AI?"
    "Explain machine learning"
    "What is deep learning?"
)

for q in "${questions[@]}"; do
    echo "Q: $q"
    python -m blossom_ai.utils.cli --text "$q"
    echo "---"
done

# Vision analysis pipeline
for img in *.jpg; do
    echo "Analyzing: $img"
    python -c "
from blossom_ai import Blossom, MessageBuilder
with Blossom(api_token='token') as ai:
    messages = [MessageBuilder.image('user', 'Describe', image_path='$img')]
    print(ai.text.chat(messages, model='openai'))
"
done

🛡️ Production Ready

Blossom AI v0.5.0 is battle-tested with:

✅ Vision Support: Analyze images with AI models
✅ HD Image Generation: Up to 2048x2048 with quality controls
✅ Advanced Text Features: Function calling, JSON mode, streaming
✅ CLI Interface: Quick terminal access for testing and automation
✅ Comprehensive Testing: Integration tests with VCR.py
✅ Memory Safe: No memory leaks in long-running applications
✅ Secure: Tokens only in headers, SSL verification enforced
✅ Fast: Optimized caching and connection pooling
✅ Reliable: Smart retry logic with exponential backoff

Quick Health Check

from blossom_ai import Blossom

def health_check():
    """Verify everything works"""
    try:
        with Blossom(api_token="token") as client:
            # Test image
            img = client.image.generate("test", width=256, height=256)
            assert len(img) > 1000
            
            # Test text
            txt = client.text.generate("Say hello", max_tokens=10)
            assert len(txt) > 0
            
            # Test vision
            from blossom_ai import MessageBuilder
            messages = [
                MessageBuilder.image(
                    "user",
                    "What's this?",
                    image_url="https://pollinations.ai/p/test"
                )
            ]
            vision = client.text.chat(messages, model="openai")
            assert len(vision) > 0
            
            print("✅ Health check passed!")
            return True
    except Exception as e:
        print(f"❌ Health check failed: {e}")
        return False

health_check()

🎨 Advanced Features

🧠 Reasoning Module Enhance prompts with structured thinking: from blossom_ai.utils import ReasoningEnhancer enhancer = ReasoningEnhancer() enhanced = enhancer.enhance( "Design a microservices architecture", level="high", mode="auto" )	⚡ Caching Module Cache responses for better performance: from blossom_ai.utils import cached @cached(ttl=3600) def generate_text(prompt): with Blossom() as ai: return ai.text.generate(prompt)
📁 File Reader Process files for AI prompts: from blossom_ai.utils import read_file_for_prompt content = read_file_for_prompt( "code.py", max_length=8000, truncate_if_needed=True )	🌐 Web Applications Build REST APIs with FastAPI/Flask: from fastapi import FastAPI app = FastAPI() @app.post("/generate") async def generate(prompt: str): async with Blossom() as ai: return await ai.text.generate(prompt)

📚 View Full Documentation →

🤝 Contributing

Contributions are what make the open-source community amazing! Any contributions you make are greatly appreciated.

1. Fork the Project
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

See CONTRIBUTING.md for detailed guidelines.

📄 License

Distributed under the MIT License. See LICENSE for more information.

💖 Support

If you find this project helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 📢 Sharing with others

---

Made with 🌸 and ❤️ by Eclips Team

⬆️ Back to top