wizelit-sdk 0.1.29__py3-none-any.whl → 0.1.31__py3-none-any.whl

wizelit_sdk/__init__.py

@@ -6,6 +6,42 @@ from wizelit_sdk.agent_wrapper.job import Job
 from wizelit_sdk.agent_wrapper.streaming import LogStreamer
 from wizelit_sdk.models.base import BaseModel
 from wizelit_sdk.models.job import JobModel, JobLogModel, JobStatus
+from wizelit_sdk.exceptions import (
+    WizelitSDKException,
+    AgentInitializationError,
+    SignatureValidationError,
+    JobExecutionError,
+    JobNotFoundError,
+    ToolRegistrationError,
+    DatabaseManagerError,
+    StreamingError,
+    ContextVariableError,
+    InvalidConfigError,
+    TransportError,
+    TimeoutError,
+)
 
-__all__ = ["WizelitAgent", "DatabaseManager", "Job", "LogStreamer", "BaseModel", "JobModel", "JobLogModel", "JobStatus"]
+__all__ = [
+    "WizelitAgent",
+    "DatabaseManager",
+    "Job",
+    "LogStreamer",
+    "BaseModel",
+    "JobModel",
+    "JobLogModel",
+    "JobStatus",
+    # Exceptions
+    "WizelitSDKException",
+    "AgentInitializationError",
+    "SignatureValidationError",
+    "JobExecutionError",
+    "JobNotFoundError",
+    "ToolRegistrationError",
+    "DatabaseManagerError",
+    "StreamingError",
+    "ContextVariableError",
+    "InvalidConfigError",
+    "TransportError",
+    "TimeoutError",
+]
 

wizelit_sdk/agent_wrapper/agent_wrapper.py

@@ -13,6 +13,9 @@ from wizelit_sdk.agent_wrapper.signature_validation import (
     bind_and_validate_arguments,
     ensure_type_hints,
 )
+from wizelit_sdk.exceptions import (
+    StreamingError,
+)
 
 # Local Transport literal to avoid import issues when fastmcp.types is unavailable
 Transport = Literal["stdio", "http", "sse", "streamable-http"]
@@ -92,7 +95,10 @@ class WizelitAgent:
             except ImportError:
                 print("Warning: redis package not installed. Log streaming disabled.")
             except Exception as e:
