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

tamar_model_client/circuit_breaker.py

@@ -0,0 +1,140 @@
+"""
+Circuit Breaker implementation for resilient client
+
+This module provides a thread-safe circuit breaker pattern implementation
+to handle failures gracefully and prevent cascading failures.
+"""
+
+import time
+import logging
+from enum import Enum
+from threading import Lock
+from typing import Optional
+
+from .core.logging_setup import get_protected_logger
+
+logger = get_protected_logger(__name__)
+
+
+class CircuitState(Enum):
+    """Circuit breaker states"""
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Circuit is broken, requests fail fast
+    HALF_OPEN = "half_open"  # Testing if service has recovered
+
+
+class CircuitBreaker:
+    """
+    Thread-safe circuit breaker implementation
+    
+    The circuit breaker prevents cascading failures by failing fast when
+    a service is unavailable, and automatically recovers when the service
+    becomes available again.
+    """
+    
+    def __init__(self, failure_threshold: int = 5, recovery_timeout: int = 60):
+        """
+        Initialize the circuit breaker
+        
+        Args:
+            failure_threshold: Number of consecutive failures before opening circuit
+            recovery_timeout: Seconds to wait before attempting recovery
+        """
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.failure_count = 0
+        self.last_failure_time: Optional[float] = None
+        self.state = CircuitState.CLOSED
+        self._lock = Lock()
+        
+    @property
+    def is_open(self) -> bool:
+        """Check if circuit breaker is open"""
+        with self._lock:
+            if self.state == CircuitState.OPEN:
+                # Check if we should attempt recovery
+                if (self.last_failure_time and 
+                    time.time() - self.last_failure_time > self.recovery_timeout):
+                    self.state = CircuitState.HALF_OPEN
+                    logger.info("🔄 Circuit breaker entering HALF_OPEN state")
+                    return False
+                return True
+            return False
+    
+    def record_success(self) -> None:
+        """Record a successful request"""
+        with self._lock:
+            if self.state == CircuitState.HALF_OPEN:
+                # Success in half-open state means service has recovered
+                self.state = CircuitState.CLOSED
+                self.failure_count = 0
+                logger.info("🔺 Circuit breaker recovered to CLOSED state")
+            elif self.state == CircuitState.CLOSED and self.failure_count > 0:
+                # Reset failure count on success
+                self.failure_count = 0
+    
+    def record_failure(self, error_code=None) -> None:
+        """
+        Record a failed request
+        
+        Args:
+            error_code: gRPC error code for failure classification
+        """
+        with self._lock:
+            # 对于某些错误类型，不计入熔断统计或权重较低
+            if error_code and self._should_ignore_for_circuit_breaker(error_code):
+                return
+                
+            # ABORTED 错误权重较低，因为通常是瞬时的并发问题
+            import grpc
+            if error_code == grpc.StatusCode.ABORTED:
+                # ABORTED 错误只计算半个失败
+                self.failure_count += 0.5
+            else:
+                self.failure_count += 1
+                
+            self.last_failure_time = time.time()
+            
+            if self.failure_count >= self.failure_threshold:
+                if self.state != CircuitState.OPEN:
+                    self.state = CircuitState.OPEN
+                    logger.warning(
+                        f"🔻 Circuit breaker OPENED after {self.failure_count} failures",
+                        extra={
+                            "failure_count": self.failure_count,
+                            "threshold": self.failure_threshold,
+                            "trigger_error": error_code.name if error_code else "unknown"
+                        }
+                    )
+    
+    def _should_ignore_for_circuit_breaker(self, error_code) -> bool:
+        """
+        判断错误是否应该被熔断器忽略
+        
+        某些错误不应该触发熔断：
+        - 客户端主动取消的请求
+        - 认证相关错误（不代表服务不可用）
+        """
+        import grpc
+        ignored_codes = {
+            grpc.StatusCode.UNAUTHENTICATED,    # 认证问题，不是服务问题
+            grpc.StatusCode.PERMISSION_DENIED,  # 权限问题，不是服务问题
+            grpc.StatusCode.INVALID_ARGUMENT,   # 参数错误，不是服务问题
+        }
+        return error_code in ignored_codes
+    
+    def should_fallback(self) -> bool:
+        """Check if fallback should be used"""
+        return self.is_open and self.state != CircuitState.HALF_OPEN
+    
+    def get_state(self) -> str:
+        """Get current circuit state"""
+        return self.state.value
+    
+    def reset(self) -> None:
+        """Reset circuit breaker to initial state"""
+        with self._lock:
+            self.state = CircuitState.CLOSED
+            self.failure_count = 0
+            self.last_failure_time = None
+            logger.info("🔄 Circuit breaker reset to CLOSED state")

tamar_model_client/core/__init__.py

