improve error handling

[NJX-njx]

Change Type

• ✨ feat
• 🐛 fix
• ♻️ refactor
• 💄 style
• 👷 build
• ⚡️ perf
• 📝 docs
• 🔨 chore

Description of Change

This PR introduces a comprehensive custom exception class hierarchy to improve error handling, classification, and debugging across the MCPMark codebase.

Key Changes:

1. New Exception System (src/exceptions.py)

   • Created MCPMarkException as the base exception class with support for:
     • Error codes and context information
     • Retryable flag for automatic retry logic
     • Exception chaining to preserve original errors
   • Implemented 20+ specialized exception classes organized into categories:
     • Configuration Errors: MissingConfigurationError, InvalidConfigurationError, ModelConfigurationError
     • Service Errors: MCPServiceError, MCPServiceTimeoutError, MCPServiceAuthenticationError, StateManagerError, TaskManagerError
     • Agent Errors: AgentExecutionError, AgentTimeoutError, LLMRateLimitError, LLMQuotaExceededError, LLMContextWindowExceededError
     • Task Execution Errors: TaskExecutionError, TaskSetupError, TaskCleanupError

2. Enhanced Error Handling (src/errors.py)

   • Updated is_retryable_error() to support both string errors and exception objects
   • Enhanced standardize_error_message() to work with new exception classes
   • Added extract_error_message() utility function
   • Added convert_to_mcpmark_exception() for backward compatibility and gradual migration

3. Core Module Updates

   • evaluator.py: Replaced generic ValueError with InvalidConfigurationError for agent validation
   • factory.py: Added proper exception handling in import_class() using ConfigurationError
   • services.py: Replaced ValueError with InvalidConfigurationError for service validation
   • config_schema.py: Replaced ValueError with MissingConfigurationError and InvalidConfigurationError
   • model_config.py: Replaced ValueError with ModelConfigurationError

4. Agent Module Updates

   • base_agent.py: Replaced all configuration-related exceptions with appropriate custom exceptions
   • mcpmark_agent.py:
     • Replaced configuration exceptions
     • Enhanced LLM error handling with specific exception types (LLMRateLimitError, LLMQuotaExceededError, LLMContextWindowExceededError)
     • Improved timeout handling with AgentTimeoutError

5. Task Manager Updates

   • task_manager.py: Added TaskVerificationError for better verification error handling

Benefits:

• ✅ Better Error Classification: Errors are now properly categorized, making debugging easier
• ✅ Rich Context Information: Each exception includes relevant context (service name, task name, model name, etc.)
• ✅ Automatic Retry Logic: retryable flag enables smarter retry decisions
• ✅ Exception Chaining: Original exceptions are preserved for full stack trace analysis
• ✅ Backward Compatible: Existing code continues to work; is_retryable_error() and standardize_error_message() support both old and new formats
• ✅ Gradual Migration: convert_to_mcpmark_exception() allows incremental adoption

Files Changed:

• ✨ New: src/exceptions.py (320+ lines)
• 🔄 Modified:
  • src/errors.py
  • src/evaluator.py
  • src/factory.py
  • src/services.py
  • src/config/config_schema.py
  • src/model_config.py
  • src/agents/base_agent.py
  • src/agents/mcpmark_agent.py
  • src/base/task_manager.py

Testing:

• ✅ All linter checks pass
• ✅ Exception module imports successfully
• ✅ Error handling functions work with both old and new exception types
• ✅ Backward compatibility verified

Additional Information

Migration Notes:

• This change is backward compatible. Existing code that catches ValueError, RuntimeError, etc. will continue to work.
• The new exception classes can be caught using their specific types or the base MCPMarkException class.
• For gradual migration, use convert_to_mcpmark_exception() to wrap standard exceptions.

Future Improvements:

• Service-specific modules (mcp_services/) can be gradually migrated to use the new exception classes
• Additional exception types can be added as needed for specific error scenarios
• Consider adding exception serialization for distributed error tracking

Related Issues:

This PR addresses the need for better error handling and classification as identified in the project's error handling enhancement requirements.