MenuPilot 0.1.0__py3-none-any.whl

menupilot/config.py

@@ -0,0 +1,113 @@
+"""
+配置文件 — API Key、模型参数、匹配阈值。
+
+配置优先级：~/.menupilot/config.json > 环境变量 > 程序默认值
+
+使用方式：
+    from config import DEEPSEEK_API_KEY, DEEPSEEK_BASE_URL, MATCHING_CONFIG
+"""
+
+import json
+import os
+
+# ── 用户配置文件加载 ─────────────────────────────────────────────
+
+_CONFIG_DIR = os.path.expanduser("~/.menupilot")
+_CONFIG_PATH = os.path.join(_CONFIG_DIR, "config.json")
+
+
+def _load_json_config() -> dict:
+    """从 ~/.menupilot/config.json 加载用户配置。"""
+    if os.path.exists(_CONFIG_PATH):
+        try:
+            with open(_CONFIG_PATH, "r", encoding="utf-8") as f:
+                return json.load(f)
+        except (json.JSONDecodeError, IOError):
+            pass
+    return {}
+
+
+_json = _load_json_config()
+
+# ── DeepSeek API 配置 ───────────────────────────────────────────
+# 优先级：JSON 配置文件 > 环境变量 > 默认值
+
+DEEPSEEK_API_KEY = (
+    _json.get("DEEPSEEK_API_KEY") or
+    os.environ.get("DEEPSEEK_API_KEY") or
+    ""  # 不再有硬编码 fallback，未配置时为空字符串（首次运行触发配置向导）
+)
+
+DEEPSEEK_BASE_URL = (
+    _json.get("DEEPSEEK_BASE_URL") or
+    os.environ.get("DEEPSEEK_BASE_URL") or
+    "https://api.deepseek.com/v1"
+)
+
+DEEPSEEK_MODEL = (
+    _json.get("DEEPSEEK_MODEL") or
+    os.environ.get("DEEPSEEK_MODEL") or
+    "deepseek-chat"
+)
+
+# API 调用参数
+LLM_TEMPERATURE = 0.1          # Schema 分析和 Token 分类需要确定性输出
+LLM_MAX_TOKENS = 4096
+LLM_TIMEOUT_SECONDS = 30
+
+# ── 匹配引擎配置 ────────────────────────────────────────────────
+
+MATCHING_CONFIG = {
+    # 商品名匹配（RapidFuzz token_sort_ratio）
+    "product_name_threshold": 90,      # ≥ 此值视为匹配
+    "product_name_scorer": "token_sort_ratio",
+
+    # Embedding 兜底
+    "embedding_enabled": False,         # 默认关闭（按 README 设计）
+    "embedding_model": "paraphrase-multilingual-MiniLM-L12-v2",
+    "embedding_top_k": 3,              # 候选召回数量
+    "embedding_similarity_threshold": 0.85,
+
+    # 低置信度
+    "low_confidence_threshold": 80,     # 商品名匹配低于此值直接 LOW_CONFIDENCE
+}
+
+# ── 日志配置 ────────────────────────────────────────────────────
+
+LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO")
+
+# ── 自测用 Mock 配置 ───────────────────────────────────────────
+
+# 自测时使用此标志跳过真实 LLM 调用
+USE_MOCK_LLM = os.environ.get("USE_MOCK_LLM", "0") == "1"
+
+# Mock LLM 响应（Schema Analyzer）
+MOCK_SCHEMA_RESPONSE = {
+    "field_mapping": {
+        "菜品名称": "product_name",
+        "规格": "size",
+    },
+    "composite_col": "口味做法组合",
+    "target_col": "配料",
+    "irrelevant_cols": [],
+}
+
+# Mock LLM 响应（Token Classifier）
+MOCK_TOKEN_RESPONSE = [
+    {
+        "tokens": [
+            {"value": "红茶", "type": "茶底"},
+            {"value": "十二分糖", "type": "糖度"},
+            {"value": "温热", "type": "温度"},
+        ],
+        "missing": ["奶底"],
+    },
+    {
+        "tokens": [
+            {"value": "红茶", "type": "茶底"},
+            {"value": "十二分糖", "type": "糖度"},
+            {"value": "正常冰", "type": "温度"},
+        ],
+        "missing": ["奶底"],
+    },
+]

