loom-agent 0.0.1__py3-none-any.whl

loom/llm/factory.py

@@ -0,0 +1,111 @@
+"""LLM 工厂模式
+
+根据配置自动创建对应的 LLM 实例，支持：
+- 自动注册与发现
+- 统一的创建接口
+- 类型安全
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Type, Any, cast
+from .config import LLMConfig, LLMProvider
+from loom.interfaces.llm import BaseLLM
+
+
+class LLMFactory:
+    """LLM 工厂
+
+    负责根据配置创建对应的 LLM 实例。
+    """
+
+    _registry: Dict[LLMProvider, Type[BaseLLM]] = {}
+
+    @classmethod
+    def register(cls, provider: LLMProvider, llm_class: Type[BaseLLM]):
+        cls._registry[provider] = llm_class
+
+    @classmethod
+    def create(cls, config: LLMConfig) -> BaseLLM:
+        """根据配置创建 LLM 实例。优先调用 from_config，其次按 provider 适配构造。"""
+        cls._ensure_registered()
+
+        if config.provider not in cls._registry:
+            raise ValueError(
+                f"Unsupported LLM provider: {config.provider}. Available: {list(cls._registry.keys())}"
+            )
+
+        llm_class = cls._registry[config.provider]
+
+        # 优先使用 classmethod from_config(config)
+        from_config = getattr(llm_class, "from_config", None)
+        if callable(from_config):
+            return cast(BaseLLM, from_config(config))
+
+        # 无 from_config，按 provider 适配常用构造参数
+        if config.provider in (LLMProvider.OPENAI, LLMProvider.AZURE_OPENAI, LLMProvider.CUSTOM):
+            kwargs: dict[str, Any] = {
+                "model": config.model_name,
+                "temperature": config.temperature,
+            }
+            if config.max_tokens is not None:
+                kwargs["max_tokens"] = config.max_tokens
+            if config.base_url is not None:
+                kwargs["base_url"] = config.base_url
+            if config.api_key is not None:
+                kwargs["api_key"] = config.api_key
+            kwargs.update(config.extra_params)
+            return llm_class(**kwargs)  # type: ignore[arg-type]
+
+        # 其他提供商暂不内置适配
+        raise ValueError(f"Provider {config.provider} has no default constructor mapping")
+
+    @classmethod
+    def from_dict(cls, config_dict: Dict[str, Any]) -> BaseLLM:
+        config = LLMConfig.from_dict(config_dict)
+        return cls.create(config)
+
+    # 便捷创建方法
+    @classmethod
+    def create_openai(
+        cls,
+        api_key: str,
+        model: str = "gpt-4",
+        **kwargs
+    ) -> BaseLLM:
+        config = LLMConfig.openai(api_key=api_key, model=model, **kwargs)
+        return cls.create(config)
+
+    # 私有：延迟注册可用实现
+    @classmethod
+    def _ensure_registered(cls):
+        if cls._registry:
+            return
+
+        # 注册内置实现（按实际存在的实现）
+        try:
+            from loom.builtin.llms.openai import OpenAILLM
+            cls.register(LLMProvider.OPENAI, OpenAILLM)
+            # 兼容自定义/代理/azure: 复用 OpenAI 客户端风格
+            cls.register(LLMProvider.AZURE_OPENAI, OpenAILLM)
+            cls.register(LLMProvider.CUSTOM, OpenAILLM)
+        except Exception:
+            pass
+
+        try:
+            from loom.builtin.llms.mock import MockLLM
+            # 仅用于测试时手动注册（无 provider 枚举映射）
+        except Exception:
+            pass
+
+        try:
+            from loom.builtin.llms.rule import RuleLLM
+            # 规则引擎型 LLM（不绑定 provider）
+        except Exception:
+            pass
+
+    @classmethod
+    def list_available_providers(cls) -> list[str]:
+        cls._ensure_registered()
+        return [provider.value for provider in cls._registry.keys()]
+

loom/llm/model_health.py

@@ -0,0 +1,235 @@
+"""US8: Model Health Checking
+
+Tracks model health and enables intelligent fallback decisions.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, Optional
+from dataclasses import dataclass
+from enum import Enum
+
+
+class HealthStatus(str, Enum):
+    """Model health status."""
+    HEALTHY = "healthy"
+    DEGRADED = "degraded"
+    UNHEALTHY = "unhealthy"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class HealthMetrics:
+    """Health metrics for a model."""
+    status: HealthStatus
+    success_count: int = 0
+    failure_count: int = 0
+    total_requests: int = 0
+    last_success_time: Optional[float] = None
+    last_failure_time: Optional[float] = None
+    avg_latency_ms: float = 0.0
+    consecutive_failures: int = 0
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate."""
+        if self.total_requests == 0:
+            return 0.0
+        return self.success_count / self.total_requests
+
+    @property
+    def failure_rate(self) -> float:
+        """Calculate failure rate."""
+        return 1.0 - self.success_rate
+
+
+class ModelHealthChecker:
+    """Tracks and evaluates model health.
+
+    Example:
+        checker = ModelHealthChecker()
+
+        # Record success
+        checker.record_success("gpt-4", latency_ms=234.5)
+
+        # Record failure
+        checker.record_failure("gpt-4", error="timeout")
+
+        # Check health
+        status = checker.get_status("gpt-4")
+        print(f"Model health: {status}")  # HEALTHY / DEGRADED / UNHEALTHY
+    """
+
+    def __init__(
+        self,
+        degraded_threshold: float = 0.8,  # <80% success rate = degraded
+        unhealthy_threshold: float = 0.5,  # <50% success rate = unhealthy
+        consecutive_failure_threshold: int = 5,  # 5 consecutive failures = unhealthy
+        health_check_window: int = 100,  # Last 100 requests
+    ):
+        """Initialize health checker.
+
+        Args:
+            degraded_threshold: Success rate threshold for degraded status
+            unhealthy_threshold: Success rate threshold for unhealthy status
+            consecutive_failure_threshold: Consecutive failures to mark unhealthy
+            health_check_window: Number of recent requests to consider
+        """
+        self.degraded_threshold = degraded_threshold
+        self.unhealthy_threshold = unhealthy_threshold
+        self.consecutive_failure_threshold = consecutive_failure_threshold
+        self.health_check_window = health_check_window
+
+        self._metrics: Dict[str, HealthMetrics] = {}
+        self._latency_samples: Dict[str, list[float]] = {}  # Rolling window
+
+    def record_success(
+        self,
+        model_id: str,
+        latency_ms: float = 0.0
+    ) -> None:
+        """Record a successful request.
+
+        Args:
+            model_id: Model identifier
+            latency_ms: Request latency in milliseconds
+        """
+        if model_id not in self._metrics:
+            self._metrics[model_id] = HealthMetrics(status=HealthStatus.UNKNOWN)
+
+        metrics = self._metrics[model_id]
+        metrics.success_count += 1
+        metrics.total_requests += 1
+        metrics.last_success_time = time.time()
+        metrics.consecutive_failures = 0
+
+        # Update rolling latency
+        if model_id not in self._latency_samples:
+            self._latency_samples[model_id] = []
+
+        self._latency_samples[model_id].append(latency_ms)
+
+        # Keep only recent samples
+        if len(self._latency_samples[model_id]) > self.health_check_window:
+            self._latency_samples[model_id].pop(0)
+
+        # Update average latency
+        if self._latency_samples[model_id]:
+            metrics.avg_latency_ms = sum(self._latency_samples[model_id]) / len(self._latency_samples[model_id])
+
+        # Update status
+        self._update_status(model_id)
+
+    def record_failure(
+        self,
+        model_id: str,
+        error: Optional[str] = None
+    ) -> None:
+        """Record a failed request.
+
+        Args:
+            model_id: Model identifier
+            error: Error message
+        """
+        if model_id not in self._metrics:
+            self._metrics[model_id] = HealthMetrics(status=HealthStatus.UNKNOWN)
+
+        metrics = self._metrics[model_id]
+        metrics.failure_count += 1
+        metrics.total_requests += 1
+        metrics.last_failure_time = time.time()
+        metrics.consecutive_failures += 1
+
+        # Update status
+        self._update_status(model_id)
+
+    def _update_status(self, model_id: str) -> None:
+        """Update health status based on metrics.
+
+        Args:
+            model_id: Model identifier
+        """
+        metrics = self._metrics[model_id]
+
+        # Check consecutive failures
+        if metrics.consecutive_failures >= self.consecutive_failure_threshold:
+            metrics.status = HealthStatus.UNHEALTHY
+            return
+
+        # Check success rate (only if we have enough data)
+        if metrics.total_requests > 0:
+            success_rate = metrics.success_rate
+
+            if success_rate >= self.degraded_threshold:
+                metrics.status = HealthStatus.HEALTHY
+            elif success_rate >= self.unhealthy_threshold:
+                metrics.status = HealthStatus.DEGRADED
+            else:
+                metrics.status = HealthStatus.UNHEALTHY
+        else:
+            metrics.status = HealthStatus.UNKNOWN
+
+    def get_status(self, model_id: str) -> HealthStatus:
+        """Get current health status.
+
+        Args:
+            model_id: Model identifier
+
+        Returns:
+            Current health status
+        """
+        if model_id not in self._metrics:
+            return HealthStatus.UNKNOWN
+
+        return self._metrics[model_id].status
+
+    def get_metrics(self, model_id: str) -> Optional[HealthMetrics]:
+        """Get detailed health metrics.
+
+        Args:
+            model_id: Model identifier
+
+        Returns:
+            HealthMetrics or None if not tracked
+        """
+        return self._metrics.get(model_id)
+
+    def is_healthy(self, model_id: str) -> bool:
+        """Check if model is healthy.
+
+        Args:
+            model_id: Model identifier
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        status = self.get_status(model_id)
+        return status == HealthStatus.HEALTHY
+
+    def get_all_healthy_models(self) -> list[str]:
+        """Get list of all healthy models.
+
+        Returns:
+            List of model IDs with healthy status
+        """
+        return [
+            model_id
+            for model_id, metrics in self._metrics.items()
+            if metrics.status == HealthStatus.HEALTHY
+        ]
+
+    def reset(self, model_id: Optional[str] = None) -> None:
+        """Reset health metrics.
+
+        Args:
+            model_id: Model to reset (None = reset all)
+        """
+        if model_id:
+            if model_id in self._metrics:
+                self._metrics[model_id] = HealthMetrics(status=HealthStatus.UNKNOWN)
+            if model_id in self._latency_samples:
+                self._latency_samples[model_id] = []
+        else:
+            self._metrics.clear()
+            self._latency_samples.clear()

