precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/generation/profiler.py

@@ -0,0 +1,279 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 数据文件画像
+
+读取数据文件的前 N 行，提取列名、数据类型、空值数和样本值，生成供
+Prompt 构建与 Agent 任务消息使用的画像数据。纯数据加工逻辑，无 Provider
+依赖；取消检查通过 is_cancelled 回调注入，保持模块无状态。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import CancelledError
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProfilingOptions:
+    """数据画像选项"""
+
+    sample_rows: int = 100
+    sample_values_per_column: int = 100
+    max_files: int = 50
+    max_cell_chars: int = 500
+
+
+async def profile_files(
+    file_paths: list[str], options: ProfilingOptions, is_cancelled: Callable[[], bool]
+) -> list[dict]:
+    """分析数据文件获取画像。
+
+    读取各类数据文件的前 N 行，提取列名、数据类型、空值数和样本值。
+    Excel 多 sheet 时每个 sheet 产出独立的 table 画像。
+
+    参数:
+        file_paths: 数据文件路径列表
+        options: 画像选项（采样行数/每列样本数/文件数上限/单元格截断长度）
+        is_cancelled: 取消状态探测回调，返回 True 时抛出 CancelledError
+
+    返回:
+        画像结果列表，每项含 path/table_name/sheet_name/columns
+    """
+    import pandas as pd
+
+    results = []
+
+    # 限制最多处理的文件数量
+    for path in file_paths[: options.max_files]:
+        if is_cancelled():
+            raise CancelledError("Generation cancelled")
+        if not os.path.exists(path):
+            continue
+
+        ext = os.path.splitext(path)[1].lower()
+        # 使用文件名（不含扩展名）作为默认表名
+        table_name = os.path.splitext(os.path.basename(path))[0]
+
+        try:
+            # 收集该文件的所有 sheets：(sheet_name, df) 列表。
+            # Excel 可能多 sheet，每个 sheet 作为独立 table 画像；其他类型单 sheet（sheet_name=None）
+            sheets: list[tuple[str | None, pd.DataFrame]] = []
+            if ext in [".xlsx", ".xls"]:
+                xl = pd.ExcelFile(path)
+                if not xl.sheet_names:
+                    continue
+                # 读取所有 sheet（修复：原仅读 sheet_names[0]，多 sheet Excel 会丢数据）
+                for sn in xl.sheet_names:
+                    sheet_df = pd.read_excel(path, sheet_name=sn, nrows=options.sample_rows)
+                    sheets.append((sn, sheet_df))
+            elif ext == ".csv":
+                df = pd.read_csv(path, nrows=options.sample_rows, encoding="utf-8")
+                sheets.append((None, df))
+            elif ext == ".json":
+                # JSON 文件处理
+                with open(path, encoding="utf-8") as f:
+                    data = json.load(f)
+                # 处理嵌套结构
+                if isinstance(data, dict):
+                    # 查找数据记录数组
+                    records = find_json_records(data)
+                    if records:
+                        df = pd.json_normalize(records)
+                    else:
+                        df = pd.json_normalize([data])
+                elif isinstance(data, list):
+                    df = pd.json_normalize(data)
+                else:
+                    continue
+                # 限制行数
+                sheets.append((None, df.head(options.sample_rows)))
+            elif ext == ".jsonl":
+                # JSON Lines 文件处理
+                records = []
+                with open(path, encoding="utf-8") as f:
+                    for i, line in enumerate(f):
+                        if i >= options.sample_rows:
+                            break
+                        line = line.strip()
+                        if line:
+                            records.append(json.loads(line))
+                sheets.append((None, pd.json_normalize(records)))
+            else:
+                # 不支持的文件类型
+                continue
+
+            # 每个 sheet 独立构建画像结果（Excel 多 sheet 会产出多个 table 画像）
+            multi_sheet = len(sheets) > 1
+            for sheet_name, df in sheets:
+                if df is None or df.empty:
+                    continue
+                # 分析列信息
+                columns = []
+                for col_name in df.columns:
+                    if is_cancelled():
+                        raise CancelledError("Generation cancelled")
+                    col_data = df[col_name]
+
+                    # 获取样本值（处理复杂类型如列表、字典）
+                    # 使用 dict.fromkeys 保序去重，避免 list 的 O(n) in 查找导致的 O(n²) 开销
+                    seen: dict[str, None] = {}
+                    max_samples = options.sample_values_per_column
+                    for v in col_data.dropna():
+                        if len(seen) >= max_samples:
+                            break
+                        # 处理复杂类型并截断
+                        v_str = str(v)[: options.max_cell_chars]
+                        if v_str not in seen:
+                            seen[v_str] = None
+                    sample_values: list[str] = list(seen.keys())
+
+                    columns.append(
+                        {
+                            "name": str(col_name),
+                            "dtype": str(col_data.dtype),
+                            "null_count": int(col_data.isna().sum()),
+                            "sample_values": sample_values,
+                        }
+                    )
+
+                # 多 sheet Excel 时用 "文件名_sheet名" 作为 table_name 区分，避免多表同名
+                effective_table_name = f"{table_name}_{sheet_name}" if (multi_sheet and sheet_name) else table_name
+                result = {
+                    "path": path,
+                    "table_name": effective_table_name,
+                    "sheet_name": sheet_name,
+                    "columns": columns,
+                }
+                results.append(result)
+
+        except Exception as e:
+            # 读取失败，记录警告并跳过，不影响其他文件的处理。
+            # 注意：与原实现一致，列循环内取消抛出的 CancelledError 也会走到这里被记为
+            # 警告跳过——取消最终由调用方的阶段边界检查（_check_cancelled）兜底。
+            logger.warning(f"无法分析文件 {path}: {e}")
+            continue
+
+    return results
+
+
+def find_json_records(data: dict) -> list[dict] | None:
+    """在嵌套 JSON 对象中查找数据记录数组。
+
+    策略：递归遍历 JSON 的所有节点，找到最长的、元素为字典的数组。
+
+    参数:
+        data: 已解析的 JSON 对象
+
+    返回:
+        最长的记录数组；不存在时返回 None
+    """
+    best_array = None
+    best_length = 0
+
+    def search(obj: Any) -> None:
+        nonlocal best_array, best_length
+
+        if isinstance(obj, dict):
+            for key, value in obj.items():
+                if isinstance(value, list):
+                    # 检查是否是数据记录数组（元素是字典）
+                    if value and isinstance(value[0], dict):
+                        if len(value) > best_length:
+                            best_length = len(value)
+                            best_array = value
+                    # 继续搜索数组内部（处理嵌套列表）
+                    for item in value:
+                        if isinstance(item, (dict, list)):
+                            search(item)
+                elif isinstance(value, (dict, list)):
+                    search(value)
+        elif isinstance(obj, list):
+            for item in obj:
+                if isinstance(item, (dict, list)):
+                    search(item)
+
+    search(data)
+    return best_array
+
+
+def filter_profiling(
+    profiling_data: list[dict],
+    table_names: list[str] | None,
+    columns_filter: list[str] | None,
+) -> list[dict]:
+    """根据 scope 过滤画像数据。
+
+    参数:
+        profiling_data: 完整画像数据
+        table_names: 表名白名单，None 表示不过滤表
+        columns_filter: 列过滤，支持 "table.column" 或裸列名，None 表示不过滤列
+
+    返回:
+        过滤后的画像数据（浅拷贝，columns 为新列表）
+    """
+    result = []
+    table_col_map: dict[str, list[str]] = {}
+    if columns_filter:
+        for tc in columns_filter:
+            if "." in tc:
+                t, c = tc.split(".", 1)
+                table_col_map.setdefault(t, []).append(c)
+            else:
+                table_col_map.setdefault("", []).append(tc)
+
+    for item in profiling_data:
+        table_name = item.get("table_name", "")
+        if table_names and table_name not in table_names:
+            continue
+
+        columns = item.get("columns", [])
+        if columns_filter:
+            allowed = set(table_col_map.get(table_name, []) + table_col_map.get("", []))
+            if allowed:
+                columns = [c for c in columns if c.get("name", "") in allowed]
+
+        if columns:
+            filtered = dict(item)
+            filtered["columns"] = columns
+            result.append(filtered)
+    return result
+
+
+def format_profiling_for_agent(profiling_data: list[dict]) -> str:
+    """将画像数据格式化为 Agent 任务消息中的文本段落。"""
+    lines = []
+    for item in profiling_data:
+        table_name = item.get("table_name", "")
+        lines.append(f"### {table_name}")
+        lines.append(f"文件: {item.get('path', '')}")
+        if item.get("sheet_name"):
+            lines.append(f"Sheet: {item['sheet_name']}")
+        for col in item.get("columns", []):
+            samples = col.get("sample_values", [])[:3]
+            samples_str = ", ".join(str(s)[:30] for s in samples)
+            line = f"- {col['name']}: {col['dtype']}, 空值{col['null_count']}"
+            if samples_str:
+                line += f", 例: {samples_str}"
+            lines.append(line)
+    return "\n".join(lines)

