webscout 8.2.7__py3-none-any.whl → 8.2.8__py3-none-any.whl

webscout/Provider/TTI/huggingface/async_huggingface.py

@@ -0,0 +1,199 @@
+"""
+AsyncHFimager - Your go-to async provider for generating fire images with HuggingFace! ⚡
+
+Examples:
+    >>> from webscout import AsyncHFimager
+    >>> import asyncio
+    >>> 
+    >>> async def example():
+    ...     # Initialize with your API key
+    ...     provider = AsyncHFimager(api_token="your-hf-token")
+    ...     
+    ...     # Generate a single image
+    ...     images = await provider.generate("A shiny red sports car")
+    ...     paths = await provider.save(images)
+    ...     
+    ...     # Generate multiple images with parameters
+    ...     images = await provider.generate(
+    ...         prompt="Epic dragon in cyberpunk city",
+    ...         amount=3,
+    ...         model="runwayml/stable-diffusion-v1-5",
+    ...         guidance_scale=7.5,
+    ...         negative_prompt="blurry, bad quality",
+    ...         num_inference_steps=50,
+    ...         width=768,
+    ...         height=768
+    ...     )
+    ...     paths = await provider.save(images, name="dragon", dir="outputs")
+    >>> 
+    >>> # Run the example
+    >>> asyncio.run(example())
+"""
+
+import os
+import aiohttp
+import aiofiles
+import asyncio
+from typing import Union, Any, List, Optional, Dict
+from webscout.AIbase import AsyncImageProvider
+from webscout.Litlogger import Logger, LogFormat
+from webscout.litagent import LitAgent
+
+# Initialize our fire logger and agent 🔥
+logger = Logger(
+    "AsyncHuggingFace",
+    format=LogFormat.MODERN_EMOJI,
+
+)
+agent = LitAgent()
+
+class AsyncHFimager(AsyncImageProvider):
+    """Your go-to async provider for generating fire images with HuggingFace! ⚡"""
+
+    def __init__(
+        self,
+        api_token: str = None,
+        timeout: int = 60,
+        proxies: dict = {},
+        logging: bool = True
+    ):
+        """Initialize your async HuggingFace provider with custom settings! ⚙️
+
+        Args:
+            api_token (str, optional): HuggingFace API token. Uses env var "HUGGINGFACE_API_TOKEN" if None
+            timeout (int): Request timeout in seconds (default: 60)
+            proxies (dict): Proxy settings for requests (default: {})
+            logging (bool): Enable fire logging (default: True)
+        """
+        self.base_url = "https://api-inference.huggingface.co/models/"
+        self.api_token = api_token or os.environ["HUGGINGFACE_API_TOKEN"]
+        self.headers = {
+            "Authorization": f"Bearer {self.api_token}",
+            "User-Agent": agent.random(),
+            "Accept": "application/json"
+        }
+        self.timeout = timeout
+        self.proxies = proxies
+        self.prompt: str = "AI-generated image - webscout"
+        self.image_extension: str = "jpg"
+        self.logging = logging
+        if self.logging:
+            logger.info("AsyncHuggingFace provider initialized! 🚀")
+
+    async def generate(
+        self,
+        prompt: str,
+        amount: int = 1,
+        model: str = "stabilityai/stable-diffusion-xl-base-1.0",
+        guidance_scale: Optional[float] = None,
+        negative_prompt: Optional[str] = None,
+        num_inference_steps: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        scheduler: Optional[str] = None,
+        seed: Optional[int] = None,
+    ) -> List[bytes]:
+        """Generate some fire images asynchronously! ⚡
+
+        Args:
+            prompt (str): Your lit image description
+            amount (int): How many images to generate (default: 1)
+            model (str): Which model to use (default: "stabilityai/stable-diffusion-xl-base-1.0")
+            guidance_scale (float, optional): Control how much to follow your prompt
+            negative_prompt (str, optional): What you don't want in the image
+            num_inference_steps (int, optional): More steps = better quality but slower
+            width (int, optional): Image width
+            height (int, optional): Image height
+            scheduler (str, optional): Which scheduler to use
+            seed (int, optional): Random seed for reproducibility
+
+        Returns:
+            List[bytes]: Your generated images as bytes
+        """
+        assert bool(prompt), "Yo fam, prompt can't be empty! 🚫"
+        assert isinstance(amount, int), f"Amount gotta be an integer, not {type(amount)} 🤔"
+        assert amount > 0, "Amount gotta be greater than 0! 📈"
+
+        self.prompt = prompt
+        response = []
+        if self.logging:
+            logger.info(f"Generating {amount} images with {model}... 🎨")
+
+        async with aiohttp.ClientSession(headers=self.headers) as session:
+            for _ in range(amount):
+                url = self.base_url + model
+                payload: Dict[str, Any] = {"inputs": prompt}
+                parameters = {}
+
+                if guidance_scale is not None:
+                    parameters["guidance_scale"] = guidance_scale
+                if negative_prompt is not None:
+                    parameters["negative_prompt"] = negative_prompt
+                if num_inference_steps is not None:
+                    parameters["num_inference_steps"] = num_inference_steps
+                if width is not None and height is not None:
+                    parameters["target_size"] = {"width": width, "height": height}
+                if scheduler is not None:
+                    parameters["scheduler"] = scheduler
+                if seed is not None:
+                    parameters["seed"] = seed
+
+                if parameters:
+                    payload["parameters"] = parameters
+
+                try:
+                    async with session.post(url, json=payload, timeout=self.timeout) as resp:
+                        resp.raise_for_status()
+                        response.append(await resp.read())
+                        if self.logging:
+                            logger.success("Image generated successfully! 🎉")
+                except aiohttp.ClientError as e:
+                    if self.logging:
+                        logger.error(f"Failed to generate image: {e} 😢")
+                    raise
+
+        return response
+
+    async def save(
+        self,
+        response: List[bytes],
+        name: str = None,
+        dir: str = os.getcwd(),
+        filenames_prefix: str = "",
+    ) -> List[str]:
+        """Save your fire images asynchronously! 💾
+
+        Args:
+            response (List[bytes]): Your generated images
+            name (str, optional): Custom name (default: uses prompt)
+            dir (str, optional): Where to save (default: current directory)
+            filenames_prefix (str, optional): Add prefix to filenames
+
+        Returns:
+            List[str]: Where your images were saved
+        """
+        assert isinstance(response, list), f"Response gotta be a list, not {type(response)} 🤔"
+        name = self.prompt if name is None else name
+
+        filenames = []
+        count = 0
+        if self.logging:
+            logger.info(f"Saving {len(response)} images... 💾")
+
+        for image_bytes in response:
+            def complete_path():
+                count_value = "" if count == 0 else f"_{count}"
+                return os.path.join(dir, name + count_value + "." + self.image_extension)
+
+            while os.path.isfile(complete_path()):
+                count += 1
+
+            absolute_path_to_file = complete_path()
+            filenames.append(filenames_prefix + os.path.split(absolute_path_to_file)[1])
+
+            async with aiofiles.open(absolute_path_to_file, "wb") as fh:
+                await fh.write(image_bytes)
+
+        if self.logging:
+            logger.success(f"Images saved successfully! Check {dir} 🎉")
+        return filenames

