mingpan 0.1.0__py3-none-any.whl

mingpan/__init__.py

@@ -0,0 +1,65 @@
+"""明判（MingPan）Python SDK —— 三原语判断接口的类型安全客户端。
+
+    from mingpan import Client, choice, score, noul
+
+    client = Client(api_key="sk-xxx")          # 控制台创建
+    result = client.judge(
+        state="工单：客户反映发票抬头开错，要求尽快重开，语气着急。",
+        questions={
+            "intent":  choice({"售后": "退换货", "物流": "发货配送", "计费": "账单退款"}),
+            "urgency": score(["平静", "略不满", "明显不满", "情绪激烈", "准备投诉"]),
+            "is_vip":  noul("该用户是 VIP 客户"),
+        },
+    )
+
+    result.choice("intent").choice      # '计费'
+    result.score("urgency").score       # 1.5
+    result.noul("is_vip").noul          # 0.58
+
+三个原语的响应形状不同，SDK 如实分派成三个类 —— 尤其 noul **没有 confidence**，
+所以 `NoulAnswer` 上没有这个属性。别指望它「统一」：给不存在的字段补 0.0
+只会让路由代码静默走错分支。
+"""
+
+from .client import DEFAULT_BASE_URL, DEFAULT_MODEL, DEFAULT_PATH, Client
+from .errors import (
+    AuthenticationError,
+    InvalidRequestError,
+    MingpanError,
+    RateLimitError,
+    ServiceUnavailableError,
+    TransportError,
+    TypeMismatchError,
+)
+from .questions import choice, noul, score
+from .types import Answer, ChoiceAnswer, JudgeResult, NoulAnswer, ScoreAnswer, Usage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # 客户端
+    "Client",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_MODEL",
+    "DEFAULT_PATH",
+    # 原语构造
+    "choice",
+    "score",
+    "noul",
+    # 结果类型
+    "JudgeResult",
+    "ChoiceAnswer",
+    "ScoreAnswer",
+    "NoulAnswer",
+    "Answer",
+    "Usage",
+    # 异常
+    "MingpanError",
+    "TransportError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "TypeMismatchError",
+    "__version__",
+]

mingpan/client.py

