xg-cli 1.0__py3-none-any.whl

xg/adaptive/signals.py

@@ -0,0 +1,125 @@
+"""隐式信号的运行时判定与采集（phase-03 步骤 B）。
+
+判定用短关键词列表（不走 LLM），与 rule_router 特征共用同一条"中文子串匹配"
+思路。这里只负责"识别 + 交给 FeedbackRecorder"，不触碰路由/UI。
+
+四类可采集信号：
+- interrupt        回答中途 Ctrl+C（inline 主循环 KeyboardInterrupt 处记录）
+- clarify          上轮后紧接追问/否定，且上轮档 ≤Superior
+- cmd_retry        紧接重试类输入
+- short_high_tier  简短闲聊却落到中高档（本轮档 ≥Enhanced）
+
+红线：采集只发生在调用方显式触发时；开关关闭时调用方根本不会调用本模块，
+因此不产生任何磁盘写。
+"""
+
+from __future__ import annotations
+
+from .feedback import FeedbackRecorder, SignalType
+
+# 简短文本判定阈值（字符数）
+SHORT_TEXT_CHARS = 60
+
+# 追问/否定词（clarify 触发：上轮后紧接这类输入）
+_FOLLOWUP_WORDS = (
+    "不对", "不行", "不是这个", "再改", "再调", "重新来", "换一种", "这样呢",
+    "继续", "然后呢", "那接下来",
+    "no", "not this", "again", "instead", "rewrite", "redesign", "try again",
+)
+
+# 重试类词（cmd_retry 触发；与 clarify 部分重叠，但语义聚焦"重新执行"）
+_RETRY_WORDS = (
+    "重来", "再来", "重新试", "再试一次", "重做",
+    "retry", "redo", "again", "try once more",
+)
+
+
+def _short_and_simple(features: dict) -> bool:
+    """是否"简短闲聊/简单问答"（short_high_tier 的文本侧条件）。"""
+    return bool(features.get("is_chatty") or features.get("question_mark"))
+
+
+def detect_clarify(text: str, prev_tier: str | None, TIER_NAMES: list[str]) -> tuple[bool, int]:
+    """上轮后紧接追问/否定，且上轮档 ≤Superior。返回 (是否触发, 上轮档索引)。"""
+    if prev_tier is None:
+        return False, -1
+    try:
+        prev_idx = TIER_NAMES.index(prev_tier)
+    except ValueError:
+        return False, -1
+    low = text.lower()
+    hit = any(w in low for w in _FOLLOWUP_WORDS)
+    # ≤Superior => 索引 <= 2
+    return (hit and prev_idx <= 2), prev_idx
+
+
+def detect_cmd_retry(text: str, prev_tier: str | None) -> bool:
+    """紧接重试类输入（需有上一轮）。"""
+    if prev_tier is None:
+        return False
+    low = text.lower()
+    return any(w in low for w in _RETRY_WORDS)
+
+
+def detect_short_high_tier(text: str, features: dict, cur_tier: str | None,
+                           TIER_NAMES: list[str]) -> bool:
+    """简短闲聊却落到中高档（本轮档 ≥Enhanced，即索引 >= 1）。"""
+    if cur_tier is None:
+        return False
+    try:
+        cur_idx = TIER_NAMES.index(cur_tier)
+    except ValueError:
+        return False
+    if cur_idx < 1:
+        return False
+    if len(text) > SHORT_TEXT_CHARS:
+        return False
+    return _short_and_simple(features)
+
+
+def capture_turn_signals(
+    recorder: FeedbackRecorder,
+    text: str,
+    features: dict,
+    prev_tier: str | None,
+    cur_tier: str,
+    TIER_NAMES: list[str],
+) -> list[SignalType]:
+    """对一轮普通输入判定四类信号（不含 interrupt）并采集到 recorder。
+
+    返回实际采集的信号列表，便于测试断言。clarify / cmd_retry 用上轮档，
+    short_high_tier 用本轮档（cur_tier）。
+    """
+    emitted: list[SignalType] = []
+
+    clarify, _ = detect_clarify(text, prev_tier, TIER_NAMES)
+    if clarify:
+        recorder.capture(SignalType.CLARIFY, model_tier=prev_tier or cur_tier,
+                         text=text, features=features)
+        emitted.append(SignalType.CLARIFY)
+
+    if detect_cmd_retry(text, prev_tier):
+        recorder.capture(SignalType.CMD_RETRY, model_tier=prev_tier or cur_tier,
+                         text=text, features=features)
+        emitted.append(SignalType.CMD_RETRY)
+
+    if detect_short_high_tier(text, features, cur_tier, TIER_NAMES):
+        recorder.capture(SignalType.SHORT_HIGH_TIER, model_tier=cur_tier,
+                         text=text, features=features)
+        emitted.append(SignalType.SHORT_HIGH_TIER)
+
+    return emitted
+
+
+def capture_interrupt(
+    recorder: FeedbackRecorder,
+    cur_tier: str | None,
+) -> bool:
+    """inline 主循环在 KeyboardInterrupt 处调用，记录 interrupt 信号。
+
+    需上一个已路由档位 cur_tier 作为 model_tier；无档位则跳过。
+    """
+    if cur_tier is None:
+        return False
+    recorder.capture(SignalType.INTERRUPT, model_tier=cur_tier)
+    return True

xg/adaptive/store.py

