precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/config_generator.py

@@ -0,0 +1,163 @@
+# 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 V2 YAML 配置生成器兼容模块
+
+功能概述:
+- 提供配置生成服务的向后兼容入口（generate_full_config_v2）
+- 封装新版 ConfigGenerationService，适配旧版参数接口
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from app.shared.services.llm.generation import (
+    ConfigGenerationService,
+    GenerationOptions,
+    ProfilingOptions,
+)
+
+# V2 清单文件名常量
+V2_MANIFEST_FILENAME = "project.precis.yaml"
+
+
+def generate_full_config_v2(
+    data_paths: list[str],
+    output_dir: str,
+    profiling_options: ProfilingOptions | None = None,
+    generation_options: GenerationOptions | None = None,
+    provider_id: str | None = None,
+) -> dict[str, Any]:
+    """
+    @methoddesc 生成完整 V2 项目配置（向后兼容的适配函数）
+
+    内部使用新版 ConfigGenerationService，将旧版参数名适配为新接口：
+    - data_paths -> file_paths
+    - output_dir -> config_path
+
+    参数:
+        data_paths: 数据文件路径列表
+        output_dir: 配置输出目录
+        profiling_options: 数据画像选项，None 则使用默认值
+        generation_options: 生成选项，None 则使用默认值
+        provider_id: 指定使用的 AI Provider ID
+
+    返回:
+        生成结果字典，包含 manifest、schemas、constraints 等
+    """
+    service = ConfigGenerationService(provider_id=provider_id)
+
+    if profiling_options is None:
+        profiling_options = ProfilingOptions()
+    if generation_options is None:
+        generation_options = GenerationOptions()
+
+    # 适配旧参数名：data_paths -> file_paths，output_dir -> config_path
+    return asyncio.run(
+        service.generate(
+            file_paths=data_paths,
+            project_name="generated_project",
+            project_id="generated_project",
+            config_path=output_dir,
+            profiling_options=profiling_options,
+            generation_options=generation_options,
+        )
+    )
+
+
+def expand_data_input_paths(paths: list[str]) -> list[str]:
+    """
+    @methoddesc 展开数据输入路径
+
+    如果传入的是目录，递归遍历其中所有支持的数据文件；
+    如果传入的是文件，直接保留。
+
+    参数:
+        paths: 路径列表（文件或目录）
+
+    返回:
+        展开后的文件路径列表
+
+    示例:
+        >>> expand_data_input_paths(["./data"])
+        ['./data/users.xlsx', './data/orders.csv']
+    """
+    import os
+
+    expanded = []
+    for path in paths:
+        if os.path.isdir(path):
+            # 递归遍历目录，收集所有支持的数据文件
+            for root, dirs, files in os.walk(path):
+                for file in files:
+                    if file.endswith((".xlsx", ".csv", ".json", ".yaml", ".yml")):
+                        expanded.append(os.path.join(root, file))
+        elif os.path.isfile(path):
+            expanded.append(path)
+    return expanded
+
+
+def profile_files(file_paths: list[str], options: ProfilingOptions | None = None) -> dict[str, Any]:
+    """
+    @methoddesc 分析文件画像
+
+    收集每个文件的基本信息（大小、扩展名），用于快速了解数据输入。
+
+    参数:
+        file_paths: 文件路径列表
+        options: 画像选项，None 则使用默认值
+
+    返回:
+        画像结果字典，包含 files 列表、total_count 和 sample
+    """
+    import os
+
+    if options is None:
+        options = ProfilingOptions()
+
+    profiles = []
+    for file_path in file_paths:
+        if os.path.exists(file_path):
+            stat = os.stat(file_path)
+            profiles.append(
+                {
+                    "path": file_path,
+                    "size": stat.st_size,
+                    "extension": os.path.splitext(file_path)[1],
+                }
+            )
+
+    return {
+        "files": profiles,
+        "total_count": len(profiles),
+        "sample": profiles[: options.sample_rows] if profiles else [],
+    }
+
+
+# 为了向后兼容，保留旧名称
+GenerateOptions = GenerationOptions
+
+__all__ = [
+    "ConfigGenerationService",
+    "GenerationOptions",
+    "GenerateOptions",  # 别名
+    "ProfilingOptions",
+    "V2_MANIFEST_FILENAME",
+    "generate_full_config_v2",
+    "expand_data_input_paths",
+    "profile_files",
+]

