lattifai 0.4.5__py3-none-any.whl → 1.0.0__py3-none-any.whl

lattifai/errors.py

@@ -7,18 +7,18 @@ import colorful
 
 # Error help messages
 LATTICE_DECODING_FAILURE_HELP = (
-    'Failed to decode lattice alignment. Possible reasons:\n\n'
-    '1) Audio and text content mismatch:\n'
-    '   - The transcript/subtitle does not accurately match the audio content\n'
-    '   - Text may be from a different version or section of the audio\n'
-    '   ⚠️  Note: Gemini transcription may occasionally skip large segments of audio, causing alignment failures.\n'
-    '       We will detect and fix this issue in the next version.\n\n'
-    '2) Unsupported audio type:\n'
-    '   - Singing is not yet supported, this will be optimized in future versions\n\n'
-    '💡 Troubleshooting tips:\n'
-    '   • Verify the transcript matches the audio by listening to a few segments\n'
-    '   • For YouTube videos, manually check if auto-generated transcript are accurate\n'
-    '       • Consider using a different transcription source if Gemini results are incomplete'
+    "Failed to decode lattice alignment. Possible reasons:\n\n"
+    "1) Media(Audio/Video) and text content mismatch:\n"
+    "   - The transcript/caption does not accurately match the media content\n"
+    "   - Text may be from a different version or section of the media\n"
+    "   ⚠️  Note: Gemini transcription may occasionally skip large segments of media, causing alignment failures.\n"
+    "       We will detect and fix this issue in the next version.\n\n"
+    "2) Unsupported media type:\n"
+    "   - Singing is not yet supported, this will be optimized in future versions\n\n"
+    "💡 Troubleshooting tips:\n"
+    "   • Verify the transcript matches the media by listening to a few segments\n"
+    "   • For YouTube videos, manually check if auto-generated transcript are accurate\n"
+    "       • Consider using a different transcription source if Gemini results are incomplete"
 )
 
 
@@ -43,19 +43,19 @@ class LattifAIError(Exception):
         return (
             f'\n{colorful.green("🔧 Need help? Here are two ways to get support:")}\n'
             f'   1. 📝 Create a GitHub issue: {colorful.green("https://github.com/lattifai/lattifai-python/issues")}\n'
-            '      Please include:\n'
-            '      - Your audio file format and duration\n'
-            "      - The text/subtitle content you're trying to align\n"
-            '      - This error message and stack trace\n'
+            "      Please include:\n"
+            "      - Your audio file format and duration\n"
+            "      - The text/caption content you're trying to align\n"
+            "      - This error message and stack trace\n"
             f'   2. 💬 Join our Discord community: {colorful.green("https://discord.gg/vzmTzzZgNu")}\n'
-            '      Our team and community can help you troubleshoot\n'
+            "      Our team and community can help you troubleshoot\n"
         )
 
     def get_message(self) -> str:
         """Return formatted error message without support information."""
         base_message = f'{colorful.red(f"[{self.error_code}] {self.message}")}'
         if self.context:
-            context_str = f'\n{colorful.yellow("Context:")} ' + ', '.join(f'{k}={v}' for k, v in self.context.items())
+            context_str = f'\n{colorful.yellow("Context:")} ' + ", ".join(f"{k}={v}" for k, v in self.context.items())
             base_message += context_str
         return base_message
 
@@ -71,72 +71,72 @@ class LattifAIError(Exception):
 class AudioProcessingError(LattifAIError):
     """Error during audio processing operations."""
 
-    def __init__(self, message: str, audio_path: Optional[str] = None, **kwargs):
-        context = kwargs.get('context', {})
-        if audio_path:
-            context['audio_path'] = audio_path
-        kwargs['context'] = context
+    def __init__(self, message: str, media_path: Optional[str] = None, **kwargs):
+        context = kwargs.get("context", {})
+        if media_path:
+            context["media_path"] = media_path
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
 class AudioLoadError(AudioProcessingError):
     """Error loading or reading audio file."""
 
-    def __init__(self, audio_path: str, original_error: Optional[Exception] = None, **kwargs):
-        message = f'Failed to load audio file: {colorful.red(audio_path)}'
+    def __init__(self, media_path: str, original_error: Optional[Exception] = None, **kwargs):
+        message = f"Failed to load audio file: {colorful.red(media_path)}"
         if original_error:
