Taiwan Stock Agent

# Taiwan Stock Agent - Error Handling System ## Overview A comprehensive, production-ready error handling system has been implemented for the Taiwan Stock Agent MCP server. This system provides structured error responses, proper validation, retry mechanisms, and circuit breaker patterns for robust operation. ## Key Components ### 1. Custom Exception Hierarchy **Base Exception**: `TwStockAgentError` - Structured error information with codes, severity, and context - Error enrichment capabilities - MCP protocol compliance - JSON serialization support **Specialized Exceptions**: - **Stock Exceptions**: `StockNotFoundError`, `InvalidStockCodeError`, `StockDataUnavailableError`, `StockMarketClosedError` - **API Exceptions**: `RateLimitError`, `DataSourceUnavailableError`, `ExternalAPIError`, `TimeoutError` - **Cache Exceptions**: `CacheConnectionError`, `CacheKeyError`, `CacheSerializationError` - **MCP Exceptions**: `MCPValidationError`, `MCPResourceError`, `MCPToolError` - **Validation Exceptions**: `ParameterValidationError`, `DataFormatError`, `TypeValidationError` ### 2. Input Validation System **Stock Code Validation**: - Taiwan stock code format validation (4-6 digits) - Support for ETFs (0050-0999) and regular stocks (1000-9999) - Stock type detection and market classification - Bulk validation capabilities **Parameter Validation**: - Type checking and conversion - Range validation - Enum validation - String length validation - Date format validation ### 3. Error Context and Enrichment **Error Context**: `ErrorContext` - Correlation IDs for tracking - Timestamps - Stock codes - Operation names - User IDs - Request IDs - Additional metadata **Error Enrichment**: `ErrorEnricher` - Automatic context addition - Exception type mapping - Severity determination - Cause chain preservation ### 4. Production Error Handling Patterns **Retry Manager**: - Exponential backoff with jitter - Configurable retry policies - Non-retryable error detection - Maximum retry limits **Circuit Breaker**: - Failure threshold monitoring - Automatic state management (CLOSED/OPEN/HALF_OPEN) - Service recovery detection - Graceful degradation **Error Decorators**: - `@with_error_handling` - Synchronous error handling - `@with_async_error_handling` - Asynchronous error handling - `@with_retry` - Retry mechanism - `@mcp_error_handler` - MCP tool error handling ### 5. MCP Protocol Integration **MCP Error Handler**: `MCPErrorHandler` - Tool error handling - Resource error handling - Validation error handling - JSON-RPC compliant responses **Response Formatter**: `MCPResponseFormatter` - Stock data formatting - Price data formatting - Error response formatting - Metadata preservation ### 6. Logging and Monitoring **Structured Logging**: `ErrorLogger` - Severity-based log levels - Correlation ID tracking - Context preservation - Configurable output ## Implementation Examples ### Basic Error Handling ```python from tw_stock_agent.exceptions import StockNotFoundError from tw_stock_agent.utils.validation import StockCodeValidator # Validate stock code try: validated_code = StockCodeValidator.validate_stock_code("2330") except InvalidStockCodeError as e: print(f"Error: {e.message}") print(f"Suggestions: {e.suggestions}") ``` ### Service Layer with Decorators ```python @with_async_error_handling(operation="fetch_stock_data") @with_retry(max_retries=3, base_delay=1.0) async def fetch_stock_data(stock_code: str): # Service implementation pass ``` ### MCP Tool Error Handling ```python @mcp_error_handler("get_stock_data") async def get_stock_data_tool(stock_code: str): try: return await get_stock_data(stock_code) except TwStockAgentError as e: # Automatically handled by decorator raise ``` ### Circuit Breaker Usage ```python circuit_breaker = CircuitBreaker(failure_threshold=3) async def api_call(): return await circuit_breaker.acall(external_api_function) ``` ## Error Response Formats ### Standard Error Response ```json { "error": true, "error_code": "STOCK_NOT_FOUND", "message": "Stock with code '9999' was not found", "severity": "medium", "timestamp": "2023-12-01T10:00:00.000000", "correlation_id": "abc123-def456-ghi789", "stock_code": "9999", "suggestions": [ "Verify the stock code is correct", "Check if the stock is listed on Taiwan stock exchanges" ] } ``` ### MCP Error Response ```json { "error": { "code": "STOCK_NOT_FOUND", "message": "Stock with code '9999' was not found", "data": { "severity": "medium", "correlation_id": "abc123-def456-ghi789", "timestamp": "2023-12-01T10:00:00.000000", "suggestions": ["Verify the stock code is correct"], "context": { "stock_code": "9999", "operation": "tool_execution_get_stock_data" } } } } ``` ## Validation Rules ### Taiwan Stock Codes - **Format**: 4-6 digits only - **ETFs**: 0050-0999 (e.g., 0050 for Taiwan 50 ETF) - **Regular Stocks**: 1000-9999 (e.g., 2330 for TSMC) - **Reserved Codes**: 0000-0003, 9999 (invalid) ### Common Stock Examples - `2330` - Taiwan Semiconductor (TSMC) - `2317` - Hon Hai Precision (Foxconn) - `1301` - Formosa Plastics Corp - `0050` - Taiwan Top 50 ETF - `1101` - Taiwan Cement Corp ## Testing The error handling system includes comprehensive tests: ### Unit Tests - Exception creation and serialization - Validation logic - Error enrichment - Retry mechanisms - Circuit breaker functionality - MCP error handling ### Integration Tests - End-to-end error flows - Service layer integration - MCP protocol compliance - Concurrent error handling - Real-world scenarios ### Running Tests ```bash # Run all error handling tests uv run pytest tests/unit/test_exceptions.py -v uv run pytest tests/unit/test_validation.py -v uv run pytest tests/unit/test_error_handler.py -v uv run pytest tests/unit/test_mcp_error_handler.py -v # Run integration tests uv run pytest tests/integration/test_error_handling_integration.py -v ``` ## Benefits 1. **Robust Error Handling**: Comprehensive coverage of all error scenarios 2. **Production Ready**: Circuit breakers, retries, and graceful degradation 3. **Developer Friendly**: Clear error messages and helpful suggestions 4. **MCP Compliant**: Proper JSON-RPC error responses 5. **Debuggable**: Correlation IDs and structured logging 6. **Maintainable**: Clean exception hierarchy and error handling patterns 7. **Performance**: Efficient error processing with minimal overhead 8. **Testable**: Comprehensive test coverage for all components ## File Structure ``` tw_stock_agent/ ├── exceptions/ │ ├── __init__.py # Exception exports │ ├── base.py # Base exception classes │ ├── stock_exceptions.py # Stock-specific exceptions │ ├── api_exceptions.py # API-related exceptions │ ├── cache_exceptions.py # Cache-related exceptions │ ├── mcp_exceptions.py # MCP protocol exceptions │ └── validation_exceptions.py # Validation exceptions ├── utils/ │ ├── error_handler.py # Error handling utilities │ ├── validation.py # Input validation │ └── mcp_error_handler.py # MCP error handling └── services/ └── stock_service.py # Updated with error handling tests/ ├── unit/ │ ├── test_exceptions.py │ ├── test_validation.py │ ├── test_error_handler.py │ └── test_mcp_error_handler.py └── integration/ └── test_error_handling_integration.py ``` This error handling system provides a solid foundation for building reliable, production-ready applications with the Taiwan Stock Agent MCP server.