app/shared/services/llm/constraints/__init__.py

@@ -0,0 +1,41 @@
+# 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 约束文件操作子包
+
+功能概述:
+- constraint_builder: 构建约束 refs/params 结构
+- constraint_deletion: 删除独立约束文件
+- constraint_id: 生成语义化约束 ID
+- frontend_instructions: 生成前端渲染指令
+- inline_batch: 批量处理内联约束（减少 IO）
+
+架构设计:
+- 工具函数集合: 各模块提供单一职责的纯函数
+- 协作模式: builder + id_gen 被 handlers 和 inline_batch 共享调用
+"""
+
+from app.shared.services.llm.constraints.constraint_builder import CONSTRAINT_TYPE_MAP
+from app.shared.services.llm.constraints.constraint_deletion import delete_constraint_file
+from app.shared.services.llm.constraints.frontend_instructions import generate_frontend_instructions
+from app.shared.services.llm.constraints.inline_batch import process_inline_batch
+
+__all__ = [
+    "CONSTRAINT_TYPE_MAP",
+    "delete_constraint_file",
+    "generate_frontend_instructions",
+    "process_inline_batch",
+]

app/shared/services/llm/constraints/constraint_builder.py

@@ -0,0 +1,177 @@
+# 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 约束结构构建模块
+
+功能概述:
+- 根据约束类型构建约束的 refs（引用区）结构
+- 根据约束类型构建约束的 params（参数区）结构
+- 处理类型标准化和名称到 ID 的 Fallback 解析
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from app.shared.services.llm.schema_resolver import _resolve_id_from_name
+
+logger = logging.getLogger(__name__)
+
+# 约束类型别名映射（大写 → PascalCase 标准名）。
+# 单一事实源是 actions/registry.py 的 CONSTRAINT_TYPE_ALIASES；此处保持同步副本。
+# 历史问题：旧副本缺 CHARSET/COMPOSITE，已补齐。直接 import registry 会形成循环导入
+# （actions/__init__ → action_handlers → constraint_builder → actions 包），故维持副本。
+# 新增约束类型时，两处都必须同步更新。
+CONSTRAINT_TYPE_MAP = {
+    "NOT_NULL": "NotNull",
+    "UNIQUE": "Unique",
+    "ALLOWED_VALUES": "AllowedValues",
+    "RANGE": "Range",
+    "REGEX": "Scripted",
+    "FOREIGN_KEY": "ForeignKey",
+    "CONDITIONAL": "Conditional",
+    "DATE_LOGIC": "DateLogic",
+    "CHARSET": "Charset",
+    "COMPOSITE": "Composite",
+}
+
+
+def _build_constraint_refs(
+    constraint_type: str, table_name: str, column_name: str, constraint_spec: dict[str, Any], workspace_path: str = ""
+) -> dict[str, Any]:
+    """
+    @methoddesc 构建约束的 refs 字段
+
+    业务用途:
+    - 根据约束类型（NotNull/Unique/ForeignKey/...）组装符合 YAML 规范的 refs 字典
+    - 必要时根据工作区路径将名称回退解析为 table_id / column_id
+
+    参数:
+        constraint_type: AI 给出的原始约束类型（可能大小写不规范）
+        table_name: 表名（用于名称回退）
+        column_name: 列名（用于名称回退）
+        constraint_spec: AI 输出的 spec 字典
+        workspace_path: 工作区路径，启用名称回退
+
+    返回:
+        refs 字典，结构因约束类型而异
+    """
+    std_type = CONSTRAINT_TYPE_MAP.get(constraint_type, constraint_type)
+    table_id = constraint_spec.get("targetNodeId")
+    column_id = constraint_spec.get("targetColumnId")
+
+    if workspace_path and table_name:
+        fallback_table_id, fallback_column_id = _resolve_id_from_name(
+            workspace_path, table_name, column_name or column_id
+        )
+        if fallback_table_id:
+            table_id = fallback_table_id
+            if fallback_column_id:
+                column_id = fallback_column_id
+
+    if std_type == "NotNull":
+        return {"table_id": table_id, "column_id": column_id}
+    elif std_type == "Unique":
+        return {"table_id": table_id, "column_ids": [column_id]}
+    elif std_type == "ForeignKey":
+        params = constraint_spec.get("params", {})
+        return {
+            "from_table_id": table_id,
+            "from_column_id": column_id,
+            "to_table_id": params.get("toTableId", ""),
+            "to_column_id": params.get("toColumnId", ""),
+        }
+    elif std_type == "Conditional":
+        params = constraint_spec.get("params", {})
+        then_column_id = constraint_spec.get("targetColumnId", column_name)
+        if_conditions = params.get("ifConditions", [])
+        formatted_conditions = []
+        for cond in if_conditions:
+            formatted_conditions.append(
+                {
+                    "if_column_id": cond.get("ifColumnId", ""),
+                    "operator": cond.get("operator", "eq"),
+                    "value": cond.get("value"),
+                    "values": cond.get("values"),
+                }
+            )
+        return {
+            "table_id": table_id,
+            "then_column_id": then_column_id,
+            "if_conditions": formatted_conditions,
+            "if_logic": params.get("ifLogic", "and"),
+        }
+    else:
+        return {"table_id": table_id, "column_id": column_id}
+
+
+def _build_constraint_params(constraint_type: str, constraint_spec: dict[str, Any]) -> dict[str, Any]:
+    """
+    @methoddesc 构建约束的 params 字段
+
+    业务用途:
+    - 将 AI 输出的 camelCase 字段（allowedValues, min/max, logicMode 等）映射为 YAML 标准的 snake_case 字段
+    - Scripted 约束支持从 pattern 自动生成 expression
+
+    参数:
+        constraint_type: 原始约束类型
+        constraint_spec: AI 输出的 spec 字典
+
+    返回:
+        params 字典
+    """
+    std_type = CONSTRAINT_TYPE_MAP.get(constraint_type, constraint_type)
+    params = constraint_spec.get("params", {})
+
+    if std_type == "AllowedValues":
+        return {"allowed_values": params.get("allowedValues", [])}
+    elif std_type == "Range":
+        return {"min": params.get("min"), "max": params.get("max")}
+    elif std_type == "Scripted":
+        pattern = params.get("pattern")
+        expression = params.get("expression")
+        if pattern and not expression:
+            safe_pattern = re.escape(pattern)
+            # repr 生成自带引号转义的字符串字面量，pattern 含单/双引号均安全
+            expression = f"re.match({safe_pattern!r}, str(value)) is not None"
+        if not expression:
+            # 空表达式不再兜底为 "True"（恒真约束会静默失效还报成功），
+            # 抛出让上层按失败上报且不落盘。三个调用方（update_yaml_config 内联/独立分支、
+            # process_inline_batch）均有 except Exception 兜底，会把异常转为该动作的失败结果。
+            raise ValueError(
+                "Scripted 约束缺少有效参数: 需要 params.expression 或 params.pattern 之一（恒真表达式已被禁止）"
+            )
+        return {"expression": expression}
+    elif std_type == "DateLogic":
+        result: dict[str, Any] = {
+            "logic_mode": params.get("logicMode", "compare"),
+            "compare_op": params.get("compareOp", "gt"),
+        }
+        if params.get("compareOp") == "range":
+            result["reference_date"] = params.get("referenceDate", "")
+            result["reference_date_end"] = params.get("referenceDateEnd", "")
+            result["reference_column"] = params.get("referenceColumn", "")
+            result["reference_column_end"] = params.get("referenceColumnEnd", "")
+        else:
+            result["reference_date"] = params.get("referenceDate", "")
+            result["reference_column"] = params.get("referenceColumn", "")
+        return result
+    elif std_type == "Conditional":
+        return {"then_value": params.get("thenValue")}
+    else:
+        return {}

app/shared/services/llm/constraints/constraint_deletion.py

@@ -0,0 +1,84 @@
+# 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 约束文件删除模块
+
+功能概述:
+- 根据约束类型、表名和列名生成约束 ID
+- 删除对应的 .constraint.yaml 文件
+- 使用文件锁保护删除操作
+
+输入示例:
+    success, message = delete_constraint_file("NotNull", "users", "email", "/workspace")
+
+输出示例:
+    (True, "notnull_users_email")
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from app.shared.services.llm.constraints.constraint_id import _generate_constraint_id
+from app.shared.services.llm.yaml_io import FileLock
+
+logger = logging.getLogger(__name__)
+
+
+def delete_constraint_file(
+    constraint_type: str, table_name: str, column_name: str, workspace_path: str
+) -> tuple[bool, str]:
+    """
+    @methoddesc 删除独立约束文件
+
+    根据约束类型、表名和列名生成约束 ID，然后删除对应的 .constraint.yaml 文件。
+    使用文件锁保护删除操作，防止并发冲突。
+
+    参数:
+        constraint_type: 约束类型
+        table_name: 表名
+        column_name: 列名
+        workspace_path: 工作区路径
+
+    返回:
+        元组 (是否成功, 约束ID 或错误信息)
+
+    示例:
+        >>> success, msg = delete_constraint_file("NotNull", "users", "email", "/workspace")
+        >>> success
+        True
+    """
+    try:
+        # 根据类型、表、列生成预期的约束文件 ID
+        constraint_id = _generate_constraint_id(constraint_type, table_name, column_name)
+        constraint_file_path = Path(workspace_path) / "constraints" / f"{constraint_id}.constraint.yaml"
+
+        # 使用文件锁保护删除操作，防止并发冲突
+        with FileLock(str(constraint_file_path)):
+            if constraint_file_path.exists():
+                constraint_file_path.unlink()
+                logger.info(f"[updateYamlConfig] 成功删除约束文件: {constraint_file_path}")
+                return True, constraint_id
+            else:
+                error_msg = f"约束文件不存在: {constraint_file_path}"
+                logger.warning(f"[updateYamlConfig] {error_msg}")
+                return False, error_msg
+
+    except Exception as e:
+        error_msg = f"删除约束文件失败: {str(e)}"
+        logger.error(f"[updateYamlConfig] {error_msg}")
+        return False, error_msg

app/shared/services/llm/constraints/constraint_id.py

@@ -0,0 +1,174 @@
+# 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 约束 ID 生成模块"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+logger = logging.getLogger(__name__)
+
+
+def _generate_constraint_id(constraint_type: str, table_name: str, column_name: str) -> str:
+    """
+    @methoddesc 生成符合命名规范的约束 ID
+
+    业务用途:
+    - 拼接 {type}_{table}_{column} 形式的 ID
+    - 中文表/列名通过 _chinese_to_abbr 转拼音或内建映射
+
+    参数:
+        constraint_type: 约束类型（如 "NotNull" / "Unique"）
+        table_name: 表名
+        column_name: 列名
+
+    返回:
+        标准化后的约束 ID 字符串
+    """
+    type_prefix = constraint_type.lower()
+
+    if re.match(r"^[\u4e00-\u9fff]+$", column_name):
+        safe_column = _chinese_to_abbr(column_name) or "col"
+    else:
+        safe_column = re.sub(r"[^a-zA-Z0-9_]", "_", column_name).strip("_")
+
+    if re.match(r"^[\u4e00-\u9fff]+$", table_name):
+        table_abbr = _chinese_to_abbr(table_name)
+    else:
+        # §2.4: 不再截断到 10 字符——customers_eu_2024 与 customers_us_2024 截断后
+        # 同前缀，同列同类型算出同一 ID，第二个约束静默覆盖第一个
+        safe_table = re.sub(r"[^a-zA-Z0-9_]", "_", table_name).strip("_")
+        table_abbr = safe_table
+
+    if table_abbr:
+        return f"{type_prefix}_{table_abbr}_{safe_column}"
+    else:
+        return f"{type_prefix}_{safe_column}"
+
+
+def _chinese_to_abbr(text: str) -> str:
+    """
+    @methoddesc 中文文本到拼音/英文缩写
+
+    业务用途:
+    - 内建常用业务词映射（订单→order, 用户→user 等）
+    - 不在内建表中的词使用 pypinyin 转换（若可用），否则返回原文本
+
+    参数:
+        text: 中文文本
+
+    返回:
+        拼音或英文缩写
+    """
+    mappings = {
+        "订单": "order",
+        "订单表": "order",
+        "用户": "user",
+        "用户表": "user",
+        "产品": "prod",
+        "产品表": "prod",
+        "商品": "prod",
+        "商品表": "prod",
+        "分类": "cat",
+        "分类表": "cat",
+        "部门": "dept",
+        "部门表": "dept",
+        "员工": "emp",
+        "员工表": "emp",
+        "供应商": "supplier",
+        "供应商表": "supplier",
+        "客户": "customer",
+        "客户表": "customer",
+        "名称": "name",
+        "姓名": "name",
+        "邮箱": "email",
+        "电子邮件": "email",
+        "联系邮箱": "contact_email",
+        "电话": "phone",
+        "手机": "mobile",
+        "地址": "address",
+        "编码": "code",
+        "编号": "code",
+        "类型": "type",
+        "状态": "status",
+        "描述": "desc",
+        "备注": "note",
+        "创建时间": "created_at",
+        "更新时间": "updated_at",
+        "创建日期": "created_date",
+        "更新日期": "updated_date",
+        "金额": "amount",
+        "价格": "price",
+        "数量": "qty",
+        "总数": "total",
+        "用户名": "username",
+    }
+
+    if text in mappings:
+        return mappings[text]
+
+    # §2.4: 子串匹配删除——"订单" in "订单明细" 会把不同表缩写成同一 ID 前缀，
+    # 命中错误映射还引入碰撞面。不在内建表中的词走下方首字母路径
+
+    if re.match(r"^[\u4e00-\u9fff]+$", text):
+        pinyin_map = {
+            "供": "g",
+            "应": "y",
+            "商": "s",
+            "表": "b",
+            "用": "y",
+            "户": "h",
+            "订": "d",
+            "单": "d",
+            "产": "c",
+            "品": "p",
+            "库": "k",
+            "存": "c",
+            "交": "j",
+            "易": "y",
+            "员": "y",
+            "工": "g",
+            "部": "b",
+            "门": "m",
+            "名": "m",
+            "称": "c",
+            "邮": "y",
+            "箱": "x",
+            "电": "d",
+            "话": "h",
+            "地": "d",
+            "址": "z",
+            "编": "b",
+            "码": "m",
+            "类": "l",
+            "型": "x",
+            "状": "z",
+            "态": "t",
+            "描": "m",
+            "述": "s",
+            "备": "b",
+            "注": "z",
+            "价": "j",
+            "格": "g",
+            "数": "s",
+            "量": "l",
+        }
+        # §2.4: 不限前 5 字——长中文名的前 5 字相同仍会碰撞，全名逐字转换
+        return "".join([pinyin_map.get(c, c) for c in text])
+    else:
+        # §2.4: 同理不限前 5 段，全名首字母展开
+        return "".join([c[0] for c in text.split("_") if c])