-            message += f' - {colorful.red(str(original_error))}'
+            message += f" - {colorful.red(str(original_error))}"
 
-        context = kwargs.get('context', {})
-        context.update({'audio_path': audio_path, 'original_error': str(original_error) if original_error else None})
-        kwargs['context'] = context
+        context = kwargs.get("context", {})
+        context.update({"media_path": media_path, "original_error": str(original_error) if original_error else None})
+        kwargs["context"] = context
 
-        super().__init__(message, audio_path=audio_path, **kwargs)
+        super().__init__(message, media_path=media_path, **kwargs)
 
 
 class AudioFormatError(AudioProcessingError):
     """Error with audio format or codec."""
 
-    def __init__(self, audio_path: str, format_issue: str, **kwargs):
-        message = f'Audio format error for {colorful.red(audio_path)}: {colorful.red(format_issue)}'
-        context = kwargs.get('context', {})
-        context.update({'audio_path': audio_path, 'format_issue': format_issue})
-        kwargs['context'] = context
-        super().__init__(message, audio_path=audio_path, **kwargs)
+    def __init__(self, media_path: str, format_issue: str, **kwargs):
+        message = f"Audio format error for {colorful.red(media_path)}: {colorful.red(format_issue)}"
+        context = kwargs.get("context", {})
+        context.update({"media_path": media_path, "format_issue": format_issue})
+        kwargs["context"] = context
+        super().__init__(message, media_path=media_path, **kwargs)
 
 
-class SubtitleProcessingError(LattifAIError):
-    """Error during subtitle/text processing operations."""
+class CaptionProcessingError(LattifAIError):
+    """Error during caption/text processing operations."""
 
-    def __init__(self, message: str, subtitle_path: Optional[str] = None, **kwargs):
-        context = kwargs.get('context', {})
-        if subtitle_path:
-            context['subtitle_path'] = subtitle_path
-        kwargs['context'] = context
+    def __init__(self, message: str, caption_path: Optional[str] = None, **kwargs):
+        context = kwargs.get("context", {})
+        if caption_path:
+            context["caption_path"] = caption_path
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
-class SubtitleParseError(SubtitleProcessingError):
-    """Error parsing subtitle or text file."""
+class CaptionParseError(CaptionProcessingError):
+    """Error parsing caption or text file."""
 
-    def __init__(self, subtitle_path: str, parse_issue: str, **kwargs):
-        message = f'Failed to parse subtitle file {subtitle_path}: {parse_issue}'
-        context = kwargs.get('context', {})
-        context.update({'subtitle_path': subtitle_path, 'parse_issue': parse_issue})
-        kwargs['context'] = context
-        super().__init__(message, subtitle_path=subtitle_path, **kwargs)
+    def __init__(self, caption_path: str, parse_issue: str, **kwargs):
+        message = f"Failed to parse caption file {caption_path}: {parse_issue}"
+        context = kwargs.get("context", {})
+        context.update({"caption_path": caption_path, "parse_issue": parse_issue})
+        kwargs["context"] = context
+        super().__init__(message, caption_path=caption_path, **kwargs)
 
 
 class AlignmentError(LattifAIError):
     """Error during audio-text alignment process."""
 
-    def __init__(self, message: str, audio_path: Optional[str] = None, subtitle_path: Optional[str] = None, **kwargs):
-        context = kwargs.get('context', {})
-        if audio_path:
-            context['audio_path'] = audio_path
-        if subtitle_path:
-            context['subtitle_path'] = subtitle_path
-        kwargs['context'] = context
+    def __init__(self, message: str, media_path: Optional[str] = None, caption_path: Optional[str] = None, **kwargs):
+        context = kwargs.get("context", {})
+        if media_path:
+            context["media_path"] = media_path
+        if caption_path:
+            context["caption_path"] = caption_path
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
@@ -144,19 +144,19 @@ class LatticeEncodingError(AlignmentError):
     """Error generating lattice graph from text."""
 
     def __init__(self, text_content: str, original_error: Optional[Exception] = None, **kwargs):
-        message = 'Failed to generate lattice graph from text'
+        message = "Failed to generate lattice graph from text"
         if original_error:
-            message += f': {colorful.red(str(original_error))}'
+            message += f": {colorful.red(str(original_error))}"
 