@@ -0,0 +1,293 @@
+"""判断接口客户端。
+
+只做三件事：拼 JSON、发 POST、把响应派发成类型化对象。**没有任何隐藏逻辑** ——
+不重试、不缓存、不改写参数、不吞错误。每一层行为都能从代码上一眼确认。
+
+        from mingpan import Client, choice, score, noul
+
+        client = Client(api_key="sk-xxx")
+        result = client.judge(
+            state="工单：客户反映发票抬头开错，要求尽快重开，语气着急。",
+            questions={
+                "intent":  choice({"售后": "退换货", "物流": "发货配送", "计费": "账单退款"}),
+                "urgency": score(["平静", "略不满", "明显不满", "情绪激烈", "准备投诉"]),
+                "is_vip":  noul("该用户是 VIP 客户"),
+            },
+        )
+
+        print(result.choice("intent").choice)        # 类型确定，不是 dict
+        print(result.score("urgency").score)         # float
+        print(result.noul("is_vip").is_true(0.6))    # bool
+
+为什么用标准库 urllib 而不是 requests / httpx：
+    SDK 的价值在于「薄」。多一个运行时依赖就多一份版本冲突，而它要做的只是
+    发一个 POST。代价是少了连接池复用 —— 但判断是**同步请求-响应**，
+    单次 700ms 量级，连接池收益远小于依赖成本；真要高并发请用 `judge_batch`。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import urllib.error
+import urllib.request
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Union
+
+from .errors import MingpanError, TransportError, error_for
+from .types import JudgeResult, Usage, parse_answers
+
+__all__ = ["Client", "DEFAULT_BASE_URL", "DEFAULT_PATH", "DEFAULT_MODEL"]
+
+# 判断接口的正式入口。走 BFF 的统一入口，用户无需关心底层是哪台网关。
+DEFAULT_BASE_URL = "https://mingpan.oneapis.cn"
+DEFAULT_PATH = "/v1/judge"
+
+# 滚动别名：上游会把它解析成具体版本号（如 jev-1.13.0）并回填在响应的 model 字段里。
+DEFAULT_MODEL = "jev-latest"
+
+DEFAULT_TIMEOUT = 90.0  # 输入上限 64k token，网关侧还有一层转发，给足余量
+
+_VERSION = "0.1.0"
+_USER_AGENT = f"mingpan-python/{_VERSION}"
+
+
+def _with_sk(key: str) -> str:
+    """补齐 `sk-` 前缀（幂等）。
+
+    上游存的 Key 是纯随机串，但**调用必须带 `sk-`**。缺前缀时服务端返回 401
+    「令牌无效」，而 Key 本身看起来完全正常 —— 这是最难自己发现的一类错，
+    所以在这里兜住，而不是等用户去比对字符。
+    """
+    if not key or not str(key).strip():
+        raise ValueError("api_key 不能为空（控制台「API Key」页可创建）")
+    key = str(key).strip()
+    return key if key.startswith("sk-") else "sk-" + key
+
+
+def _extract_message(body: Any, status: int) -> str:
+    """从各种错误信封里取一句可读的 message。
+
+    服务端在不同层次会返回不同形状，逐个探测、只在明确命中时取值：
+        {"error": {"message": ...}}   —— 对外接口（OpenAI 风格）
+        {"success": false, "message": ...}
+        {"detail": ...}               —— FastAPI 校验错误
+    """
+    if isinstance(body, dict):
+        err = body.get("error")
+        if isinstance(err, dict) and err.get("message"):
+            return str(err["message"])
+        if isinstance(err, str) and err:
+            return err
+        if body.get("message"):
+            return str(body["message"])
+        if body.get("detail"):
+            detail = body["detail"]
+            if isinstance(detail, str):
+                return detail
+            if isinstance(detail, list) and detail:
+                parts = []
+                for d in detail[:4]:
+                    if isinstance(d, dict):
+                        loc = ".".join(str(x) for x in (d.get("loc") or []))
+                        parts.append(f"{loc}: {d.get('msg', '')}".strip(": "))
+                if parts:
+                    return "; ".join(parts)
+    if isinstance(body, str) and body.strip():
+        return body.strip()[:300]
+    return f"HTTP {status}"
+
+
+def _to_result(body: Mapping[str, Any]) -> JudgeResult:
+    usage = body.get("usage") or {}
+    return JudgeResult(
+        model=str(body.get("model") or ""),
+        answers=parse_answers(body.get("answers")),
+        usage=Usage(
+            input_tokens=int(usage.get("input_tokens") or 0),
+            output_tokens=int(usage.get("output_tokens") or 0),
+        ),
+        raw=body,
+    )
+
+
+class Client:
+    """判断接口客户端。
+
+    :param api_key: 控制台创建的 API Key（`sk-` 开头）
+    :param base_url: 服务地址，默认正式环境；自建网关时改成自己的域名
+    :param path: 判断接口路径。只有直连插件网关时才需要改，例如
+        `Client(key, base_url="https://your-gateway", path="/typesafe/v1/systemone")`
+    :param model: 默认模型，可在单次调用里用 `model=` 覆盖
+    :param timeout: 单次请求超时（秒）
+    :param use_env_proxy: 是否沿用环境变量里的 HTTP(S)_PROXY。
+        **默认 True**（企业网络下通常必须走代理）；置 False 可绕过本机代理 ——
+        代理配错时的症状是「同一个 Key 在 curl 里能通、在脚本里连不上」。
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        path: str = DEFAULT_PATH,
+        model: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        use_env_proxy: bool = True,
+        user_agent: Optional[str] = None,
+    ) -> None:
+        self.api_key = _with_sk(api_key)
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self.path = path if path.startswith("/") else "/" + path
+        self.model = model or DEFAULT_MODEL
+        self.timeout = float(timeout)
+        self.user_agent = user_agent or _USER_AGENT
+        # 显式构造 opener：urllib 默认会读 http_proxy/https_proxy，
+        # 这里把它变成一个可见的选择，而不是一个难以定位的隐式行为。
+        if use_env_proxy:
+            self._opener = urllib.request.build_opener()
+        else:
+            self._opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+
+    # ---------- 公开 API ----------
+    def judge(
+        self,
+        *,
+        questions: Mapping[str, Any],
+        state: Any = None,
+        model: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> JudgeResult:
+        """发起一次判断。
+
+        :param questions: 问题表，键为自定义 ID，值用 `choice()` / `score()` / `noul()` 构造
+        :param state: 被判断的材料。文本、JSON 对象、数组均可；模型只读它、不续写它
+        :param model: 覆盖默认模型
+        :return: `JudgeResult`
+        :raises AuthenticationError: Key 无效或无权限
+        :raises InvalidRequestError: 参数不符合契约（message 会指出正确写法）
+        :raises RateLimitError: 限流或额度用尽
+        :raises ServiceUnavailableError: 服务端/上游暂时不可用（不计费，可退避重试）
+        :raises TransportError: 网络层失败
+        """
+        if not isinstance(questions, Mapping) or not questions:
+            raise ValueError("questions 必须是非空映射，例如 {'intent': choice([...])}")
+
+        payload: Dict[str, Any] = {
+            "model": model or self.model,
+            "questions": dict(questions),
+        }
+        if state is not None:
+            payload["state"] = state
+
+        return _to_result(self._post(payload, timeout))
+
+    async def judge_async(
+        self,
+        *,
+        questions: Mapping[str, Any],
+        state: Any = None,
+        model: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> JudgeResult:
+        """异步版本。
+
+        实现是 `asyncio.to_thread` 包装同步调用 —— 目的是**不阻塞事件循环**，
+        而不是并发（单次判断本身就是同步请求-响应）。要并发多个 state 用 `judge_batch`。
+        """
+        return await asyncio.to_thread(
+            self.judge, questions=questions, state=state, model=model, timeout=timeout
+        )
+
+    def judge_batch(
+        self,
+        *,
+        states: Sequence[Any],
+        questions: Mapping[str, Any],
+        model: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_workers: int = 8,
+        return_exceptions: bool = False,
+    ) -> List[Union[JudgeResult, MingpanError]]:
+        """批量：多个 state 共享同一套 questions。
+
+        返回值与 `states` **按下标一一对应**（不是完成顺序）。
+
+        :param max_workers: 并发上限。默认 8 —— 再高只会先撞上游限流，
+            换来一批 429，不如小并发稳跑。
+        :param return_exceptions: True 时把单条失败作为异常对象放进结果列表，
+            便于「一批里坏了一条不影响其余」的离线批处理。默认 False（任一失败即抛）。
+        """
+        items = list(states)
+        if not items:
+            return []
+
+        results: List[Any] = [None] * len(items)
+
+        def _one(st: Any):
+            return self.judge(questions=questions, state=st, model=model, timeout=timeout)
+
+        with ThreadPoolExecutor(max_workers=max(1, min(max_workers, len(items)))) as ex:
+            futures = [ex.submit(_one, st) for st in items]
+            for i, fut in enumerate(futures):
+                try:
+                    results[i] = fut.result()
+                except MingpanError as e:
+                    if not return_exceptions:
+                        # 别让剩下的请求继续跑：多半是同一个原因（限流/Key 失效），
+                        # 继续只会把限流窗口打得更深。
+                        for f in futures:
+                            f.cancel()
+                        raise
+                    results[i] = e
+        return results
+
+    # ---------- 内部 ----------
+    def _post(self, payload: Mapping[str, Any], timeout: Optional[float]) -> Mapping[str, Any]:
+        url = self.base_url + self.path
+        data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+                "User-Agent": self.user_agent,
+            },
+        )
+
+        try:
+            with self._opener.open(req, timeout=timeout or self.timeout) as resp:
+                raw = resp.read()
+                status = resp.status
+        except urllib.error.HTTPError as e:
+            raw = e.read()
+            status = e.code
+        except urllib.error.URLError as e:
+            raise TransportError(f"无法连接判断服务（{url}）：{e.reason}") from e
+        except (TimeoutError, OSError) as e:
+            raise TransportError(f"请求判断服务失败（{url}）：{e}") from e
+
+        body: Any = None
+        if raw:
+            try:
+                body = json.loads(raw.decode("utf-8"))
+            except (ValueError, UnicodeDecodeError):
+                # 拿到 HTML 而不是 JSON，几乎总是「路径写错」或「服务没起」，
+                # 把开头一段带出来，比一句「解析失败」有用得多。
+                snippet = raw[:200].decode("utf-8", "replace").strip()
+                raise MingpanError(
+                    f"服务返回了非 JSON 内容（HTTP {status}），请检查地址 {url} 是否正确："
+                    f"{snippet}",
+                    status,
+                    raw,
+                ) from None
+
+        if status != 200:
+            raise error_for(status, _extract_message(body, status), body)
+
+        if not isinstance(body, Mapping):
+            raise MingpanError("服务返回的响应体不是 JSON 对象", status, body)
+        return body

