tamar-model-client 0.1.20__py3-none-any.whl → 0.1.22__py3-none-any.whl

tamar_model_client/core/http_fallback.py

@@ -0,0 +1,249 @@
+"""
+HTTP fallback functionality for resilient clients
+
+This module provides mixin classes for HTTP-based fallback when gRPC
+connections fail, supporting both synchronous and asynchronous clients.
+"""
+
+import json
+import logging
+from typing import Optional, Iterator, AsyncIterator, Dict, Any
+
+from . import generate_request_id, get_protected_logger
+from ..schemas import ModelRequest, ModelResponse
+
+logger = get_protected_logger(__name__)
+
+
+class HttpFallbackMixin:
+    """HTTP fallback functionality for synchronous clients"""
+    
+    def _ensure_http_client(self) -> None:
+        """Ensure HTTP client is initialized"""
+        if not hasattr(self, '_http_client') or not self._http_client:
+            import requests
+            self._http_client = requests.Session()
+            
+            # Set authentication header if available
+            # Note: JWT token will be set per request in headers
+            
+            # Set default headers
+            self._http_client.headers.update({
+                'Content-Type': 'application/json',
+                'User-Agent': 'TamarModelClient/1.0'
+            })
+    
+    def _convert_to_http_format(self, model_request: ModelRequest) -> Dict[str, Any]:
+        """Convert ModelRequest to HTTP payload format"""
+        payload = {
+            "provider": model_request.provider.value,
+            "model": model_request.model,
+            "user_context": model_request.user_context.model_dump(),
+            "stream": model_request.stream
+        }
+        
+        # Add provider-specific fields
+        if hasattr(model_request, 'messages') and model_request.messages:
+            payload['messages'] = model_request.messages
+        if hasattr(model_request, 'contents') and model_request.contents:
+            payload['contents'] = model_request.contents
+        
+        # Add optional fields
+        if model_request.channel:
+            payload['channel'] = model_request.channel.value
+        if model_request.invoke_type:
+            payload['invoke_type'] = model_request.invoke_type.value
+            
+        # Add extra parameters
+        if hasattr(model_request, 'model_extra') and model_request.model_extra:
+            for key, value in model_request.model_extra.items():
+                if key not in payload:
+                    payload[key] = value
+                
+        return payload
+    
+    def _handle_http_stream(self, url: str, payload: Dict[str, Any], 
+                           timeout: Optional[float], request_id: str, headers: Dict[str, str]) -> Iterator[ModelResponse]:
+        """Handle HTTP streaming response"""
+        import requests
+        
+        response = self._http_client.post(
+            url,
+            json=payload,
+            timeout=timeout or 30,
+            headers=headers,
+            stream=True
+        )
+        response.raise_for_status()
+        
+        # Parse SSE stream
+        for line in response.iter_lines():
+            if line:
+                line_str = line.decode('utf-8')
+                if line_str.startswith('data: '):
+                    data_str = line_str[6:]
+                    if data_str == '[DONE]':
+                        break
+                    try:
+                        data = json.loads(data_str)
+                        yield ModelResponse(**data)
+                    except json.JSONDecodeError:
+                        logger.warning(f"Failed to parse streaming response: {data_str}")
+    
+    def _invoke_http_fallback(self, model_request: ModelRequest, 
+                             timeout: Optional[float] = None,
+                             request_id: Optional[str] = None) -> Any:
+        """HTTP fallback implementation"""
+        self._ensure_http_client()
+        
+        # Generate request ID if not provided
+        if not request_id:
+            request_id = generate_request_id()
+        
+        # Log fallback usage
+        logger.warning(
+            f"🔻 Using HTTP fallback for request",
+            extra={
+                "request_id": request_id,
+                "provider": model_request.provider.value,
+                "model": model_request.model,
+                "fallback_url": self.http_fallback_url
+            }
+        )
+        
+        # Convert to HTTP format
+        http_payload = self._convert_to_http_format(model_request)
+        
+        # Construct URL
+        url = f"{self.http_fallback_url}/v1/invoke"
+        
+        # Build headers with authentication
+        headers = {'X-Request-ID': request_id}
+        if hasattr(self, 'jwt_token') and self.jwt_token:
+            headers['Authorization'] = f'Bearer {self.jwt_token}'
+        
+        if model_request.stream:
+            # Return streaming iterator
+            return self._handle_http_stream(url, http_payload, timeout, request_id, headers)
+        else:
+            # Non-streaming request
+            response = self._http_client.post(
+                url,
+                json=http_payload,
+                timeout=timeout or 30,
+                headers=headers
+            )
+            response.raise_for_status()
+            
+            # Parse response
+            data = response.json()
+            return ModelResponse(**data)
+
+
+class AsyncHttpFallbackMixin:
+    """HTTP fallback functionality for asynchronous clients"""
+    
+    async def _ensure_http_client(self) -> None:
+        """Ensure async HTTP client is initialized"""
+        if not hasattr(self, '_http_session') or not self._http_session:
+            import aiohttp
+            self._http_session = aiohttp.ClientSession(
+                headers={
+                    'Content-Type': 'application/json',
+                    'User-Agent': 'AsyncTamarModelClient/1.0'
+                }
+            )
+            
+            # Note: JWT token will be set per request in headers
+    
+    def _convert_to_http_format(self, model_request: ModelRequest) -> Dict[str, Any]:
+        """Convert ModelRequest to HTTP payload format (reuse sync version)"""
+        # This method doesn't need to be async, so we can reuse the sync version
+        return HttpFallbackMixin._convert_to_http_format(self, model_request)
+    
+    async def _handle_http_stream(self, url: str, payload: Dict[str, Any],
+                                 timeout: Optional[float], request_id: str, headers: Dict[str, str]) -> AsyncIterator[ModelResponse]:
+        """Handle async HTTP streaming response"""
+        import aiohttp
+        
+        timeout_obj = aiohttp.ClientTimeout(total=timeout or 30) if timeout else None
+        
+        async with self._http_session.post(
+            url,
+            json=payload,
+            timeout=timeout_obj,
+            headers=headers
+        ) as response:
+            response.raise_for_status()
+            
+            # Parse SSE stream
+            async for line_bytes in response.content:
+                if line_bytes:
+                    line_str = line_bytes.decode('utf-8').strip()
+                    if line_str.startswith('data: '):
+                        data_str = line_str[6:]
+                        if data_str == '[DONE]':
+                            break
+                        try:
+                            data = json.loads(data_str)
+                            yield ModelResponse(**data)
+                        except json.JSONDecodeError:
+                            logger.warning(f"Failed to parse streaming response: {data_str}")
+    
+    async def _invoke_http_fallback(self, model_request: ModelRequest,
+                                   timeout: Optional[float] = None,
+                                   request_id: Optional[str] = None) -> Any:
+        """Async HTTP fallback implementation"""
+        await self._ensure_http_client()
+        
+        # Generate request ID if not provided
+        if not request_id:
+            request_id = generate_request_id()
+        
+        # Log fallback usage
+        logger.warning(
+            f"🔻 Using HTTP fallback for request",
+            extra={
+                "request_id": request_id,
+                "provider": model_request.provider.value,
+                "model": model_request.model,
+                "fallback_url": self.http_fallback_url
+            }
+        )
+        
+        # Convert to HTTP format
+        http_payload = self._convert_to_http_format(model_request)
+        
+        # Construct URL
+        url = f"{self.http_fallback_url}/v1/invoke"
+        
+        # Build headers with authentication
+        headers = {'X-Request-ID': request_id}
+        if hasattr(self, 'jwt_token') and self.jwt_token:
+            headers['Authorization'] = f'Bearer {self.jwt_token}'
+        
+        if model_request.stream:
+            # Return async streaming iterator
+            return self._handle_http_stream(url, http_payload, timeout, request_id, headers)
+        else:
+            # Non-streaming request
+            import aiohttp
+            timeout_obj = aiohttp.ClientTimeout(total=timeout or 30) if timeout else None
+            
+            async with self._http_session.post(
+                url,
+                json=http_payload,
+                timeout=timeout_obj,
+                headers=headers
+            ) as response:
+                response.raise_for_status()
+                
+                # Parse response
+                data = await response.json()
+                return ModelResponse(**data)
+    
+    async def _cleanup_http_session(self) -> None:
+        """Clean up HTTP session"""
+        if hasattr(self, '_http_session') and self._http_session:
+            await self._http_session.close()
+            self._http_session = None