-                print(f"Warning: Failed to initialize log streamer: {e}")
+                raise StreamingError(
+                    "Failed to initialize log streaming",
+                    f"Could not connect to Redis at {redis_url}: {str(e)}"
+                )
 
         print(
             f"WizelitAgent initialized with name: {name}, transport: {transport}, host: {host}, port: {port}"

wizelit_sdk/agent_wrapper/job.py

@@ -6,7 +6,7 @@ import asyncio
 import uuid
 import time
 from datetime import datetime, UTC
-from typing import List, Optional, Awaitable, Any, TYPE_CHECKING
+from typing import Optional, Awaitable, Any, TYPE_CHECKING
 from fastmcp import Context
 
 if TYPE_CHECKING:
@@ -19,7 +19,7 @@ class MemoryLogHandler(logging.Handler):
     Custom logging handler that stores log messages in a list.
     """
 
-    def __init__(self, logs_list: List[str]):
+    def __init__(self, logs_list: list[str]):
         super().__init__()
         self.logs_list = logs_list
         self.setFormatter(logging.Formatter('%(message)s'))
@@ -156,7 +156,7 @@ class Job:
         self._ctx = ctx
         self._id = job_id or f"JOB-{str(uuid.uuid4())[:8]}"
         self._status = "running"
-        self._logs: List[str] = []
+        self._logs: list[str] = []
         self._result: Optional[str] = None
         self._error: Optional[str] = None
         self._db_manager = db_manager
@@ -176,7 +176,7 @@ class Job:
         return self._logger
 
     @property
-    def logs(self) -> List[str]:
+    def logs(self) -> list[str]:
         """List of log messages (timestamped strings)."""
         return self._logs
 

wizelit_sdk/agent_wrapper/streaming.py

@@ -196,11 +196,11 @@ class LogStreamer:
             self._redis = None
             logger.info("Redis connection closed")
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> 'LogStreamer':
         """Async context manager entry."""
         await self._ensure_connected()
         return self
 
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         """Async context manager exit."""
         await self.close()

wizelit_sdk/database.py

@@ -132,7 +132,7 @@ class DatabaseManager:
         finally:
             await session.close()
 
-    async def close(self):
+    async def close(self) -> None:
         """Dispose of the engine and close all connections."""
         await self.engine.dispose()
         logger.info("Database connections closed")

wizelit_sdk/exceptions.py

@@ -0,0 +1,206 @@
+"""
+Custom exceptions for Wizelit SDK with helpful error messages and suggestions.
+"""
+
+
+class WizelitSDKException(Exception):
+    """Base exception class for all Wizelit SDK errors."""
+
+    def __init__(self, message: str, suggestion: str = ""):
+        self.message = message
+        self.suggestion = suggestion
+        full_message = message
+        if suggestion:
+            full_message = f"{message}\n💡 Suggestion: {suggestion}"
+        super().__init__(full_message)
+
+
+class AgentInitializationError(WizelitSDKException):
+    """Raised when WizelitAgent cannot be initialized."""
+
+    def __init__(self, reason: str = "", original_error: str = ""):
+        message = "Failed to initialize WizelitAgent"
+        if reason:
+            message += f": {reason}"
+        if original_error:
+            message += f" ({original_error})"
+        suggestion = (
+            "1. Verify all required dependencies are installed\n"
+            "2. Check that the name parameter is provided\n"
+            "3. Verify the transport mode is valid (sse, http, streamable-http, stdio)\n"
+            "4. Check that host and port are available and not in use\n"
+            "5. Review the initialization code for configuration errors"
+        )
+        super().__init__(message, suggestion)
+
+
+class SignatureValidationError(WizelitSDKException):
+    """Raised when a function signature doesn't meet requirements."""
+
+    def __init__(self, function_name: str, reason: str = ""):
+        message = f"Signature validation failed for function '{function_name}'"
+        if reason:
+            message += f": {reason}"
+        suggestion = (
+            f"1. Ensure all parameters of '{function_name}' have type hints\n"
+            f"2. Verify parameter names match between definition and usage\n"
+            f"3. Check that the function signature is compatible with the ingest decorator\n"
+            f"4. Ensure complex types are properly imported and defined\n"
+            f"5. Review the decorator parameters for compatibility"
+        )
+        super().__init__(message, suggestion)
+
+
+class JobExecutionError(WizelitSDKException):
+    """Raised when a job fails during execution."""
+
+    def __init__(self, job_id: str, reason: str = "", original_error: str = ""):
+        message = f"Job execution failed for job_id '{job_id}'"
+        if reason:
+            message += f": {reason}"
+        if original_error:
+            message += f" ({original_error})"
+        suggestion = (
+            "1. Check the job logs for detailed error information\n"
+            "2. Verify job inputs are valid and complete\n"
+            "3. Check if the underlying tool/function has dependencies\n"
+            "4. Try running the job again with the same inputs\n"
+            "5. Check application logs and database logs for more context"
+        )
+        super().__init__(message, suggestion)
+
+
+class JobNotFoundError(WizelitSDKException):
+    """Raised when a job cannot be found."""
+
+    def __init__(self, job_id: str):
+        message = f"Job not found: {job_id}"
+        suggestion = (
+            "1. Verify the job_id is correct and complete\n"
+            "2. Check if the job has expired or been deleted\n"
+            "3. Verify the job was created in the current session\n"
+            "4. Check the database for job records\n"
+            "5. Review job retention policies"
+        )
+        super().__init__(message, suggestion)
+
+
+class ToolRegistrationError(WizelitSDKException):
+    """Raised when a tool cannot be registered with the MCP server."""
+
+    def __init__(self, tool_name: str, reason: str = ""):
+        message = f"Failed to register tool '{tool_name}' with MCP server"
+        if reason:
+            message += f": {reason}"
+        suggestion = (
+            f"1. Verify '{tool_name}' function is properly decorated with @ingest\n"
+            f"2. Check that function name is unique across all registered tools\n"
+            f"3. Verify function signature is valid with type hints\n"
+            f"4. Check for duplicate tool registrations\n"
+            f"5. Ensure the FastMCP server is properly initialized"
+        )
+        super().__init__(message, suggestion)
+
+
+class DatabaseManagerError(WizelitSDKException):
+    """Raised when database operations fail."""
+
+    def __init__(self, operation: str, reason: str = ""):
+        message = f"Database operation failed: {operation}"
+        if reason:
+            message += f" ({reason})"
+        suggestion = (
+            "1. Verify the database is running and accessible\n"
+            "2. Check database connection parameters (host, port, credentials)\n"
+            "3. Verify the database has sufficient disk space\n"
+            "4. Check if the database tables are properly initialized\n"
+            "5. Review database logs for detailed error information"
+        )
+        super().__init__(message, suggestion)
+
+
+class StreamingError(WizelitSDKException):
+    """Raised when log streaming fails."""
+
+    def __init__(self, reason: str = "", original_error: str = ""):
+        message = "Error in log streaming"
+        if reason:
+            message += f": {reason}"
+        if original_error:
+            message += f" ({original_error})"
+        suggestion = (
+            "1. Verify Redis is running and accessible\n"
+            "2. Check REDIS_URL environment variable is set correctly\n"
+            "3. Verify network connectivity to Redis\n"
+            "4. Check Redis logs for connection errors\n"
+            "5. Log streaming is optional - the SDK will continue without it"
+        )
+        super().__init__(message, suggestion)
+
+
+class ContextVariableError(WizelitSDKException):
+    """Raised when context variable operations fail."""
+
+    def __init__(self, variable_name: str, reason: str = ""):
+        message = f"Error accessing context variable '{variable_name}'"
+        if reason:
+            message += f": {reason}"
+        suggestion = (
+            f"1. Ensure '{variable_name}' is set before accessing\n"
+            f"2. Verify the context is active in the current async task\n"
+            f"3. Check if using the decorator or dependency injection correctly\n"
+            f"4. Ensure context propagation across async calls\n"
+            f"5. Review context variable usage documentation"
+        )
+        super().__init__(message, suggestion)
+
+
+class InvalidConfigError(WizelitSDKException):
+    """Raised when configuration is invalid or missing."""
+
+    def __init__(self, config_key: str, expected_type: str = "", reason: str = ""):
+        message = f"Invalid configuration for '{config_key}'"
+        if expected_type:
+            message += f" (expected: {expected_type})"
+        if reason:
+            message += f": {reason}"
+        suggestion = (
+            f"1. Verify {config_key} is set in environment variables\n"
+            f"2. Check the value format and type\n"
+            f"3. Review configuration documentation for valid values\n"
+            f"4. Check .env file or deployment configuration\n"
+            f"5. Restart the application after fixing configuration"
+        )
+        super().__init__(message, suggestion)
+
+
+class TransportError(WizelitSDKException):
+    """Raised when transport/communication errors occur."""
+
+    def __init__(self, transport_type: str, reason: str = ""):
+        message = f"Transport error with '{transport_type}'"
+        if reason:
+            message += f": {reason}"
+        suggestion = (
+            f"1. Verify the {transport_type} transport is properly configured\n"
+            f"2. Check network connectivity and firewall rules\n"
+            f"3. Verify server ports are open and accessible\n"
+            f"4. Check if there are proxy or routing issues\n"
+            f"5. Review transport-specific logs for detailed information"
+        )
+        super().__init__(message, suggestion)
+
+
+class TimeoutError(WizelitSDKException):
+    """Raised when an operation exceeds the timeout limit."""
+
+    def __init__(self, operation: str, timeout_seconds: float):
+        message = f"Operation '{operation}' exceeded timeout of {timeout_seconds} seconds"
+        suggestion = (
+            f"1. The {operation} took too long to complete\n"
+            f"2. Check if there are resource constraints (CPU, memory)\n"
+            f"3. Simplify the job inputs or query\n"
+            f"4. Check application and system logs for bottlenecks\n"
+            f"5. Consider increasing timeout if the operation is expected to be slow"
+        )
+        super().__init__(message, suggestion)

wizelit_sdk/models/base.py

@@ -3,6 +3,7 @@ from sqlalchemy import Column
 from sqlalchemy.dialects.postgresql import UUID
 import uuid
 from datetime import datetime
+from typing import Dict, Any
 
 Base = declarative_base()
 
@@ -10,7 +11,7 @@ class TimestampMixin:
     """Mixin for models that need timestamp functionality."""
 
     @staticmethod
-    def get_timestamp():
+    def get_timestamp() -> str:
         return datetime.utcnow().isoformat()
 
 
@@ -20,6 +21,6 @@ class BaseModel(Base):
 
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
 
-    def to_dict(self):
+    def to_dict(self) -> Dict[str, Any]:
         """Convert model to dictionary."""
         return {c.name: getattr(self, c.name) for c in self.__table__.columns}

wizelit_sdk/models/job.py

@@ -41,7 +41,7 @@ class JobModel(BaseModel):
         Index('idx_job_created_at', 'created_at'),
     )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<JobModel(id={self.id}, status={self.status})>"
 
 