mingpan/errors.py

@@ -0,0 +1,99 @@
+"""异常类型。
+
+设计原则：**每一类失败对应一个可分别捕获的类型**，且异常自带可读的中文 message。
+
+为什么不用一个笼统的 `MingpanError` 打天下：
+判断接口最常见的两种失败是「Key 不对」（要换 Key）和「参数写错」（要改代码），
+它们的处理方式完全不同 —— 前者重试一万次也没用，后者重试一次就成功。
+调用方需要能用 `except` 把它们分开，而不是去 parse 错误字符串。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class MingpanError(Exception):
+    """所有 SDK 异常的基类。
+
+    :param message: 可直接展示给终端用户的中文说明
+    :param status: HTTP 状态码（网络层失败时为 0）
+    :param body: 服务端返回的原始响应体，便于排查
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status: int = 0,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.body = body
+
+    def __str__(self) -> str:  # pragma: no cover - 仅影响打印
+        return f"[{self.status}] {self.message}" if self.status else self.message
+
+
+class TransportError(MingpanError):
+    """网络层失败：连不上、DNS 失败、超时。
+
+    与 HTTP 层错误分开：这个通常意味着「本机网络/代理/域名」有问题，
+    而不是「请求内容」有问题。
+    """
+
+
+class AuthenticationError(MingpanError):
+    """401 / 403：令牌缺失、无效、被吊销，或无权调用判断服务。
+
+    ⚠️ 重试没有意义。检查 Key 是否带 `sk-` 前缀、是否已被轮换。
+    """
+
+
+class InvalidRequestError(MingpanError):
+    """400 / 422：请求不符合契约。
+
+    好消息是这个错误的 message **通常直接指出了正确写法**，例如
+        "Choice criteria must contain between 1 and 255 options"
+    照着改即可，不必翻文档。
+    """
+
+
+class RateLimitError(MingpanError):
+    """429：触发限流或额度用尽。退避重试，或改用批量接口。"""
+
+
+class ServiceUnavailableError(MingpanError):
+    """5xx：服务端或上游暂时不可用。可退避重试，且这类失败不计费。"""
+
+
+class TypeMismatchError(MingpanError):
+    """取值器与原语类型不符。
+
+    这是 SDK 在**客户端**主动抛的 —— 例如对一道 `noul` 题调用 `result.choice("q1")`。
+    本地立刻报错，比拿回一个 `None` 然后在几十行之外 KeyError 好得多。
+    """
+
+
+_STATUS_MAP = {
+    400: InvalidRequestError,
+    401: AuthenticationError,
+    403: AuthenticationError,
+    422: InvalidRequestError,
+    429: RateLimitError,
+}
+
+# 上游把「路由没注册 / 未配置凭据」也归在 503，但它不是「稍后重试就好」，
+# 重试永远不会成功。单独给一句可操作的话。
+_ROUTE_HINTS = ("路由未注册", "未配置", "未注册")
+
+
+def error_for(status: int, message: str, body: Optional[Any] = None) -> MingpanError:
+    """按状态码选异常类型。"""
+    if status >= 500:
+        return ServiceUnavailableError(message, status, body)
+    cls = _STATUS_MAP.get(status)
+    if cls is not None:
+        return cls(message, status, body)
+    return MingpanError(message, status, body)