menupilot/data/canonical_schema.py

@@ -0,0 +1,135 @@
+"""
+Canonical Schema — 所有模板字段统一转换为此内部标准结构。
+
+位于 Rule Engine 层的核心数据模型，被 Matching Engine / workflow 引用。
+"""
+
+from typing import Dict, List
+
+# ── Canonical 字段列表 ────────────────────────────────────────
+# 所有字段（含 tea_base 扩展字段 + composite_col/sop 特殊字段）
+CANONICAL_FIELDS = [
+    "product_name", "size", "milk_base", "temperature", "sugar", "tea_base",
+    "composite_col", "sop",
+]
+
+# 必要维度：匹配时这些字段必须存在
+REQUIRED_DIMENSIONS = ["size", "temperature", "sugar"]
+
+# 可通配维度：主数据中为空时匹配任意值
+WILDCARD_DIMENSIONS = ["milk_base", "tea_base"]
+
+# ── 主数据表固定列映射 ────────────────────────────────────────
+# 主数据表字段名固定为中文，不需要 LLM 识别
+MASTER_COLUMN_MAP: Dict[str, str] = {
+    "品名": "product_name",
+    "杯型": "size",
+    "奶底": "milk_base",
+    "做法": "temperature",
+    "糖":   "sugar",
+}
+
+# ── Token 中文类型名 → Canonical 字段名 ────────────────────────
+TOKEN_TYPE_TO_FIELD: Dict[str, str] = {
+    "温度": "temperature",
+    "糖度": "sugar",
+    "奶底": "milk_base",
+    "规格": "size",
+    "茶底": "tea_base",
+}
+
+# 反向映射：Canonical 字段名 → Token 中文类型名
+FIELD_TO_TOKEN_TYPE: Dict[str, str] = {v: k for k, v in TOKEN_TYPE_TO_FIELD.items()}
+
+
+def create_canonical_row(**kwargs) -> Dict:
+    """创建一条 Canonical Schema 行，缺失字段默认为 None。"""
+    row = {f: None for f in CANONICAL_FIELDS}
+    row.update(kwargs)
+    return row
+
+
+def get_missing_required(row: Dict) -> List[str]:
+    """返回行中缺失的必要维度列表。"""
+    return [f for f in REQUIRED_DIMENSIONS if row.get(f) is None]
+
+
+def is_wildcard(field: str) -> bool:
+    """检查字段是否允许通配（主数据为空时可匹配任意值）。"""
+    return field in WILDCARD_DIMENSIONS
+
+
+# ── 自测 ──────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    passed = 0
+    failed = 0
+
+    def check(condition, msg):
+        global passed, failed
+        if condition:
+            passed += 1
+            print(f"  PASS  {msg}")
+        else:
+            failed += 1
+            print(f"  FAIL  {msg}")
+
+    print("=== Canonical Schema 自测 ===\n")
+
+    # 1. 字段数量
+    print("1. 字段定义")
+    check(len(CANONICAL_FIELDS) == 8, f"CANONICAL_FIELDS 包含 8 个字段（实际 {len(CANONICAL_FIELDS)}）")
+    check("tea_base" in CANONICAL_FIELDS, "包含 tea_base 扩展字段")
+    check("composite_col" in CANONICAL_FIELDS, "包含 composite_col 特殊字段")
+    check("sop" in CANONICAL_FIELDS, "包含 sop 特殊字段")
+    check(len(REQUIRED_DIMENSIONS) == 3, "3 个必要维度")
+    check(len(WILDCARD_DIMENSIONS) == 2, "2 个通配维度")
+    print()
+
+    # 2. 主数据列映射
+    print("2. 主数据列映射")
+    check(MASTER_COLUMN_MAP["品名"] == "product_name", "品名 → product_name")
+    check(MASTER_COLUMN_MAP["做法"] == "temperature", "做法 → temperature")
+    check(MASTER_COLUMN_MAP["糖"] == "sugar", "糖 → sugar")
+    check(len(MASTER_COLUMN_MAP) == 5, "共 5 个映射")
+    print()
+
+    # 3. Token 类型映射
+    print("3. Token 类型映射")
+    check(TOKEN_TYPE_TO_FIELD["温度"] == "temperature", "温度 → temperature")
+    check(TOKEN_TYPE_TO_FIELD["茶底"] == "tea_base", "茶底 → tea_base")
+    check(FIELD_TO_TOKEN_TYPE["temperature"] == "温度", "反向: temperature → 温度")
+    print()
+
+    # 4. create_canonical_row
+    print("4. create_canonical_row")
+    row = create_canonical_row(product_name="测试", size="中杯")
+    check(row["product_name"] == "测试", "自定义字段生效")
+    check(row["size"] == "中杯", "自定义字段生效")
+    check(row["milk_base"] is None, "未指定字段默认 None")
+    check(len(row) == 8, f"始终包含 8 个字段（实际 {len(row)}）")
+    print()
+
+    # 5. get_missing_required
+    print("5. get_missing_required")
+    complete = {"size": "中杯", "temperature": "少冰", "sugar": "七分糖"}
+    check(get_missing_required(complete) == [], "完整行 → 空列表")
+
+    partial = {"size": "大杯", "temperature": None, "sugar": "全糖"}
+    missing = get_missing_required(partial)
+    check("temperature" in missing and len(missing) == 1, "缺 1 个维度被检测到")
+
+    empty = {"size": None, "temperature": None, "sugar": None}
+    check(len(get_missing_required(empty)) == 3, "缺 3 个维度全部检测到")
+    print()
+
+    # 6. is_wildcard
+    print("6. is_wildcard")
+    check(is_wildcard("milk_base") is True, "milk_base 是通配维度")
+    check(is_wildcard("tea_base") is True, "tea_base 是通配维度")
+    check(is_wildcard("size") is False, "size 不是通配维度")
+    check(is_wildcard("temperature") is False, "temperature 不是通配维度")
+    print()
+
+    # ── 汇总 ──
+    print(f"=== 结果: {passed} passed, {failed} failed ===")