-        context = kwargs.get('context', {})
+        context = kwargs.get("context", {})
         context.update(
             {
-                'text_content_length': len(text_content),
-                'text_preview': text_content[:100] + '...' if len(text_content) > 100 else text_content,
-                'original_error': str(original_error) if original_error else None,
+                "text_content_length": len(text_content),
+                "text_preview": text_content[:100] + "..." if len(text_content) > 100 else text_content,
+                "original_error": str(original_error) if original_error else None,
             }
         )
-        kwargs['context'] = context
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
@@ -164,28 +164,28 @@ class LatticeDecodingError(AlignmentError):
     """Error decoding lattice alignment results."""
 
     def __init__(self, lattice_id: str, original_error: Optional[Exception] = None, **kwargs):
-        message = f'Failed to decode lattice alignment results for lattice ID: {colorful.red(lattice_id)}'
+        message = f"Failed to decode lattice alignment results for lattice ID: {colorful.red(lattice_id)}"
 
         # Don't duplicate the help message if it's already in original_error
         if original_error and str(original_error) != LATTICE_DECODING_FAILURE_HELP:
-            message += f' - {colorful.red(str(original_error))}'
+            message += f" - {colorful.red(str(original_error))}"
 
-        context = kwargs.get('context', {})
+        context = kwargs.get("context", {})
         # Don't store the entire help message in context to avoid duplication
         if original_error and str(original_error) != LATTICE_DECODING_FAILURE_HELP:
-            context['original_error'] = str(original_error)
-        context['lattice_id'] = lattice_id
-        kwargs['context'] = context
+            context["original_error"] = str(original_error)
+        context["lattice_id"] = lattice_id
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
     def get_message(self) -> str:
         """Return formatted error message with help text."""
         base_message = f'{colorful.red(f"[{self.error_code}]")} {self.message}'
-        if self.context and self.context.get('lattice_id'):
+        if self.context and self.context.get("lattice_id"):
             # Only show essential context (lattice_id), not the duplicated help message
             base_message += f'\n{colorful.yellow("Lattice ID:")} {self.context["lattice_id"]}'
         # Append help message once at the end
-        base_message += f'\n\n{colorful.yellow(LATTICE_DECODING_FAILURE_HELP)}'
+        base_message += f"\n\n{colorful.yellow(LATTICE_DECODING_FAILURE_HELP)}"
         return base_message
 
 
@@ -193,13 +193,13 @@ class ModelLoadError(LattifAIError):
     """Error loading AI model."""
 
     def __init__(self, model_name: str, original_error: Optional[Exception] = None, **kwargs):
-        message = f'Failed to load model: {colorful.red(model_name)}'
+        message = f"Failed to load model: {colorful.red(model_name)}"
         if original_error:
-            message += f' - {colorful.red(str(original_error))}'
+            message += f" - {colorful.red(str(original_error))}"
 
-        context = kwargs.get('context', {})
-        context.update({'model_name': model_name, 'original_error': str(original_error) if original_error else None})
-        kwargs['context'] = context
+        context = kwargs.get("context", {})
+        context.update({"model_name": model_name, "original_error": str(original_error) if original_error else None})
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
@@ -207,13 +207,13 @@ class DependencyError(LattifAIError):
     """Error with required dependencies."""
 
     def __init__(self, dependency_name: str, install_command: Optional[str] = None, **kwargs):
-        message = f'Missing required dependency: {colorful.red(dependency_name)}'
+        message = f"Missing required dependency: {colorful.red(dependency_name)}"
         if install_command:
-            message += f'\nPlease install it using: {colorful.yellow(install_command)}'
+            message += f"\nPlease install it using: {colorful.yellow(install_command)}"
 
-        context = kwargs.get('context', {})
-        context.update({'dependency_name': dependency_name, 'install_command': install_command})
-        kwargs['context'] = context
+        context = kwargs.get("context", {})
+        context.update({"dependency_name": dependency_name, "install_command": install_command})
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
@@ -221,9 +221,9 @@ class APIError(LattifAIError):
     """Error communicating with LattifAI API."""
 
     def __init__(self, message: str, status_code: Optional[int] = None, response_text: Optional[str] = None, **kwargs):
-        context = kwargs.get('context', {})
-        context.update({'status_code': status_code, 'response_text': response_text})
-        kwargs['context'] = context
+        context = kwargs.get("context", {})
+        context.update({"status_code": status_code, "response_text": response_text})
+        kwargs["context"] = context
         super().__init__(message, **kwargs)
 
 