loom/llm/model_pool_advanced.py

@@ -0,0 +1,305 @@
+"""US8: Advanced Model Pool with Fallback Chain
+
+Provides intelligent model selection with health-aware fallback.
+
+Features:
+- Fallback chain: [primary, fallback1, fallback2]
+- Automatic fallback on 5xx errors
+- Health-based model selection
+- Connection pooling for reduced latency
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import List, Optional, Dict, Any
+from dataclasses import dataclass
+
+from loom.interfaces.llm import BaseLLM
+from loom.llm.model_health import ModelHealthChecker, HealthStatus
+from loom.core.error_classifier import ErrorClassifier, ErrorCategory
+
+
+@dataclass
+class ModelConfig:
+    """Configuration for a model in the pool."""
+    model_id: str
+    llm: BaseLLM
+    priority: int = 0  # Higher priority = preferred (for same health status)
+    max_concurrent: int = 10  # Max concurrent requests to this model
+
+
+class FallbackChain:
+    """Manages fallback chain for model selection.
+
+    Example:
+        chain = FallbackChain([
+            ModelConfig("gpt-4", gpt4_llm, priority=100),
+            ModelConfig("gpt-3.5-turbo", gpt35_llm, priority=50),
+            ModelConfig("claude-2", claude_llm, priority=30),
+        ])
+
+        # Automatically selects best available model
+        llm = await chain.get_next_model()
+    """
+
+    def __init__(
+        self,
+        models: List[ModelConfig],
+        health_checker: Optional[ModelHealthChecker] = None,
+    ):
+        """Initialize fallback chain.
+
+        Args:
+            models: List of model configurations (ordered by preference)
+            health_checker: Health checker instance
+        """
+        self.models = models
+        self.health_checker = health_checker or ModelHealthChecker()
+        self._model_map = {m.model_id: m for m in models}
+        self._semaphores: Dict[str, asyncio.Semaphore] = {}
+
+        # Create semaphores for rate limiting
+        for model in models:
+            self._semaphores[model.model_id] = asyncio.Semaphore(model.max_concurrent)
+
+    def get_next_model(
+        self,
+        skip_unhealthy: bool = True,
+        prefer_healthy: bool = True,
+    ) -> Optional[ModelConfig]:
+        """Get next best model from fallback chain.
+
+        Args:
+            skip_unhealthy: Skip models marked as unhealthy
+            prefer_healthy: Prefer healthy models over degraded
+
+        Returns:
+            ModelConfig or None if no models available
+        """
+        # Categorize models by health
+        healthy = []
+        degraded = []
+        unhealthy = []
+        unknown = []
+
+        for model in self.models:
+            status = self.health_checker.get_status(model.model_id)
+
+            if status == HealthStatus.HEALTHY:
+                healthy.append(model)
+            elif status == HealthStatus.DEGRADED:
+                degraded.append(model)
+            elif status == HealthStatus.UNHEALTHY:
+                unhealthy.append(model)
+            else:
+                unknown.append(model)
+
+        # Select based on preference
+        candidates = []
+
+        if prefer_healthy and healthy:
+            candidates = healthy
+        elif healthy or degraded:
+            candidates = healthy + degraded
+        elif unknown:
+            candidates = unknown
+        elif not skip_unhealthy:
+            candidates = unhealthy
+
+        if not candidates:
+            return None
+
+        # Sort by priority (highest first)
+        candidates.sort(key=lambda m: m.priority, reverse=True)
+
+        return candidates[0]
+
+    async def call_with_fallback(
+        self,
+        operation: str,  # "generate" or "generate_with_tools"
+        *args: Any,
+        max_fallback_attempts: int = 3,
+        **kwargs: Any,
+    ) -> Any:
+        """Call model with automatic fallback on failure.
+
+        Args:
+            operation: LLM method name
+            *args: Positional arguments
+            max_fallback_attempts: Max models to try
+            **kwargs: Keyword arguments
+
+        Returns:
+            Result from successful model call
+
+        Raises:
+            Exception if all models fail
+        """
+        attempts = 0
+        last_exception = None
+
+        while attempts < max_fallback_attempts:
+            model_config = self.get_next_model()
+
+            if not model_config:
+                break
+
+            try:
+                # Acquire semaphore for rate limiting
+                async with self._semaphores[model_config.model_id]:
+                    # Call the model
+                    import time
+                    start = time.time()
+
+                    method = getattr(model_config.llm, operation)
+                    result = await method(*args, **kwargs)
+
+                    latency_ms = (time.time() - start) * 1000
+
+                    # Record success
+                    self.health_checker.record_success(
+                        model_config.model_id,
+                        latency_ms=latency_ms
+                    )
+
+                    return result
+
+            except Exception as e:
+                last_exception = e
+
+                # Record failure
+                self.health_checker.record_failure(
+                    model_config.model_id,
+                    error=str(e)
+                )
+
+                # Check if error is retryable
+                category = ErrorClassifier.classify(e)
+
+                if category == ErrorCategory.SERVICE_ERROR:
+                    # 5xx error - try fallback
+                    attempts += 1
+                    continue
+                else:
+                    # Non-retryable error - propagate
+                    raise
+
+            attempts += 1
+
+        # All models failed
+        if last_exception:
+            raise last_exception
+        else:
+            raise RuntimeError("No healthy models available")
+
+    def get_health_summary(self) -> Dict[str, Any]:
+        """Get health summary for all models.
+
+        Returns:
+            Dict with health information
+        """
+        summary = {}
+
+        for model in self.models:
+            metrics = self.health_checker.get_metrics(model.model_id)
+            if metrics:
+                summary[model.model_id] = {
+                    "status": metrics.status.value,
+                    "success_rate": metrics.success_rate,
+                    "avg_latency_ms": metrics.avg_latency_ms,
+                    "consecutive_failures": metrics.consecutive_failures,
+                }
+            else:
+                summary[model.model_id] = {"status": "unknown"}
+
+        return summary
+
+
+class ModelPoolLLM(BaseLLM):
+    """LLM wrapper that uses fallback chain.
+
+    Drop-in replacement for any BaseLLM with automatic fallback.
+
+    Example:
+        # Create pool with fallback chain
+        pool_llm = ModelPoolLLM([
+            ModelConfig("gpt-4", gpt4_llm, priority=100),
+            ModelConfig("gpt-3.5-turbo", gpt35_llm, priority=50),
+        ])
+
+        # Use like any LLM
+        agent = Agent(llm=pool_llm, tools=tools)
+    """
+
+    def __init__(
+        self,
+        models: List[ModelConfig],
+        max_fallback_attempts: int = 3,
+    ):
+        """Initialize model pool LLM.
+
+        Args:
+            models: List of model configurations
+            max_fallback_attempts: Max models to try on failure
+        """
+        self.fallback_chain = FallbackChain(models)
+        self.max_fallback_attempts = max_fallback_attempts
+
+        # Use first model's capabilities as default
+        if models:
+            self._supports_tools = models[0].llm.supports_tools
+            self._model_name = f"pool({','.join([m.model_id for m in models])})"
+        else:
+            self._supports_tools = False
+            self._model_name = "pool(empty)"
+
+    @property
+    def model_name(self) -> str:
+        """Get pool model name."""
+        return self._model_name
+
+    @property
+    def supports_tools(self) -> bool:
+        """Check if pool supports tools."""
+        return self._supports_tools
+
+    async def generate(self, messages: List[dict]) -> str:
+        """Generate completion with automatic fallback."""
+        return await self.fallback_chain.call_with_fallback(
+            "generate",
+            messages,
+            max_fallback_attempts=self.max_fallback_attempts,
+        )
+
+    async def generate_with_tools(
+        self,
+        messages: List[dict],
+        tools: List[dict],
+    ) -> dict:
+        """Generate with tools, with automatic fallback."""
+        return await self.fallback_chain.call_with_fallback(
+            "generate_with_tools",
+            messages,
+            tools,
+            max_fallback_attempts=self.max_fallback_attempts,
+        )
+
+    async def stream(self, messages: List[dict]):
+        """Stream responses (uses first healthy model)."""
+        model_config = self.fallback_chain.get_next_model()
+        if not model_config:
+            raise RuntimeError("No healthy models available")
+
+        # Delegate to model's stream
+        if hasattr(model_config.llm, 'stream'):
+            async for chunk in model_config.llm.stream(messages):
+                yield chunk
+        else:
+            # Fallback to non-streaming
+            result = await self.generate(messages)
+            yield result
+
+    def get_health_summary(self) -> Dict[str, Any]:
+        """Get health summary for pool."""
+        return self.fallback_chain.get_health_summary()