ai-coding-assistant 0.5.0__py3-none-any.whl

coding_assistant/exceptions/base.py

@@ -0,0 +1,110 @@
+"""Base exception classes for the AI Coding Assistant."""
+
+from typing import Optional, Dict, Any
+
+
+class AssistantError(Exception):
+    """
+    Base exception for all assistant errors.
+
+    Attributes:
+        message: Human-readable error message
+        recoverable: Whether the error can be recovered from
+        suggestion: Suggested action to fix the error
+        details: Additional error details
+        error_code: Unique error code for categorization
+    """
+
+    def __init__(
+        self,
+        message: str,
+        recoverable: bool = True,
+        suggestion: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+        error_code: Optional[str] = None
+    ):
+        """
+        Initialize assistant error.
+
+        Args:
+            message: Error message
+            recoverable: Whether error can be recovered from
+            suggestion: Suggestion for fixing the error
+            details: Additional error details
+            error_code: Unique error code
+        """
+        super().__init__(message)
+        self.message = message
+        self.recoverable = recoverable
+        self.suggestion = suggestion
+        self.details = details or {}
+        self.error_code = error_code or self.__class__.__name__
+
+    def format_message(self, color: bool = True) -> str:
+        """
+        Format error message for display.
+
+        Args:
+            color: Whether to include Rich color markup
+
+        Returns:
+            Formatted error message
+        """
+        if color:
+            lines = [f"[red]❌ Error: {self.message}[/red]"]
+
+            if self.suggestion:
+                lines.append(f"\n[yellow]💡 Suggestion: {self.suggestion}[/yellow]")
+
+            if self.details:
+                lines.append("\n[dim]Details:[/dim]")
+                for key, value in self.details.items():
+                    lines.append(f"  [dim]{key}: {value}[/dim]")
+
+            if not self.recoverable:
+                lines.append("\n[red bold]⚠️  This error is not recoverable.[/red bold]")
+
+        else:
+            lines = [f"Error: {self.message}"]
+
+            if self.suggestion:
+                lines.append(f"\nSuggestion: {self.suggestion}")
+
+            if self.details:
+                lines.append("\nDetails:")
+                for key, value in self.details.items():
+                    lines.append(f"  {key}: {value}")
+
+            if not self.recoverable:
+                lines.append("\n⚠️  This error is not recoverable.")
+
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        """String representation."""
+        return self.format_message(color=False)
+
+    def __repr__(self) -> str:
+        """Developer representation."""
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"recoverable={self.recoverable}, "
+            f"error_code={self.error_code})"
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert error to dictionary.
+
+        Returns:
+            Dictionary representation of error
+        """
+        return {
+            'error_code': self.error_code,
+            'message': self.message,
+            'recoverable': self.recoverable,
+            'suggestion': self.suggestion,
+            'details': self.details,
+            'error_type': self.__class__.__name__
+        }

coding_assistant/exceptions/llm.py

@@ -0,0 +1,249 @@
+"""LLM-related exceptions."""
+
+from typing import Optional
+from coding_assistant.exceptions.base import AssistantError
+
+
+class LLMError(AssistantError):
+    """Base exception for LLM-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        recoverable: bool = True,
+        suggestion: Optional[str] = None,
+        **kwargs
+    ):
+        super().__init__(
+            message=message,
+            recoverable=recoverable,
+            suggestion=suggestion,
+            error_code="LLM_ERROR",
+            **kwargs
+        )
+
+
+class LLMConnectionError(LLMError):
+    """
+    LLM connection failed.
+
+    Raised when cannot connect to LLM provider.
+    """
+
+    def __init__(self, provider: str, endpoint: str, reason: Optional[str] = None):
+        """
+        Initialize connection error.
+
+        Args:
+            provider: LLM provider name (ollama, openai, etc.)
+            endpoint: Connection endpoint
+            reason: Optional reason for failure
+        """
+        message = f"Failed to connect to {provider} LLM at {endpoint}"
+        if reason:
+            message += f": {reason}"
+
+        suggestion = self._get_suggestion(provider, endpoint)
+
+        super().__init__(
+            message=message,
+            recoverable=True,
+            suggestion=suggestion,
+            details={
+                'provider': provider,
+                'endpoint': endpoint,
+                'reason': reason
+            }
+        )
+
+    @staticmethod
+    def _get_suggestion(provider: str, endpoint: str) -> str:
+        """Get provider-specific suggestion."""
+        if provider.lower() == "ollama":
+            return (
+                f"Make sure Ollama is running:\n"
+                f"  1. Install Ollama: https://ollama.ai\n"
+                f"  2. Start Ollama service: ollama serve\n"
+                f"  3. Check it's running: curl {endpoint}"
+            )
+        elif provider.lower() == "groq":
+            return (
+                "Check your Groq API configuration:\n"
+                "  1. Get free API key: https://console.groq.com\n"
+                "  2. Set API key: assistant config set-api-key groq <your-key>\n"
+                "  3. Or set env var: GROQ_API_KEY=<your-key>"
+            )
+        elif provider.lower() == "together":
+            return (
+                "Check your Together AI configuration:\n"
+                "  1. Get API key ($25 free trial): https://api.together.xyz\n"
+                "  2. Set API key: assistant config set-api-key together <your-key>\n"
+                "  3. Or set env var: TOGETHER_API_KEY=<your-key>"
+            )
+        elif provider.lower() == "gemini":
+            return (
+                "Check your Google Gemini configuration:\n"
+                "  1. Get free API key: https://makersuite.google.com/app/apikey\n"
+                "  2. Set API key: assistant config set-api-key gemini <your-key>\n"
+                "  3. Or set env var: GEMINI_API_KEY=<your-key>"
+            )
+        elif provider.lower() in ["openai", "claude"]:
+            return (
+                f"Check your API configuration:\n"
+                f"  1. Verify API key is set\n"
+                f"  2. Check network connectivity\n"
+                f"  3. Verify endpoint: {endpoint}"
+            )
+        else:
+            return f"Check that {provider} is running at {endpoint}"
+
+
+class LLMResponseError(LLMError):
+    """
+    LLM returned invalid or error response.
+
+    Raised when LLM response is malformed or indicates an error.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        provider: str,
+        status_code: Optional[int] = None,
+        response_text: Optional[str] = None
+    ):
+        """
+        Initialize response error.
+
+        Args:
+            message: Error message
+            provider: LLM provider
+            status_code: HTTP status code if applicable
+            response_text: Raw response text
+        """
+        suggestion = "Try again or switch to a different LLM provider"
+
+        if status_code == 429:
+            suggestion = "Rate limit exceeded. Wait a moment and try again."
+        elif status_code == 401:
+            suggestion = "Authentication failed. Check your API key."
+        elif status_code == 503:
+            suggestion = "Service unavailable. Try again later."
+
+        super().__init__(
+            message=message,
+            recoverable=True,
+            suggestion=suggestion,
+            details={
+                'provider': provider,
+                'status_code': status_code,
+                'response_preview': response_text[:200] if response_text else None
+            }
+        )
+
+
+class LLMTimeoutError(LLMError):
+    """
+    LLM request timed out.
+
+    Raised when LLM takes too long to respond.
+    """
+
+    def __init__(self, provider: str, timeout_seconds: int):
+        """
+        Initialize timeout error.
+
+        Args:
+            provider: LLM provider
+            timeout_seconds: Timeout duration
+        """
+        super().__init__(
+            message=f"LLM request to {provider} timed out after {timeout_seconds}s",
+            recoverable=True,
+            suggestion=(
+                "Try one of the following:\n"
+                "  1. Increase timeout in settings\n"
+                "  2. Reduce context size (use fewer code chunks)\n"
+                "  3. Try a faster model"
+            ),
+            details={
+                'provider': provider,
+                'timeout_seconds': timeout_seconds
+            }
+        )
+
+
+class LLMModelNotFoundError(LLMError):
+    """
+    Requested LLM model not found.
+
+    Raised when specified model is not available.
+    """
+
+    def __init__(self, provider: str, model: str, available_models: Optional[list] = None):
+        """
+        Initialize model not found error.
+
+        Args:
+            provider: LLM provider
+            model: Requested model name
+            available_models: List of available models
+        """
+        message = f"Model '{model}' not found for provider '{provider}'"
+
+        suggestion = f"Available models:\n"
+        if available_models:
+            for m in available_models[:5]:  # Show first 5
+                suggestion += f"  - {m}\n"
+            if len(available_models) > 5:
+                suggestion += f"  ... and {len(available_models) - 5} more"
+        else:
+            suggestion = f"Check model name or pull the model:\n  ollama pull {model}"
+
+        super().__init__(
+            message=message,
+            recoverable=True,
+            suggestion=suggestion,
+            details={
+                'provider': provider,
+                'requested_model': model,
+                'available_models': available_models
+            }
+        )
+
+
+class LLMContextTooLargeError(LLMError):
+    """
+    Context exceeds model's token limit.
+
+    Raised when total context is too large for model.
+    """
+
+    def __init__(self, tokens_used: int, max_tokens: int, model: str):
+        """
+        Initialize context too large error.
+
+        Args:
+            tokens_used: Number of tokens used
+            max_tokens: Maximum tokens allowed
+            model: Model name
+        """
+        super().__init__(
+            message=(
+                f"Context size ({tokens_used:,} tokens) exceeds "
+                f"model limit ({max_tokens:,} tokens)"
+            ),
+            recoverable=True,
+            suggestion=(
+                "Reduce context size:\n"
+                "  1. Use fewer code chunks (--top-k parameter)\n"
+                "  2. Clear conversation history (/reset in chat)\n"
+                "  3. Use a model with larger context window"
+            ),
+            details={
+                'tokens_used': tokens_used,
+                'max_tokens': max_tokens,
+                'model': model,
+                'overflow': tokens_used - max_tokens
+            }
+        )

coding_assistant/exceptions/recovery.py

@@ -0,0 +1,263 @@
+"""Error recovery utilities."""
+
+import time
+from typing import Callable, Any, Optional, Type
+from functools import wraps
+from rich.console import Console
+
+from coding_assistant.exceptions.base import AssistantError
+
+console = Console()
+
+
+class ErrorRecovery:
+    """
+    Utilities for error recovery and retry logic.
+
+    Provides decorators and helpers for handling transient failures.
+    """
+
+    @staticmethod
+    def retry(
+        max_attempts: int = 3,
+        delay: float = 1.0,
+        backoff: float = 2.0,
+        exceptions: tuple = (Exception,),
+        on_retry: Optional[Callable] = None
+    ):
+        """
+        Retry decorator with exponential backoff.
+
+        Args:
+            max_attempts: Maximum number of attempts
+            delay: Initial delay between retries (seconds)
+            backoff: Backoff multiplier
+            exceptions: Exceptions to catch and retry
+            on_retry: Callback function called on each retry
+
+        Usage:
+            @ErrorRecovery.retry(max_attempts=3, delay=1.0)
+            def flaky_function():
+                # May fail occasionally
+                pass
+        """
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args, **kwargs) -> Any:
+                current_delay = delay
+
+                for attempt in range(1, max_attempts + 1):
+                    try:
+                        return func(*args, **kwargs)
+
+                    except exceptions as e:
+                        if attempt == max_attempts:
+                            # Last attempt failed, re-raise
+                            raise
+
+                        # Log retry
+                        if on_retry:
+                            on_retry(attempt, max_attempts, e)
+                        else:
+                            console.print(
+                                f"[yellow]⚠️  Attempt {attempt}/{max_attempts} failed: {e}[/yellow]"
+                            )
+                            console.print(
+                                f"[yellow]   Retrying in {current_delay:.1f}s...[/yellow]"
+                            )
+
+                        # Wait before retry
+                        time.sleep(current_delay)
+                        current_delay *= backoff
+
+            return wrapper
+        return decorator
+
+    @staticmethod
+    def fallback(
+        fallback_func: Callable,
+        exceptions: tuple = (Exception,),
+        log_error: bool = True
+    ):
+        """
+        Fallback decorator - use fallback function on error.
+
+        Args:
+            fallback_func: Function to call on error
+            exceptions: Exceptions to catch
+            log_error: Whether to log the error
+
+        Usage:
+            def fallback_handler(*args, **kwargs):
+                return default_value
+
+            @ErrorRecovery.fallback(fallback_handler)
+            def risky_function():
+                # May fail
+                pass
+        """
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args, **kwargs) -> Any:
+                try:
+                    return func(*args, **kwargs)
+
+                except exceptions as e:
+                    if log_error:
+                        console.print(
+                            f"[yellow]⚠️  {func.__name__} failed: {e}[/yellow]"
+                        )
+                        console.print(
+                            f"[yellow]   Using fallback...[/yellow]"
+                        )
+
+                    return fallback_func(*args, **kwargs)
+
+            return wrapper
+        return decorator
+
+    @staticmethod
+    def graceful_degradation(
+        default_value: Any = None,
+        exceptions: tuple = (Exception,),
+        log_error: bool = True
+    ):
+        """
+        Graceful degradation - return default value on error.
+
+        Args:
+            default_value: Value to return on error
+            exceptions: Exceptions to catch
+            log_error: Whether to log the error
+
+        Usage:
+            @ErrorRecovery.graceful_degradation(default_value=[])
+            def get_items():
+                # May fail
+                return items
+        """
+        def decorator(func: Callable) -> Callable:
+            @wraps(func)
+            def wrapper(*args, **kwargs) -> Any:
+                try:
+                    return func(*args, **kwargs)
+
+                except exceptions as e:
+                    if log_error:
+                        console.print(
+                            f"[yellow]⚠️  {func.__name__} failed: {e}[/yellow]"
+                        )
+                        console.print(
+                            f"[yellow]   Returning default value: {default_value}[/yellow]"
+                        )
+
+                    return default_value
+
+            return wrapper
+        return decorator
+
+    @staticmethod
+    def handle_error(
+        error: Exception,
+        console: Optional[Console] = None,
+        exit_on_fatal: bool = True
+    ) -> None:
+        """
+        Handle error with appropriate user feedback.
+
+        Args:
+            error: Error to handle
+            console: Rich console for output
+            exit_on_fatal: Whether to exit on non-recoverable errors
+        """
+        if console is None:
+            console = Console()
+
+        # Check if it's our custom error
+        if isinstance(error, AssistantError):
+            # Show formatted error message
+            console.print(error.format_message())
+
+            # Exit if not recoverable
+            if not error.recoverable and exit_on_fatal:
+                console.print("\n[red]Exiting due to fatal error.[/red]")
+                raise SystemExit(1)
+
+        else:
+            # Generic error
+            console.print(f"[red]❌ Unexpected error: {error}[/red]")
+            console.print(f"[dim]Error type: {type(error).__name__}[/dim]")
+
+            if exit_on_fatal:
+                console.print("\n[yellow]💡 Suggestion: Run with --verbose for more details[/yellow]")
+                raise SystemExit(1)
+
+    @staticmethod
+    def safe_execute(
+        func: Callable,
+        *args,
+        default_value: Any = None,
+        log_error: bool = True,
+        **kwargs
+    ) -> Any:
+        """
+        Safely execute function, returning default value on error.
+
+        Args:
+            func: Function to execute
+            *args: Function arguments
+            default_value: Value to return on error
+            log_error: Whether to log errors
+            **kwargs: Function keyword arguments
+
+        Returns:
+            Function result or default value
+        """
+        try:
+            return func(*args, **kwargs)
+
+        except Exception as e:
+            if log_error:
+                console.print(
+                    f"[yellow]⚠️  {func.__name__} failed: {e}[/yellow]"
+                )
+
+            return default_value
+
+    @staticmethod
+    def validate_or_exit(
+        condition: bool,
+        error_message: str,
+        suggestion: Optional[str] = None
+    ) -> None:
+        """
+        Validate condition or exit with error message.
+
+        Args:
+            condition: Condition to check
+            error_message: Error message if condition fails
+            suggestion: Optional suggestion
+        """
+        if not condition:
+            console.print(f"[red]❌ Error: {error_message}[/red]")
+
+            if suggestion:
+                console.print(f"[yellow]💡 Suggestion: {suggestion}[/yellow]")
+
+            raise SystemExit(1)
+
+
+# Convenience decorators
+def retry_on_failure(max_attempts: int = 3, delay: float = 1.0):
+    """Shorthand for retry decorator."""
+    return ErrorRecovery.retry(max_attempts=max_attempts, delay=delay)
+
+
+def with_fallback(fallback_func: Callable):
+    """Shorthand for fallback decorator."""
+    return ErrorRecovery.fallback(fallback_func)
+
+
+def ignore_errors(default_value: Any = None):
+    """Shorthand for graceful degradation decorator."""
+    return ErrorRecovery.graceful_degradation(default_value=default_value)