@@ -0,0 +1,40 @@
+"""
+Core components for Tamar Model Client
+
+This package contains shared components used by both sync and async clients.
+"""
+
+from .utils import (
+    is_effective_value,
+    serialize_value,
+    remove_none_from_dict,
+    generate_request_id,
+    set_request_id,
+    get_request_id
+)
+
+from .logging_setup import (
+    setup_logger,
+    RequestIdFilter,
+    TamarLoggerAdapter,
+    get_protected_logger,
+    reset_logger_config,
+    MAX_MESSAGE_LENGTH
+)
+
+__all__ = [
+    # Utils
+    'is_effective_value',
+    'serialize_value',
+    'remove_none_from_dict',
+    'generate_request_id',
+    'set_request_id',
+    'get_request_id',
+    # Logging
+    'setup_logger',
+    'RequestIdFilter',
+    'TamarLoggerAdapter',
+    'get_protected_logger',
+    'reset_logger_config',
+    'MAX_MESSAGE_LENGTH',
+]

tamar_model_client/core/base_client.py

@@ -0,0 +1,221 @@
+"""
+Base client class for Tamar Model Client
+
+This module provides the base client class with shared initialization logic
+and configuration management for both sync and async clients.
+"""
+
+import os
+import logging
+from typing import Optional, Dict, Any
+from abc import ABC, abstractmethod
+
+from ..auth import JWTAuthHandler
+from ..error_handler import GrpcErrorHandler, ErrorRecoveryStrategy
+from .logging_setup import MAX_MESSAGE_LENGTH, get_protected_logger
+
+
+class BaseClient(ABC):
+    """
+    基础客户端抽象类
+    
+    提供同步和异步客户端的共享功能：
+    - 配置管理
+    - 认证设置
+    - 连接选项构建
+    - 错误处理器初始化
+    """
+    
+    def __init__(
+            self,
+            server_address: Optional[str] = None,
+            jwt_secret_key: Optional[str] = None,
+            jwt_token: Optional[str] = None,
+            default_payload: Optional[dict] = None,
+            token_expires_in: int = 3600,
+            max_retries: Optional[int] = None,
+            retry_delay: Optional[float] = None,
+            logger_name: str = None,
+    ):
+        """
+        初始化基础客户端
+        
+        Args:
+            server_address: gRPC 服务器地址，格式为 "host:port"
+            jwt_secret_key: JWT 签名密钥，用于生成认证令牌
+            jwt_token: 预生成的 JWT 令牌（可选）
+            default_payload: JWT 令牌的默认载荷
+            token_expires_in: JWT 令牌过期时间（秒）
+            max_retries: 最大重试次数（默认从环境变量读取）
+            retry_delay: 初始重试延迟（秒，默认从环境变量读取）
+            logger_name: 日志记录器名称
+            
+        Raises:
+            ValueError: 当服务器地址未提供时
+        """
+        # === 服务端地址配置 ===
+        self.server_address = server_address or os.getenv("MODEL_MANAGER_SERVER_ADDRESS")
+        if not self.server_address:
+            raise ValueError("Server address must be provided via argument or environment variable.")
+        
+        # 默认调用超时时间
+        self.default_invoke_timeout = float(os.getenv("MODEL_MANAGER_SERVER_INVOKE_TIMEOUT", 30.0))
+        
+        # === JWT 认证配置 ===
+        self.jwt_secret_key = jwt_secret_key or os.getenv("MODEL_MANAGER_SERVER_JWT_SECRET_KEY")
+        self.jwt_handler = JWTAuthHandler(self.jwt_secret_key) if self.jwt_secret_key else None
+        self.jwt_token = jwt_token  # 用户传入的预生成 Token（可选）
+        self.default_payload = default_payload
+        self.token_expires_in = token_expires_in
+        
+        # === TLS/Authority 配置 ===
+        self.use_tls = os.getenv("MODEL_MANAGER_SERVER_GRPC_USE_TLS", "true").lower() == "true"
+        self.default_authority = os.getenv("MODEL_MANAGER_SERVER_GRPC_DEFAULT_AUTHORITY")
+        
+        # === 重试配置 ===
+        self.max_retries = max_retries if max_retries is not None else int(
+            os.getenv("MODEL_MANAGER_SERVER_GRPC_MAX_RETRIES", 3))
+        self.retry_delay = retry_delay if retry_delay is not None else float(
+            os.getenv("MODEL_MANAGER_SERVER_GRPC_RETRY_DELAY", 1.0))
+        
+        # === 日志配置 ===
+        self.logger = get_protected_logger(logger_name or __name__)
+        
+        # === 错误处理器 ===
+        self.error_handler = GrpcErrorHandler(self.logger)
+        self.recovery_strategy = ErrorRecoveryStrategy(self)
+        
+        # === 连接状态 ===
+        self._closed = False
+        
+        # === 熔断降级配置 ===
+        self._init_resilient_features()
+    
+    def build_channel_options(self) -> list:
+        """
+        构建 gRPC 通道选项
+        
+        Returns:
+            list: gRPC 通道配置选项列表
+            
+        包含的配置：
+        - 消息大小限制
+        - Keepalive 设置（30秒ping间隔，10秒超时）
+        - 连接生命周期管理（1小时最大连接时间）
+        - 性能优化选项（带宽探测、内置重试）
+        """
+        options = [
+            # 消息大小限制
+            ('grpc.max_send_message_length', MAX_MESSAGE_LENGTH),
+            ('grpc.max_receive_message_length', MAX_MESSAGE_LENGTH),
+            
+            # Keepalive 核心配置
+            ('grpc.keepalive_time_ms', 30000),  # 30秒发送一次 keepalive ping
+            ('grpc.keepalive_timeout_ms', 10000),  # ping 响应超时时间 10秒
+            ('grpc.keepalive_permit_without_calls', True),  # 空闲时也发送 keepalive
+            ('grpc.http2.max_pings_without_data', 2),  # 无数据时最大 ping 次数
+            
+            # 连接管理增强配置
+            ('grpc.http2.min_time_between_pings_ms', 10000),  # ping 最小间隔 10秒
+            ('grpc.http2.max_connection_idle_ms', 300000),  # 最大空闲时间 5分钟
+            ('grpc.http2.max_connection_age_ms', 3600000),  # 连接最大生存时间 1小时
+            ('grpc.http2.max_connection_age_grace_ms', 5000),  # 优雅关闭时间 5秒
+            
+            # 性能相关配置
+            ('grpc.http2.bdp_probe', 1),  # 启用带宽延迟探测
+            ('grpc.enable_retries', 1),  # 启用内置重试
+        ]
+        
+        if self.default_authority:
+            options.append(("grpc.default_authority", self.default_authority))
+            
+        return options
+    
+    def _build_auth_metadata(self, request_id: str) -> list:
+        """
+        构建认证元数据
+        
+        为每个请求构建包含认证信息和请求ID的gRPC元数据。
+        JWT令牌会在每次请求时重新生成以确保有效性。
+        
+        Args:
+            request_id: 当前请求的唯一标识符
+            
+        Returns:
+            list: gRPC元数据列表，包含请求ID和认证令牌
+        """
+        metadata = [("x-request-id", request_id)]  # 将 request_id 添加到 headers
+        
+        if self.jwt_handler:
+            self.jwt_token = self.jwt_handler.encode_token(
+                self.default_payload, 
+                expires_in=self.token_expires_in
+            )
+            metadata.append(("authorization", f"Bearer {self.jwt_token}"))
+            
+        return metadata
+    
+    @abstractmethod
+    def close(self):
+        """关闭客户端连接（由子类实现）"""
+        pass
+    
+    @abstractmethod
+    def __enter__(self):
+        """进入上下文管理器（由子类实现）"""
+        pass
+    
+    @abstractmethod
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """退出上下文管理器（由子类实现）"""
+        pass
+    
+    def _init_resilient_features(self):
+        """初始化熔断降级特性"""
+        # 是否启用熔断降级
+        self.resilient_enabled = os.getenv('MODEL_CLIENT_RESILIENT_ENABLED', 'false').lower() == 'true'
+        
+        if self.resilient_enabled:
+            # HTTP 降级地址
+            self.http_fallback_url = os.getenv('MODEL_CLIENT_HTTP_FALLBACK_URL')
+            
+            if not self.http_fallback_url:
+                self.logger.warning("🔶 Resilient mode enabled but MODEL_CLIENT_HTTP_FALLBACK_URL not set")
+                self.resilient_enabled = False
+                return
+            
+            # 初始化熔断器
+            from ..circuit_breaker import CircuitBreaker
+            self.circuit_breaker = CircuitBreaker(
+                failure_threshold=int(os.getenv('MODEL_CLIENT_CIRCUIT_BREAKER_THRESHOLD', '5')),
+                recovery_timeout=int(os.getenv('MODEL_CLIENT_CIRCUIT_BREAKER_TIMEOUT', '60'))
+            )
+            
+            # HTTP 客户端（延迟初始化）
+            self._http_client = None
+            self._http_session = None  # 异步客户端使用
+            
+            self.logger.info(
+                "🛡️ Resilient mode enabled",
+                extra={
+                    "http_fallback_url": self.http_fallback_url,
+                    "circuit_breaker_threshold": self.circuit_breaker.failure_threshold,
+                    "circuit_breaker_timeout": self.circuit_breaker.recovery_timeout
+                }
+            )
+        else:
+            self.circuit_breaker = None
+            self.http_fallback_url = None
+    
+    def get_resilient_metrics(self):
+        """获取熔断降级指标"""
+        if not self.resilient_enabled or not self.circuit_breaker:
+            return None
+            
+        return {
+            "enabled": self.resilient_enabled,
+            "circuit_state": self.circuit_breaker.get_state(),
+            "failure_count": self.circuit_breaker.failure_count,
+            "last_failure_time": self.circuit_breaker.last_failure_time,
+            "http_fallback_url": self.http_fallback_url
+        }

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