tamar_model_client/core/logging_setup.py

@@ -6,7 +6,8 @@ It includes request ID tracking, JSON formatting, and consistent log configurati
 """
 
 import logging
-from typing import Optional
+import threading
+from typing import Optional, Dict
 
 from ..json_formatter import JSONFormatter
 from .utils import get_request_id
@@ -14,6 +15,15 @@ from .utils import get_request_id
 # gRPC 消息长度限制（32位系统兼容）
 MAX_MESSAGE_LENGTH = 2 ** 31 - 1
 
+# SDK 专用的 logger 名称前缀
+TAMAR_LOGGER_PREFIX = "tamar_model_client"
+
+# 线程安全的 logger 配置锁
+_logger_lock = threading.Lock()
+
+# 已配置的 logger 缓存
+_configured_loggers: Dict[str, logging.Logger] = {}
+
 
 class RequestIdFilter(logging.Filter):
     """
@@ -38,9 +48,54 @@ class RequestIdFilter(logging.Filter):
         return True
 
 
+class TamarLoggerAdapter:
+    """
+    Logger 适配器，确保 SDK 的日志格式不被外部修改
+    
+    这个适配器包装了原始的 logger，拦截所有的日志方法调用，
+    确保使用正确的格式和处理器。
+    """
+    
+    def __init__(self, logger: logging.Logger):
+        self._logger = logger
+        self._lock = threading.Lock()
+        
+    def _ensure_format(self):
+        """确保 logger 使用正确的格式"""
+        with self._lock:
+            # 检查并修复处理器
+            for handler in self._logger.handlers[:]:
+                if not isinstance(handler.formatter, JSONFormatter):
+                    handler.setFormatter(JSONFormatter())
+            
+            # 确保 propagate 设置正确
+            if self._logger.propagate:
+                self._logger.propagate = False
+    
+    def _log(self, level, msg, *args, **kwargs):
+        """统一的日志方法"""
+        self._ensure_format()
+        getattr(self._logger, level)(msg, *args, **kwargs)
+    
+    def debug(self, msg, *args, **kwargs):
+        self._log('debug', msg, *args, **kwargs)
+    
+    def info(self, msg, *args, **kwargs):
+        self._log('info', msg, *args, **kwargs)
+    
+    def warning(self, msg, *args, **kwargs):
+        self._log('warning', msg, *args, **kwargs)
+    
+    def error(self, msg, *args, **kwargs):
+        self._log('error', msg, *args, **kwargs)
+    
+    def critical(self, msg, *args, **kwargs):
+        self._log('critical', msg, *args, **kwargs)
+
+
 def setup_logger(logger_name: str, level: int = logging.INFO) -> logging.Logger:
     """
-    设置并配置logger
+    设置并配置logger (保持向后兼容)
     
     为指定的logger配置处理器、格式化器和过滤器。
     如果logger已经有处理器，则不会重复配置。
@@ -57,28 +112,83 @@ def setup_logger(logger_name: str, level: int = logging.INFO) -> logging.Logger:
     - 添加请求ID过滤器用于请求追踪
     - 避免重复配置
     """