webscout/Provider/TTI/huggingface/sync_huggingface.py

@@ -0,0 +1,195 @@
+"""
+HFimager - Your go-to provider for generating fire images with HuggingFace! 🔥
+
+Examples:
+    >>> from webscout import HFimager
+    >>> 
+    >>> # Initialize with your API key
+    >>> provider = HFimager(api_token="your-hf-token")
+    >>> 
+    >>> # Generate a single image
+    >>> images = provider.generate("A shiny red sports car", model="stabilityai/stable-diffusion-xl-base-1.0")
+    >>> paths = provider.save(images)
+    >>> 
+    >>> # Generate multiple images with parameters
+    >>> images = provider.generate(
+    ...     prompt="Epic dragon in cyberpunk city",
+    ...     amount=3,
+    ...     model="runwayml/stable-diffusion-v1-5",
+    ...     guidance_scale=7.5,
+    ...     negative_prompt="blurry, bad quality",
+    ...     num_inference_steps=50,
+    ...     width=768,
+    ...     height=768
+    ... )
+    >>> paths = provider.save(images, name="dragon", dir="outputs")
+"""
+
+import os
+import requests
+import io
+from PIL import Image
+from typing import Union, Any, List, Optional, Dict
+from webscout.AIbase import ImageProvider
+from webscout.Litlogger import Logger, LogFormat
+from webscout.litagent import LitAgent
+
+# Initialize our fire logger and agent 🔥
+logger = Logger(
+    "HuggingFace",
+    format=LogFormat.MODERN_EMOJI,
+
+)
+agent = LitAgent()
+
+class HFimager(ImageProvider):
+    """Your go-to provider for generating fire images with HuggingFace! 🔥"""
+
+    def __init__(
+        self,
+        api_token: str = None,
+        timeout: int = 60,
+        proxies: dict = {},
+        logging: bool = True
+    ):
+        """Initialize your HuggingFace provider with custom settings! ⚙️
+
+        Args:
+            api_token (str, optional): HuggingFace API token. Uses env var "HUGGINGFACE_API_TOKEN" if None
+            timeout (int): Request timeout in seconds (default: 60)
+            proxies (dict): Proxy settings for requests (default: {})
+            logging (bool): Enable fire logging (default: True)
+        """
+        self.base_url = "https://api-inference.huggingface.co/models/"
+        self.api_token = api_token or os.environ["HUGGINGFACE_API_TOKEN"]
+        self.headers = {
+            "Authorization": f"Bearer {self.api_token}",
+            "User-Agent": agent.random(),
+            "Accept": "application/json"
+        }
+        self.session = requests.Session()
+        self.session.headers.update(self.headers)
+        self.session.proxies.update(proxies)
+        self.timeout = timeout
+        self.prompt: str = "AI-generated image - webscout"
+        self.image_extension: str = "jpg"
+        self.logging = logging
+        if self.logging:
+            logger.info("HuggingFace provider initialized! 🚀")
+
+    def generate(
+        self,
+        prompt: str,
+        amount: int = 1,
+        model: str = "stabilityai/stable-diffusion-xl-base-1.0",
+        guidance_scale: Optional[float] = None,
+        negative_prompt: Optional[str] = None,
+        num_inference_steps: Optional[int] = None,
+        width: Optional[int] = None,
+        height: Optional[int] = None,
+        scheduler: Optional[str] = None,
+        seed: Optional[int] = None,
+    ) -> List[bytes]:
+        """Generate some fire images! 🎨
+
+        Args:
+            prompt (str): Your lit image description
+            amount (int): How many images to generate (default: 1)
+            model (str): Which model to use (default: "stabilityai/stable-diffusion-xl-base-1.0")
+            guidance_scale (float, optional): Control how much to follow your prompt
+            negative_prompt (str, optional): What you don't want in the image
+            num_inference_steps (int, optional): More steps = better quality but slower
+            width (int, optional): Image width
+            height (int, optional): Image height
+            scheduler (str, optional): Which scheduler to use
+            seed (int, optional): Random seed for reproducibility
+
+        Returns:
+            List[bytes]: Your generated images as bytes
+        """
+        assert bool(prompt), "Yo fam, prompt can't be empty! 🚫"
+        assert isinstance(amount, int), f"Amount gotta be an integer, not {type(amount)} 🤔"
+        assert amount > 0, "Amount gotta be greater than 0! 📈"
+
+        self.prompt = prompt
+        response = []
+        if self.logging:
+            logger.info(f"Generating {amount} images with {model}... 🎨")
+
+        for _ in range(amount):
+            url = self.base_url + model
+            payload: Dict[str, Any] = {"inputs": prompt}
+            parameters = {}
+
+            if guidance_scale is not None:
+                parameters["guidance_scale"] = guidance_scale
+            if negative_prompt is not None:
+                parameters["negative_prompt"] = negative_prompt
+            if num_inference_steps is not None:
+                parameters["num_inference_steps"] = num_inference_steps
+            if width is not None and height is not None:
+                parameters["target_size"] = {"width": width, "height": height}
+            if scheduler is not None:
+                parameters["scheduler"] = scheduler
+            if seed is not None:
+                parameters["seed"] = seed
+
+            if parameters:
+                payload["parameters"] = parameters
+
+            try:
+                resp = self.session.post(url, headers=self.headers, json=payload, timeout=self.timeout)
+                resp.raise_for_status()
+                response.append(resp.content)
+                if self.logging:
+                    logger.success("Image generated successfully! 🎉")
+            except requests.RequestException as e:
+                if self.logging:
+                    logger.error(f"Failed to generate image: {e} 😢")
+                raise
+
+        return response
+
+    def save(
+        self,
+        response: List[bytes],
+        name: str = None,
+        dir: str = os.getcwd(),
+        filenames_prefix: str = "",
+    ) -> List[str]:
+        """Save your fire images! 💾
+
+        Args:
+            response (List[bytes]): Your generated images
+            name (str, optional): Custom name (default: uses prompt)
+            dir (str, optional): Where to save (default: current directory)
+            filenames_prefix (str, optional): Add prefix to filenames
+
+        Returns:
+            List[str]: Where your images were saved
+        """
+        assert isinstance(response, list), f"Response gotta be a list, not {type(response)} 🤔"
+        name = self.prompt if name is None else name
+
+        filenames = []
+        count = 0
+        if self.logging:
+            logger.info(f"Saving {len(response)} images... 💾")
+
+        for image_bytes in response:
+            def complete_path():
+                count_value = "" if count == 0 else f"_{count}"
+                return os.path.join(dir, name + count_value + "." + self.image_extension)
+
+            while os.path.isfile(complete_path()):
+                count += 1
+
+            absolute_path_to_file = complete_path()
+            filenames.append(filenames_prefix + os.path.split(absolute_path_to_file)[1])
+
+            with open(absolute_path_to_file, "wb") as fh:
+                fh.write(image_bytes)
+
+        if self.logging:
+            logger.success(f"Images saved successfully! Check {dir} 🎉")
+        return filenames

