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

tamar_model_client/core/logging_setup.py

@@ -0,0 +1,194 @@
+"""
+Logging configuration for Tamar Model Client
+
+This module provides centralized logging setup for both sync and async clients.
+It includes request ID tracking, JSON formatting, and consistent log configuration.
+"""
+
+import logging
+import threading
+from typing import Optional, Dict
+
+from ..json_formatter import JSONFormatter
+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):
+    """
+    自定义日志过滤器，向日志记录中添加 request_id
+    
+    这个过滤器从 ContextVar 中获取当前请求的 ID，
+    并将其添加到日志记录中，便于追踪和调试。
+    """
+
+    def filter(self, record):
+        """
+        过滤日志记录，添加 request_id 字段
+        
+        Args:
+            record: 日志记录对象
+            
+        Returns:
+            bool: 总是返回 True，表示记录应被处理
+        """
+        # 从 ContextVar 中获取当前的 request_id
+        record.request_id = get_request_id()
+        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已经有处理器，则不会重复配置。
+    
+    Args:
+        logger_name: logger的名称
+        level: 日志级别，默认为 INFO
+        
+    Returns:
+        logging.Logger: 配置好的logger实例
+        
+    特性：
+    - 使用 JSON 格式化器提供结构化日志输出
+    - 添加请求ID过滤器用于请求追踪
+    - 避免重复配置
+    """
+    # 确保 logger 名称以 SDK 前缀开始
+    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:
+            return _configured_loggers[logger_name]
+        
+        logger = logging.getLogger(logger_name)
+        
+        # 强制清除所有现有的处理器
+        logger.handlers.clear()
+        
+        # 创建专用的控制台处理器
+        console_handler = logging.StreamHandler()
+        console_handler.setFormatter(JSONFormatter())
+        
+        # 为处理器设置唯一标识，便于识别
+        console_handler.name = f"tamar_handler_{id(console_handler)}"
+        
+        # 添加处理器
+        logger.addHandler(console_handler)
+        
+        # 设置日志级别
+        logger.setLevel(level)
+        
+        # 添加请求ID过滤器
+        logger.addFilter(RequestIdFilter())
+        
+        # 关键设置：
+        # 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 适配器，确保日志格式不会被外部修改。
+    
+    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/core/request_builder.py

@@ -0,0 +1,221 @@
+"""
+Request building logic for Tamar Model Client
+
+This module handles the construction of gRPC request objects from
+model request objects, including provider-specific field validation.
+"""
+
+import json
+from typing import Dict, Any, Set
+
+from ..enums import ProviderType, InvokeType
+from ..generated import model_service_pb2
+from ..schemas.inputs import (
+    ModelRequest,
+    BatchModelRequest,
+    BatchModelRequestItem,
+    UserContext,
+    GoogleGenAiInput,
+    GoogleVertexAIImagesInput,
+    OpenAIResponsesInput,
+    OpenAIChatCompletionsInput,
+    OpenAIImagesInput,
+    OpenAIImagesEditInput
+)
+from .utils import is_effective_value, serialize_value, remove_none_from_dict
+
+
+class RequestBuilder:
+    """
+    请求构建器
+    
+    负责将高级的 ModelRequest 对象转换为 gRPC 协议所需的请求对象，
+    包括参数验证、序列化和提供商特定的字段处理。
+    """
+    
+    @staticmethod
+    def get_allowed_fields(provider: ProviderType, invoke_type: InvokeType) -> Set[str]:
+        """
+        获取特定提供商和调用类型组合所允许的字段
+        
+        Args:
+            provider: 提供商类型
+            invoke_type: 调用类型
+            
+        Returns:
+            Set[str]: 允许的字段名集合
+            
+        Raises:
+            ValueError: 当提供商和调用类型组合不受支持时
+        """
+        match (provider, invoke_type):
+            case (ProviderType.GOOGLE, InvokeType.GENERATION):
+                return set(GoogleGenAiInput.model_fields.keys())
+            case (ProviderType.GOOGLE, InvokeType.IMAGE_GENERATION):
+                return set(GoogleVertexAIImagesInput.model_fields.keys())
+            case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.RESPONSES | InvokeType.GENERATION):
+                return set(OpenAIResponsesInput.model_fields.keys())
+            case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.CHAT_COMPLETIONS):
+                return set(OpenAIChatCompletionsInput.model_fields.keys())
+            case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_GENERATION):
+                return set(OpenAIImagesInput.model_fields.keys())
+            case ((ProviderType.OPENAI | ProviderType.AZURE), InvokeType.IMAGE_EDIT_GENERATION):
+                return set(OpenAIImagesEditInput.model_fields.keys())
+            case _:
+                raise ValueError(
+                    f"Unsupported provider/invoke_type combination: {provider} + {invoke_type}"
+                )
+    
+    @staticmethod
+    def build_grpc_extra_fields(model_request: ModelRequest) -> Dict[str, Any]:
+        """
+        构建 gRPC 请求的额外字段
+        
+        根据提供商和调用类型，过滤并序列化请求中的参数。
+        
+        Args:
+            model_request: 模型请求对象
+            
+        Returns:
+            Dict[str, Any]: 序列化后的额外字段字典
+            
+        Raises:
+            ValueError: 当构建请求失败时
+        """
+        try:
+            # 获取允许的字段集合
+            allowed_fields = RequestBuilder.get_allowed_fields(
+                model_request.provider,
+                model_request.invoke_type
+            )
+            
+            # 将 ModelRequest 转换为字典，只包含已设置的字段
+            model_request_dict = model_request.model_dump(exclude_unset=True)
+            
+            # 构建 gRPC 请求参数
+            grpc_request_kwargs = {}
+            for field in allowed_fields:
+                if field in model_request_dict:
+                    value = model_request_dict[field]
+                    
+                    # 跳过无效的值
+                    if not is_effective_value(value):
+                        continue
+                    
+                    # 序列化不支持的类型
+                    grpc_request_kwargs[field] = serialize_value(value)
+            
+            # 清理序列化后的参数中的 None 值
+            grpc_request_kwargs = remove_none_from_dict(grpc_request_kwargs)
+            
+            return grpc_request_kwargs
+            
+        except Exception as e:
+            raise ValueError(f"构建请求失败: {str(e)}") from e
+    
+    @staticmethod
+    def build_single_request(model_request: ModelRequest) -> model_service_pb2.ModelRequestItem:
+        """
+        构建单个模型请求的 gRPC 对象
+        
+        Args:
+            model_request: 模型请求对象
+            
+        Returns:
+            model_service_pb2.ModelRequestItem: gRPC 请求对象
+            
+        Raises:
+            ValueError: 当构建请求失败时
+        """
+        # 构建额外字段
+        extra_fields = RequestBuilder.build_grpc_extra_fields(model_request)
+        
+        # 创建 gRPC 请求对象
+        return model_service_pb2.ModelRequestItem(
+            provider=model_request.provider.value,
+            channel=model_request.channel.value if model_request.channel else "",
+            invoke_type=model_request.invoke_type.value,
+            stream=model_request.stream or False,
+            org_id=model_request.user_context.org_id or "",
+            user_id=model_request.user_context.user_id or "",
+            client_type=model_request.user_context.client_type or "",
+            extra=extra_fields
+        )
+    
+    @staticmethod
+    def build_batch_request_item(
+        batch_item: "BatchModelRequestItem", 
+        user_context: "UserContext"
+    ) -> model_service_pb2.ModelRequestItem:
+        """
+        构建批量请求中的单个项目
+        
+        Args:
+            batch_item: 批量请求项
+            user_context: 用户上下文（来自父BatchModelRequest）
+            
+        Returns:
+            model_service_pb2.ModelRequestItem: gRPC 请求对象
+        """
+        # 构建额外字段
+        extra_fields = RequestBuilder.build_grpc_extra_fields(batch_item)
+        
+        # 添加 custom_id 如果存在
+        if hasattr(batch_item, 'custom_id') and batch_item.custom_id:
+            request_item = model_service_pb2.ModelRequestItem(
+                provider=batch_item.provider.value,
+                channel=batch_item.channel.value if batch_item.channel else "",
+                invoke_type=batch_item.invoke_type.value,
+                stream=batch_item.stream or False,
+                org_id=user_context.org_id or "",
+                user_id=user_context.user_id or "",
+                client_type=user_context.client_type or "",
+                custom_id=batch_item.custom_id,
+                extra=extra_fields
+            )
+        else:
+            request_item = model_service_pb2.ModelRequestItem(
+                provider=batch_item.provider.value,
+                channel=batch_item.channel.value if batch_item.channel else "",
+                invoke_type=batch_item.invoke_type.value,
+                stream=batch_item.stream or False,
+                org_id=user_context.org_id or "",
+                user_id=user_context.user_id or "",
+                client_type=user_context.client_type or "",
+                extra=extra_fields
+            )
+            
+        # 添加 priority 如果存在
+        if hasattr(batch_item, 'priority') and batch_item.priority is not None:
+            request_item.priority = batch_item.priority
+            
+        return request_item
+    
+    @staticmethod
+    def build_batch_request(batch_request: BatchModelRequest) -> model_service_pb2.ModelRequest:
+        """
+        构建批量请求的 gRPC 对象
+        
+        Args:
+            batch_request: 批量请求对象
+            
+        Returns:
+            model_service_pb2.ModelRequest: gRPC 批量请求对象
+            
+        Raises:
+            ValueError: 当构建请求失败时
+        """
+        items = []
+        
+        for batch_item in batch_request.items:
+            # 为每个请求项构建 gRPC 对象，传入 user_context
+            request_item = RequestBuilder.build_batch_request_item(
+                batch_item, 
+                batch_request.user_context
+            )
+            items.append(request_item)
+        
+        # 创建批量请求对象
+        return model_service_pb2.ModelRequest(
+            items=items
+        )

tamar_model_client/core/response_handler.py

@@ -0,0 +1,136 @@
+"""
+Response handling logic for Tamar Model Client
+
+This module provides utilities for processing gRPC responses and
+converting them to client response objects.
+"""
+
+import json
+from typing import Optional, Dict, Any
+
+from ..schemas import ModelResponse, BatchModelResponse
+
+
+class ResponseHandler:
+    """
+    响应处理器
+    
+    负责将 gRPC 响应转换为客户端响应对象，
+    包括 JSON 解析、错误处理和数据结构转换。
+    """
+    
+    @staticmethod
+    def build_model_response(grpc_response) -> ModelResponse:
+        """
+        从 gRPC 响应构建 ModelResponse 对象
+        
+        Args:
+            grpc_response: gRPC 服务返回的响应对象
+            
+        Returns:
+            ModelResponse: 客户端响应对象
+        """
+        return ModelResponse(
+            content=grpc_response.content,
+            usage=ResponseHandler._parse_json_field(grpc_response.usage),
+            error=grpc_response.error or None,
+            raw_response=ResponseHandler._parse_json_field(grpc_response.raw_response),
+            request_id=grpc_response.request_id if grpc_response.request_id else None,
+        )
+    
+    @staticmethod
+    def build_batch_response(grpc_response) -> BatchModelResponse:
+        """
+        从 gRPC 批量响应构建 BatchModelResponse 对象
+        
+        Args:
+            grpc_response: gRPC 服务返回的批量响应对象
+            
+        Returns:
+            BatchModelResponse: 客户端批量响应对象
+        """
+        responses = []
+        for response_item in grpc_response.items:
+            model_response = ResponseHandler.build_model_response(response_item)
+            responses.append(model_response)
+        
+        return BatchModelResponse(
+            responses=responses,
+            request_id=grpc_response.request_id if grpc_response.request_id else None
+        )
+    
+    @staticmethod
+    def _parse_json_field(json_str: Optional[str]) -> Optional[Dict[str, Any]]:
+        """
+        安全地解析 JSON 字符串
+        
+        Args:
+            json_str: 待解析的 JSON 字符串
+            
+        Returns:
+            Optional[Dict[str, Any]]: 解析后的字典，或 None（如果输入为空）
+        """
+        if not json_str:
+            return None
+        
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            # 如果解析失败，返回原始字符串作为错误信息
+            return {"error": "JSON parse error", "raw": json_str}
+    
+    @staticmethod
+    def build_log_data(
+        model_request,
+        response: Optional[ModelResponse] = None,
+        duration: Optional[float] = None,
+        error: Optional[Exception] = None,
+        stream_stats: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        """
+        构建日志数据
+        
+        为请求和响应日志构建结构化的数据字典。
+        
+        Args:
+            model_request: 原始请求对象
+            response: 响应对象（可选）
+            duration: 请求持续时间（秒）
+            error: 错误对象（可选）
+            stream_stats: 流式响应统计信息（可选）
+            
+        Returns:
+            Dict[str, Any]: 日志数据字典
+        """
+        data = {
+            "provider": model_request.provider.value,
+            "invoke_type": model_request.invoke_type.value,
+            "model": getattr(model_request, 'model', None),
+            "stream": getattr(model_request, 'stream', False),
+        }
+        
+        # 添加用户上下文信息（如果有）
+        if hasattr(model_request, 'user_context'):
+            data.update({
+                "org_id": model_request.user_context.org_id,
+                "user_id": model_request.user_context.user_id,
+                "client_type": model_request.user_context.client_type
+            })
+        
+        # 添加响应信息
+        if response:
+            if hasattr(response, 'content') and response.content:
+                data["content_length"] = len(response.content)
+            if hasattr(response, 'usage'):
+                data["usage"] = response.usage
+        
+        # 添加流式响应统计
+        if stream_stats:
+            data.update(stream_stats)
+        
+        # 添加错误信息
+        if error:
+            data["error_type"] = type(error).__name__
+            data["error_message"] = str(error)
+        
+        return data