@roll-agent/octopus-agent 0.1.2 → 0.2.0

package/src/octopus_skill/question_analyzer.py

@@ -1,399 +0,0 @@
-"""LLM-based question analysis: intent classification, query target extraction, and question normalization."""
-
-from __future__ import annotations
-
-import json
-import re
-from dataclasses import dataclass, field
-from datetime import date, timedelta
-from typing import Any
-
-from .llm_sql_generator import Sampler
-from .prompt_builder import (
-    filter_agent_instructions_by_stage,
-    format_numbered_instruction_lines,
-)
-
-
-QUESTION_ANALYSIS_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的需求分析专家。
-你的职责是深度理解用户的自然语言问题，输出结构化的需求分析结果，供后续 SQL 生成模块使用。
-业务规则的唯一来源是 payload 中的 mandatoryAgentInstructions；必须逐条遵守，不得使用训练记忆中的业务口径替代 schema 要求。
-
-## 你的能力
-
-1. **意图分类**：判断用户的真实意图属于哪种类型。
-2. **查询目标提取**：从问题中识别用户想查的业务对象、指标、筛选条件和排序/分组需求。
-3. **问题规范化**：把口语化、模糊的问题改写为结构清晰、无歧义的查询描述。
-4. **噪声值识别**：识别不应作为实体名称筛选值的词，并说明它应归属的语义角色。
-
-## 意图分类规则
-
-- mutation：只有当用户明确表明想新增、修改、删除、发布、提交数据等写操作时才返回。
-- query：只有当用户明确提出业务数据查询、统计、查看数据、分析报告等需求时才返回。
-- non_query：用户只是测试/检查/使用丸子Agent、询问工具或系统能力、确认是否可用、或单独回复“确认”但没有业务数据查询时返回。
-- 不要输出 clarification_needed 或 unsupported；缺少信息或暂不支持的业务查询也先归为 query，后续 schema 匹配、查询计划确认或业务校验会继续处理。
-
-## 查询目标提取规则
-
-从问题中提取以下维度（没有的留空数组或 null）：
-- targetEntities：用户想查的业务对象（如"岗位""门店""品牌""员工"）
-- metrics：用户想看的指标（如"数量""总数""平均薪资"）
-- filters：用户提到的筛选条件（如"已发布的""北京的""最近7天"）
-- groupBy：分组维度（如"按品牌""按城市"）
-- orderBy：排序要求（如"按数量从多到少"）
-- timeRange：时间范围（如"最近一周""2024年1月"）；必须保留原始时间词，并按 payload.currentDate 计算明确起止日期
-- limit：用户要求的返回条数（如"前10条""全部"）
-- entityCandidates：从问题中抽取的实体候选；只有真实名称才输出为 isNoise=false
-- noiseValues：被误当实体值会造成错误筛选的词；注意噪声值不代表丢弃，它可能仍然属于 timeRange、filters、metrics 或 intent
-- requiredConcepts：用户问题必须依赖的 schema 概念；只有当业务口径必须由 schema.concepts/metrics/examples 明确定义时才输出
-- mutationSignals：用户明确表达写操作时的信号；如果只是查询新增/修改/下架记录，不算写操作
-- planAction：用户在确认查询计划时的动作，普通业务查询填 null
-
-## 噪声值规则
-
-- 表达时间的词不要作为实体名称；应放入 timeRange。
-- timeRange.originalText 必须保留用户原文中的时间词，例如“近一年”“最近7天”“2024年1月”；normalizedQuestion 也必须保留该时间词，不要改写成某个月。
-- 相对时间必须基于 payload.currentDate 计算 start 和 endExclusive，endExclusive 使用左闭右开区间的次日或下一周期首日。
-- 例如 payload.currentDate=2026-07-07 时，“近一年”必须输出 start=2025-07-07、endExclusive=2026-07-08；严禁分析成 2025年7月、2025-07-01 到 2025-08-01。
-- “所有”“全部”“全量”“完整”只表示返回范围或 limit 诉求；不得覆盖、删除或扩大用户已经明确提出的 timeRange。
-- 表达查询动作、统计意图、范围、排序或状态口径的词不要作为实体名称；应放入 filters、metrics、orderBy 或其他对应字段。
-- 表达岗位生命周期、操作动作或状态变化的词不要作为岗位名称；例如“新上架”“上架”“下架”“发布”“新发布”“新增发布”应放入 filters 或 noiseValues.role=action/status，不要作为 job_name/name/title 的 LIKE 值。
-- 只有用户明确说“名称包含/岗位名称是/叫做/简称为”时，才可以把动作或状态词作为名称筛选值。
-- 遇到“名称 + 时间词 + 阶段/动作词 + 业务对象/指标”的连续短语时，必须拆分语义，不要把整段短语当作实体名称。
-- 例如“成都你六姐明天面试的工单数量”：`成都你六姐` 是品牌/项目候选，`明天` 是 timeRange，`面试` 是业务阶段或动作，`工单数量` 是业务对象和指标；`成都你六姐明天面试` 必须放入 noiseValues，不能作为任何时间字段、名称字段或工单字段的筛选值。
-- 遇到“名称 + 有多少 + 时间词 + 阶段/动作词 + 业务对象”时，查询对象必须是最后的业务对象，指标必须是该业务对象数量；例如“成都你六姐有多少明天面试的工单”必须输出 targetEntities=["工单"]、metrics=["工单数量"]，不能输出 targetEntities=["品牌"] 或 targetEntities=["项目"]。
-- 当用户未明确说明“品牌”或“项目”，但名称片段像品牌/项目名称时，entityCandidates 同时输出 brand 和 sponge_project 两个候选，后续模块会走实体检索确认。
-- 只有能作为品牌、项目、门店、城市、岗位等真实名称的词，才可作为 entityCandidates 的非噪声实体值。
-- 不要因为一个词是状态或时间就忽略它；必须保留到正确语义字段里。
-
-## 必需 schema 概念规则
-
-- 遇到“今天招满”“今日招满”“昨天招满”“某天招满”“近7天招满”“本月招满”“有哪些岗位招满”等时间范围内岗位招满问题时，必须输出 requiredConcepts=[{"name":"filled_job_by_period","label":"按时间段招满岗位"}]；今天、昨天、某天等只作为 timeRange，不要使用单日专用概念。
-- 如果 schema 缺少 requiredConcepts 中的概念，后续模块会返回 schema 口径缺失；你不要把招满解释成 job_store.update_at、岗位状态或名称筛选。
-
-## 问题规范化规则
-
-- 保留用户的核心业务语义
-- 去除口语化的填充词（嗯、那个、帮我看下）
-- 补全省略的主语或宾语
-- 不改变用户的原始筛选意图
-- 如果问题已经足够清晰，原样返回
-
-## 输出格式
-
-只输出一个 JSON 对象，不输出任何解释文本：
-{
-  "intent": "query|mutation|non_query",
-  "confidence": 0.0~1.0,
-  "targetEntities": ["业务对象1", "业务对象2"],
-  "metrics": ["指标1"],
-  "filters": [{"field": "字段含义", "operator": "=|LIKE|>|<|IN|BETWEEN", "value": "值"}],
-  "groupBy": ["维度1"],
-  "orderBy": [{"field": "字段", "direction": "ASC|DESC"}],
-  "timeRange": {"type": "relative|absolute", "value": "描述", "originalText": "原始时间词", "start": "YYYY-MM-DD", "endExclusive": "YYYY-MM-DD"},
-  "entityCandidates": [{"type": "实体类型", "value": "实体原文", "isNoise": false, "role": "entity"}],
-  "noiseValues": [{"value": "词语原文", "role": "time|intent|metric|scope|status|action|other", "reason": "为什么不能作为实体名称"}],
-  "requiredConcepts": [{"name": "schema概念名", "label": "中文口径名", "fallbackNames": ["可替代schema概念名"]}],
-  "mutationSignals": [{"value": "词语原文", "reason": "为什么表示写操作"}],
-  "planAction": "confirm|revise|null",
-  "limit": null,
-  "normalizedQuestion": "规范化后的问题",
-  "clarificationReason": null
-}
-
-当 intent 为 mutation 时，仍然要尽量提取已有信息。
-"""
-
-
-@dataclass(frozen=True)
-class QuestionAnalysis:
-    """Structured result of LLM-based question analysis."""
-
-    intent: str  # query | mutation | non_query
-    confidence: float
-    target_entities: list[str] = field(default_factory=list)
-    metrics: list[str] = field(default_factory=list)
-    filters: list[dict[str, str]] = field(default_factory=list)
-    group_by: list[str] = field(default_factory=list)
-    order_by: list[dict[str, str]] = field(default_factory=list)
-    time_range: dict[str, str] | None = None
-    entity_candidates: list[dict[str, Any]] = field(default_factory=list)
-    noise_values: list[dict[str, str]] = field(default_factory=list)
-    required_concepts: list[dict[str, Any]] = field(default_factory=list)
-    mutation_signals: list[dict[str, str]] = field(default_factory=list)
-    plan_action: str | None = None
-    limit: int | None = None
-    normalized_question: str = ""
-    clarification_reason: str | None = None
-    raw: dict[str, Any] = field(default_factory=dict)
-
-
-class QuestionAnalysisError(Exception):
-    """Raised when question analysis fails."""
-
-
-SAMPLING_MAX_RETRIES = 2
-
-
-def analyze_question(
-    question: str,
-    sampler: Sampler,
-    agent_instructions: list[dict[str, Any]] | None = None,
-    *,
-    max_sampling_retries: int = SAMPLING_MAX_RETRIES,
-) -> QuestionAnalysis:
-    """Use LLM to analyze user question and extract structured intent + query targets.
-
-    Args:
-        question: The user's original question text.
-        sampler: LLM sampler callback (system_prompt, user_prompt) -> response.
-        agent_instructions: Schema agentInstructions; only ``【生成前】`` entries are injected.
-
-    Returns:
-        QuestionAnalysis dataclass with structured analysis result.
-
-    Raises:
-        QuestionAnalysisError: If the LLM call fails or returns unparseable output.
-    """
-    prompt = build_question_analysis_prompt(question, agent_instructions)
-
-    raw_response: str | None = None
-    for attempt in range(max_sampling_retries + 1):
-        try:
-            raw_response = sampler(QUESTION_ANALYSIS_SYSTEM_PROMPT, prompt)
-            break
-        except Exception as exc:
-            if attempt >= max_sampling_retries:
-                raise QuestionAnalysisError(
-                    f"LLM 调用失败（已重试 {max_sampling_retries} 次）：{type(exc).__name__}: {exc}"
-                ) from exc
-
-    payload = _parse_analysis_response(raw_response or "")
-    return _build_analysis(payload, question)
-
-
-def build_question_analysis_prompt(
-    question: str,
-    agent_instructions: list[dict[str, Any]] | None = None,
-    current_date: date | None = None,
-) -> str:
-    instruction_lines = format_numbered_instruction_lines(
-        filter_agent_instructions_by_stage(agent_instructions or [], "before")
-    )
-    today = current_date or date.today()
-    recent_year_start = _one_year_before(today)
-    recent_year_end = today + timedelta(days=1)
-    payload = {
-        "mandatoryAgentInstructions": instruction_lines,
-        "currentDate": today.isoformat(),
-        "instruction": (
-            "分析 question 并输出 JSON；意图分类、时间范围识别与问题规范化必须遵守 "
-            "mandatoryAgentInstructions 和 timeRangeRules。"
-        ),
-        "question": question,
-        "timeRangeRules": {
-            "mustKeepOriginalText": "timeRange.originalText 与 normalizedQuestion 必须保留用户原始时间词，不要把相对时间改写成某个月。",
-            "relativeDateBase": "所有相对时间按 currentDate 计算。",
-            "interval": "时间范围使用左闭右开区间：[start, endExclusive)。",
-            "recentOneYearExample": {
-                "currentDate": today.isoformat(),
-                "originalText": "近一年",
-                "start": recent_year_start.isoformat(),
-                "endExclusive": recent_year_end.isoformat(),
-                "forbidden": "不得输出为某个自然月，例如 2025-07-01 到 2025-08-01。",
-            },
-        },
-        "outputSchema": {
-            "intent": "query|mutation|non_query",
-            "confidence": 0.0,
-            "targetEntities": ["业务对象1"],
-            "metrics": ["指标1"],
-            "filters": [{"field": "字段含义", "operator": "=", "value": "值"}],
-            "groupBy": ["维度1"],
-            "orderBy": [{"field": "字段", "direction": "ASC"}],
-            "timeRange": {
-                "type": "relative",
-                "value": "近一年",
-                "originalText": "近一年",
-                "start": recent_year_start.isoformat(),
-                "endExclusive": recent_year_end.isoformat(),
-            },
-            "entityCandidates": [{"type": "job", "value": "店员", "isNoise": False, "role": "entity"}],
-            "noiseValues": [
-                {"value": "今天", "role": "time", "reason": "时间条件，不是实体名称"},
-                {"value": "新上架", "role": "action", "reason": "岗位生命周期动作，不是岗位名称"},
-                {"value": "成都你六姐明天面试", "role": "other", "reason": "组合短语，必须拆成品牌/项目候选、时间和业务阶段，不是单一实体名称"},
-            ],
-            "compoundEntityExample": {
-                "question": "成都你六姐有多少明天面试的工单",
-                "targetEntities": ["工单"],
-                "metrics": ["工单数量"],
-                "entityCandidates": [
-                    {"type": "brand", "value": "成都你六姐", "isNoise": False, "role": "entity"},
-                    {"type": "sponge_project", "value": "成都你六姐", "isNoise": False, "role": "entity"},
-                ],
-                "timeRange": {"originalText": "明天"},
-                "filters": [{"field": "业务阶段", "operator": "=", "value": "面试"}],
-                "forbiddenEntityValue": "成都你六姐明天面试",
-                "forbiddenTargetEntities": ["品牌", "项目"],
-            },
-            "requiredConcepts": [
-                {"name": "filled_job_by_period", "label": "按时间段招满岗位"}
-            ],
-            "mutationSignals": [],
-            "planAction": None,
-            "limit": None,
-            "normalizedQuestion": "规范化后的问题",
-            "clarificationReason": None,
-        },
-    }
-    return json.dumps(payload, ensure_ascii=False, indent=2)
-
-
-def _one_year_before(value: date) -> date:
-    try:
-        return value.replace(year=value.year - 1)
-    except ValueError:
-        return value.replace(year=value.year - 1, day=28)
-
-
-def _parse_analysis_response(text: str) -> dict[str, Any]:
-    """Parse LLM JSON response, tolerating markdown fences and extra text."""
-    cleaned = (text or "").strip()
-    if cleaned.startswith("```"):
-        cleaned = cleaned.strip("`")
-        if cleaned.lower().startswith("json"):
-            cleaned = cleaned[4:].strip()
-    try:
-        payload = json.loads(cleaned)
-    except json.JSONDecodeError:
-        start = cleaned.find("{")
-        end = cleaned.rfind("}")
-        if start == -1 or end == -1 or end <= start:
-            raise QuestionAnalysisError("LLM 返回内容无法解析为 JSON")
-        try:
-            payload = json.loads(cleaned[start : end + 1])
-        except json.JSONDecodeError as exc:
-            raise QuestionAnalysisError(f"LLM JSON 解析失败：{exc}") from exc
-    if not isinstance(payload, dict):
-        raise QuestionAnalysisError("LLM 返回内容不是 JSON 对象")
-    return payload
-
-
-def _build_analysis(payload: dict[str, Any], original_question: str) -> QuestionAnalysis:
-    """Build QuestionAnalysis from parsed LLM JSON payload."""
-    intent = str(payload.get("intent") or "query")
-    if intent not in {"query", "mutation", "non_query"}:
-        intent = "query"
-
-    confidence = payload.get("confidence")
-    if not isinstance(confidence, (int, float)) or confidence < 0 or confidence > 1:
-        confidence = 0.5
-
-    target_entities = _str_list(payload.get("targetEntities"))
-    metrics = _str_list(payload.get("metrics"))
-    filters = _dict_list(payload.get("filters"))
-    group_by = _str_list(payload.get("groupBy"))
-    order_by = _dict_list(payload.get("orderBy"))
-    entity_candidates = _entity_candidate_list(payload.get("entityCandidates"))
-    noise_values = _dict_list(payload.get("noiseValues"))
-    required_concepts = _required_concept_list(payload.get("requiredConcepts"))
-    mutation_signals = _dict_list(payload.get("mutationSignals"))
-
-    plan_action = payload.get("planAction")
-    if plan_action not in {"confirm", "revise"}:
-        plan_action = None
-
-    time_range = payload.get("timeRange")
-    if not isinstance(time_range, dict):
-        time_range = None
-
-    limit_val = payload.get("limit")
-    limit = int(limit_val) if isinstance(limit_val, (int, float)) and limit_val > 0 else None
-
-    normalized = str(payload.get("normalizedQuestion") or "").strip()
-    if not normalized:
-        normalized = original_question
-
-    clarification_reason = payload.get("clarificationReason")
-    if not isinstance(clarification_reason, str):
-        clarification_reason = None
-
-    return QuestionAnalysis(
-        intent=intent,
-        confidence=float(confidence),
-        target_entities=target_entities,
-        metrics=metrics,
-        filters=filters,
-        group_by=group_by,
-        order_by=order_by,
-        time_range=time_range,
-        entity_candidates=entity_candidates,
-        noise_values=noise_values,
-        required_concepts=required_concepts,
-        mutation_signals=mutation_signals,
-        plan_action=plan_action,
-        limit=limit,
-        normalized_question=normalized,
-        clarification_reason=clarification_reason,
-        raw=payload,
-    )
-
-
-def _str_list(value: Any) -> list[str]:
-    """Safely convert to list of strings."""
-    if not isinstance(value, list):
-        return []
-    return [str(item) for item in value if item]
-
-
-def _dict_list(value: Any) -> list[dict[str, str]]:
-    """Safely convert to list of dicts with string values."""
-    if not isinstance(value, list):
-        return []
-    result: list[dict[str, str]] = []
-    for item in value:
-        if isinstance(item, dict):
-            result.append({str(k): str(v) for k, v in item.items()})
-    return result
-
-
-def _entity_candidate_list(value: Any) -> list[dict[str, Any]]:
-    """Safely convert entity candidate payloads while preserving boolean flags."""
-    if not isinstance(value, list):
-        return []
-    result: list[dict[str, Any]] = []
-    for item in value:
-        if not isinstance(item, dict):
-            continue
-        entry: dict[str, Any] = {}
-        for key, raw_value in item.items():
-            if key == "isNoise":
-                entry[key] = bool(raw_value)
-            elif raw_value is not None:
-                entry[str(key)] = str(raw_value)
-        if entry:
-            result.append(entry)
-    return result
-
-
-def _required_concept_list(value: Any) -> list[dict[str, Any]]:
-    """Normalize required schema concept payloads while preserving fallback names."""
-    if not isinstance(value, list):
-        return []
-    result: list[dict[str, Any]] = []
-    for item in value:
-        if not isinstance(item, dict):
-            continue
-        name = str(item.get("name") or "").strip()
-        if not name:
-            continue
-        entry: dict[str, Any] = {"name": name}
-        label = str(item.get("label") or "").strip()
-        if label:
-            entry["label"] = label
-        fallback_names = _str_list(item.get("fallbackNames"))
-        if fallback_names:
-            entry["fallbackNames"] = fallback_names
-        result.append(entry)
-    return result