-    logger = logging.getLogger(logger_name)
+    # 确保 logger 名称以 SDK 前缀开始
+    if not logger_name.startswith(TAMAR_LOGGER_PREFIX):
+        logger_name = f"{TAMAR_LOGGER_PREFIX}.{logger_name}"
     
-    # 仅在没有处理器时配置，避免重复配置
-    if not logger.hasHandlers():
-        # 创建控制台日志处理器
+    with _logger_lock:
+        # 检查缓存
+        if logger_name in _configured_loggers:
+            return _configured_loggers[logger_name]
+        
+        logger = logging.getLogger(logger_name)
+        
+        # 强制清除所有现有的处理器
+        logger.handlers.clear()
+        
+        # 创建专用的控制台处理器
         console_handler = logging.StreamHandler()
+        console_handler.setFormatter(JSONFormatter())
         
-        # 使用自定义的 JSON 格式化器，提供结构化日志输出
-        formatter = JSONFormatter()
-        console_handler.setFormatter(formatter)
+        # 为处理器设置唯一标识，便于识别
+        console_handler.name = f"tamar_handler_{id(console_handler)}"
         
-        # 为logger添加处理器
+        # 添加处理器
         logger.addHandler(console_handler)
         
         # 设置日志级别
         logger.setLevel(level)
         
-        # 添加自定义的请求ID过滤器，用于请求追踪
+        # 添加请求ID过滤器
         logger.addFilter(RequestIdFilter())
         
