viscribe 1.0.1__py3-none-any.whl

viscribe/__init__.py

@@ -0,0 +1,4 @@
+from .async_client import AsyncClient
+from .client import Client
+
+__all__ = ["Client", "AsyncClient"]

viscribe/async_client.py

@@ -0,0 +1,316 @@
+import asyncio
+from typing import Any, Optional, Type, Union
+
+from aiohttp import ClientSession, ClientTimeout, TCPConnector
+from aiohttp.client_exceptions import ClientError
+from pydantic import BaseModel
+
+from viscribe.config import API_BASE_URL, DEFAULT_HEADERS
+from viscribe.exceptions import APIError
+from viscribe.logger import viscribe_logger as logger
+from viscribe.models.image import (
+    CreditsResponse,
+    ExtractField,
+    FeedbackRequest,
+    FeedbackResponse,
+    ImageAskRequest,
+    ImageAskResponse,
+    ImageClassifyRequest,
+    ImageClassifyResponse,
+    ImageCompareRequest,
+    ImageCompareResponse,
+    ImageDescribeRequest,
+    ImageDescribeResponse,
+    ImageExtractRequest,
+    ImageExtractResponse,
+)
+from viscribe.utils.helpers import handle_async_response, validate_api_key
+
+
+class AsyncClient:
+    @classmethod
+    def from_env(
+        cls,
+        verify_ssl: bool = True,
+        timeout: Optional[float] = None,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        """Initialize AsyncClient using API key from environment variable.
+
+        Args:
+            verify_ssl: Whether to verify SSL certificates
+            timeout: Request timeout in seconds. None means no timeout (infinite)
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+        """
+        from os import getenv
+
+        api_key = getenv("VISCRIBE_API_KEY")
+        if not api_key:
+            raise ValueError("VISCRIBE_API_KEY environment variable not set")
+        return cls(
+            api_key=api_key,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+
+    def __init__(
+        self,
+        api_key: str = None,
+        verify_ssl: bool = True,
+        timeout: Optional[float] = None,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        """Initialize AsyncClient with configurable parameters.
+
+        Args:
+            api_key: API key for authentication. If None, will try to load from environment
+            verify_ssl: Whether to verify SSL certificates
+            timeout: Request timeout in seconds. None means no timeout (infinite)
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+        """
+        logger.info("🔑 Initializing AsyncClient")
+
+        # Try to get API key from environment if not provided
+        if api_key is None:
+            from os import getenv
+
+            api_key = getenv("VISCRIBE_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "VISCRIBE_API_KEY not provided and not found in environment"
+                )
+
+        validate_api_key(api_key)
+        logger.debug(
+            f"🛠️ Configuration: verify_ssl={verify_ssl}, timeout={timeout}, max_retries={max_retries}"
+        )
+        self.api_key = api_key
+        self.headers = {**DEFAULT_HEADERS, "VISCRIBE-APIKEY": api_key}
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        ssl = None if verify_ssl else False
+        self.timeout = ClientTimeout(total=timeout) if timeout is not None else None
+
+        self.session = ClientSession(
+            headers=self.headers, connector=TCPConnector(ssl=ssl), timeout=self.timeout
+        )
+
+        logger.info("✅ AsyncClient initialized successfully")
+
+    async def _make_request(self, method: str, url: str, **kwargs) -> Any:
+        """Make HTTP request with retry logic."""
+        for attempt in range(self.max_retries):
+            try:
+                logger.info(
+                    f"🚀 Making {method} request to {url} (Attempt {attempt + 1}/{self.max_retries})"
+                )
+                logger.debug(f"🔍 Request parameters: {kwargs}")
+
+                async with self.session.request(method, url, **kwargs) as response:
+                    logger.debug(f"📥 Response status: {response.status}")
+                    result = await handle_async_response(response)
+                    logger.info(f"✅ Request completed successfully: {method} {url}")
+                    return result
+
+            except ClientError as e:
+                logger.warning(f"⚠️ Request attempt {attempt + 1} failed: {str(e)}")
+                if hasattr(e, "status") and e.status is not None:
+                    try:
+                        error_data = await e.response.json()
+                        error_msg = error_data.get("error", str(e))
+                        logger.error(f"🔴 API Error: {error_msg}")
+                        raise APIError(error_msg, status_code=e.status)
+                    except ValueError:
+                        logger.error("🔴 Could not parse error response")
+                        raise APIError(
+                            str(e),
+                            status_code=e.status if hasattr(e, "status") else None,
+                        )
+
+                if attempt == self.max_retries - 1:
+                    logger.error(f"❌ All retry attempts failed for {method} {url}")
+                    raise ConnectionError(f"Failed to connect to API: {str(e)}")
+
+                retry_delay = self.retry_delay * (attempt + 1)
+                logger.info(f"⏳ Waiting {retry_delay}s before retry {attempt + 2}")
+                await asyncio.sleep(retry_delay)
+
+    async def submit_feedback(self, request_id: str, rating: int, feedback_text: Optional[str] = None) -> FeedbackResponse:
+        """Submit feedback for a request"""
+        logger.info(f"📝 Submitting feedback for request {request_id}")
+        feedback = FeedbackRequest(
+            request_id=request_id, rating=rating, feedback_text=feedback_text
+        )
+        payload = feedback.model_dump(exclude_none=True)
+        result = await self._make_request("POST", f"{API_BASE_URL}/feedback", json=payload)
+        return FeedbackResponse(**result)
+
+    async def get_credits(self) -> CreditsResponse:
+        """Get credits information"""
+        logger.info("💳 Fetching credits information")
+        result = await self._make_request("GET", f"{API_BASE_URL}/credits")
+        return CreditsResponse(**result)
+
+    async def close(self):
+        """Close the session to free up resources"""
+        logger.info("🔒 Closing AsyncClient session")
+        await self.session.close()
+        logger.debug("✅ Session closed successfully")
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def describe_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        instruction: str = None,
+        generate_tags: bool = True,
+    ) -> ImageDescribeResponse:
+        """Send a describe image request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image describe request")
+
+        req = ImageDescribeRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            instruction=instruction,
+            generate_tags=generate_tags,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = await self._make_request(
+            "POST", f"{API_BASE_URL}/images/describe", json=payload
+        )
+        return ImageDescribeResponse(**result)
+
+    async def extract_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        fields: list = None,
+        advanced_schema: Union[dict, BaseModel, Type[BaseModel]] = None,
+        instruction: str = None,
+    ) -> ImageExtractResponse:
+        """Send an extract structured data from image request with explicit arguments and validate with Pydantic.
+        
+        Args:
+            image_url: URL of the image
+            image_base64: Base64 encoded string of the image
+            fields: List of dictionaries with 'name', 'type', and optional 'description' keys.
+                   Each field type can be 'text', 'number', 'array_text' (max 5), or 'array_number' (max 5).
+                   Max 10 fields allowed.
+            advanced_schema: Full JSON schema for complex extraction (dict), a Pydantic BaseModel instance,
+                           or a Pydantic BaseModel class. If a BaseModel is provided, it will be serialized
+                           to its JSON schema. Use this for nested structures.
+            instruction: Optional instruction to guide the extraction process.
+        
+        Note: Either fields or advanced_schema must be provided, not both.
+        """
+        logger.info("🔍 Starting image extract request")
+
+        # Convert dictionaries to ExtractField models if fields are provided
+        validated_fields = None
+        if fields is not None:
+            validated_fields = [ExtractField(**field) if isinstance(field, dict) else field for field in fields]
+
+        # Convert Pydantic BaseModel to JSON schema if advanced_schema is a BaseModel
+        validated_schema = advanced_schema
+        if advanced_schema is not None:
+            if isinstance(advanced_schema, BaseModel):
+                # BaseModel instance
+                validated_schema = advanced_schema.model_json_schema()
+            elif isinstance(advanced_schema, type) and issubclass(advanced_schema, BaseModel):
+                # BaseModel class
+                validated_schema = advanced_schema.model_json_schema()
+
+        req = ImageExtractRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            fields=validated_fields,
+            advanced_schema=validated_schema,
+            instruction=instruction,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = await self._make_request(
+            "POST", f"{API_BASE_URL}/images/extract", json=payload
+        )
+        return ImageExtractResponse(**result)
+
+    async def classify_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        classes: list = None,
+        class_descriptions: dict = None,
+        instruction: str = None,
+        multi_label: bool = False,
+    ) -> ImageClassifyResponse:
+        """Send an image classify request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image classify request")
+
+        req = ImageClassifyRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            classes=classes,
+            class_descriptions=class_descriptions,
+            instruction=instruction,
+            multi_label=multi_label,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = await self._make_request(
+            "POST", f"{API_BASE_URL}/images/classify", json=payload
+        )
+        return ImageClassifyResponse(**result)
+
+    async def ask_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        question: str = None,
+    ) -> ImageAskResponse:
+        """Send an image VQA (ask) request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image ask (VQA) request")
+
+        req = ImageAskRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            question=question,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = await self._make_request("POST", f"{API_BASE_URL}/images/ask", json=payload)
+        return ImageAskResponse(**result)
+
+    async def compare_images(
+        self,
+        image1_url: str = None,
+        image1_base64: str = None,
+        image2_url: str = None,
+        image2_base64: str = None,
+        instruction: str = None,
+    ) -> ImageCompareResponse:
+        """Send an image compare request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image compare request")
+
+        req = ImageCompareRequest(
+            image1_url=image1_url,
+            image1_base64=image1_base64,
+            image2_url=image2_url,
+            image2_base64=image2_base64,
+            instruction=instruction,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = await self._make_request(
+            "POST", f"{API_BASE_URL}/images/compare", json=payload
+        )
+        return ImageCompareResponse(**result)
+
+

viscribe/client.py

@@ -0,0 +1,327 @@
+# Client implementation goes here
+from typing import Any, Optional, Type, Union
+
+import requests
+import urllib3
+from pydantic import BaseModel
+from requests.exceptions import RequestException
+
+from viscribe.config import API_BASE_URL, DEFAULT_HEADERS
+from viscribe.exceptions import APIError
+from viscribe.logger import viscribe_logger as logger
+from viscribe.models.image import CreditsResponse, FeedbackRequest, FeedbackResponse
+from viscribe.models.image import (
+    ExtractField,
+    ImageDescribeRequest,
+    ImageDescribeResponse,
+    ImageExtractRequest,
+    ImageExtractResponse,
+    ImageClassifyRequest,
+    ImageClassifyResponse,
+    ImageAskRequest,
+    ImageAskResponse,
+    ImageCompareRequest, ImageCompareResponse
+)
+from viscribe.utils.helpers import handle_sync_response, validate_api_key
+
+
+class Client:
+    @classmethod
+    def from_env(
+        cls,
+        verify_ssl: bool = True,
+        timeout: Optional[float] = None,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        """Initialize Client using API key from environment variable.
+
+        Args:
+            verify_ssl: Whether to verify SSL certificates
+            timeout: Request timeout in seconds. None means no timeout (infinite)
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+        """
+        from os import getenv
+
+        api_key = getenv("VISCRIBE_API_KEY")
+        if not api_key:
+            raise ValueError("VISCRIBE_API_KEY environment variable not set")
+        return cls(
+            api_key=api_key,
+            verify_ssl=verify_ssl,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_delay=retry_delay,
+        )
+
+    def __init__(
+        self,
+        api_key: str = None,
+        verify_ssl: bool = True,
+        timeout: Optional[float] = None,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        """Initialize Client with configurable parameters.
+
+        Args:
+            api_key: API key for authentication. If None, will try to load from environment
+            verify_ssl: Whether to verify SSL certificates
+            timeout: Request timeout in seconds. None means no timeout (infinite)
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+        """
+        logger.info("🔑 Initializing Client")
+
+        # Try to get API key from environment if not provided
+        if api_key is None:
+            from os import getenv
+
+            api_key = getenv("VISCRIBE_API_KEY")
+            if not api_key:
+                raise ValueError(
+                    "VISCRIBE_API_KEY not provided and not found in environment"
+                )
+
+        validate_api_key(api_key)
+        logger.debug(
+            f"🛠️ Configuration: verify_ssl={verify_ssl}, timeout={timeout}, max_retries={max_retries}"
+        )
+
+        self.api_key = api_key
+        self.headers = {**DEFAULT_HEADERS, "VISCRIBE-APIKEY": api_key}
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        # Create a session for connection pooling
+        self.session = requests.Session()
+        self.session.headers.update(self.headers)
+        self.session.verify = verify_ssl
+
+        # Configure retries
+        adapter = requests.adapters.HTTPAdapter(
+            max_retries=requests.urllib3.Retry(
+                total=max_retries,
+                backoff_factor=retry_delay,
+                status_forcelist=[500, 502, 503, 504],
+            )
+        )
+        self.session.mount("http://", adapter)
+        self.session.mount("https://", adapter)
+
+        # Add warning suppression if verify_ssl is False
+        if not verify_ssl:
+            urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+        logger.info("✅ Client initialized successfully")
+
+    def _make_request(self, method: str, url: str, **kwargs) -> Any:
+        """Make HTTP request with error handling."""
+        try:
+            logger.info(f"🚀 Making {method} request to {url}")
+            logger.debug(f"🔍 Request parameters: {kwargs}")
+
+            response = self.session.request(method, url, timeout=self.timeout, **kwargs)
+            logger.debug(f"📥 Response status: {response.status_code}")
+
+            result = handle_sync_response(response)
+            logger.info(f"✅ Request completed successfully: {method} {url}")
+            return result
+
+        except RequestException as e:
+            logger.error(f"❌ Request failed: {str(e)}")
+            if hasattr(e, "response") and e.response is not None:
+                try:
+                    error_data = e.response.json()
+                    error_msg = error_data.get("error", str(e))
+                    logger.error(f"🔴 API Error: {error_msg}")
+                    raise APIError(error_msg, status_code=e.response.status_code)
+                except ValueError:
+                    logger.error("🔴 Could not parse error response")
+                    raise APIError(
+                        str(e),
+                        status_code=(
+                            e.response.status_code
+                            if hasattr(e.response, "status_code")
+                            else None
+                        ),
+                    )
+            logger.error(f"🔴 Connection Error: {str(e)}")
+            raise ConnectionError(f"Failed to connect to API: {str(e)}")
+
+    def submit_feedback(self, request_id: str, rating: int, feedback_text: Optional[str] = None) -> FeedbackResponse:
+        """Submit feedback for a request"""
+        logger.info(f"📝 Submitting feedback for request {request_id}")
+        request = FeedbackRequest(
+            request_id=request_id,
+            rating=rating,
+            feedback_text=feedback_text,
+        )
+        payload = request.model_dump(exclude_none=True)
+        result = self._make_request(
+            "POST", f"{API_BASE_URL}/feedback", json=payload
+        )
+        return FeedbackResponse(**result)
+
+    def get_credits(self) -> CreditsResponse:
+        """Get credits information"""
+        logger.info("💳 Fetching credits information")
+        result = self._make_request("GET", f"{API_BASE_URL}/credits")
+        return CreditsResponse(**result)
+
+    def describe_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        instruction: str = None,
+        generate_tags: bool = True,
+    ):
+        """Send a describe image request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image describe request")
+
+        req = ImageDescribeRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            instruction=instruction,
+            generate_tags=generate_tags,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = self._make_request(
+            "POST", f"{API_BASE_URL}/images/describe", json=payload
+        )
+        return ImageDescribeResponse(**result)
+
+    def extract_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        fields: list = None,
+        advanced_schema: Union[dict, BaseModel, Type[BaseModel]] = None,
+        instruction: str = None,
+    ):
+        """Send an extract structured data from image request with explicit arguments and validate with Pydantic.
+        
+        Args:
+            image_url: URL of the image
+            image_base64: Base64 encoded string of the image
+            fields: List of dictionaries with 'name', 'type', and optional 'description' keys.
+                   Each field type can be 'text', 'number', 'array_text' (max 5), or 'array_number' (max 5).
+                   Max 10 fields allowed.
+            advanced_schema: Full JSON schema for complex extraction (dict), a Pydantic BaseModel instance,
+                           or a Pydantic BaseModel class. If a BaseModel is provided, it will be serialized
+                           to its JSON schema. Use this for nested structures.
+            instruction: Optional instruction to guide the extraction process.
+        
+        Note: Either fields or advanced_schema must be provided, not both.
+        """
+        logger.info("🔍 Starting image extract request")
+
+        # Convert dictionaries to ExtractField models if fields are provided
+        validated_fields = None
+        if fields is not None:
+            validated_fields = [ExtractField(**field) if isinstance(field, dict) else field for field in fields]
+
+        # Convert Pydantic BaseModel to JSON schema if advanced_schema is a BaseModel
+        validated_schema = advanced_schema
+        if advanced_schema is not None:
+            if isinstance(advanced_schema, BaseModel):
+                # BaseModel instance
+                validated_schema = advanced_schema.model_json_schema()
+            elif isinstance(advanced_schema, type) and issubclass(advanced_schema, BaseModel):
+                # BaseModel class
+                validated_schema = advanced_schema.model_json_schema()
+
+        req = ImageExtractRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            fields=validated_fields,
+            advanced_schema=validated_schema,
+            instruction=instruction,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = self._make_request(
+            "POST", f"{API_BASE_URL}/images/extract", json=payload
+        )
+        return ImageExtractResponse(**result)
+
+    def classify_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        classes: list = None,
+        class_descriptions: dict = None,
+        instruction: str = None,
+        multi_label: bool = False,
+    ):
+        """Send an image classify request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image classify request")
+
+        req = ImageClassifyRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            classes=classes,
+            class_descriptions=class_descriptions,
+            instruction=instruction,
+            multi_label=multi_label,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = self._make_request(
+            "POST", f"{API_BASE_URL}/images/classify", json=payload
+        )
+        return ImageClassifyResponse(**result)
+
+    def ask_image(
+        self,
+        image_url: str = None,
+        image_base64: str = None,
+        question: str = None,
+    ):
+        """Send an image VQA (ask) request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image ask (VQA) request")
+
+        req = ImageAskRequest(
+            image_url=image_url,
+            image_base64=image_base64,
+            question=question,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = self._make_request("POST", f"{API_BASE_URL}/images/ask", json=payload)
+        return ImageAskResponse(**result)
+
+    def compare_images(
+        self,
+        image1_url: str = None,
+        image1_base64: str = None,
+        image2_url: str = None,
+        image2_base64: str = None,
+        instruction: str = None,
+    ):
+        """Send an image compare request with explicit arguments and validate with Pydantic."""
+        logger.info("🔍 Starting image compare request")
+
+        req = ImageCompareRequest(
+            image1_url=image1_url,
+            image1_base64=image1_base64,
+            image2_url=image2_url,
+            image2_base64=image2_base64,
+            instruction=instruction,
+        )
+        payload = req.model_dump(exclude_none=True)
+        result = self._make_request(
+            "POST", f"{API_BASE_URL}/images/compare", json=payload
+        )
+        return ImageCompareResponse(**result)
+
+    def close(self):
+        """Close the session to free up resources"""
+        logger.info("🔒 Closing Client session")
+        self.session.close()
+        logger.debug("✅ Session closed successfully")
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

viscribe/config.py

@@ -0,0 +1,6 @@
+# Configuration and constants
+API_BASE_URL = "https://api.viscribe.ai/v1"
+DEFAULT_HEADERS = {
+    "accept": "application/json",
+    "Content-Type": "application/json",
+}

viscribe/exceptions.py

@@ -0,0 +1,7 @@
+class APIError(Exception):
+    """Base exception for API errors."""
+
+    def __init__(self, message: str, status_code: int = None):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"[{status_code}] {message}")

viscribe/logger.py

@@ -0,0 +1,119 @@
+import logging
+import logging.handlers
+from typing import Dict, Optional
+
+# Emoji mappings for different log levels
+LOG_EMOJIS: Dict[int, str] = {
+    logging.DEBUG: "🐛",
+    logging.INFO: "💬",
+    logging.WARNING: "⚠️",
+    logging.ERROR: "❌",
+    logging.CRITICAL: "🚨",
+}
+
+
+class EmojiFormatter(logging.Formatter):
+    """Custom formatter that adds emojis to log messages"""
+
+    def format(self, record: logging.LogRecord) -> str:
+        # Add emoji based on log level
+        emoji = LOG_EMOJIS.get(record.levelno, "")
+        record.emoji = emoji
+        return super().format(record)
+
+
+class ViscribeLogger:
+    """Class to manage Viscribe logging configuration"""
+
+    _instance = None
+    _initialized = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(ViscribeLogger, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not self._initialized:
+            self.logger = logging.getLogger("viscribe")
+            self.logger.setLevel(logging.INFO)
+            self.enabled = False
+            self._initialized = True
+
+    def set_logging(
+        self,
+        level: Optional[str] = None,
+        log_file: Optional[str] = None,
+        log_format: Optional[str] = None,
+    ) -> None:
+        """
+        Configure logging settings. If level is None, logging will be disabled.
+
+        Args:
+            level: Logging level (e.g., 'DEBUG', 'INFO'). None to disable logging.
+            log_file: Optional file path to write logs to
+            log_format: Optional custom log format string
+        """
+        # Clear existing handlers
+        self.logger.handlers.clear()
+
+        if level is None:
+            # Disable logging
+            self.enabled = False
+            return
+
+        # Enable logging with specified level
+        self.enabled = True
+        level = getattr(logging, level.upper(), logging.INFO)
+        self.logger.setLevel(level)
+
+        # Default format if none provided
+        if not log_format:
+            log_format = "%(emoji)s %(asctime)-15s %(message)s"
+
+        formatter = EmojiFormatter(log_format)
+
+        # Console handler
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(formatter)
+        self.logger.addHandler(console_handler)
+
+        # File handler if log_file specified
+        if log_file:
+            file_handler = logging.FileHandler(log_file)
+            file_handler.setFormatter(formatter)
+            self.logger.addHandler(file_handler)
+
+    def disable(self) -> None:
+        """Disable all logging"""
+        self.logger.handlers.clear()
+        self.enabled = False
+
+    def debug(self, message: str) -> None:
+        """Log debug message if logging is enabled"""
+        if self.enabled:
+            self.logger.debug(message)
+
+    def info(self, message: str) -> None:
+        """Log info message if logging is enabled"""
+        if self.enabled:
+            self.logger.info(message)
+
+    def warning(self, message: str) -> None:
+        """Log warning message if logging is enabled"""
+        if self.enabled:
+            self.logger.warning(message)
+
+    def error(self, message: str) -> None:
+        """Log error message if logging is enabled"""
+        if self.enabled:
+            self.logger.error(message)
+
+    def critical(self, message: str) -> None:
+        """Log critical message if logging is enabled"""
+        if self.enabled:
+            self.logger.critical(message)
+
+
+# Default logger instance
+viscribe_logger = ViscribeLogger()

viscribe/models/__init__.py

@@ -0,0 +1,16 @@
+from .image import (
+    CreditsResponse,
+    ExtractField,
+    FeedbackRequest,
+    FeedbackResponse,
+    ImageAskRequest,
+    ImageAskResponse,
+    ImageClassifyRequest,
+    ImageClassifyResponse,
+    ImageCompareRequest,
+    ImageCompareResponse,
+    ImageDescribeRequest,
+    ImageDescribeResponse,
+    ImageExtractRequest,
+    ImageExtractResponse,
+)

viscribe/models/image.py

@@ -0,0 +1,188 @@
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+from viscribe.utils.helpers import validate_base64_image, validate_url_format
+
+# 1. Image Endpoints
+
+
+class ImageSourceBase(BaseModel):
+    image_url: Optional[str] = Field(default=None, description="URL of the image.")
+    image_base64: Optional[str] = Field(
+        default=None, description="Base64 encoded string of the image."
+    )
+
+    @model_validator(mode="before")
+    @classmethod
+    def check_image_source(cls, values):
+        """Ensure exactly one image source is provided and validate formats."""
+        url = values.get("image_url")
+        b64 = values.get("image_base64")
+
+        if not url and not b64:
+            raise ValueError("Either image_url or image_base64 must be provided.")
+        if url and b64:
+            raise ValueError("Provide either image_url or image_base64, not both.")
+
+        # Validate URL format if provided
+        if url:
+            try:
+                validate_url_format(url)
+            except ValueError as e:
+                raise ValueError(f"Invalid image_url: {str(e)}")
+
+        # Validate base64 format if provided
+        if b64:
+            try:
+                validate_base64_image(b64)
+            except ValueError as e:
+                raise ValueError(f"Invalid image_base64: {str(e)}")
+
+        return values
+
+
+class ImageDescribeRequest(ImageSourceBase):
+    instruction: Optional[str] = None
+    generate_tags: bool = True
+
+
+class ImageDescribeResponse(BaseModel):
+    request_id: str
+    credits_used: int
+    image_description: str
+    tags: Optional[List[str]] = None
+
+
+class ExtractField(BaseModel):
+    """Simple field definition for extraction."""
+
+    name: str = Field(..., description="Field name")
+    type: str = Field(
+        ..., description="Field type: 'text', 'number', 'array_text', or 'array_number'"
+    )
+    description: Optional[str] = Field(
+        None, description="Optional description to guide extraction"
+    )
+
+    @field_validator("type")
+    @classmethod
+    def validate_type(cls, v):
+        valid_types = ["text", "number", "array_text", "array_number"]
+        if v not in valid_types:
+            raise ValueError(f"type must be one of {valid_types}")
+        return v
+
+
+class ImageExtractRequest(ImageSourceBase):
+    fields: Optional[List[ExtractField]] = Field(
+        default=None,
+        description="Simple list of fields to extract (max 10). Each field can be text, number, array_text (max 5), or array_number (max 5).",
+        max_length=10,
+    )
+    advanced_schema: Optional[dict] = Field(
+        default=None,
+        description="Advanced: Full JSON schema for complex extraction. Use this for nested structures.",
+    )
+    instruction: Optional[str] = Field(
+        default=None,
+        description="Optional instruction to guide the extraction process.",
+    )
+
+    @model_validator(mode="after")
+    def check_schema_or_fields(self):
+        """Ensure either fields or advanced_schema is provided, not both."""
+        if not self.fields and not self.advanced_schema:
+            raise ValueError("Either 'fields' or 'advanced_schema' must be provided")
+        if self.fields and self.advanced_schema:
+            raise ValueError("Provide either 'fields' or 'advanced_schema', not both")
+
+        # Validate advanced_schema if provided
+        if self.advanced_schema:
+            if (
+                not isinstance(self.advanced_schema, dict)
+                or self.advanced_schema.get("type") != "object"
+                or not self.advanced_schema.get("properties")
+            ):
+                raise ValueError(
+                    "advanced_schema must be a valid JSON object schema with 'type': 'object' and a 'properties' field."
+                )
+        return self
+
+
+class ImageExtractResponse(BaseModel):
+    request_id: str
+    credits_used: int
+    extracted_data: Dict[str, Any]
+
+
+class ImageClassifyRequest(ImageSourceBase):
+    classes: Optional[List[str]] = None
+    class_descriptions: Optional[Dict[str, str]] = None
+    instruction: Optional[str] = None
+    multi_label: bool = False
+
+
+class ImageClassifyResponse(BaseModel):
+    request_id: str
+    credits_used: int
+    classification: List[str]
+
+
+class ImageAskRequest(ImageSourceBase):
+    question: str
+
+
+class ImageAskResponse(BaseModel):
+    request_id: str
+    credits_used: int
+    answer: str
+
+
+class ImageCompareRequest(BaseModel):
+    image1_url: Optional[str] = None
+    image1_base64: Optional[str] = None
+    image2_url: Optional[str] = None
+    image2_base64: Optional[str] = None
+    instruction: Optional[str] = Field(
+        default="Describe the similarities and differences between these two images."
+    )
+
+
+class ImageCompareResponse(BaseModel):
+    request_id: str
+    credits_used: int
+    comparison_result: str
+
+
+# 2. User Endpoints
+
+
+class CreditsResponse(BaseModel):
+    remaining_credits: int
+    total_credits_used: int
+
+
+class FeedbackRequest(BaseModel):
+    """Request model for feedback endpoint"""
+
+    request_id: str = Field(..., example="123e4567-e89b-12d3-a456-426614174000")
+    rating: int = Field(..., ge=1, le=5, example=5)
+    feedback_text: Optional[str] = Field(None, example="Great results!")
+
+    @model_validator(mode="after")
+    def validate_request_id(self) -> "FeedbackRequest":
+        try:
+            UUID(self.request_id)
+        except ValueError:
+            raise ValueError("request_id must be a valid UUID")
+        return self
+
+
+class FeedbackResponse(BaseModel):
+    feedback_id: UUID
+    request_id: UUID
+    message: str
+    feedback_timestamp: datetime

viscribe/utils/helpers.py

@@ -0,0 +1,80 @@
+# Utility functions go here
+
+import base64
+from typing import Any, Dict
+from urllib.parse import urlparse
+from uuid import UUID
+
+import aiohttp
+from requests import Response
+
+from viscribe.exceptions import APIError
+
+
+def validate_api_key(api_key: str) -> bool:
+    if not api_key.startswith("vscrb-"):
+        raise ValueError("Invalid API key format. API key must start with 'vscrb-'")
+    uuid_part = api_key[5:]  # Strip out 'vscrb-'
+    try:
+        UUID(uuid_part)
+    except ValueError:
+        raise ValueError(
+            "Invalid API key format. API key must be 'vscrb-' followed by a valid UUID. You can get one at https://app.viscribe.ai/"
+        )
+    return True
+
+
+def handle_sync_response(response: Response) -> Dict[str, Any]:
+    data = response.json()
+
+    if response.status_code >= 400:
+        error_msg = data.get("error", "Unknown error occurred")
+        raise APIError(error_msg, status_code=response.status_code)
+
+    return data
+
+
+async def handle_async_response(response: aiohttp.ClientResponse) -> Dict[str, Any]:
+    data = await response.json()
+
+    if response.status >= 400:
+        error_msg = data.get("error", "Unknown error occurred")
+        raise APIError(error_msg, status_code=response.status)
+
+    return data
+
+
+def validate_url_format(url: str) -> bool:
+    """Validate URL format."""
+    try:
+        result = urlparse(url)
+        if not all([result.scheme, result.netloc]):
+            raise ValueError("URL must have a valid scheme and netloc")
+        if result.scheme not in ["http", "https"]:
+            raise ValueError("URL scheme must be http or https")
+        return True
+    except ValueError:
+        raise
+    except Exception as e:
+        raise ValueError(f"Invalid URL format: {str(e)}")
+
+
+def validate_base64_image(b64: str) -> bool:
+    """Validate base64 encoded image format."""
+    try:
+        # Check if it's a data URL
+        if b64.startswith("data:image/"):
+            # Extract the base64 part after the comma
+            b64_part = b64.split(",", 1)[1] if "," in b64 else b64
+        else:
+            b64_part = b64
+
+        # Try to decode
+        decoded = base64.b64decode(b64_part, validate=True)
+        if len(decoded) == 0:
+            raise ValueError("Base64 string is empty after decoding")
+        return True
+    except ValueError:
+        raise
+    except Exception as e:
+        raise ValueError(f"Invalid base64 image format: {str(e)}")

viscribe-1.0.1.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.3
+Name: viscribe
+Version: 1.0.1
+Summary: ViscribeAI SDK
+Author-email: viscriber0 <contact@viscribe.ai>
+License: MIT
+Keywords: ai,api,artificial intelligence,gpt,image,image2text,llm,machine learning,multimodal,natural language processing,nlp,openai,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <4.0,>=3.10
+Requires-Dist: aiohttp>=3.10
+Requires-Dist: beautifulsoup4>=4.13.4
+Requires-Dist: pydantic>=2.10.2
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.32.3
+Provides-Extra: docs
+Requires-Dist: furo==2024.5.6; extra == 'docs'
+Requires-Dist: sphinx==6.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <a href="https://viscribe.ai"><img src="assets/viscribe-logo.png" alt="Viscribe Logo" width="200"></a>
+</div>
+
+# 🌐 ViscribeAI -  Python SDK
+
+[![PyPI version](https://badge.fury.io/py/viscribe.svg)](https://badge.fury.io/py/viscribe)
+[![Python Support](https://img.shields.io/pypi/pyversions/viscribe.svg)](https://pypi.org/project/viscribe/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Documentation Status](https://readthedocs.org/projects/viscribe/badge/?version=latest)](https://docs.viscribe.ai)
+
+Official [Python SDK](https://viscribe.ai) for ViscribeAI - AI-powered image understanding and analysis.
+
+> 🎁 **Get started with free credits!** Visit [dashboard.viscribe.ai](https://dashboard.viscribe.ai) to sign up and get your API key.
+
+## 📦 Installation
+
+```bash
+pip install viscribe
+```
+
+## 🚀 Features
+
+- 🖼️ AI-powered image description, extraction, classification, VQA (Visual Question Answering), and comparison
+- 🔄 Both sync and async clients
+- 📊 Structured output with Pydantic schemas
+- 🔍 Detailed logging
+- ⚡ Automatic retries
+- 🔐 Secure authentication
+
+## 🎯 Quick Start
+
+```python
+from viscribe import Client
+
+client = Client(api_key="your-api-key-here")
+```
+
+> **Note:**
+> You can set the `VISCRIBE_API_KEY` environment variable and initialize the client without parameters: `client = Client()`
+
+## 📚 Image Endpoints
+
+### 1. Describe Image
+Generate a natural language description of an image, optionally with tags.
+
+```python
+from viscribe.client import Client
+client = Client(api_key="your-api-key-here")
+
+resp = client.describe_image(
+    image_url="https://img.com/cat.jpg",
+    generate_tags=True
+)
+print(resp)
+```
+
+### 2. Classify Image
+Classify an image into one or more categories.
+
+```python
+resp = client.classify_image(
+    image_url="https://img.com/cat.jpg",
+    classes=["cat", "dog"]
+)
+print(resp)
+```
+
+### 3. Visual Question Answering (VQA)
+Ask a question about the content of an image and get an answer.
+
+```python
+resp = client.ask_image(
+    image_url="https://img.com/car.jpg",
+    question="What color is the car?"
+)
+print(resp)
+```
+
+### 4. Extract Structured Data from Image
+Extract structured data from an image using either simple fields or an advanced schema.
+
+#### Simple Fields (Recommended for basic extraction)
+Use simple fields for straightforward data extraction (max 10 fields):
+
+```python
+resp = client.extract_image(
+    image_url="https://img.com/prod.jpg",
+    fields=[
+        {"name": "product_name", "type": "text", "description": "Name of the product"},
+        {"name": "price", "type": "number", "description": "Product price"},
+        {"name": "tags", "type": "array_text", "description": "Product tags"},
+    ]
+)
+print(resp.extracted_data)
+```
+
+**Field Types:**
+- `text`: Single text value
+- `number`: Single numeric value
+- `array_text`: Array of text values (max 5 items)
+- `array_number`: Array of numeric values (max 5 items)
+
+#### Advanced Schema (For complex/nested structures)
+Use advanced schema for complex nested structures or when you need more control:
+
+```python
+from pydantic import BaseModel
+
+class Product(BaseModel):
+    product_name: str
+    price: float
+    specifications: dict
+
+resp = client.extract_image(
+    image_url="https://img.com/prod.jpg",
+    advanced_schema=Product  # Pass the class directly
+)
+print(resp.extracted_data)
+```
+
+> **Note:** Either `fields` or `advanced_schema` must be provided, not both.
+
+### 5. Compare Images
+Compare two images and get a description of their similarities and differences.
+
+```python
+resp = client.compare_images(
+    image1_url="https://img.com/cat1.jpg",
+    image2_url="https://img.com/cat2.jpg"
+)
+print(resp)
+```
+
+## 👤 User Endpoints
+
+Check credits and submit feedback.
+
+### Get Credits
+```python
+credits = client.get_credits()
+print(credits)
+```
+
+### Submit Feedback
+```python
+feedback_response = client.submit_feedback(
+    request_id="your-request-id",
+    rating=5,  # Rating from 1-5
+    feedback_text="Perfect image description!",
+)
+print(feedback_response)
+```
+
+## ⚡ Async Usage
+
+All endpoints support async operations:
+
+```python
+import asyncio
+from viscribe.async_client import AsyncClient
+
+async def main():
+    client = AsyncClient(api_key="your-api-key-here")
+    resp = await client.describe_image({"image_url": "https://img.com/cat.jpg"})
+    print(resp)
+    # ... use other endpoints as above
+
+asyncio.run(main())
+```
+
+## 📖 Documentation
+
+For detailed documentation, visit [docs.viscribe.ai](https://docs.viscribe.ai)
+
+## 🛠️ Development
+
+For information about setting up the development environment and contributing to the project, see our [Contributing Guide](CONTRIBUTING.md).
+
+## 💬 Support & Feedback
+
+- 📧 Email: support@viscribe.ai
+- 💻 GitHub Issues: [Create an issue](https://github.com/ViscribeAI/python-sdk/issues)
+- 🌟 Feature Requests: [Request a feature](https://github.com/ViscribeAI/python-sdk/issues/new)
+- ⭐ API Feedback: You can also submit feedback programmatically using the feedback endpoint:
+  ```python
+  from viscribe import Client
+
+  client = Client(api_key="your-api-key-here")
+
+  client.submit_feedback(
+      request_id="your-request-id",
+      rating=5,
+      feedback_text="Great results!"
+  )
+  ```
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🔗 Links
+
+- [Website](https://viscribe.ai)
+- [Documentation](https://docs.viscribe.ai)
+- [GitHub](https://github.com/ViscribeAI/python-sdk)
+
+---
+
+> 🎁 **Get started with free credits!** Visit [dashboard.viscribe.ai](https://dashboard.viscribe.ai) to sign up and get your API key.
+
+Made with ❤️ by [ViscribeAI](https://viscribe.ai)

viscribe-1.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+viscribe/__init__.py,sha256=9v9X-o8CGf5goWydq-BeHY0U8BVEiDrTk_o15YQXIp4,106
+viscribe/async_client.py,sha256=_kuI_B1yI4YImEl0j3-7FjOgkuo6uSPsXwrKwbyGwa0,12387
+viscribe/client.py,sha256=aI2w4TUQBBVKWJGVp0RMdkhTxUVY9icrieeiJ1qw2t8,12277
+viscribe/config.py,sha256=0Qp5Tf-J1q2c-rNFdEViZjQfW8U5xJCzzcUUWKEghYg,170
+viscribe/exceptions.py,sha256=TFROaihQQAmLO56s3J-st0BR74xeqjHT_tpzgrMaM74,264
+viscribe/logger.py,sha256=Sdli1r1KG2NzMaPRHVCiNHiI6_ykifHKPh7hor-MrsY,3555
+viscribe/models/__init__.py,sha256=uvr4voFaDXYc4JSomF8SXrFJNmFhNPgX-gfDEuVAGDA,356
+viscribe/models/image.py,sha256=rsDGq32Q9-iO67G1wJ692xdk8R8Vxyoaksyad3662to,5706
+viscribe/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+viscribe/utils/helpers.py,sha256=fzdRK_QhQBsOEWEJxaedVraSEjdzuE3GFLqqtH9u2eY,2431
+viscribe-1.0.1.dist-info/METADATA,sha256=KlFdb_GwQxrdTuvepk-aKryhfHOhvIXvkVJO3kPxcYQ,6718
+viscribe-1.0.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+viscribe-1.0.1.dist-info/licenses/LICENSE,sha256=PO1JKSHKXkev7dpsYZIgd-wXxIzigpPunGgQQa3dNA4,1067
+viscribe-1.0.1.dist-info/RECORD,,

viscribe-1.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.26.3
+Root-Is-Purelib: true
+Tag: py3-none-any

viscribe-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ViscribeAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.