@@ -231,10 +231,17 @@ class ConfigurationError(LattifAIError):
     """Error with client configuration."""
 
     def __init__(self, config_issue: str, **kwargs):
-        message = f'Configuration error: {config_issue}'
+        message = f"Configuration error: {config_issue}"
         super().__init__(message, **kwargs)
 
 
+class QuotaExceededError(APIError):
+    """Error when user quota or API key limit is exceeded."""
+
+    def __init__(self, message: str, **kwargs):
+        super().__init__(message, status_code=402, **kwargs)
+
+
 def handle_exception(func):
     """Decorator to handle exceptions and convert them to LattifAI errors."""
 
@@ -246,11 +253,11 @@ def handle_exception(func):
             raise
         except Exception as e:
             # Convert other exceptions to LattifAI errors
-            error_msg = f'Unexpected error in {func.__name__}: {str(e)}'
+            error_msg = f"Unexpected error in {func.__name__}: {str(e)}"
             context = {
-                'function': func.__name__,
-                'original_exception': e.__class__.__name__,
-                'traceback': traceback.format_exc(),
+                "function": func.__name__,
+                "original_exception": e.__class__.__name__,
+                "traceback": traceback.format_exc(),
             }
             raise LattifAIError(error_msg, context=context) from e
 

lattifai/logging.py

@@ -0,0 +1,116 @@
+"""Unified logging configuration for LattifAI."""
+
+import logging
+import sys
+from typing import Optional
+
+# Default log format
+DEFAULT_FORMAT = "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+SIMPLE_FORMAT = "%(levelname)s: %(message)s"
+
+
+def setup_logger(
+    name: str,
+    level: Optional[int] = None,
+    format_string: Optional[str] = None,
+    handler: Optional[logging.Handler] = None,
+) -> logging.Logger:
+    """
+    Setup logger with consistent formatting for LattifAI modules.
+
+    Args:
+        name: Logger name (will be prefixed with 'lattifai.')
+        level: Logging level (defaults to INFO)
+        format_string: Custom format string (defaults to SIMPLE_FORMAT)
+        handler: Custom handler (defaults to StreamHandler)
+
+    Returns:
+        Configured logger instance
+
+    Examples:
+        >>> logger = setup_logger(__name__)
+        >>> logger.info("Processing started")
+
+        >>> logger = setup_logger("alignment", level=logging.DEBUG)
+        >>> logger.debug("Debug information")
+    """
+    # Ensure name is prefixed with 'lattifai.'
+    if not name.startswith("lattifai."):
+        logger_name = f"lattifai.{name}"
+    else:
+        logger_name = name
+
+    logger = logging.getLogger(logger_name)
+
+    # Set level
+    if level is None:
+        level = logging.INFO
+    logger.setLevel(level)
+
+    # Avoid duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # Setup handler
+    if handler is None:
+        handler = logging.StreamHandler(sys.stderr)
+
+    # Setup formatter
+    if format_string is None:
+        format_string = SIMPLE_FORMAT
+    formatter = logging.Formatter(format_string)
+    handler.setFormatter(formatter)
+
+    logger.addHandler(handler)
+    return logger
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get existing logger or create new one with default settings.
+
+    Args:
+        name: Logger name (will be prefixed with 'lattifai.')
+
+    Returns:
+        Logger instance
+    """
+    if not name.startswith("lattifai."):
+        logger_name = f"lattifai.{name}"
+    else:
+        logger_name = name
+
+    logger = logging.getLogger(logger_name)
+
+    # If logger has no handlers, set it up with defaults
+    if not logger.handlers:
+        return setup_logger(name)
+
+    return logger
+
+
+def set_log_level(level: int) -> None:
+    """
+    Set log level for all LattifAI loggers.
+
+    Args:
+        level: Logging level (e.g., logging.DEBUG, logging.INFO)
+
+    Examples:
+        >>> from lattifai.logging import set_log_level
+        >>> import logging
+        >>> set_log_level(logging.DEBUG)
+    """
+    root_logger = logging.getLogger("lattifai")
+    root_logger.setLevel(level)
+    for handler in root_logger.handlers:
+        handler.setLevel(level)
+
+
+__all__ = [
+    "setup_logger",
+    "get_logger",
+    "set_log_level",
+    "DEFAULT_FORMAT",
+    "SIMPLE_FORMAT",
+]