menupilot/data/mapping_rules.yaml

@@ -0,0 +1,387 @@
+# PosAgent 模板映射规则
+# ========================
+# 从 agent/rule_engine.py、data/canonical_schema.py、data/token_dict.py、
+# agent/matching_engine.py、config.py 中提取，作为映射规则的声明式参考。
+#
+# 用途：
+#   - 新增模板映射规则时的参考基准
+#   - 未来可从 YAML 加载规则替代硬编码
+#
+# 更新日期：2026-06-16
+
+version: "1.0"
+description: "PosAgent 模板映射规则 — 所有模板字段统一转换为此内部标准结构"
+
+# ═══════════════════════════════════════════════════════════════════
+# 1. Canonical Schema（内部标准字段）
+# ═══════════════════════════════════════════════════════════════════
+
+canonical_schema:
+  # 所有 canonical 字段（含扩展字段和特殊字段）
+  fields:
+    - product_name   # 商品名称
+    - size           # 规格/杯型
+    - milk_base      # 奶底
+    - temperature    # 温度/做法
+    - sugar          # 糖度
+    - tea_base       # 茶底（扩展字段）
+    - composite_col  # 组合字段名（如"口味做法组合"，特殊字段）
+    - sop            # SOP 代码（目标值，特殊字段）
+
+  # 必要维度：匹配时这些字段必须有值，缺列直接报错
+  required_dimensions:
+    - size
+    - temperature
+    - sugar
+
+  # 通配维度：主数据中为空时可匹配任意值
+  wildcard_dimensions:
+    - milk_base
+    - tea_base
+
+# ═══════════════════════════════════════════════════════════════════
+# 2. 主数据表列映射（中文列名 → Canonical 字段）
+# ═══════════════════════════════════════════════════════════════════
+# 主数据表字段名固定为中文，不需要 LLM 识别
+# 来源: data/canonical_schema.py MASTER_COLUMN_MAP
+
+master_column_map:
+  品名: product_name
+  杯型: size
+  奶底: milk_base
+  做法: temperature
+  糖:   sugar
+
+# 主数据表 SOP 列的候选名称（按优先级查找）
+master_sop_candidates:
+  - SOP
+  - 配料
+  - SOP 代码
+  - 代码
+
+# ═══════════════════════════════════════════════════════════════════
+# 3. Token 类型映射（中文类型名 → Canonical 字段）
+# ═══════════════════════════════════════════════════════════════════
+# 来源: data/canonical_schema.py TOKEN_TYPE_TO_FIELD
+
+token_type_mapping:
+  温度: temperature
+  糖度: sugar
+  奶底: milk_base
+  规格: size
+  茶底: tea_base
+
+# ═══════════════════════════════════════════════════════════════════
+# 4. Token 词典（属性值 → 类型）
+# ═══════════════════════════════════════════════════════════════════
+# 词典为软约束：LLM Token Classifier 可识别词典外的值并标注 UNKNOWN_TOKEN
+# 来源: data/token_dict.py _RAW_TOKENS
+
+token_dictionary:
+  温度:
+    - 热
+    - 温热
+    - 正常冰
+    - 少冰
+    - 去冰
+    - 冰沙
+
+  糖度:
+    - 全糖
+    - 十二分糖
+    - 标准糖
+    - 七分糖
+    - 五分糖
+    - 三分糖
+    - 不另加糖
+    - 无糖
+
+  奶底:
+    - 牛奶
+    - 燕麦奶
+    - 厚乳
+    - 椰乳
+
+  规格:
+    - 大杯
+    - 中杯
+    - 小杯
+    - 五角瓶
+
+  茶底:
+    - 红茶
+    - 绿茶
+    - 乌龙茶
+    - 五角排红茶
+    - 五黄标准茶
+    - 茉莉绿茶  # 2026-06-05: testdata 口味做法组合中出现
+
+# 已知后缀模式（文档备忘，normalize_token 通过分隔符边界检测自动处理）
+known_suffixes:
+  - "|推荐"   # 主数据糖度列常见：七分糖|推荐
+  - "/新"     # 模板规格列偶尔出现：大杯/新
+
+# normalize_token 分隔符集合（用于子串边界检测和后缀切割）
+separators:
+  - "|"
+  - "/"
+  - " "
+
+# ═══════════════════════════════════════════════════════════════════
+# 5. 匹配引擎配置
+# ═══════════════════════════════════════════════════════════════════
+# 来源: config.py MATCHING_CONFIG + agent/matching_engine.py 常量
+
+matching:
+  # 商品名匹配（RapidFuzz）
+  product_name_threshold: 90       # token_sort_ratio ≥ 此值视为高置信匹配
+  low_confidence_threshold: 80    # 低于此值直接 LOW_CONFIDENCE
+  scorer: token_sort_ratio
+
+  # Embedding 兜底（默认关闭）
+  embedding:
+    enabled: false
+    model: paraphrase-multilingual-MiniLM-L12-v2
+    top_k: 3
+    similarity_threshold: 0.85
+
+# 匹配类型枚举
+match_types:
+  exact:            "exact"             # 商品名 + 全属性精确匹配
+  attribute_match:  "attribute_match"   # 属性组合匹配
+  product_only:     "product_only"      # 仅商品名匹配（属性不匹配）
+  best_guess:       "best_guess"        # 兜底最佳猜测
+
+# 置信度枚举
+confidence_levels:
+  high:           "HIGH"
+  low_confidence: "LOW_CONFIDENCE"
+
+# ═══════════════════════════════════════════════════════════════════
+# 6. 失败原因码及中文描述
+# ═══════════════════════════════════════════════════════════════════
+# 来源: agent/matching_engine.py _REASON_CN_MAP / _REASON_SUGGESTION_MAP
+
+failure_reasons:
+  PRODUCT_NOT_FOUND:
+    cn: "商品名称在主数据中未找到"
+    suggestion: "检查商品名称是否有错别字，或补充主数据表"
+
+  MILK_BASE_NOT_FOUND:
+    cn: "{extra}规格在主数据中缺失"
+    suggestion: "补充 {extra} 相关 SOP 到主数据表"
+
+  SIZE_NOT_FOUND:
+    cn: "规格在主数据中缺失"
+    suggestion: ""
+
+  TEMPERATURE_NOT_FOUND:
+    cn: "温度/做法在主数据中缺失"
+    suggestion: ""
+
+  SUGAR_NOT_FOUND:
+    cn: "糖度在主数据中缺失"
+    suggestion: ""
+
+  TEA_BASE_NOT_FOUND:
+    cn: "茶底在主数据中缺失"
+    suggestion: ""
+
+# ═══════════════════════════════════════════════════════════════════
+# 7. 模板预处理规则
+# ═══════════════════════════════════════════════════════════════════
+# 来源: agent/template_preprocessor.py
+
+template_preprocessing:
+  # 模板类型检测条件（chowbus 类型）
+  detection:
+    chowbus:
+      # 条件 1: 第一行至少有 3 个纯英文列名
+      min_english_headers: 3
+      # 条件 2: 第二行包含中文字符
+      row1_contains_chinese: true
+      # 条件 3: 必须存在 item_cn 列
+      required_columns:
+        - item_cn
+      # 条件 4: 必须存在至少一个 customization{N}_id 列
+      customization_pattern: "^customization\\d+_id$"
+
+  # chowbus 行收集规则
+  chowbus_row_collection:
+    # 从第 3 行开始读取（跳过英文表头 + 中文注释行）
+    data_start_row: 2
+    # 以 item_cn 列为锚点
+    anchor_column: item_cn
+    # 仅收集锚点右侧的中文值
+    scan_direction: right
+    # 过滤规则：纯英文、纯数字值跳过
+    skip_patterns:
+      - "^[a-zA-Z_][a-zA-Z0-9_]*$"   # 纯英文标识符
+      - "^\\d+$"                       # 纯数字
+    # 值清洗：去除 |推荐 等后缀标记
+    clean_suffix_markers: true
+
+# ═══════════════════════════════════════════════════════════════════
+# 8. 属性匹配规则
+# ═══════════════════════════════════════════════════════════════════
+# 来源: agent/matching_engine.py _attributes_match()
+
+attribute_matching:
+  # 必要维度匹配：master 和 template 都必须有值且精确相等
+  required_rules:
+    - field: size
+      match: exact
+      miss_penalty: unmatched
+    - field: temperature
+      match: exact
+      miss_penalty: unmatched
+    - field: sugar
+      match: exact
+      miss_penalty: unmatched
+
+  # 通配维度匹配：master 为空时通配（跳过），master 有值时精确匹配
+  wildcard_rules:
+    - field: milk_base
+      master_empty: wildcard     # master 为空 → 通配任意 template 值
+      master_has_value: exact    # master 有值 → 必须精确匹配
+    - field: tea_base
+      master_empty: wildcard
+      master_has_value: exact
+
+  # LOW_CONFIDENCE 失败原因推断优先级（从高到低）
+  failure_reason_priority:
+    - milk_base
+    - size
+    - temperature
+    - sugar
+    - tea_base
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 9. 选项规格模板展开规则（Option Specification Template Expander）
+# ═══════════════════════════════════════════════════════════════════
+# 将主数据表中的选项规格数据展开为空白选项模板的行。
+# 来源: agent/option_expander.py
+
+option_expansion:
+  description: >
+    将包含选项规格定义的主数据表展开为选项模板的明细行。
+    每个主数据行按 5 个维度（糖度/温度/规格/奶底/茶底）展开，
+    每个维度的每个选项值生成一行模板数据。
+    纯规则引擎，不调用 LLM。
+
+  # ── 主数据表列定义 ──
+
+  master_columns:
+    # 固定列（必须存在）
+    fixed:
+      - name: 主编码
+        canonical: product_code
+        required: true
+        description: 商品唯一编码
+
+      - name: 商品名称
+        canonical: product_name
+        required: true
+        description: 商品名称
+
+    # 展开维度（按遍历顺序）
+    dimensions:
+      - 糖度
+      - 温度
+      - 规格
+      - 奶底
+      - 茶底
+
+    # 每个维度下的 3 种列模式
+    dimension_column_patterns:
+      - prefix: "推荐"
+        example: 推荐糖度
+        description: 推荐值（单个，可为空）
+      - prefix: "默认"
+        example: 默认糖度
+        description: 默认值（单个，可为空）
+      - prefix: ""
+        example: 糖度
+        description: 选项值列表（；分隔）
+
+  # ── 模板输出列定义 ──
+
+  template_columns:
+    - 商品编码       # ← master.主编码
+    - 商品名称       # ← master.商品名称
+    - 口味做法组名   # ← 维度名（糖度/温度/规格/奶底/茶底）
+    - 选项名称       # ← 列表中的单个值
+    - 最少必选       # ← 固定为 1（严格整数）
+    - 最多可选       # ← 固定为 1（严格整数）
+    - 推荐项         # ← "是" 或 "否"
+    - 默认项         # ← "是" 或 "否"
+
+  # ── 展开逻辑 ──
+
+  expansion:
+    dimension_list_separator: "；"
+    dimension_order:
+      - 糖度
+      - 温度
+      - 规格
+      - 奶底
+      - 茶底
+
+    recommendation_rule: >
+      选项值 == 推荐{dim} → 推荐项 = "是"，否则 "否"
+      选项值 == 默认{dim} → 默认项 = "是"，否则 "否"
+      推荐/默认值为空时，全部填"否"
+      同一值可以同时是推荐项和默认项
+
+    deduplicate: true
+    skip_empty_values: true
+
+    empty_dimension_behavior: skip
+    all_dimensions_empty_behavior: skip
+
+  constants:
+    最少必选: 1
+    最多可选: 1
+    yes_value: "是"
+    no_value: "否"
+
+  differences_from_sop_pipeline:
+    - "不需要 Schema Analyzer：主数据列名固定，不需要 LLM 分析"
+    - "不需要 Token Classifier：没有组合字段需要解析"
+    - "不需要 Rule Engine：不需要 Canonical Schema 标准化"
+    - "不需要 Matching Engine：不做主数据与模板的匹配"
+    - "不需要 LangGraph 工作流：纯顺序执行，无条件路由"
+    - "不使用 LLM：100% 规则驱动，API 调用 = 0"
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 10. LLM Tool 注册表（agent/tools.py + agent/sandbox.py）
+# ═══════════════════════════════════════════════════════════════════
+
+llm_tool_registry:
+  description: >
+    将规则函数注册为 LLM 可调用的 Tool，供 LangGraph create_react_agent 消费。
+    pipeline 类 Tool 禁止 LLM 自行实现；supplementary 类 Tool 供辅助操作。
+
+  tools:
+    - name: run_sop_matching
+      category: pipeline
+      handler: agent.orchestration.run_sop_pipeline
+      guardrail: "LLM 必须调用此 tool 执行匹配，禁止自行生成匹配代码"
+
+    - name: run_option_expansion
+      category: pipeline
+      handler: agent.orchestration.run_expand_pipeline
+      guardrail: "LLM 必须调用此 tool 执行展开"
+
+    - name: execute_python
+      category: supplementary
+      handler: agent.sandbox.execute
+      guardrail: "LLM 可生成 Python 代码增删改查数据，禁止生成匹配/填充逻辑"
+      sandbox_allowed: [pandas, openpyxl, numpy, json, csv, re, collections]
+
+    - name: query_token_dict
+      category: supplementary
+      handler: agent.tools.query_token_dict
+      guardrail: "只读操作，可安全调用"