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

tamar_model_client/core/utils.py

@@ -0,0 +1,171 @@
+"""
+Common utility functions for Tamar Model Client
+
+This module contains shared utility functions used by both sync and async clients.
+All functions in this module are pure functions without side effects.
+"""
+
+import base64
+import uuid
+from typing import Any, Iterable
+from contextvars import ContextVar
+
+from openai import NOT_GIVEN
+from pydantic import BaseModel
+
+# 使用 contextvars 管理请求ID，支持异步和同步上下文中的请求追踪
+_request_id: ContextVar[str] = ContextVar('request_id', default='-')
+
+
+def is_effective_value(value) -> bool:
+    """
+    递归判断值是否为有效值
+    
+    用于过滤掉空值、None、NOT_GIVEN 等无意义的参数，
+    确保只有有效的参数被发送到服务器。
+    
+    Args:
+        value: 待检查的值
+        
+    Returns:
+        bool: True 表示值有效，False 表示值无效
+        
+    处理的无效值类型：
+    - None 和 NOT_GIVEN
+    - 空字符串（仅包含空白字符）
+    - 空字节序列
+    - 空字典（所有值都无效）
+    - 空列表（所有元素都无效）
+    """
+    if value is None or value is NOT_GIVEN:
+        return False
+
+    if isinstance(value, str):
+        return value.strip() != ""
+
+    if isinstance(value, bytes):
+        return len(value) > 0
+
+    if isinstance(value, dict):
+        # 递归检查字典中的所有值
+        for v in value.values():
+            if is_effective_value(v):
+                return True
+        return False
+
+    if isinstance(value, list):
+        # 递归检查列表中的所有元素
+        for item in value:
+            if is_effective_value(item):
+                return True
+        return False
+
+    # 其他类型（int/float/bool）只要不是 None 就算有效
+    return True
+
+
+def serialize_value(value):
+    """
+    递归序列化值，处理各种复杂数据类型
+    
+    将 Pydantic 模型、字典、列表、字节等复杂类型转换为
+    可以发送给 gRPC 服务的简单类型。
+    
+    Args:
+        value: 待序列化的值
+        
+    Returns:
+        序列化后的值，如果值无效则返回 None
+        
+    支持的类型转换：
+    - BaseModel -> dict (通过 model_dump)
+    - bytes -> base64 字符串
+    - dict -> 递归处理所有键值对
+    - list -> 递归处理所有元素
+    - 其他类型 -> 直接返回
+    """
+    if not is_effective_value(value):
+        return None
+    if isinstance(value, BaseModel):
+        return serialize_value(value.model_dump())
+    if hasattr(value, "dict") and callable(value.dict):
+        return serialize_value(value.dict())
+    if isinstance(value, dict):
+        return {k: serialize_value(v) for k, v in value.items()}
+    if isinstance(value, list) or (isinstance(value, Iterable) and not isinstance(value, (str, bytes))):
+        return [serialize_value(v) for v in value]
+    if isinstance(value, bytes):
+        return f"bytes:{base64.b64encode(value).decode('utf-8')}"
+    return value
+
+
+def remove_none_from_dict(data: Any) -> Any:
+    """
+    递归清理数据结构中的 None 值
+    
+    遍历字典和列表，移除所有值为 None 的字段，
+    确保发送给服务器的数据结构干净整洁。
+    
+    Args:
+        data: 待清理的数据（dict、list 或其他类型）
+        
+    Returns:
+        清理后的数据结构
+        
+    示例：
+        >>> remove_none_from_dict({"a": 1, "b": None, "c": {"d": None, "e": 2}})
+        {"a": 1, "c": {"e": 2}}
+    """
+    if isinstance(data, dict):
+        new_dict = {}
+        for key, value in data.items():
+            if value is None:
+                continue
+            # 递归清理嵌套结构
+            cleaned_value = remove_none_from_dict(value)
+            new_dict[key] = cleaned_value
+        return new_dict
+    elif isinstance(data, list):
+        # 递归处理列表中的每个元素
+        return [remove_none_from_dict(item) for item in data]
+    else:
+        # 其他类型直接返回
+        return data
+
+
+def generate_request_id():
+    """
+    生成唯一的请求ID
+    
+    使用 UUID4 生成全局唯一的请求标识符，
+    用于追踪和调试单个请求的生命周期。
+    
+    Returns:
+        str: 格式为 "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx" 的UUID字符串
+    """
+    return str(uuid.uuid4())
+
+
+def set_request_id(request_id: str):
+    """
+    设置当前上下文的请求ID
+    
+    在 ContextVar 中设置请求ID，使得在整个异步调用链中
+    都能访问到同一个请求ID，便于日志追踪。
+    
+    Args:
+        request_id: 要设置的请求ID字符串
+    """
+    _request_id.set(request_id)
+
+
+def get_request_id() -> str:
+    """
+    获取当前上下文的请求ID
+    
+    从 ContextVar 中获取当前的请求ID，如果没有设置则返回默认值 '-'
+    
+    Returns:
+        str: 当前的请求ID或默认值
+    """
+    return _request_id.get()