mingpan/questions.py

@@ -0,0 +1,73 @@
+"""三原语的请求侧构造。
+
+原语参数名容易记错，而且**记错时上游报的 400 恰好会告诉你正确写法**：
+
+    {"type": "choice", "options": [...]}  → 400 "Choice criteria must contain between 1 and 255 options"
+    {"type": "score",  "levels": 5}       → 400 "Score criteria must contain between 2 and 10 levels"
+    {"type": "noul",   "hint": "..."}     → 400 "Noul question must have criteria or instructions"
+
+也就是说三个原语都用 `criteria`（choice/score），noul 用 `instructions`。
+用下面这三个函数就不必记这些细节。
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Sequence, Union
+
+__all__ = ["choice", "score", "noul"]
+
+
+def choice(criteria: Union[Mapping[str, str], Sequence[str]]) -> Dict[str, Any]:
+    """choice 原语：从候选中选出唯一答案。
+
+    `criteria` 有两种写法：
+
+      · **映射（推荐）** —— 键是选项名，值是判定说明，说明会进模型：
+            choice({"售后": "退换货、维修", "物流": "发货与配送", "计费": "账单与退款"})
+
+      · **序列（简写）** —— 每个值同时当标签与说明：
+            choice(["退款", "发票", "物流"])
+
+    项数上限 255。序列写法上传的是 `{标签: 标签}`，不会产生空说明 ——
+    空字符串说明在部分上游版本会被判为非法。
+    """
+    if isinstance(criteria, Mapping):
+        if not criteria:
+            raise ValueError("choice 至少需要 1 个候选项")
+        return {"type": "choice", "criteria": {str(k): str(v) for k, v in criteria.items()}}
+    items = [str(x) for x in criteria]
+    if not items:
+        raise ValueError("choice 至少需要 1 个候选项")
+    return {"type": "choice", "criteria": {x: x for x in items}}
+
+
+def score(criteria: Sequence[str]) -> Dict[str, Any]:
+    """score 原语：把材料放到一个有序量级上打分。
+
+    `criteria` 是**从低到高**排列的级别名数组，2–10 级：
+
+        score(["平静", "略不满", "明显不满", "情绪激烈", "准备投诉"])
+
+    顺序即语义 —— 返回值 `score` 是级别序号的概率加权（0-based）。
+    写成从高到低会让所有阈值判断反过来，且不会报错。
+    """
+    items = [str(x) for x in criteria]
+    if len(items) < 2:
+        raise ValueError("score 至少需要 2 个级别")
+    if len(items) > 10:
+        raise ValueError("score 最多 10 个级别")
+    return {"type": "score", "criteria": items}
+
+
+def noul(instructions: str = "") -> Dict[str, Any]:
+    """noul 原语：判断某个命题是否成立。
+
+    返回 0–1 的连续值，**不返回 confidence**：
+
+        noul("该用户是 VIP 客户")
+        noul("用户已经准备好按方案直接落地，而非仅了解概念")
+
+    写成「可验证的完整命题」比写成关键词效果好得多 ——
+    "VIP" 这种两字提示会让模型无从判断依据是什么。
+    """
+    return {"type": "noul", "instructions": str(instructions)}

mingpan/types.py

@@ -0,0 +1,222 @@
+"""响应类型。
+
+三原语的响应形状**不同**，这是接口设计的核心事实：
+
+    noul   → {"type": "noul",  "noul": 0.58}
+                                ↑ 只有连续值，**没有 confidence**
+
+    choice → {"type": "choice", "choice": "计费", "confidence": 0.91,
+              "probabilities": {"售后": 0.09, "计费": 0.91}}
+
+    score  → {"type": "score",  "score": 1.5, "confidence": 0.32,
+              "probabilities": {"0": 0.2, "1": 0.26, ...},
+              "legend": {"0": "平静", "1": "略不满", ...}}
+
+SDK 把它们派发成三个不同的类，并且**不给 `NoulAnswer` 提供 `confidence` 属性** ——
+如果这里为了「统一」塞一个 `confidence=0.0` 进去，路由代码就会在 noul 上
+静默走错分支，而这种 bug 只会在线上以「误判率异常」的形式暴露。
+宁可让 `answer.confidence` 在 noul 上抛 AttributeError。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Union
+
+from .errors import TypeMismatchError
+
+__all__ = [
+    "ChoiceAnswer",
+    "ScoreAnswer",
+    "NoulAnswer",
+    "Answer",
+    "Usage",
+    "JudgeResult",
+]
+
+
+@dataclass(frozen=True)
+class ChoiceAnswer:
+    """choice 结果：唯一命中项 + 完整概率分布 + 置信度。"""
+
+    choice: str
+    confidence: float
+    probabilities: Mapping[str, float]
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    type = "choice"
+
+    def top(self, n: int = 2) -> list:
+        """按概率降序取前 n 项，形如 `[("计费", 0.91), ("售后", 0.09)]`。
+
+        「第二名」是判断质量的重要信号：当 top1 与 top2 贴得很近时，
+        即使 top1 概率看起来不低，也值得转人工。
+        """
+        items = sorted(self.probabilities.items(), key=lambda kv: kv[1], reverse=True)
+        return items[:n]
+
+
+@dataclass(frozen=True)
+class ScoreAnswer:
+    """score 结果：概率加权的浮点得分（0-based）。"""
+
+    score: float
+    confidence: float
+    probabilities: Mapping[str, float]
+    legend: Mapping[str, str] = field(default_factory=dict)
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    type = "score"
+
+    def label(self) -> str:
+        """得分四舍五入到最近的级别名。
+
+        ⚠️ 注意这是**为了可读性**的换算，不是接口契约的一部分：
+        `score` 本身是连续值，业务判断应直接用 `score` 比阈值，
+        不要用 label 做分支（会把边界附近的细微差别抹掉）。
+        """
+        if not self.legend:
+            return ""
+        idx = int(round(self.score))
+        return self.legend.get(str(idx), "")
+
+    def top(self, n: int = 2) -> list:
+        items = sorted(self.probabilities.items(), key=lambda kv: kv[1], reverse=True)
+        return items[:n]
+
+
+@dataclass(frozen=True)
+class NoulAnswer:
+    """noul 结果：命题成立程度，0–1 连续值。
+
+    **本类型刻意没有 `confidence` 属性** —— 上游对这个原语不返回它。
+    """
+
+    noul: float
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    type = "noul"
+
+    def is_true(self, threshold: float = 0.5) -> bool:
+        """是否判定为成立。阈值由业务定 —— SDK 给 0.5 只是为了有个可用的默认值。"""
+        return self.noul >= threshold
+
+
+Answer = Union[ChoiceAnswer, ScoreAnswer, NoulAnswer]
+
+
+@dataclass(frozen=True)
+class Usage:
+    """用量。**只有 input_tokens 计费**，output_tokens 会返回但不在计费式里。"""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+
+    @property
+    def billable_tokens(self) -> int:
+        return self.input_tokens
+
+
+@dataclass(frozen=True)
+class JudgeResult:
+    """一次判断的结果。
+
+    `answers` 与请求的 `questions` **同构**：键一一对应，形状由该题的原语类型决定。
+
+    取值优先用类型化取值器，而不是字典下标：
+
+        result.choice("intent").choice        # str，类型确定
+        result.score("urgency").score         # float
+        result.noul("is_vip").is_true(0.6)    # bool
+
+    对类型不符的题调用错误的取值器会抛 `TypeMismatchError`，
+    而不是返回 None 让你在别处踩坑。
+    """
+
+    model: str
+    answers: Dict[str, Answer]
+    usage: Usage
+    raw: Mapping[str, Any] = field(default_factory=dict, repr=False)
+
+    def __getitem__(self, qid: str) -> Answer:
+        """按问题 ID 取答案。"""
+        try:
+            return self.answers[qid]
+        except KeyError:
+            known = "、".join(self.answers) or "(空)"
+            raise KeyError(f"响应里没有问题 {qid!r}；本次返回的问题有：{known}") from None
+
+    def _typed(self, qid: str, cls, hint: str):
+        ans = self[qid]
+        if not isinstance(ans, cls):
+            raise TypeMismatchError(
+                f"问题 {qid!r} 的实际类型是 {getattr(ans, 'type', '?')}，"
+                f"不能用 {hint} 取值"
+            )
+        return ans
+
+    def choice(self, qid: str) -> ChoiceAnswer:
+        """取 choice 题的结果。类型不符则抛 `TypeMismatchError`。"""
+        return self._typed(qid, ChoiceAnswer, "result.choice()")
+
+    def score(self, qid: str) -> ScoreAnswer:
+        """取 score 题的结果。类型不符则抛 `TypeMismatchError`。"""
+        return self._typed(qid, ScoreAnswer, "result.score()")
+
+    def noul(self, qid: str) -> NoulAnswer:
+        """取 noul 题的结果。类型不符则抛 `TypeMismatchError`。"""
+        return self._typed(qid, NoulAnswer, "result.noul()")
+
+    def __repr__(self) -> str:  # pragma: no cover - 仅影响打印
+        parts = []
+        for qid, a in self.answers.items():
+            if isinstance(a, ChoiceAnswer):
+                parts.append(f"{qid}=choice({a.choice!r}, conf={a.confidence})")
+            elif isinstance(a, ScoreAnswer):
+                parts.append(f"{qid}=score({a.score}, conf={a.confidence})")
+            else:
+                parts.append(f"{qid}=noul({a.noul})")
+        return f"<JudgeResult model={self.model} {'; '.join(parts)}>"
+
+
+def parse_answers(raw_answers: Optional[Mapping[str, Any]]) -> Dict[str, Answer]:
+    """把上游响应里的 `answers` 派发成类型化对象。
+
+    未知的 `type` 一律退化成 dict 包一层的通用对象 —— 上游加了新原语时，
+    旧版 SDK 不应该直接崩（向前兼容优先于完备性）。
+    """
+    out: Dict[str, Answer] = {}
+    for qid, a in (raw_answers or {}).items():
+        if not isinstance(a, Mapping):
+            continue
+        kind = a.get("type")
+        if kind == "choice":
+            out[qid] = ChoiceAnswer(
+                choice=str(a.get("choice", "")),
+                confidence=float(a.get("confidence", 0.0) or 0.0),
+                probabilities=dict(a.get("probabilities") or {}),
+                raw=a,
+            )
+        elif kind == "score":
+            out[qid] = ScoreAnswer(
+                score=float(a.get("score", 0.0) or 0.0),
+                confidence=float(a.get("confidence", 0.0) or 0.0),
+                probabilities=dict(a.get("probabilities") or {}),
+                legend={str(k): str(v) for k, v in (a.get("legend") or {}).items()},
+                raw=a,
+            )
+        elif kind == "noul":
+            out[qid] = NoulAnswer(noul=float(a.get("noul", 0.0) or 0.0), raw=a)
+        else:
+            # 未知原语：原样保留，不猜语义
+            out[qid] = _UnknownAnswer(kind=str(kind or "?"), raw=a)  # type: ignore[assignment]
+    return out
+
+
+@dataclass(frozen=True)
+class _UnknownAnswer:
+    """上游新增了本版 SDK 不认识的原语时的兜底容器。"""
+
+    kind: str
+    raw: Mapping[str, Any] = field(default_factory=dict)
+    type = "unknown"