app/shared/services/llm/generation/prompt_builder.py

@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview Prompt 构建器
+
+功能概述:
+- 根据数据画像结果构建 LLM 提示词
+- 包含 Schema、Constraint、Regex Node 的格式说明
+- 支持 prompt 长度预算：超限后自动降级（减少列数 → 减少文件数）
+
+输入示例:
+    profiling_data = [{"table_name": "users", "columns": [...]}]
+    prompt, warnings = build_prompt(profiling_data, "电商数据校验")
+
+输出示例:
+    (prompt_string, ["部分文件因 prompt 过长被省略: ..."])
+"""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# 默认 prompt 长度预算（字符数）。DeepSeek v4-flash 支持 1M 上下文，
+# 但给 system prompt、输出和 overhead 留余量，预算设为 80K 字符。
+DEFAULT_MAX_PROMPT_CHARS = 80_000
+
+
+def _estimate_prompt_len(
+    profiling_data: list[dict],
+    project_name: str,
+    max_columns_per_table: int,
+    max_sample_values: int,
+    max_sample_length: int,
+) -> int:
+    """估算 prompt 长度（不实际构建完整字符串）"""
+    length = len(project_name) + 200  # 固定开销（header、格式说明等）
+    for item in profiling_data:
+        length += 100  # 表头开销
+        length += len(item.get("table_name", ""))
+        length += len(item.get("path", ""))
+        if item.get("sheet_name"):
+            length += 50
+        columns = item.get("columns", [])[:max_columns_per_table]
+        for col in columns:
+            length += 80 + len(col["name"]) + len(str(col["dtype"]))
+            samples = col.get("sample_values", [])[:max_sample_values]
+            length += sum(min(len(str(s)), max_sample_length) for s in samples)
+        remaining = len(item.get("columns", [])) - max_columns_per_table
+        if remaining > 0:
+            length += 40
+    return length
+
+
+def build_prompt(
+    profiling_data: list[dict],
+    project_name: str,
+    max_prompt_chars: int = DEFAULT_MAX_PROMPT_CHARS,
+    extra_context: list[str] | None = None,
+) -> tuple[str, list[str]]:
+    """
+    @methoddesc 构建生成提示词（带长度预算和自动降级）
+
+    策略（渐进式降级）：
+    1. 先用较宽松的列数限制（20 列/表，2 样本值）估算长度
+    2. 若超限，先降低列数限制（20 → 10 → 5）
+    3. 若仍超限，减少文件数（保留前 N 个）
+    4. 最终返回 truncation 警告列表
+
+    参数:
+        profiling_data: 数据画像结果列表
+        project_name: 项目名称
+        max_prompt_chars: prompt 最大字符数预算
+        extra_context: 额外上下文文本列表（如上一轮结果、校验问题等）
+
+    返回:
+        (prompt 字符串, truncation 警告列表)
+    """
+    max_columns_per_table = 20
+    max_sample_values = 2
+    max_sample_length = 30
+    warnings: list[str] = []
+
+    # 阶段 1: 估算长度，尝试逐步降级
+    # 降级策略：列数限制 [20, 10, 5, 3]，然后截断文件数
+    for columns_limit in (20, 10, 5, 3):
+        max_columns_per_table = columns_limit
+        estimated = _estimate_prompt_len(
+            profiling_data, project_name, max_columns_per_table, max_sample_values, max_sample_length
+        )
+        if estimated <= max_prompt_chars:
+            if columns_limit < 20:
+                warnings.append(f"数据文件较多，prompt 长度受限，每表仅展示前 {columns_limit} 列")
+            break
+    else:
+        # 即使 3 列也超限，需要截断文件数
+        # 二分查找最大可处理的文件数
+        lo, hi = 1, len(profiling_data)
+        best_files = 1
+        while lo <= hi:
+            mid = (lo + hi) // 2
+            estimated = _estimate_prompt_len(
+                profiling_data[:mid], project_name, 3, max_sample_values, max_sample_length
+            )
+            if estimated <= max_prompt_chars:
+                best_files = mid
+                lo = mid + 1
+            else:
+                hi = mid - 1
+
+        # 先记录总数再切片：旧实现在切片后取 len，omitted 恒为 0，
+        # 超预算文件被静默丢弃且无任何警告
+        total_files = len(profiling_data)
+        profiling_data = profiling_data[:best_files]
+        omitted = total_files - best_files
+        if omitted > 0:
+            warnings.append(f"数据文件过多（共 {total_files} 个），仅分析前 {best_files} 个文件")
+        max_columns_per_table = 3
+
+    # 阶段 2: 实际构建 prompt
+    prompt = f"""为项目 "{project_name}" 生成数据验证配置。
+
+## 数据画像
+
+"""
+    for item in profiling_data:
+        table_name = item.get("table_name", "")
+        prompt += f"### {table_name}\n"
+        prompt += f"文件: {item.get('path', '')}\n"
+        if item.get("sheet_name"):
+            prompt += f"Sheet: {item['sheet_name']}\n"
+
+        columns = item.get("columns", [])[:max_columns_per_table]
+        for col in columns:
+            samples = col.get("sample_values", [])[:max_sample_values]
+            samples_str = ", ".join(str(s)[:max_sample_length] for s in samples)
+            prompt += f"- {col['name']}: {col['dtype']}, 空值{col['null_count']}"
+            if samples_str:
+                prompt += f", 例: {samples_str}"
+            prompt += "\n"
+
+        remaining = len(item.get("columns", [])) - max_columns_per_table
+        if remaining > 0:
+            prompt += f"- ... 还有 {remaining} 列未显示\n"
+
+    # 追加额外上下文
+    if extra_context:
+        prompt += "\n## 额外上下文\n\n"
+        for ctx in extra_context:
+            prompt += f"{ctx}\n\n"
+
+    prompt += """
+## 输出要求
+
+返回 JSON 配置，包含 schemas、constraints、regex_nodes 三个字段。
+
+Schema 格式（请为每个 schema 提供语义化、唯一的 id，使用小写英文+下划线，如 "users"、"order_items"。该 id 会作为约束和正则节点引用的主键）：
+{"id": "users", "name": "用户表", "source": {"mode": "relative_file", "path": "data/users.xlsx", "header_row": 0}, "columns": [{"id": "email", "name": "邮箱", "type": "string", "primary_key": true, "nullable": false}]}
+
+Constraint 格式（V2，refs/params 分离，table_id 必须与 schema 的 id 一致）：
+{"id": "users_email_notnull", "type": "NotNull", "enabled": true, "refs": {"table_id": "users", "column_id": "email"}, "params": {}}
+
+支持类型：NotNull, Unique, AllowedValues(refs+params{allowed_values}), Range(refs+params{min,max}), ForeignKey, Conditional。
+
+Regex Node 格式：
+{"id": "email_regex", "name": "邮箱格式", "pattern": "^[^@]+@[^@]+$", "match_mode": "full", "source_ref": {"table_id": "users", "column_id": "email"}}
+
+建议：
+- email/手机号/身份证 → regex_nodes
+- status/gender → AllowedValues
+- 主键 → Unique
+- 非空列 → NotNull
+- 数值列 → Range
+
+直接返回 JSON，不要解释。"""
+
+    actual_len = len(prompt)
+    logger.info(
+        "[build_prompt] files=%d, columns_limit=%d, estimated=%d, actual=%d",
+        len(profiling_data),
+        max_columns_per_table,
+        _estimate_prompt_len(profiling_data, project_name, max_columns_per_table, max_sample_values, max_sample_length),
+        actual_len,
+    )
+
+    return prompt, warnings

app/shared/services/llm/generation/response_parser.py

@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview LLM 响应 JSON 提取与解析
+
+从 LLM 返回的自由文本中可靠地提取 JSON 配置对象。核心是字符串感知的
+大括号配平扫描：JSON 字符串值内的 '{' / '}' 不参与配平，避免字符串值
+包含 '}' 时把合法 JSON 截断（如 {"a":"x}y"} 被截成 {"a":"x}）。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from .errors import GenerationParseError
+
+
+def find_json_object_end(text: str, start: int) -> int | None:
+    """从 start（应指向 '{'）开始做字符串感知的大括号配平扫描。
+
+    跟踪扫描位置是否处于双引号字符串内部（处理反斜杠转义）：
+    字符串内的 '{' / '}' 不参与配平，避免 JSON 字符串值包含 '}' 时
+    把合法 JSON 截断（如 {"a":"x}y"} 被截成 {"a":"x}）。
+
+    参数:
+        text: 待扫描文本
+        start: 起始索引（text[start] 应为 '{'）
+
+    返回:
+        匹配闭括号的索引（含）；扫描不到配平闭括号时返回 None
+    """
+    balance = 0
+    in_string = False
+    escaped = False
+    for i in range(start, len(text)):
+        char = text[i]
+        if in_string:
+            if escaped:
+                # 转义序列的第二个字符被消耗，不参与边界判断
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            balance += 1
+        elif char == "}":
+            balance -= 1
+            if balance == 0:
+                return i
+    return None
+
+
+def parse_llm_response(content: str) -> dict:
+    """解析 LLM 返回的文本，提取其中的 JSON 配置。
+
+    处理步骤：
+    1. 尝试提取 Markdown 代码块（```json ... ```）中的内容
+    2. 通过大括号平衡计数找到最外层的 JSON 对象
+    3. 使用 json.loads 解析
+
+    参数:
+        content: LLM 返回的原始文本
+
+    返回:
+        解析出的 JSON 对象字典
+
+    异常:
+        GenerationParseError: 内容无法解析为 JSON 对象（携带原始内容前 2000 字符）
+    """
+    original = content
+
+    # 尝试找到 Markdown JSON 代码块
+    match = re.search(r"```(?:json)?\s*(.*?)\s*```", content, re.DOTALL)
+    if match:
+        content = match.group(1).strip()
+
+    # 通过大括号平衡计数找到最外层的 JSON 对象（字符串感知，字符串内的 '}' 不参与配平）
+    start = content.find("{")
+    if start != -1:
+        end = find_json_object_end(content, start)
+        if end is not None:
+            content = content[start : end + 1]
+
+    try:
+        parsed = json.loads(content)
+        if not isinstance(parsed, dict):
+            raise GenerationParseError(
+                f"LLM 响应解析结果不是 JSON 对象，实际类型: {type(parsed).__name__}",
+                raw_content=original[:2000],
+            )
+        return parsed
+    except json.JSONDecodeError as e:
+        raise GenerationParseError(
+            f"AI 返回的内容无法解析为有效配置，请重试或调整描述后重试（{e}）",
+            raw_content=original[:2000],
+        )
+
+
+def try_extract_json_object(content: str | None) -> dict | None:
+    """尽力从文本中提取一个 JSON 对象，失败返回 None（不抛异常）。
+
+    与 parse_llm_response 的差别：本函数用于"兜底解析"场景
+    （如 Agent 最后一轮 content），解析失败不视为错误。
+
+    参数:
+        content: 待提取的文本，可为 None
+
+    返回:
+        提取到的 JSON 对象字典；无法提取时返回 None
+    """
+    if not content:
+        return None
+    match = re.search(r"```(?:json)?\s*(.*?)\s*```", content, re.DOTALL)
+    text = match.group(1).strip() if match else content
+    start = text.find("{")
+    if start == -1:
+        return None
+    end = find_json_object_end(text, start)
+    if end is None:
+        return None
+    try:
+        parsed = json.loads(text[start : end + 1])
+        if isinstance(parsed, dict):
+            return parsed
+    except json.JSONDecodeError:
+        return None
+    return None