@@ -68,5 +68,5 @@ class JobLogModel(BaseModel):
         Index('idx_job_log_job_id_timestamp', 'job_id', 'timestamp'),
     )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<JobLogModel(id={self.id}, job_id={self.job_id}, level={self.level})>"

{wizelit_sdk-0.1.29.dist-info → wizelit_sdk-0.1.31.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wizelit-sdk
-Version: 0.1.29
+Version: 0.1.31
 Summary: Wizelit Agent Wrapper - Internal utility package
 Author-email: Your Name <your.email@company.com>
 Requires-Python: >=3.10

wizelit_sdk-0.1.31.dist-info/RECORD

@@ -0,0 +1,14 @@
+wizelit_sdk/__init__.py,sha256=GRV3STJaNUg2KelKmvU60nhpYMdQ5lX0_FQyV_e5g1I,1168
+wizelit_sdk/database.py,sha256=HzvMY-KZQBkGs-Ey_wKAIPOJEb5BqGjEi98Tip7CQBo,4830
+wizelit_sdk/exceptions.py,sha256=KHkexTbD5t05nD-t9RnrJIFcqOsATBOUX9y5uHVfQeE,8557
+wizelit_sdk/agent_wrapper/__init__.py,sha256=srVcHZfvpf3q8m2nzIST6Ofl2V8Vv5GRtcNXudOLiD8,333
+wizelit_sdk/agent_wrapper/agent_wrapper.py,sha256=2IE1RXTpwzJJMnpEgetU8OCkR7txG_NMqJ-1W-rv9j0,23650
+wizelit_sdk/agent_wrapper/job.py,sha256=jW2Cl7QvSgZDUqWqZSND-V1XphGdISJuh9ViHgCn7iU,13770
+wizelit_sdk/agent_wrapper/signature_validation.py,sha256=Njplwofw36jXoWgBooaZCbwhkf72pR-UoRQ3Q6-biro,3729
+wizelit_sdk/agent_wrapper/streaming.py,sha256=l7SbvPuQYMdGO38t1upyI5wTVdd5eB-2BSwU-BQSlvc,6673
+wizelit_sdk/models/__init__.py,sha256=UB7nfHoE6hGcjfzy7w8AmuKVmYrTg9wIgGjG8GWziJ0,143
+wizelit_sdk/models/base.py,sha256=11XyxLUG0VjdiNxe4zmzGDUjKEOsjSvUjA8yaQgfCa0,758
+wizelit_sdk/models/job.py,sha256=HD8ohVqzakC8J7VAwmh8UCi_BLLiqx85TbR0FjO2rlg,2494
+wizelit_sdk-0.1.31.dist-info/METADATA,sha256=fOk9ur63IBthIIyjAMPW-cjahQVWycOAgPsy2ORfqOY,3297
+wizelit_sdk-0.1.31.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+wizelit_sdk-0.1.31.dist-info/RECORD,,

wizelit_sdk-0.1.29.dist-info/RECORD

@@ -1,13 +0,0 @@
-wizelit_sdk/__init__.py,sha256=76Dt-WxNbEJwOCPqu2P9AooVSQoGmc8-CH1fxIWJ5Lo,471
-wizelit_sdk/database.py,sha256=6F2Nyt-sr5U5GkAB9OeSCU-iv2byZBDsg7aXqCl-ntk,4822
-wizelit_sdk/agent_wrapper/__init__.py,sha256=srVcHZfvpf3q8m2nzIST6Ofl2V8Vv5GRtcNXudOLiD8,333
-wizelit_sdk/agent_wrapper/agent_wrapper.py,sha256=qkskmRRjhIooXVeyZHbH5q1OIp30zw29bBRUoqTPYLE,23476
-wizelit_sdk/agent_wrapper/job.py,sha256=Gk2CyLBQFzIosYuGrqUj6_rZ9kDIO6YLYQ7Pxk6ASuM,13776
-wizelit_sdk/agent_wrapper/signature_validation.py,sha256=Njplwofw36jXoWgBooaZCbwhkf72pR-UoRQ3Q6-biro,3729
-wizelit_sdk/agent_wrapper/streaming.py,sha256=f0VV3IzGAlfQY_cw2OHgxWjvM16Hs42_b700EUX2QpY,6633
-wizelit_sdk/models/__init__.py,sha256=UB7nfHoE6hGcjfzy7w8AmuKVmYrTg9wIgGjG8GWziJ0,143
-wizelit_sdk/models/base.py,sha256=aEPGMZVczKnlWz4Ps99e_xI5TcuSV3DxCigRMU5BnhE,704
-wizelit_sdk/models/job.py,sha256=P68Vb1k77Z_Tha4dE0GzrLPa0LJrnMCxyYMENZyD7Kc,2480
-wizelit_sdk-0.1.29.dist-info/METADATA,sha256=iHeysF2Hd1I49-GtFeqEVIfmK0u_LHQIXtFc5OavD0g,3297
-wizelit_sdk-0.1.29.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-wizelit_sdk-0.1.29.dist-info/RECORD,,