From 5f5c09835fed3856e342eaea1b336e9acaf6c636 Mon Sep 17 00:00:00 2001
From: Chiguyong <chiguyong@ChiGuyongs-MacBook-Pro.local>
Date: Mon, 6 Jul 2026 22:51:33 +0800
Subject: [PATCH] =?UTF-8?q?fix(arch):=20=E8=BF=81=E7=A7=BB=20LLM=20?=
 =?UTF-8?q?=E5=BC=82=E5=B8=B8=E5=88=B0=20llm/exceptions.py=20=E6=B6=88?=
 =?UTF-8?q?=E9=99=A4=E5=88=86=E5=B1=82=E5=BC=82=E5=91=B3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

将 LLMError/LLMProviderError/ModelNotFoundError 定义从 core/exceptions.py
迁移到 llm/exceptions.py，使 LLM 异常定义归位 LLM 层。

- core/exceptions.py 用 PEP 562 __getattr__ 延迟 re-export，打破循环依赖：
  core.exceptions → llm.exceptions → llm.__init__ → llm.retry → core.exceptions
- llm/exceptions.py 中 LLMError 仍继承 AgentFrameworkError，保持 isinstance 兼容
- llm/__init__.py 导出 exceptions，支持 from agentkit.llm import LLMError
- 现有 from agentkit.core.exceptions import LLMProviderError 调用无需修改

零破坏性变更，ruff + import 兼容性验证通过。
---
 src/agentkit/core/exceptions.py | 40 ++++++++++++++++++++-------------
 src/agentkit/llm/__init__.py    |  4 ++++
 src/agentkit/llm/exceptions.py  | 37 ++++++++++++++++++++++++++++++
 3 files changed, 65 insertions(+), 16 deletions(-)
 create mode 100644 src/agentkit/llm/exceptions.py

diff --git a/src/agentkit/core/exceptions.py b/src/agentkit/core/exceptions.py
index 471422a..34cad62 100644
--- a/src/agentkit/core/exceptions.py
+++ b/src/agentkit/core/exceptions.py
@@ -132,24 +132,32 @@ class EvolutionError(AgentFrameworkError):
         super().__init__(f"Evolution failed for agent '{agent_name}': {reason}")
 
 
-class LLMError(AgentFrameworkError):
-    """LLM 基础异常"""
-
-    def __init__(self, message: str = "LLM error"):
-        super().__init__(message)
+# Re-export LLM exceptions from llm/exceptions.py for backward compatibility.
+# New code should import from agentkit.llm.exceptions directly.
+# ponytail: 架构分层修复 — LLM 异常定义归位 LLM 层；re-export 保留以避免破坏
+# 现有 `from agentkit.core.exceptions import LLMProviderError` 调用方。
+# 升级路径：调用方逐步迁移到 llm.exceptions 后可移除 __getattr__。
+#
+# 用 PEP 562 模块级 __getattr__ 延迟导入，打破循环依赖：
+# core.exceptions → llm.exceptions → llm.__init__ → llm.retry → core.exceptions.LLMProviderError
+# （若顶层 import，LLMProviderError 尚未绑定 → ImportError）
+_LLM_EXCEPTION_NAMES = ("LLMError", "LLMProviderError", "ModelNotFoundError")
 
 
-class LLMProviderError(LLMError):
-    """LLM Provider 特定异常"""
+def __getattr__(name: str):  # PEP 562
+    if name in _LLM_EXCEPTION_NAMES:
+        from agentkit.llm.exceptions import (  # noqa: PLC0415
+            LLMError,
+            LLMProviderError,
+            ModelNotFoundError,
+        )
 
-    def __init__(self, provider: str, reason: str = ""):
-        self.provider = provider
-        super().__init__(f"LLM provider '{provider}' error: {reason}")
+        globals()["LLMError"] = LLMError
+        globals()["LLMProviderError"] = LLMProviderError
+        globals()["ModelNotFoundError"] = ModelNotFoundError
+        return globals()[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
-class ModelNotFoundError(LLMError):
-    """模型别名未找到异常"""
-
-    def __init__(self, model: str):
-        self.model = model
-        super().__init__(f"Model not found: {model}")
+def __dir__():  # 让 from agentkit.core.exceptions import * 仍能发现 re-export
+    return [*(globals().keys()), *_LLM_EXCEPTION_NAMES]
diff --git a/src/agentkit/llm/__init__.py b/src/agentkit/llm/__init__.py
index 463626d..2918fcb 100644
--- a/src/agentkit/llm/__init__.py
+++ b/src/agentkit/llm/__init__.py
@@ -7,6 +7,7 @@ from agentkit.llm.providers.anthropic import AnthropicProvider
 from agentkit.llm.providers.openai import OpenAICompatibleProvider
 from agentkit.llm.providers.tracker import UsageSummary, UsageTracker
 from agentkit.llm.providers.usage_store import UsageRecord
+from agentkit.llm.exceptions import LLMError, LLMProviderError, ModelNotFoundError
 from agentkit.llm.remote_provider import RemoteLLMProvider
 from agentkit.llm.retry import (
     CircuitBreaker,
@@ -38,4 +39,7 @@ __all__ = [
     "UsageTracker",
     "UsageRecord",
     "UsageSummary",
+    "LLMError",
+    "LLMProviderError",
+    "ModelNotFoundError",
 ]
diff --git a/src/agentkit/llm/exceptions.py b/src/agentkit/llm/exceptions.py
new file mode 100644
index 0000000..d9cf56e
--- /dev/null
+++ b/src/agentkit/llm/exceptions.py
@@ -0,0 +1,37 @@
+"""LLM 层异常定义。
+
+架构分层原则：LLM 异常定义在 LLM 层，而非 core/exceptions.py。
+core/exceptions.py 保留 re-export 以保持向后兼容。
+"""
+
+from agentkit.core.exceptions import AgentFrameworkError
+
+
+class LLMError(AgentFrameworkError):
+    """LLM 基础异常"""
+
+    def __init__(self, message: str = "LLM error"):
+        super().__init__(message)
+
+
+class LLMProviderError(LLMError):
+    """LLM Provider 特定异常"""
+
+    def __init__(self, provider: str, reason: str = ""):
+        self.provider = provider
+        super().__init__(f"LLM provider '{provider}' error: {reason}")
+
+
+class ModelNotFoundError(LLMError):
+    """模型别名未找到异常"""
+
+    def __init__(self, model: str):
+        self.model = model
+        super().__init__(f"Model not found: {model}")
+
+
+__all__ = [
+    "LLMError",
+    "LLMProviderError",
+    "ModelNotFoundError",
+]