echotools 1.0.2__tar.gz → 1.0.4__tar.gz

{echotools-1.0.2 → echotools-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 1.0.2
+Version: 1.0.4
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Author: nichengfuben
 License: MIT

{echotools-1.0.2 → echotools-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "1.0.2"
+version = "1.0.4"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
 readme = "README.md"
 requires-python = ">=3.8"

{echotools-1.0.2 → echotools-1.0.4}/src/echotools/cache/list_cache.py

@@ -34,6 +34,7 @@ class ListCache:
         fallback: List[str],
         cache_path: str,
         overwrite: bool = True,
+        data_key: str = "items",
     ) -> None:
         """初始化列表缓存。
 
@@ -42,6 +43,7 @@ class ListCache:
             fallback: 兜底列表。
             cache_path: 持久化文件路径。
             overwrite: True=覆盖，False=只增不减。
+            data_key: JSON 中存储列表的键名，默认 "items"。
         """
         self._name = name
         self._fallback = list(fallback)
@@ -49,6 +51,7 @@ class ListCache:
         self._items: List[str] = list(fallback)
         self._cache_path = Path(cache_path)
         self._refreshing = False
+        self._data_key = data_key
 
     async def load(self) -> List[str]:
         """从缓存文件加载列表。
@@ -60,7 +63,7 @@ class ListCache:
             if self._cache_path.is_file():
                 text = self._cache_path.read_text(encoding="utf-8")
                 data = json.loads(text)
-                items = data.get("items", [])
+                items = data.get(self._data_key, [])
                 if items:
                     self._items = list(items)
                     logger.info(
@@ -80,7 +83,7 @@ class ListCache:
         """
         try:
             self._cache_path.parent.mkdir(parents=True, exist_ok=True)
-            data = {"items": items, "updated_at": int(time.time())}
+            data = {self._data_key: items, "updated_at": int(time.time())}
             self._cache_path.write_text(
                 json.dumps(data, ensure_ascii=False, indent=2),
                 encoding="utf-8",

{echotools-1.0.2 → echotools-1.0.4}/src/echotools/dispatch/__init__.py

@@ -9,6 +9,7 @@ from echotools.dispatch.selector import (
     TASRecord,
     TASWeights,
 )
+from echotools.dispatch.usage import fallback_usage, normalize_usage
 
 __all__ = [
     "TaskCandidate",
@@ -17,4 +18,6 @@ __all__ = [
     "TASRecord",
     "TASWeights",
     "TaskDispatcher",
+    "normalize_usage",
+    "fallback_usage",
 ]

echotools-1.0.4/src/echotools/dispatch/usage.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+"""LLM token usage 规范化。"""
+
+from typing import Any, Dict
+
+__all__ = ["normalize_usage", "fallback_usage"]
+
+
+def fallback_usage(prompt_len: int, resp_text: str) -> Dict[str, int]:
+    """估算 token 用量（无精确数据时的回退）。
+
+    按字符数 / 3 粗略估算。
+
+    Args:
+        prompt_len: 提示文本字符数。
+        resp_text: 响应文本。
+
+    Returns:
+        用量字典。
+    """
+    pt = max(prompt_len // 3, 1)
+    ct = max(len(resp_text) // 3, 0)
+    return {"prompt_tokens": pt, "completion_tokens": ct, "total_tokens": pt + ct}
+
+
+def normalize_usage(
+    raw: Any,
+    prompt_len: int,
+    resp_text: str,
+) -> Dict[str, int]:
+    """规范化 usage 字典。
+
+    兼容 OpenAI (prompt_tokens/completion_tokens) 和
+    Anthropic (input_tokens/output_tokens) 格式。
+
+    Args:
+        raw: 原始 usage 数据（dict 或 None）。
+        prompt_len: 提示文本字符数。
+        resp_text: 响应文本。
+
+    Returns:
+        规范化后的用量字典。
+    """
+    if not isinstance(raw, dict):
+        return fallback_usage(prompt_len, resp_text)
+    try:
+        pt = int(raw.get("prompt_tokens", raw.get("input_tokens", 0)))
+        ct = int(raw.get("completion_tokens", raw.get("output_tokens", 0)))
+        if pt <= 0 and ct <= 0:
+            return fallback_usage(prompt_len, resp_text)
+        if pt <= 0:
+            pt = prompt_len // 3
+        return {
+            "prompt_tokens": pt,
+            "completion_tokens": ct,
+            "total_tokens": pt + ct,
+        }
+    except (TypeError, ValueError):
+        return fallback_usage(prompt_len, resp_text)

{echotools-1.0.2 → echotools-1.0.4}/src/echotools/errors/__init__.py

@@ -14,9 +14,21 @@ from echotools.errors.common import (
     TimeoutError,
     ValidationError,
 )
+from echotools.errors.http import (
+    AuthError,
+    ContextLengthError,
+    ForbiddenError,
+    HttpError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+    StreamError,
+)
 
 __all__ = [
     "EchoError",
+    "HttpError",
     "ConfigError",
     "ValidationError",
     "NetworkError",
@@ -25,5 +37,13 @@ __all__ = [
     "NoCandidateError",
     "PluginError",
     "ProtocolError",
+    "AuthError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ContextLengthError",
+    "ServerError",
+    "StreamError",
     "classify_http_error",
 ]

echotools-1.0.4/src/echotools/errors/classify.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+"""HTTP 状态码错误分类——含上下文长度检测。"""
+
+from typing import Optional
+
+from echotools.errors.base import EchoError
+from echotools.errors.common import (
+    NetworkError,
+    NotSupportedError,
+    TimeoutError,
+    ValidationError,
+)
+from echotools.errors.http import (
+    AuthError,
+    ContextLengthError,
+    NotFoundError,
+    QuotaExceededError,
+    RateLimitError,
+    ServerError,
+)
+
+__all__ = ["classify_http_error"]
+
+_CONTEXT_KEYWORDS = (
+    "context",
+    "token",
+    "max_tokens",
+    "maximum context",
+    "prompt is too long",
+    "上下文",
+    "超长",
+    "超出",
+)
+
+
+def classify_http_error(
+    status_code: int,
+    message: str,
+    original: Optional[Exception] = None,
+) -> EchoError:
+    """根据 HTTP 状态码分类错误。
+
+    支持的特殊检测：
+    - 400 + 上下文关键词 → ContextLengthError
+    - 401 → AuthError
+    - 402 → QuotaExceededError
+    - 404 → NotFoundError
+    - 429 → RateLimitError
+    - 5xx → ServerError
+
+    Args:
+        status_code: HTTP 状态码。
+        message: 错误信息。
+        original: 原始异常。
+
+    Returns:
+        对应的 EchoError 实例。
+    """
+    if status_code == 400:
+        msg_lower = message.lower()
+        if any(kw in msg_lower for kw in _CONTEXT_KEYWORDS):
+            return ContextLengthError(message, original=original)
+        return ValidationError(message)
+    if status_code == 401:
+        return AuthError(message, original=original)
+    if status_code == 402:
+        return QuotaExceededError(message, original=original)
+    if status_code == 404:
+        return NotFoundError(message, original=original)
+    if status_code in (408, 504):
+        return TimeoutError(message)
+    if status_code == 429:
+        return RateLimitError(message, original=original)
+    if status_code == 501:
+        return NotSupportedError(message)
+    if status_code >= 500:
+        return ServerError(message, http_status=status_code, original=original)
+    err = EchoError(message, original=original, status_code=status_code)
+    return err

echotools-1.0.4/src/echotools/errors/http.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+"""HTTP 状态码相关的通用异常类。
+
+适用于 API 网关、代理等 HTTP 服务场景。
+"""
+
+from typing import Optional
+
+from echotools.errors.base import EchoError
+
+__all__ = [
+    "HttpError",
+    "AuthError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "ContextLengthError",
+    "ServerError",
+    "StreamError",
+]
+
+
+class HttpError(EchoError):
+    """HTTP 错误基类。"""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, original=original, status_code=status_code)
+
+
+class AuthError(HttpError):
+    """认证失败 (401)。"""
+
+    def __init__(
+        self,
+        message: str = "认证失败",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=401, original=original)
+
+
+class ForbiddenError(HttpError):
+    """权限不足 (403)。"""
+
+    def __init__(
+        self,
+        message: str = "权限不足",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=403, original=original)
+
+
+class NotFoundError(HttpError):
+    """资源不存在 (404)。"""
+
+    def __init__(
+        self,
+        message: str = "资源不存在",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=404, original=original)
+
+
+class RateLimitError(HttpError):
+    """速率限制 (429)。"""
+
+    def __init__(
+        self,
+        message: str = "请求频率超限",
+        retry_after: Optional[float] = None,
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=429, original=original)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(HttpError):
+    """配额耗尽 (402)。"""
+
+    def __init__(
+        self,
+        message: str = "配额已耗尽",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=402, original=original)
+
+
+class ContextLengthError(HttpError):
+    """上下文长度超限 (400)。"""
+
+    def __init__(
+        self,
+        message: str = "输入超过最大上下文长度",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=400, original=original)
+
+
+class ServerError(HttpError):
+    """服务器错误 (5xx)。"""
+
+    def __init__(
+        self,
+        message: str = "服务器错误",
+        http_status: int = 500,
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=http_status, original=original)
+        self.http_status = http_status
+
+
+class StreamError(HttpError):
+    """流式响应错误。"""
+
+    def __init__(
+        self,
+        message: str = "流式响应中断",
+        original: Optional[Exception] = None,
+    ) -> None:
+        super().__init__(message, status_code=502, original=original)

{echotools-1.0.2 → echotools-1.0.4}/src/echotools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 1.0.2
+Version: 1.0.4
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Author: nichengfuben
 License: MIT

{echotools-1.0.2 → echotools-1.0.4}/src/echotools.egg-info/SOURCES.txt

@@ -18,10 +18,12 @@ src/echotools/dispatch/__init__.py
 src/echotools/dispatch/candidate.py
 src/echotools/dispatch/dispatcher.py
 src/echotools/dispatch/selector.py
+src/echotools/dispatch/usage.py
 src/echotools/errors/__init__.py
 src/echotools/errors/base.py
 src/echotools/errors/classify.py
 src/echotools/errors/common.py
+src/echotools/errors/http.py
 src/echotools/events/__init__.py
 src/echotools/events/bus.py
 src/echotools/events/event.py

echotools-1.0.2/src/echotools/errors/classify.py

@@ -1,42 +0,0 @@
-from __future__ import annotations
-
-"""HTTP 状态码错误分类。"""
-
-from typing import Optional
-
-from echotools.errors.base import EchoError
-from echotools.errors.common import (
-    NetworkError,
-    NotSupportedError,
-    TimeoutError,
-    ValidationError,
-)
-
-__all__ = ["classify_http_error"]
-
-
-def classify_http_error(
-    status_code: int,
-    message: str,
-    original: Optional[Exception] = None,
-) -> EchoError:
-    """根据 HTTP 状态码分类错误。
-
-    Args:
-        status_code: HTTP 状态码。
-        message: 错误信息。
-        original: 原始异常。
-
-    Returns:
-        对应的 EchoError 实例。
-    """
-    if status_code == 400:
-        return ValidationError(message)
-    if status_code in (408, 504):
-        return TimeoutError(message)
-    if status_code == 501:
-        return NotSupportedError(message)
-    if status_code >= 500:
-        return NetworkError(message, original=original)
-    err = EchoError(message, original=original, status_code=status_code)
-    return err