phocinae-cli 0.1.0__py3-none-any.whl

phocinae_cli/__init__.py

@@ -0,0 +1,10 @@
+"""phocinae CLI —— 斑海豹 /v1/systemone 命令行客户端。
+
+一行命令本地决策：decide / classify / route / score / gate / ping。
+协议：TypeSafe System One API（POST /v1/systemone）。
+"""
+
+__version__ = "0.1.0"
+
+DEFAULT_SERVER = "http://127.0.0.1:8155"
+DEFAULT_MODEL = "Phocinae-Largha-150M-v1"

phocinae_cli/__main__.py

@@ -0,0 +1,6 @@
+"""python -m phocinae_cli 入口。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

phocinae_cli/classify_route.py

@@ -0,0 +1,129 @@
+"""classify_route.py —— classify 与 route 子命令。
+
+classify：state + labels → choice 题，输出选中标签 + 置信度 + 各标签概率。
+route   ：state + 工具列表（≤10，name 或 name:desc）→ choice 题 + 4 排列平均
+          （canonical 口径，与 phocinae-router 一致），输出工具 + 概率 + escalate。
+tau=0.6 为 E1 升级门冻结口径：置信度 < tau 建议升级外部模型。
+"""
+
+import sys
+
+import typer
+
+from . import output
+from .client import MAX_OPTIONS, PhocinaeError, unwrap_choice
+from .questions import QuestionSpecError
+from .router_const import MAX_TOOLS, TAU_DEFAULT
+
+
+def _read_state_stdin(state):
+    if state == "-" or (not state and not sys.stdin.isatty()):
+        data = sys.stdin.read().strip()
+        if not data:
+            raise QuestionSpecError("stdin 为空，无法取得 state")
+        return data
+    if state:
+        return state
+    raise QuestionSpecError(
+        "需要 state：--state '文本'，或 echo '文本' | phocinae ...")
+
+
+def _print_choice_result(ctx, body, qid, options, what):
+    answers = body.get("answers", {})
+    confs = body.get("answer_confidence", {})
+    raw = unwrap_choice(answers.get(qid))
+    if not isinstance(raw, int) or not 0 <= raw < len(options):
+        raise PhocinaeError("choice 答案异常：%r（选项数 %d）"
+                            % (raw, len(options)))
+    conf = confs.get(qid)
+    conf_f = float(conf) if isinstance(conf, (int, float)) else None
+    if ctx.obj.json:
+        output.print_json(body)
+        return
+    output.console.print(
+        "[bold green]%s: %s[/]  (index=%d)"
+        % (what, options[raw], raw))
+    if conf_f is not None:
+        escalate = conf_f < TAU_DEFAULT
+        output.console.print(
+            "confidence: %.4f   tau=%.2f   escalate: [bold %s]%s[/]"
+            % (conf_f, TAU_DEFAULT,
+               "red" if escalate else "green", escalate))
+    scores = (body.get("option_scores") or {}).get(qid)
+    if scores:
+        output.scores_table(qid, scores, title="选项概率（标定）",
+                            labels=options)
+    output.console.print(
+        "  model: %s" % body.get("model", "?"), style="dim")
+
+
+def _parse_tools(tools):
+    """工具列表解析：'name' 或 'name:desc'（逗号分隔，可重复）。"""
+    names, descs = [], []
+    for spec in tools:
+        for part in spec.split(","):
+            part = part.strip()
+            if not part:
+                continue
+            name, sep, desc = part.partition(":")
+            name = name.strip()
+            if not name:
+                raise QuestionSpecError("工具名不能为空：%r" % part)
+            if name in names:
+                raise QuestionSpecError("工具名重复：%r" % name)
+            names.append(name)
+            descs.append(desc.strip() if sep and desc.strip() else None)
+    if not names:
+        raise QuestionSpecError("--tools 至少需要一个工具（name 或 name:desc）")
+    if len(names) > MAX_TOOLS:
+        raise QuestionSpecError(
+            "工具数 %d 超过 %d 上限（JevBench tool_selection 域界）"
+            % (len(names), MAX_TOOLS))
+    options = [("%s: %s" % (n, d[:160])) if d else n
+               for n, d in zip(names, descs)]
+    return names, options
+
+
+def classify(
+    ctx: typer.Context,
+    state: str = typer.Option(None, "--state", "-s", help="决策上下文"),
+    labels: str = typer.Option(..., "--labels", "-l",
+                               help="候选标签，逗号分隔（1–255 个）"),
+    perm: bool = typer.Option(False, "--perm", help="4 排列平均"),
+):
+    """state + labels → 单选标签。"""
+    opts = [x.strip() for x in labels.split(",") if x.strip()]
+    if not opts:
+        output.fail("--labels 至少需要一个标签")
+    if len(opts) > MAX_OPTIONS:
+        output.fail("标签数 %d 超过上限 %d" % (len(opts), MAX_OPTIONS))
+    try:
+        state_text = _read_state_stdin(state)
+        body = ctx.obj.client().systemone(
+            state_text, [{"id": "classify", "type": "choice", "options": opts}],
+            perm=perm)
+    except (PhocinaeError, QuestionSpecError) as exc:
+        output.fail(str(exc))
+    _print_choice_result(ctx, body, "classify", opts, "label")
+    raise SystemExit(output.EXIT_OK)
+
+
+def route(
+    ctx: typer.Context,
+    state: str = typer.Option(None, "--state", "-s", help="决策上下文"),
+    tools: list[str] = typer.Option(
+        ..., "--tools", "-t", help="工具列表 'name' 或 'name:desc'，逗号分隔，可重复"),
+    no_perm: bool = typer.Option(
+        False, "--no-perm", help="关闭 4 排列平均（默认开启，canonical 口径）"),
+):
+    """state + 工具列表 → 工具选择（4 排列平均 + escalate）。"""
+    try:
+        names, options = _parse_tools(tools)
+        state_text = _read_state_stdin(state)
+        body = ctx.obj.client().systemone(
+            state_text, [{"id": "tool", "type": "choice", "options": options}],
+            perm=not no_perm)
+    except (PhocinaeError, QuestionSpecError) as exc:
+        output.fail(str(exc))
+    _print_choice_result(ctx, body, "tool", names, "tool")
+    raise SystemExit(output.EXIT_OK)

phocinae_cli/cli.py

@@ -0,0 +1,121 @@
+"""cli.py —— phocinae CLI 主程序（typer）。
+
+子命令：decide / classify / route / score / gate / ping。
+全局选项：--server（env PHOC_SERVER）、--timeout、--retries、--model、
+--json、--verbose。
+"""
+
+import os
+import sys
+from dataclasses import dataclass
+
+import typer
+
+from . import DEFAULT_MODEL, DEFAULT_SERVER, __version__
+from .client import CONNECT_TIMEOUT, DEFAULT_RETRIES, DEFAULT_TIMEOUT, Client
+from .output import EXIT_ERROR, EXIT_OK, console, kv_table, print_json
+
+app = typer.Typer(
+    name="phocinae",
+    help="斑海豹 phocinae CLI —— 一行命令本地决策（/v1/systemone 客户端）。",
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+
+@dataclass
+class Ctx:
+    """全局配置（typer callback 注入 ctx.obj）。"""
+    server: str = DEFAULT_SERVER
+    timeout: float = DEFAULT_TIMEOUT
+    retries: int = DEFAULT_RETRIES
+    model: str = DEFAULT_MODEL
+    json: bool = False
+    verbose: bool = False
+
+    def client(self, timeout=None):
+        return Client(server=self.server, timeout=timeout or self.timeout,
+                      retries=self.retries, model=self.model,
+                      verbosity=1 if self.verbose else 0)
+
+
+@app.callback()
+def _main(
+    ctx: typer.Context,
+    server: str = typer.Option(
+        os.environ.get("PHOC_SERVER", DEFAULT_SERVER),
+        "--server", help="phocinae-server 基地址（env PHOC_SERVER）"),
+    timeout: float = typer.Option(
+        DEFAULT_TIMEOUT, "--timeout", help="总请求超时秒数（默认 30）"),
+    retries: int = typer.Option(
+        DEFAULT_RETRIES, "--retries", help="连接错误/5xx 重试次数（默认 3）"),
+    model: str = typer.Option(
+        DEFAULT_MODEL, "--model", help="模型名（默认 Phocinae-Largha-150M-v1）"),
+    json_: bool = typer.Option(
+        False, "--json", help="输出原始 JSON（默认富表格）"),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="显示重试与完整选项概率"),
+    version_flag: bool = typer.Option(
+        False, "--version", help="打印版本并退出"),
+):
+    if version_flag:
+        console.print("phocinae CLI %s" % __version__)
+        raise SystemExit(EXIT_OK)
+    ctx.obj = Ctx(server=server, timeout=timeout, retries=retries,
+                  model=model, json=json_, verbose=verbose)
+
+
+@app.command()
+def ping(ctx: typer.Context):
+    """健康检查：GET /health + GET /v1/models。成功 exit 0，失败 exit 1。"""
+    c = ctx.obj.client()
+    try:
+        health = c.health()
+        models = c.models()
+    except Exception as exc:
+        sys.stderr.write("phocinae: 错误：%s\n" % exc)
+        raise SystemExit(EXIT_ERROR)
+    if ctx.obj.json:
+        print_json({"health": health, "models": models})
+        raise SystemExit(EXIT_OK)
+    data = (models.get("data") or [{}])[0]
+    kv_table([
+        ("endpoint", c.server),
+        ("status", health.get("status")),
+        ("model", health.get("model")),
+        ("model_loaded", health.get("model_loaded")),
+        ("device", health.get("device")),
+        ("uptime_s", health.get("uptime_s")),
+        ("context_length", data.get("context_length")),
+        ("perm_avg", data.get("perm_avg")),
+        ("extensions", ", ".join(data.get("extensions") or [])),
+    ], title="phocinae-server 健康检查")
+    raise SystemExit(EXIT_OK)
+
+
+# 子命令注册（函数定义于各模块，直接挂到主 app：phocinae decide ...）
+from . import classify_route, decide, score_gate_cli  # noqa: E402
+
+app.command("decide",
+            help="state + questions → answers（表格式/JSON；管道与批量模式）")(
+    decide.decide)
+app.command("classify",
+            help="state + labels → 单选标签（choice 题）")(
+    classify_route.classify)
+app.command("route",
+            help="state + 工具列表 → 工具选择（4 排列平均 + escalate）")(
+    classify_route.route)
+app.command("score",
+            help="state + criteria → 2–10 风险分（含各档概率）")(
+    score_gate_cli.score)
+app.command("gate",
+            help="命令审批门：allow / deny / ask（L0 离线 + 可选 L1 + fail-closed）")(
+    score_gate_cli.gate)
+
+
+def main():
+    # typer 的 no_args_is_help 在无子命令时会跳过 callback → 预先处理 --version
+    if "--version" in sys.argv[1:]:
+        console.print("phocinae CLI %s" % __version__)
+        raise SystemExit(EXIT_OK)
+    app()

phocinae_cli/client.py

@@ -0,0 +1,243 @@
+"""client.py —— phocinae-server HTTP 客户端。
+
+httpx 重试（连接错误/5xx，指数退避，4xx 不重试）、超时分层
+（connect 5s / 总 timeout 默认 30s）、错误分类（服务未启动给可行动提示）。
+"""
+
+import json
+import os
+import time
+
+import httpx
+
+from . import DEFAULT_MODEL, DEFAULT_SERVER, __version__
+
+DEFAULT_TIMEOUT = 30.0
+CONNECT_TIMEOUT = 5.0
+DEFAULT_RETRIES = 3
+MAX_QUESTIONS = 64
+MAX_OPTIONS = 255
+MAX_BATCH = 64
+
+STARTUP_HINT = (
+    "phocinae-server 似乎未在运行（{server}）。启动方式：\n"
+    "  · 官方包：pip install phocinae-server，然后运行其 run_server.sh\n"
+    "    （export PHOC_MODEL_DIR=<hf_repo 路径>；默认端口 8155）\n"
+    "  · 源码：python -m phocinae.main --host 127.0.0.1 --port 8155\n"
+    "或先运行 `phocinae ping` 确认服务状态；"
+    "本 CLI 可用 --server 指定地址，或用环境变量 PHOC_SERVER。"
+)
+
+
+class PhocinaeError(Exception):
+    """phocinae CLI 错误基类（exit 1）。"""
+
+
+class ServerUnavailableError(PhocinaeError):
+    """连接不上 / DNS / 连接拒绝。"""
+
+
+class ServerTimeoutError(PhocinaeError):
+    """请求超时。"""
+
+
+class ServerHTTPError(PhocinaeError):
+    """服务返回非 2xx（含 422 校验错、401 鉴权、413 超大）。"""
+
+    def __init__(self, status, detail):
+        super().__init__("phocinae-server 返回 HTTP %d：%s" % (status, detail))
+        self.status = status
+        self.detail = detail
+
+
+class ResponseShapeError(PhocinaeError):
+    """200 但响应结构不符合 /v1/systemone 协议。"""
+
+
+# ---------------------------------------------------------- 应答解包（P0 兼容）
+def _unwrap(value, keys):
+    """兼容 P0 扁平值与旧 mock 嵌套对象（{type, noul|score|choice, ...}）。
+
+    与 phocinae-mcp backend._unwrap 同口径。
+    """
+    seen = 0
+    while isinstance(value, dict) and seen < 4:
+        seen += 1
+        hit = None
+        for key in keys:
+            if key in value:
+                hit = value[key]
+                break
+        if hit is None:
+            for key in ("answer", "value"):
+                if key in value:
+                    hit = value[key]
+                    break
+        if hit is None:
+            return None
+        value = hit
+    return value
+
+
+def unwrap_noul(value):
+    return _unwrap(value, ("noul",))
+
+
+def unwrap_choice(value):
+    return _unwrap(value, ("choice", "index"))
+
+
+def unwrap_score(value):
+    return _unwrap(value, ("score",))
+
+
+def noul_to_probability(noul):
+    """扁平 bool → 放行概率；数值原样传递（与 guard/mcp 同口径）。"""
+    if noul is True:
+        return 1.0
+    if noul is False:
+        return 0.0
+    return float(noul)
+
+
+class Client:
+    """/v1/systemone 客户端：重试 + 超时 + 错误分类。"""
+
+    def __init__(self, server=DEFAULT_SERVER, timeout=DEFAULT_TIMEOUT,
+                 retries=DEFAULT_RETRIES, model=DEFAULT_MODEL,
+                 token=None, verbosity=0):
+        self.server = (server or DEFAULT_SERVER).rstrip("/")
+        self.timeout = max(0.1, float(timeout))
+        self.retries = max(0, int(retries))
+        self.model = model or DEFAULT_MODEL
+        self.token = token or os.environ.get("PHOC_BEARER_TOKEN") or None
+        self.verbosity = verbosity
+
+    # ------------------------------------------------------------ 内部工具
+    def _headers(self):
+        h = {"Content-Type": "application/json",
+             "User-Agent": "phocinae-cli/" + __version__}
+        if self.token:
+            h["Authorization"] = "Bearer " + self.token
+        return h
+
+    def _request(self, method, path, body=None):
+        """带重试的 HTTP 请求。连接错误/超时/5xx 重试，4xx 立即抛出。"""
+        url = self.server + path
+        payload = json.dumps(body, ensure_ascii=False).encode("utf-8") if body is not None else None
+        last_exc = None
+        for attempt in range(self.retries + 1):
+            if self.verbosity >= 1 and attempt > 0:
+                print("  [retry %d/%d] %s %s" % (attempt, self.retries, method, path),
+                      file=os.sys.stderr)
+            try:
+                with httpx.Client(timeout=httpx.Timeout(
+                        self.timeout, connect=CONNECT_TIMEOUT),
+                        trust_env=False) as http:
+                    resp = http.request(method, url, content=payload,
+                                        headers=self._headers())
+            except (httpx.ConnectError, httpx.ConnectTimeout) as exc:
+                last_exc = exc
+                if attempt < self.retries:
+                    time.sleep(0.4 * (2 ** attempt))
+                    continue
+                raise ServerUnavailableError(
+                    "无法连接 phocinae-server（%s）：%s\n%s"
+                    % (url, exc, STARTUP_HINT.format(server=self.server))) from exc
+            except httpx.ReadTimeout as exc:
+                last_exc = exc
+                if attempt < self.retries:
+                    time.sleep(0.4 * (2 ** attempt))
+                    continue
+                raise ServerTimeoutError(
+                    "请求超时（>%.1fs）：%s\n可加大 --timeout 或检查服务负载（"
+                    "permute 端点 4× 前向、批量端点 ≤64 题，都更慢）。"
+                    % (self.timeout, url)) from exc
+            if 500 <= resp.status_code <= 599 and attempt < self.retries:
+                last_exc = ServerHTTPError(resp.status_code,
+                                           resp.text[:300].replace("\n", " "))
+                time.sleep(0.4 * (2 ** attempt))
+                continue
+            if resp.status_code >= 400:
+                if resp.status_code == 422:
+                    detail = self._extract_detail(resp)
+                    raise ServerHTTPError(422, detail)
+                raise ServerHTTPError(resp.status_code,
+                                      resp.text[:300].replace("\n", " "))
+            return resp
+        raise last_exc  # pragma: no cover
+
+    @staticmethod
+    def _extract_detail(resp):
+        try:
+            data = resp.json()
+        except ValueError:
+            return resp.text[:300].replace("\n", " ")
+        if isinstance(data, dict):
+            if "detail" in data:
+                d = data["detail"]
+                return json.dumps(d, ensure_ascii=False)[:300]
+            err = data.get("error")
+            if isinstance(err, dict):
+                return "%s: %s" % (err.get("code"), err.get("message"))
+        return resp.text[:300].replace("\n", " ")
+
+    @staticmethod
+    def _parse(resp):
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise ResponseShapeError(
+                "服务响应不是合法 JSON（%s；URL=%s）" % (exc, resp.url)) from exc
+
+    def _check_answers(self, body, questions):
+        answers = body.get("answers")
+        if not isinstance(answers, dict):
+            raise ResponseShapeError(
+                "响应缺少 answers 字段（可能是别的服务，"
+                "请确认指向 phocinae-server 的 /v1/systemone）")
+        missing = [q["id"] for q in questions if q["id"] not in answers]
+        if missing:
+            raise ResponseShapeError("响应缺少问题答案：%s" % missing)
+
+    # ------------------------------------------------------------ 对外接口
+    def systemone(self, state, questions, perm=False):
+        """POST /v1/systemone（perm=True 时走 /permute）。"""
+        body = {"model": self.model, "state": state, "questions": questions}
+        path = "/v1/systemone/permute" if perm else "/v1/systemone"
+        resp = self._request("POST", path, body)
+        data = self._parse(resp)
+        if not isinstance(data, dict):
+            raise ResponseShapeError("响应顶层不是 JSON 对象")
+        self._check_answers(data, questions)
+        return data
+
+    def batch(self, items, perm=False):
+        """POST /v1/systemone/batch；items = [(state, questions), ...]。
+        自动按 MAX_BATCH=64 分片，保持顺序。"""
+        out = []
+        reqs = [{"model": self.model, "state": s, "questions": q}
+                for s, q in items]
+        for i in range(0, len(reqs), MAX_BATCH):
+            chunk = reqs[i:i + MAX_BATCH]
+            resp = self._request("POST", "/v1/systemone/batch",
+                                 {"requests": chunk})
+            data = self._parse(resp)
+            if not isinstance(data, list):
+                raise ResponseShapeError("batch 响应顶层不是 JSON 数组")
+            out.extend(data)
+        for body, (_, questions) in zip(out, items):
+            self._check_answers(body, questions)
+        return out
+
+    def health(self):
+        resp = self._request("GET", "/health")
+        data = self._parse(resp)
+        if not isinstance(data, dict):
+            raise ResponseShapeError("/health 响应不是 JSON 对象")
+        return data
+
+    def models(self):
+        resp = self._request("GET", "/v1/models")
+        data = self._parse(resp)
+        return data

phocinae_cli/decide.py

@@ -0,0 +1,105 @@
+"""decide.py —— decide 子命令：state + questions → answers。
+
+模式：
+  常规   --state TEXT（或管道/--state - 从 stdin 读一条 state）
+  批量   --batch：stdin 每行一条 state（JSON 对象行取 "state" 键），
+         经 /v1/systemone/batch 提交（自动按 64 分片）。
+题目：--noul ID[:thr] / --choice ID:o1,o2 / --score ID / --questions-json。
+"""
+
+import json
+import sys
+
+import typer
+
+from . import output
+from .client import PhocinaeError
+from .output import console
+from .questions import QuestionSpecError, parse_specs
+
+
+def _read_state(stdin_text=None):
+    """解析 --state 参数：None 且 stdin 非 tty → 读 stdin；'-' → 读 stdin。"""
+    if stdin_text == "-":
+        return sys.stdin.read().strip()
+    if stdin_text:
+        return stdin_text
+    if not sys.stdin.isatty():
+        data = sys.stdin.read().strip()
+        if not data:
+            raise QuestionSpecError("stdin 为空，无法取得 state")
+        return data
+    raise QuestionSpecError(
+        "需要 state：--state '文本'，或 echo '文本' | phocinae decide ...")
+
+
+def _read_batch_states():
+    """批量模式：每行一条 state；JSON 对象行取 state 键。"""
+    states = []
+    for lineno, line in enumerate(sys.stdin, 1):
+        line = line.strip()
+        if not line:
+            continue
+        if line.startswith("{"):
+            try:
+                obj = json.loads(line)
+            except ValueError as exc:
+                raise QuestionSpecError(
+                    "批量输入第 %d 行不是合法 JSON：%s" % (lineno, exc))
+            if not isinstance(obj, dict) or not isinstance(obj.get("state"), str):
+                raise QuestionSpecError(
+                    "批量输入第 %d 行 JSON 对象必须含字符串 state 字段" % lineno)
+            states.append(obj["state"])
+        else:
+            states.append(line)
+    if not states:
+        raise QuestionSpecError("批量模式需要 stdin 提供至少一行 state")
+    return states
+
+
+def decide(
+    ctx: typer.Context,
+    state: str = typer.Option(None, "--state", "-s",
+                              help="决策上下文；缺省且 stdin 被管道时读 stdin"),
+    noul: list[str] = typer.Option(
+        None, "--noul", help="noul 题 ID[:threshold]，可重复"),
+    choice: list[str] = typer.Option(
+        None, "--choice", help="choice 题 ID:选项1,选项2，可重复"),
+    score: list[str] = typer.Option(
+        None, "--score", help="score 题 ID，可重复"),
+    questions_json: str = typer.Option(
+        None, "--questions-json",
+        help="完整题目规格：内联 JSON 数组或文件路径"),
+    batch: bool = typer.Option(False, "--batch", help="批量模式：stdin 每行一条 state"),
+    perm: bool = typer.Option(
+        False, "--perm", help="choice 题 4 排列平均（/v1/systemone/permute）"),
+):
+    """state + questions → answers。"""
+    client = ctx.obj.client()
+    try:
+        questions = parse_specs(noul, choice, score, questions_json)
+        if batch:
+            if state:
+                raise QuestionSpecError("--batch 与 --state 互斥")
+            states = _read_batch_states()
+            bodies = client.batch([(s, questions) for s in states], perm=perm)
+            if ctx.obj.json:
+                output.print_json(bodies)
+            else:
+                for s, body in zip(states, bodies):
+                    output.answers_table(
+                        body, questions,
+                        title="state: %s" % (s if len(s) <= 64 else s[:61] + "…"),
+                        show_option_scores=ctx.obj.verbose)
+            raise SystemExit(output.EXIT_OK)
+        state_text = _read_state(state)
+        body = client.systemone(state_text, questions, perm=perm)
+    except (PhocinaeError, QuestionSpecError) as exc:
+        output.fail(str(exc))
+    if ctx.obj.json:
+        output.print_json(body)
+    else:
+        console.print("state: %s" % state_text, style="dim")
+        output.answers_table(body, questions,
+                             show_option_scores=ctx.obj.verbose)
+    raise SystemExit(output.EXIT_OK)