webscout/Provider/TTI/piclumen/README.md

@@ -0,0 +1,161 @@
+# 🎨 PiclumenImager - Professional AI Image Generation
+
+Welcome to PiclumenImager - a powerful provider for creating high-quality AI-generated images.
+
+## ✨ Features
+
+- Professional-grade image generation with photorealistic outputs
+- Synchronous and asynchronous operation support
+- Robust error handling and retry mechanisms
+- Dynamic user agent management
+- Configurable proxy support
+- Customizable timeouts and retry settings
+- Smart error recovery system
+
+## 📦 Installation
+
+```bash
+pip install webscout
+```
+
+## 📘 Usage Guide
+
+### Synchronous Usage (PiclumenImager)
+
+```python
+from webscout import PiclumenImager
+
+# Basic initialization
+imager = PiclumenImager()
+
+# Generate a single image
+images = imager.generate("Dragon in flight over mountain peaks")
+paths = imager.save(images)
+print(f"Image saved to: {paths[0]}")
+
+# Generate multiple images with retry configuration
+images = imager.generate(
+    "Bioluminescent deep sea creature in natural habitat",
+    amount=3,
+    max_retries=5,
+    retry_delay=3
+)
+paths = imager.save(images)
+print(f"Images saved to: {paths}")
+
+# Configure with custom settings
+custom_imager = PiclumenImager(timeout=180)
+images = custom_imager.generate("Abstract architectural concept")
+paths = custom_imager.save(images)
+```
+
+### Asynchronous Usage (AsyncPiclumenImager)
+
+```python
+from webscout import AsyncPiclumenImager
+import asyncio
+
+async def generate_images():
+    imager = AsyncPiclumenImager()
+    
+    # Generate multiple images concurrently
+    images = await imager.generate(
+        "Architectural visualization of modern building",
+        amount=2,
+        max_retries=3,
+        retry_delay=5
+    )
+    paths = await imager.save(images)
+    print(f"Generated images: {paths}")
+
+    # Custom save configuration
+    images = await imager.generate("Modern art composition")
+    paths = await imager.save(
+        images, 
+        dir="artwork",
+        filenames_prefix="modern_"
+    )
+
+# Execute the async function
+asyncio.run(generate_images())
+```
+
+### Advanced Configuration
+
+```python
+# Initialize with proxy and extended timeout
+imager = PiclumenImager(
+    timeout=180,
+    proxies={
+        'http': 'http://proxy.example.com:8000',
+        'https': 'http://proxy.example.com:8000'
+    }
+)
+
+# Advanced image generation with custom settings
+images = imager.generate(
+    "Professional product photography of luxury watch",
+    max_retries=5,
+    retry_delay=3
+)
+paths = imager.save(
+    images,
+    name="product_photo",
+    dir="product_images",
+    filenames_prefix="watch_"
+)
+```
+
+## ⚡ Error Handling
+
+Comprehensive error handling implementation:
+
+```python
+try:
+    images = imager.generate("Product photography")
+    paths = imager.save(images)
+except requests.exceptions.RequestException as e:
+    print(f"Network error: {e}")
+except ValueError as e:
+    print(f"Invalid parameter: {e}")
+except Exception as e:
+    print(f"Unexpected error: {e}")
+```
+
+## 🎯 Image Quality Specializations
+
+PiclumenImager excels in generating:
+
+- Photorealistic images with accurate lighting and shadows
+- Detailed textures and material representations
+- Complex underwater and nature scenes
+- Architectural and product visualizations
+- Macro photography simulations
+
+## 🔒 Security Considerations
+
+- Implement proxy configuration for enhanced privacy
+- Use secure network connections
+- Follow API rate limiting guidelines
+- Handle sensitive data appropriately
+- Monitor and log API usage when needed
+
+## 💡 Optimization Tips
+
+For optimal results:
+
+1. Provide detailed, specific prompts
+2. Include lighting and environment details
+3. Reference professional photography styles
+4. Specify desired color schemes
+5. Adjust timeouts for complex generations
+6. Use appropriate retry settings for reliability
+
+## 📚 Technical Notes
+
+- Default timeout: 120 seconds
+- Maximum retries: 3 (configurable)
+- Supports JPEG image format
+- Implements automatic error recovery
+- Handles concurrent image generation
+- Supports both sync and async workflows

webscout/Provider/TTI/piclumen/__init__.py

@@ -0,0 +1,23 @@
+"""PiclumenImager Provider Package - Your go-to for high-quality AI art! 🎨
+
+Examples:
+    >>> # Synchronous usage
+    >>> from webscout import PiclumenImager
+    >>> provider = PiclumenImager()
+    >>> images = provider.generate("A cool underwater creature")
+    >>> provider.save(images, dir="my_images")
+    >>> 
+    >>> # Asynchronous usage
+    >>> import asyncio
+    >>> from webscout import AsyncPiclumenImager
+    >>> async def main():
+    ...     provider = AsyncPiclumenImager()
+    ...     images = await provider.generate("A cool cyberpunk city")
+    ...     await provider.save(images, dir="my_images")
+    >>> asyncio.run(main())
+"""
+
+from .sync_piclumen import PiclumenImager
+from .async_piclumen import AsyncPiclumenImager
+
+__all__ = ["PiclumenImager", "AsyncPiclumenImager"]