-        # 关键：设置 propagate = False，防止日志传播到父logger
-        # 这样可以避免测试脚本的日志格式影响客户端日志
+        # 关键设置：
+        # 1. 不传播到父 logger
         logger.propagate = False
+        
+        # 2. 禁用外部修改（Python 3.8+）
+        if hasattr(logger, 'disabled'):
+            logger.disabled = False
+        
+        # 缓存配置好的 logger
+        _configured_loggers[logger_name] = logger
+        
+        return logger
+
+
+def get_protected_logger(logger_name: str, level: int = logging.INFO) -> TamarLoggerAdapter:
+    """
+    获取受保护的 logger
+    
+    返回一个 logger 适配器，确保日志格式不会被外部修改。
     
-    return logger
+    Args:
+        logger_name: logger的名称
+        level: 日志级别，默认为 INFO
+        
+    Returns:
+        TamarLoggerAdapter: 受保护的 logger 适配器
+    """
+    logger = setup_logger(logger_name, level)
+    return TamarLoggerAdapter(logger)
+
+
+def reset_logger_config(logger_name: str) -> None:
+    """
+    重置 logger 配置
+    
+    用于测试或需要重新配置的场景。
+    
+    Args:
+        logger_name: logger的名称
+    """
+    if not logger_name.startswith(TAMAR_LOGGER_PREFIX):
+        logger_name = f"{TAMAR_LOGGER_PREFIX}.{logger_name}"
+    
+    with _logger_lock:
+        if logger_name in _configured_loggers:
+            del _configured_loggers[logger_name]
+            
+        logger = logging.getLogger(logger_name)
+        logger.handlers.clear()
+        logger.filters.clear()

tamar_model_client/error_handler.py

@@ -43,9 +43,32 @@ class GrpcErrorHandler:
         error_context = ErrorContext(error, context)
         
         # 记录详细错误日志
+        # 将error_context的重要信息平铺到日志的data字段中
+        log_data = {
+            "log_type": "info",
+            "request_id": error_context.request_id,
+            "data": {
+                "error_code": error_context.error_code.name if error_context.error_code else 'UNKNOWN',
+                "error_message": error_context.error_message,
+                "provider": error_context.provider,
+                "model": error_context.model,
+                "method": error_context.method,
+                "retry_count": error_context.retry_count,
+                "category": error_context._get_error_category(),
+                "is_retryable": error_context._is_retryable(),
+                "suggested_action": error_context._get_suggested_action(),
+                "debug_string": error_context.error_debug_string,
+                "is_network_cancelled": error_context.is_network_cancelled() if error_context.error_code == grpc.StatusCode.CANCELLED else None
+            }
+        }
+        
+        # 如果上下文中有 duration，添加到日志中
+        if 'duration' in context:
+            log_data['duration'] = context['duration']
+        
         self.logger.error(
-            f"gRPC Error occurred: {error_context.error_code}",
-            extra=error_context.to_dict()
+            f"gRPC Error occurred: {error_context.error_code.name if error_context.error_code else 'UNKNOWN'}",
+            extra=log_data
         )
         
         # 更新错误统计