mingpan-0.1.0.dist-info/METADATA

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: mingpan
+Version: 0.1.0
+Summary: 明判（MingPan）Python SDK —— 三原语判断接口的类型安全客户端
+License: MIT
+Project-URL: Homepage, https://mingpan.oneapis.cn
+Project-URL: Documentation, https://mingpan.oneapis.cn/docs
+Keywords: mingpan,jev,judge,llm,type-safe,routing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# 明判 Python SDK
+
+明判（MingPan）三原语判断接口的 Python 客户端。**运行时零依赖**（只用标准库 `urllib`），
+`pip install` 后即可调用，不引入任何版本冲突。
+
+```bash
+pip install mingpan
+```
+
+**零运行时依赖** —— 装完不会引入任何第三方包（只用标准库 `urllib`）。
+需要跟仓库里最新未发版的改动时，从源码目录装：`pip install ./sdk/python`。
+
+---
+
+## 快速开始
+
+```python
+from mingpan import Client, choice, score, noul
+
+client = Client(api_key="sk-xxx")          # 控制台「API Key」页创建
+
+result = client.judge(
+    state="工单：客户反映发票抬头开错，要求尽快重开，语气着急。",
+    questions={
+        "intent":  choice({"售后": "退换货、维修", "物流": "发货与配送", "计费": "账单与退款"}),
+        "urgency": score(["平静", "略不满", "明显不满", "情绪激烈", "准备投诉"]),
+        "is_vip":  noul("该用户是 VIP 客户"),
+    },
+)
+
+result.choice("intent").choice        # '计费' —— str，不是 dict 里捞出来的
+result.score("urgency").score         # 1.5   —— float，0-based 加权
+result.noul("is_vip").is_true(0.6)    # False
+result.usage.input_tokens             # 391   —— 计费依据
+```
+
+## 三个原语
+
+| 原语 | 构造 | 返回 | 说明 |
+|---|---|---|---|
+| `choice` | `choice({"标签": "说明"})` | `choice`(str) / `confidence` / `probabilities` | 从候选中选唯一答案。**`criteria` 是对象**，1–255 项 |
+| `score` | `score(["低", "中", "高"])` | `score`(float) / `confidence` / `probabilities` / `legend` | 放到有序量级上打分。**`criteria` 是数组**，2–10 级，从低到高 |
+| `noul` | `noul("命题正文")` | `noul`(float 0–1) | 判断命题是否成立。**没有 `confidence`** |
+
+几个必须知道的事实：
+
+- **`score` 是 0-based 浮点**。`score=1.5` 表示重心落在第 2 级（序号 1）附近 ——
+  不是「1.5 分 / 满分 5 分」。别拿它当整数用。
+- **`noul` 没有 `confidence`**。SDK 如实不提供该属性：读它会 `AttributeError`，
+  而不是悄悄给个 `0.0` 让你的路由代码走错分支。
+- **`criteria` 的说明会进模型**。`{"计费": "账单与退款"}` 的判定质量明显高于
+  `["计费"]`。只给标签时模型只能靠字面猜；说明才是准确率的来源。
+- **只有 `input_tokens` 计费**。`output_tokens` 会返回（实测 58–67，不是 0），
+  但不在计费式里。
+
+## 类型安全
+
+`answers` 与 `questions` 同构，但 SDK 会按原语类型**派发成不同的类**，
+取值器对类型不符直接报错：
+
+```python
+result.noul("is_vip")      # NoulAnswer
+result.choice("is_vip")    # ✗ TypeMismatchError: 实际类型是 noul，不能用 result.choice() 取值
+```
+
+这比「字典下标 + `.get()`」安全得多：类型错了在**调用点**就炸，
+而不是在几十行之外的 `NoneType has no attribute` 处炸。
+
+## 错误处理
+
+每类失败对应一个可分别捕获的类型：
+
+```python
+from mingpan import (
+    AuthenticationError, InvalidRequestError,
+    RateLimitError, ServiceUnavailableError, TransportError,
+)
+
+try:
+    result = client.judge(state=state, questions=questions)
+except AuthenticationError:      # 401/403：Key 无效、过期、无权。重试无意义
+    rotate_key()
+except InvalidRequestError as e: # 400/422：参数不符。message 通常直接给出正确写法
+    print(e.message)             #   → "Choice criteria must contain between 1 and 255 options"
+except RateLimitError:           # 429：退避重试，或改用 judge_batch 降低并发
+    backoff()
+except ServiceUnavailableError:  # 5xx：不计费，可退避重试
+    backoff()
+except TransportError:           # 网络层：连不上/DNS/超时，检查网络或代理
+    pass
+```
+
+`InvalidRequestError` 的 message 是最有价值的错误信息 ——
+上游的校验错误会直接说出**正确字段名与取值范围**，照着改即可，不必翻文档。
+
+## 并发与批量
+
+```python
+# 单次异步（不阻塞事件循环）
+result = await client.judge_async(state=state, questions=questions)
+
+# 多个 state 共享同一套 questions，并发发送，结果按下标对应
+results = client.judge_batch(
+    states=[t1, t2, t3],
+    questions=questions,
+    max_workers=8,            # 别调太高：先撞上游限流，换来一批 429
+    return_exceptions=True,   # 单条失败作为异常对象返回，不中断整批
+)
+```
+
+## 把 confidence 接进你的代码
+
+三原语的输出可以拼成一条可测试、可审计的路由链路：
+
+```python
+r = client.judge(state=ticket, questions={
+    "intent":  choice({"退款": "要退款", "咨询": "问问题", "投诉": "表达不满"}),
+    "urgency": score(["平静", "略不满", "明显不满", "情绪激烈", "准备投诉"]),
+})
+
+# 置信度足够 + 情绪不高 → 自动执行；否则转人工
+if r.choice("intent").confidence >= 0.85 and r.score("urgency").score < 2.0:
+    auto_execute(r.choice("intent").choice)
+elif r.choice("intent").confidence >= 0.5:
+    queue_for_human(r)
+else:
+    escalate(r)     # 低置信：转大模型或人工
+```
+
+阈值按**业务误判成本**定，不是按模型表现定 —— 退款错判的代价和分类错标的代价不一样。
+路由决策本身是普通代码，所以它能被单测、能被 review、能进审计日志。
+
+## 自建网关
+
+默认走明判的正式入口（`https://mingpan.oneapis.cn/v1/judge`）。
+如果判断能力挂在自己的网关上，直接指向那里即可：
+
+```python
+client = Client(
+    api_key="sk-xxx",
+    base_url="https://your-gateway.example.com",
+    path="/typesafe/v1/systemone",   # 插件自有路由，路径与 BFF 不同
+)
+```
+
+⚠️ 不同网关实例的插件 key 与路由路径可能不同（`/typesafe/v1/systemone` vs
+`/jev/v1/systemone`），照抄另一台的路径会得到 404 或「SPA 兜底返回 HTML」。
+客户端遇到 HTML 响应会明确提示「请检查地址是否正确」，而不是报一句
+含糊的解析失败。
+
+## 代理说明
+
+SDK 默认沿用环境变量里的 `HTTP_PROXY` / `HTTPS_PROXY`（企业网络下通常必须）。
+想绕过本机代理：
+
+```python
+client = Client(api_key="sk-xxx", use_env_proxy=False)
+```
+
+代理配错时的典型症状是「同一个 Key 在 `curl` 里能通、在脚本里连不上」——
+遇到这种情况先怀疑代理，再怀疑 Key。
+
+## 开发
+
+```bash
+cd sdk/python
+python tests/test_sdk.py                              # 离线：59 项，不联网
+MINGPAN_TEST_KEY=sk-xxx python tests/test_sdk.py --live   # 真实调用（会产生费用）
+```

mingpan-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+mingpan/__init__.py,sha256=-GEk5qidGKMvGu21BmDP5-JlibMCjtl4cm3sM1HHiOM,1943
+mingpan/client.py,sha256=HSlNTcHBFrT2VDg_OaPqF620eWmcMBOwtPE7UC5ahvM,12198
+mingpan/errors.py,sha256=dEoDH1bfqGMYO-v-bp0GqH2YHN6bc4zeQaWLLQHWMNU,3335
+mingpan/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mingpan/questions.py,sha256=EK1qTMu9lPCSV8R7pSdYsuzpR_EZYIO5UEQXMIs_sr0,3051
+mingpan/types.py,sha256=6_1xurdFiqhnnAojEvD6QMhEZxR2T-oET8LqXAaAnrE,7852
+mingpan-0.1.0.dist-info/METADATA,sha256=oHk07PDdQRLqF_N9kwJUxR4GUPuVeMnOe8PjwPUhPDY,7750
+mingpan-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mingpan-0.1.0.dist-info/top_level.txt,sha256=0aYBEjP5vLhVGyIZTfagBxYgFji82EjFigjkH1equQ8,8
+mingpan-0.1.0.dist-info/RECORD,,

mingpan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mingpan-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mingpan