@@ -0,0 +1,164 @@
+"""adaptive 数据的持久化工具：原子写、损坏回退读取、目录懒创建。
+
+设计依据：phase-03 步骤 A。red line 为"损坏安全"——任何读失败都回退默认
+值，绝不抛错影响启动；写文件用 tmp + os.replace（同目录原子覆盖），
+避免写一半导致 JSON 损坏。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import traceback
+from pathlib import Path
+from typing import Any
+
+from . import data_dir
+
+# 数据文件名
+FEEDBACK_LOG = "feedback.log"        # JSONL 追加，只增不改
+CALIBRATION_JSON = "calibration.json"  # 校准结果，原子写
+LEARNED_RULES_JSON = "learned_rules.json"  # 自学习规则
+ML_ROUTER_BIN = "router.lgb"         # 第 5 期 ML 精判产物（joblib 容器）
+SEMANTIC_ONNX = "router_semantics.onnx"  # 第 6 期 bge 语义编码器（ONNX int8）落盘（见 learned_rules.py）
+SEMANTIC_ONNX_TOK = "router_semantics.json"  # 与 .onnx 同名的伴生 tokenizer（semantic.py 按主文件同级取）
+
+
+def feedback_log_path() -> Path:
+    return data_dir() / FEEDBACK_LOG
+
+
+def calibration_path() -> Path:
+    return data_dir() / CALIBRATION_JSON
+
+
+def learned_rules_path() -> Path:
+    return data_dir() / LEARNED_RULES_JSON
+
+
+def semantic_onnx_path() -> Path:
+    return data_dir() / SEMANTIC_ONNX
+
+
+def reset_adaptive_data() -> list[str]:
+    """清空校准与自学习规则（feedback.log 保留作历史）。返回被删除的文件名。
+
+    phase-04 A3 的 `/smartRouter reset`。删除后校准/规则回到空态，
+    等价于"删掉 calibration.json + learned_rules.json 即回第 1 期行为"。
+    """
+    removed: list[str] = []
+    for p in (calibration_path(), learned_rules_path()):
+        try:
+            if p.exists():
+                p.unlink()
+                removed.append(p.name)
+        except OSError:
+            pass
+    return removed
+
+
+def ensure_dir() -> Path:
+    """懒创建数据目录；重复调用是幂等的。"""
+    d = data_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _atomic_copy(src: Path, dst: Path) -> None:
+    """二进制原子复制：写 tmp 后 os.replace，避免写一半损坏产物。"""
+    ensure_dir()
+    fd, tmp = tempfile.mkstemp(dir=str(dst.parent), prefix=dst.name, suffix=".tmp")
+    os.close(fd)
+    try:
+        import shutil  # noqa: PLC0415
+        shutil.copyfile(str(src), tmp)
+        os.replace(tmp, dst)
+    except Exception:
+        try:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+# 随包默认产物（xg/assets/，hatch wheel 打包自带）：包内名称 -> 数据目录的目标路径
+_BUNDLED_BASENAMES = (ML_ROUTER_BIN, SEMANTIC_ONNX, SEMANTIC_ONNX_TOK)
+
+
+def _bundled_target(name: str) -> Path:
+    """随包产物在数据目录里的对应目标路径（与默认文件名一致）。"""
+    return data_dir() / name
+
+
+def ensure_default_artifacts() -> None:
+    """首启把随包产物复制到数据目录；目标已存在则跳过（不覆盖用户数据）。
+
+    随包资源在 ``xg/assets/``：``router.lgb``（ML 精判兜底）与
+    ``router_semantics.onnx`` + ``.json``（语义编码器）。无随包资源、
+    目标已存在或复制失败时静默跳过——对应功能维持离线回落，绝不影响启动。
+    """
+    try:
+        from importlib.resources import as_file, files  # noqa: PLC0415
+        root = files("xg").joinpath("assets")
+    except Exception:
+        return
+    for name in _BUNDLED_BASENAMES:
+        target = _bundled_target(name)
+        if target.exists():
+            continue  # 用户已有产物 → 不覆盖
+        src = root.joinpath(name)
+        if not src.is_file():
+            continue
+        try:
+            with as_file(src) as p_src:
+                _atomic_copy(Path(p_src), target)
+        except Exception:
+            # 内存/沙箱/只读等任何失败都静默，绝不打断启动
+            pass
+
+
+def _atomic_replace(path: Path, payload: str) -> None:
+    """写 tmp 文件后 os.replace 覆盖目标，保证同目录内原子替换。"""
+    ensure_dir()
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=path.name, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+            fh.flush()
+            os.fsync(fh.fileno())
+        os.replace(tmp, path)
+    except Exception:
+        # 清理残留 tmp，避免堆积
+        try:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+        except OSError:
+            pass
+        raise
+
+
+def atomic_write_json(path: Path, obj: Any) -> None:
+    """把任意 JSON 可序列化对象原子写到 ``path``。"""
+    _atomic_replace(path, json.dumps(obj, ensure_ascii=False, indent=2))
+
+
+def append_jsonl(path: Path, record: dict[str, Any]) -> None:
+    """JSONL 追加写入一行（append 模式，不覆盖既有内容）。"""
+    ensure_dir()
+    with open(path, "a", encoding="utf-8") as fh:
+        fh.write(json.dumps(record, ensure_ascii=False, separators=(",", ":")))
+        fh.write("\n")
+
+
+def read_json_safe(path: Path, default: Any = None) -> Any:
+    """读 JSON，文件不存在 / 解析失败 / 结构异常时返回 ``default``，不抛错。"""
+    if not path.exists():
+        return default
+    try:
+        with open(path, encoding="utf-8") as fh:
+            return json.load(fh)
+    except Exception:
+        traceback.print_exc() if os.environ.get("XG_DEBUG") else None
+        return default