@@ -192,6 +215,10 @@ class EnhancedRetryHandler:
         Raises:
             TamarModelException: 包装后的异常
         """
+        # 记录开始时间
+        import time
+        method_start_time = time.time()
+        
         context = context or {}
         last_exception = None
         
@@ -207,13 +234,32 @@ class EnhancedRetryHandler:
                 # 判断是否可以重试
                 if not self._should_retry(e, attempt):
                     # 不可重试或已达到最大重试次数
+                    current_duration = time.time() - method_start_time
+                    context['duration'] = current_duration
                     last_exception = self.error_handler.handle_error(e, context)
                     break
+                
+                # 计算当前耗时
+                current_duration = time.time() - method_start_time
                     
                 # 记录重试日志
+                log_data = {
+                    "log_type": "info",
+                    "request_id": error_context.request_id,
+                    "data": {
+                        "error_code": error_context.error_code.name if error_context.error_code else 'UNKNOWN',
+                        "error_message": error_context.error_message,
+                        "retry_count": attempt,
+                        "max_retries": self.max_retries,
+                        "category": error_context._get_error_category(),
+                        "is_retryable": True,  # 既然在重试，说明是可重试的
+                        "method": error_context.method
+                    },
+                    "duration": current_duration
+                }
                 logger.warning(
                     f"Attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()}",
-                    extra=error_context.to_dict()
+                    extra=log_data
                 )
                 
                 # 执行退避等待
@@ -221,6 +267,7 @@ class EnhancedRetryHandler:
                     delay = self._calculate_backoff(attempt)
                     await asyncio.sleep(delay)
                 
+                context['duration'] = current_duration
                 last_exception = self.error_handler.handle_error(e, context)
             
             except Exception as e:
@@ -239,12 +286,19 @@ class EnhancedRetryHandler:
     
     def _should_retry(self, error: grpc.RpcError, attempt: int) -> bool:
         """判断是否应该重试"""
-        if attempt >= self.max_retries:
-            return False
-            
         error_code = error.code()
         policy = RETRY_POLICY.get(error_code, {})
         
+        # 先检查错误级别的 max_attempts 配置
+        # max_attempts 表示最大重试次数（不包括初始请求）
+        error_max_attempts = policy.get('max_attempts', self.max_retries)
+        if attempt >= error_max_attempts:
+            return False
+            
+        # 再检查全局的 max_retries
+        if attempt >= self.max_retries:
+            return False
+        
         # 检查基本重试策略
         retryable = policy.get('retryable', False)
         if retryable == False:

tamar_model_client/exceptions.py

@@ -17,7 +17,10 @@ ERROR_CATEGORIES = {
     'NETWORK': [
         grpc.StatusCode.UNAVAILABLE,
         grpc.StatusCode.DEADLINE_EXCEEDED,
-        grpc.StatusCode.ABORTED,
+        grpc.StatusCode.CANCELLED,      # 网络中断导致的取消
+    ],
+    'CONCURRENCY': [
+        grpc.StatusCode.ABORTED,        # 并发冲突，单独分类便于监控
     ],
     'AUTH': [
         grpc.StatusCode.UNAUTHENTICATED,
@@ -71,6 +74,19 @@ RETRY_POLICY = {
         'action': 'refresh_token',  # 特殊动作
         'max_attempts': 1
     },
+    grpc.StatusCode.CANCELLED: {
+        'retryable': True,
+        'backoff': 'linear',        # 线性退避，网络问题通常不需要指数退避
+        'max_attempts': 2,          # 最大重试次数（不包括初始请求），总共会尝试3次
+        'check_details': False      # 不检查详细信息，统一重试
+    },
+    grpc.StatusCode.ABORTED: {
+        'retryable': True,
+        'backoff': 'exponential',   # 指数退避，避免加剧并发竞争
+        'max_attempts': 3,          # 适中的重试次数
+        'jitter': True,             # 添加随机延迟，减少竞争
+        'check_details': False
+    },
     # 不可重试的错误
     grpc.StatusCode.INVALID_ARGUMENT: {'retryable': False},
     grpc.StatusCode.NOT_FOUND: {'retryable': False},
@@ -160,6 +176,7 @@ class ErrorContext:
         """获取建议的处理动作"""
         suggestions = {
             'NETWORK': '检查网络连接，稍后重试',
+            'CONCURRENCY': '并发冲突，系统会自动重试',
             'AUTH': '检查认证信息，可能需要刷新 Token',
             'VALIDATION': '检查请求参数是否正确',
             'RESOURCE': '检查资源限制或等待一段时间',
@@ -167,6 +184,37 @@ class ErrorContext:
             'DATA': '数据损坏或丢失，请检查输入数据',
         }
         return suggestions.get(self._get_error_category(), '未知错误，请联系技术支持')
+    
+    def is_network_cancelled(self) -> bool:
+        """
+        判断 CANCELLED 错误是否由网络中断导致
+        
+        Returns:
+            bool: 如果是网络中断导致的 CANCELLED 返回 True
+        """
+        if self.error_code != grpc.StatusCode.CANCELLED:
+            return False
+            
+        # 检查错误消息中是否包含网络相关的关键词
+        error_msg = (self.error_message or '').lower()
+        debug_msg = (self.error_debug_string or '').lower()
+        
+        network_patterns = [
+            'connection reset',
+            'connection refused', 
+            'connection closed',
+            'network unreachable',
+            'broken pipe',
+            'socket closed',
+            'eof',
+            'transport'
+        ]
+        
+        for pattern in network_patterns:
+            if pattern in error_msg or pattern in debug_msg:
+                return True
+                
+        return False
 
 
 # ===== 异常类层级 =====