tamar_model_client/error_handler.py

@@ -0,0 +1,283 @@
+"""
+gRPC 错误处理器
+
+提供统一的错误处理、恢复策略和重试逻辑。
+"""
+
+import asyncio
+import random
+import grpc
+import logging
+from typing import Optional, Dict, Any, Callable, Union
+from collections import defaultdict
+
+from .exceptions import (
+    ErrorContext, TamarModelException,
+    NetworkException, ConnectionException, TimeoutException,
+    AuthenticationException, TokenExpiredException, PermissionDeniedException,
+    ValidationException, InvalidParameterException,
+    RateLimitException, ProviderException,
+    ERROR_CATEGORIES, RETRY_POLICY, ErrorStats
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class GrpcErrorHandler:
+    """统一的 gRPC 错误处理器"""
+    
+    def __init__(self, client_logger: Optional[logging.Logger] = None):
+        self.logger = client_logger or logger
+        self.error_stats = ErrorStats()
+        
+    def handle_error(self, error: Union[grpc.RpcError, Exception], context: dict) -> TamarModelException:
+        """
+        统一错误处理流程：
+        1. 创建错误上下文
+        2. 记录错误日志
+        3. 更新错误统计
+        4. 决定错误类型
+        5. 返回相应异常
+        """
+        error_context = ErrorContext(error, context)
+        
+        # 记录详细错误日志
+        self.logger.error(
+            f"gRPC Error occurred: {error_context.error_code}",
+            extra=error_context.to_dict()
+        )
+        
+        # 更新错误统计
+        if error_context.error_code:
+            self.error_stats.record_error(error_context.error_code)
+        
+        # 根据错误类型返回相应异常
+        return self._create_exception(error_context)
+    
+    def _create_exception(self, error_context: ErrorContext) -> TamarModelException:
+        """根据错误上下文创建相应的异常"""
+        error_code = error_context.error_code
+        
+        if not error_code:
+            return TamarModelException(error_context)
+        
+        # 认证相关错误
+        if error_code in ERROR_CATEGORIES['AUTH']:
+            if error_code == grpc.StatusCode.UNAUTHENTICATED:
+                return TokenExpiredException(error_context)
+            else:
+                return PermissionDeniedException(error_context)
+        
+        # 网络相关错误
+        elif error_code in ERROR_CATEGORIES['NETWORK']:
+            if error_code == grpc.StatusCode.DEADLINE_EXCEEDED:
+                return TimeoutException(error_context)
+            else:
+                return ConnectionException(error_context)
+        
+        # 验证相关错误
+        elif error_code in ERROR_CATEGORIES['VALIDATION']:
+            return InvalidParameterException(error_context)
+        
+        # 资源相关错误
+        elif error_code == grpc.StatusCode.RESOURCE_EXHAUSTED:
+            return RateLimitException(error_context)
+        
+        # 服务商相关错误
+        elif error_code in ERROR_CATEGORIES['PROVIDER']:
+            return ProviderException(error_context)
+        
+        # 默认错误
+        else:
+            return TamarModelException(error_context)
+    
+    def get_error_stats(self) -> Dict[str, Any]:
+        """获取错误统计信息"""
+        return self.error_stats.get_stats()
+    
+    def reset_stats(self):
+        """重置错误统计"""
+        self.error_stats.reset()
+
+
+class ErrorRecoveryStrategy:
+    """错误恢复策略"""
+    
+    RECOVERY_ACTIONS = {
+        'refresh_token': 'handle_token_refresh',
+        'reconnect': 'handle_reconnect',
+        'backoff': 'handle_backoff',
+        'circuit_break': 'handle_circuit_break',
+    }
+    
+    def __init__(self, client):
+        self.client = client
+        
+    async def recover_from_error(self, error_context: ErrorContext):
+        """根据错误类型执行恢复动作"""
+        if not error_context.error_code:
+            return
+            
+        policy = RETRY_POLICY.get(error_context.error_code, {})
+        
+        if action := policy.get('action'):
+            if action in self.RECOVERY_ACTIONS:
+                handler = getattr(self, self.RECOVERY_ACTIONS[action])
+                await handler(error_context)
+    
+    async def handle_token_refresh(self, error_context: ErrorContext):
+        """处理 Token 刷新"""
+        self.client.logger.info("Attempting to refresh JWT token")
+        # 这里需要客户端实现 _refresh_jwt_token 方法
+        if hasattr(self.client, '_refresh_jwt_token'):
+            await self.client._refresh_jwt_token()
+    
+    async def handle_reconnect(self, error_context: ErrorContext):
+        """处理重连"""
+        self.client.logger.info("Attempting to reconnect channel")
+        # 这里需要客户端实现 _reconnect_channel 方法
+        if hasattr(self.client, '_reconnect_channel'):
+            await self.client._reconnect_channel()
+    
+    async def handle_backoff(self, error_context: ErrorContext):
+        """处理退避等待"""
+        wait_time = self._calculate_backoff(error_context.retry_count)
+        await asyncio.sleep(wait_time)
+    
+    async def handle_circuit_break(self, error_context: ErrorContext):
+        """处理熔断"""
+        self.client.logger.warning("Circuit breaker activated")
+        # 这里可以实现熔断逻辑
+        pass
+    
+    def _calculate_backoff(self, retry_count: int) -> float:
+        """计算退避时间"""
+        base_delay = 1.0
+        max_delay = 60.0
+        jitter_factor = 0.1
+        
+        delay = min(base_delay * (2 ** retry_count), max_delay)
+        jitter = random.uniform(0, delay * jitter_factor)
+        return delay + jitter
+
+
+class EnhancedRetryHandler:
+    """增强的重试处理器"""
+    
+    def __init__(self, max_retries: int = 3, base_delay: float = 1.0):
+        self.max_retries = max_retries
+        self.base_delay = base_delay
+        self.error_handler = GrpcErrorHandler()
+        
+    async def execute_with_retry(
+        self, 
+        func: Callable, 
+        *args, 
+        context: Optional[Dict[str, Any]] = None,
+        **kwargs
+    ):
+        """
+        执行函数并处理重试
+        
+        Args:
+            func: 要执行的函数
+            *args: 函数参数
+            context: 请求上下文信息
+            **kwargs: 函数关键字参数
+            
+        Returns:
+            函数执行结果
+            
+        Raises:
+            TamarModelException: 包装后的异常
+        """
+        context = context or {}
+        last_exception = None
+        
+        for attempt in range(self.max_retries + 1):
+            try:
+                context['retry_count'] = attempt
+                return await func(*args, **kwargs)
+                
+            except (grpc.RpcError, grpc.aio.AioRpcError) as e:
+                # 创建错误上下文
+                error_context = ErrorContext(e, context)
+                
+                # 判断是否可以重试
+                if not self._should_retry(e, attempt):
+                    # 不可重试或已达到最大重试次数
+                    last_exception = self.error_handler.handle_error(e, context)
+                    break
+                    
+                # 记录重试日志
+                logger.warning(
+                    f"Attempt {attempt + 1}/{self.max_retries + 1} failed: {e.code()}",
+                    extra=error_context.to_dict()
+                )
+                
+                # 执行退避等待
+                if attempt < self.max_retries:
+                    delay = self._calculate_backoff(attempt)
+                    await asyncio.sleep(delay)
+                
+                last_exception = self.error_handler.handle_error(e, context)
+            
+            except Exception as e:
+                # 非 gRPC 错误，直接包装抛出
+                context['retry_count'] = attempt
+                error_context = ErrorContext(None, context)
+                error_context.error_message = str(e)
+                last_exception = TamarModelException(error_context)
+                break
+        
+        # 抛出最后的异常
+        if last_exception:
+            raise last_exception
+        else:
+            raise TamarModelException("Unknown error occurred")
+    
+    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, {})
+        
+        # 检查基本重试策略
+        retryable = policy.get('retryable', False)
+        if retryable == False:
+            return False
+        elif retryable == True:
+            return True
+        elif retryable == 'conditional':
+            # 条件重试，需要检查错误详情
+            return self._check_conditional_retry(error)
+        
+        return False
+    
+    def _check_conditional_retry(self, error: grpc.RpcError) -> bool:
+        """检查条件重试"""
+        error_message = error.details().lower() if error.details() else ""
+        
+        # 一些可重试的内部错误模式
+        retryable_patterns = [
+            'temporary', 'timeout', 'unavailable', 
+            'connection', 'network', 'try again'
+        ]
+        
+        for pattern in retryable_patterns:
+            if pattern in error_message:
+                return True
+                
+        return False
+    
+    def _calculate_backoff(self, attempt: int) -> float:
+        """计算退避时间"""
+        max_delay = 60.0
+        jitter_factor = 0.1
+        
+        delay = min(self.base_delay * (2 ** attempt), max_delay)
+        jitter = random.uniform(0, delay * jitter_factor)
+        return delay + jitter