precis-cli 0.1.3__py3-none-any.whl

app/shared/domain/transforms/aggregate.py

@@ -0,0 +1,141 @@
+# 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 Aggregate 转换运行器
+
+功能概述:
+- 对 DataFrame 进行聚合操作
+- 支持分组聚合（group_by）和整表聚合
+- 支持 count/sum/avg/min/max 聚合函数
+
+参数:
+    aggregations: 聚合配置列表 [{column, func}]
+        - column: 聚合目标列名
+        - func: 聚合函数 ("count"|"sum"|"avg"|"min"|"max")
+    group_by: 分组列名，支持逗号分隔字符串或列表，留空则整表聚合
+
+说明:
+    - input_column 被忽略（操作整表而非单列）
+    - output_columns 定义聚合结果的列名（按 aggregations 顺序对应）
+      如果 output_columns 未提供或不足，则自动生成 "func_column" 格式列名
+    - 输出 DataFrame 索引重置为连续 0-based
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+# pandas agg 函数名映射
+_FUNC_MAP = {
+    "count": "count",
+    "sum": "sum",
+    "avg": "mean",
+    "min": "min",
+    "max": "max",
+}
+
+
+class AggregateRunner(TransformRunner):
+    """@classdesc 聚合转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行聚合转换
+
+        业务用途:
+        - 从 params.aggregations 读取 [{column, func}, ...] 配置
+        - 若指定 group_by 则按其分组聚合；否则整表聚合
+        - 输出列名优先取 output_columns[i]，缺省按 func_column 自动生成
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名（聚合场景忽略）
+            params: 包含 aggregations / group_by 的参数字典
+            output_columns: 用户指定的输出列名列表
+
+        返回:
+            聚合后的 DataFrame
+
+        异常:
+            ValueError: aggregations 为空或列名不存在
+        """
+        aggregations = params.get("aggregations", [])
+        group_by_str = params.get("group_by", "")
+
+        if not aggregations:
+            raise ValueError("Aggregate 需要至少一个 aggregation 配置")
+
+        # 解析 group_by：兼容逗号分隔字符串与列表两种格式
+        # 前端 tags 产出的是数组，旧配置/手写 YAML 可能是逗号分隔字符串
+        group_by = None
+        if group_by_str:
+            if isinstance(group_by_str, list):
+                parsed = [str(col).strip() for col in group_by_str if str(col).strip()]
+            else:
+                parsed = [col.strip() for col in str(group_by_str).split(",") if col.strip()]
+            # §1.14: 拼错列名报配置错误——原实现静默剔除后走整表聚合，
+            # "每组一行"变"全表一行"，下游约束在错误粒度上继续跑
+            missing = [col for col in parsed if col not in df.columns]
+            if missing:
+                raise ValueError(f"group_by 列不存在: {missing}（表列: {list(df.columns)}）")
+            if parsed:
+                group_by = parsed
+
+        # 构建 agg 字典：{输出列名: (源列名, pandas函数名)}
+        agg_dict: dict[str, tuple[str, str]] = {}
+        col_names: list[str] = []
+
+        for i, agg in enumerate(aggregations):
+            col = agg.get("column", "")
+            func = agg.get("func", "count")
+
+            if col not in df.columns:
+                raise ValueError(f"聚合列不存在: {col}")
+
+            # §1.14: 未知 func 报配置错误——原实现静默按 count 聚合，求和结果变计数
+            if func not in _FUNC_MAP:
+                raise ValueError(f"未知的聚合函数 '{func}'，支持: {sorted(_FUNC_MAP)}")
+            pandas_func = _FUNC_MAP[func]
+
+            # 确定输出列名：优先使用 output_columns，否则自动生成
+            if output_columns and i < len(output_columns):
+                out_name = output_columns[i]
+            else:
+                out_name = f"{func}_{col}"
+
+            agg_dict[out_name] = pd.NamedAgg(column=col, aggfunc=pandas_func)
+            col_names.append(out_name)
+
+        # 执行聚合
+        if group_by:
+            result = df.groupby(group_by, dropna=False).agg(**agg_dict).reset_index()
+        else:
+            # 整表聚合：groupby(None) 产生单行结果
+            result = df.agg(**agg_dict).to_frame().T
+
+        # 确保列顺序：group_by 列 + 聚合结果列
+        result = result.reset_index(drop=True)
+        return result

app/shared/domain/transforms/base.py

@@ -0,0 +1,171 @@
+# 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 Transform 运行器抽象基类模块
+
+功能概述:
+- 定义所有 Transform 运行器的统一接口
+- 提供 execute(df, input_column, params) -> pd.DataFrame 契约
+- 提供条件求值共享函数 evaluate_condition
+
+架构设计:
+- 抽象基类模式: TransformRunner 定义接口，子类实现具体转换逻辑
+- 单列输入: 每个 transform 操作单列，输出新列到同一 DataFrame
+- evaluate_condition: 条件类 Transform（conditional_assign / filter_rows）共享的条件求值逻辑
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+import pandas as pd
+
+
+def stringify_preserve_null(series: pd.Series) -> pd.Series:
+    """转字符串并保留空值：NaN/None → None，其余值 astype(str)。
+
+    各字符串型 runner 的输出列统一用此助手——裸 astype(str) 会把空值变成
+    "nan"/"None" 字面量写入输出列，污染下游数据（如拼接出 "Nonez"、
+    条件匹配命中 "nan"）。
+    """
+    result = series.astype(str)
+    return result.where(series.notna(), None)
+
+
+def _norm_to_str(v: Any) -> str:
+    """条件比较用字符串归一化（A7，与 allowed_values D5 的 _norm_to_str 同语义）。
+
+    含空值的整数列经类型处理后会整列升为 float64（100 → 100.0），裸 astype(str)
+    得 "100.0"，与配置值 100 的 "100" 不命中。对 is_integer() 的 float 回收为
+    整数字符串，使 float64 的 100.0 与配置 100 等价。
+    """
+    if isinstance(v, float) and v.is_integer():
+        return str(int(v))
+    return str(v)
+
+
+def evaluate_condition(df: pd.DataFrame, cond: dict[str, Any]) -> pd.Series:
+    """评估单个条件，返回布尔 Series。
+
+    支持 eq/ne/gt/gte/lt/lte/contains/startswith/endswith/in/not_in/is_null/is_not_null 操作符。
+    被 ConditionalAssignRunner 和 FilterRowsRunner 共享。
+
+    空值语义：NaN/None 行对除 is_null/is_not_null 外的所有操作符一律返回 False
+    （对齐 SQL 的 NULL 比较语义）——裸 astype(str) 会把空值字符串化成 "nan"，
+    导致 eq "nan"、contains "an" 等误命中。
+
+    Args:
+        df: 输入 DataFrame
+        cond: 条件字典，包含 column, op, value
+
+    Returns:
+        布尔 Series；列不存在或操作符未知时返回全 False
+    """
+    column = cond.get("column", "")
+    op = cond.get("op", "eq")
+    value = cond.get("value")
+
+    if column not in df.columns:
+        return pd.Series([False] * len(df), index=df.index)
+
+    series = df[column]
+
+    if op == "is_null":
+        return series.isna() | (series.astype(str).str.strip() == "")
+    elif op == "is_not_null":
+        return ~(series.isna() | (series.astype(str).str.strip() == ""))
+
+    result: pd.Series
+    if op == "eq":
+        result = series.map(_norm_to_str) == _norm_to_str(value)
+    elif op == "ne":
+        result = series.map(_norm_to_str) != _norm_to_str(value)
+    elif op in ("gt", "gte", "lt", "lte"):
+        # §1.5: 比较类阈值不可转数值/缺省 → 配置错误（原实现 NaN 参与比较恒 False，
+        # filter 结果为空表、条件赋值零命中，用户对着空输出排查不到是阈值写错）
+        if value is None:
+            raise ValueError(f"条件阈值未配置（op={op}），无法比较")
+        numeric_series = pd.to_numeric(series, errors="coerce")
+        numeric_value = pd.to_numeric(value, errors="coerce")
+        if pd.isna(numeric_value):
+            raise ValueError(f"条件阈值 '{value}' 无法转换为数值")
+        if op == "gt":
+            result = numeric_series > numeric_value
+        elif op == "gte":
+            result = numeric_series >= numeric_value
+        elif op == "lt":
+            result = numeric_series < numeric_value
+        else:
+            result = numeric_series <= numeric_value
+    elif op == "contains":
+        # regex=False：contains 按字面量子串匹配。过去默认按正则解释，用户数据含
+        # "(未分类)"、"a.b" 等字符时会报 re.error 崩溃或产生错误匹配。
+        result = series.astype(str).str.contains(str(value), na=False, regex=False)
+    elif op == "startswith":
+        result = series.astype(str).str.startswith(str(value), na=False)
+    elif op == "endswith":
+        result = series.astype(str).str.endswith(str(value), na=False)
+    elif op == "in":
+        values = value if isinstance(value, list) else [value]
+        str_values = [_norm_to_str(v) for v in values]
+        result = series.map(_norm_to_str).isin(str_values)
+    elif op == "not_in":
+        values = value if isinstance(value, list) else [value]
+        str_values = [_norm_to_str(v) for v in values]
+        result = ~series.map(_norm_to_str).isin(str_values)
+    else:
+        return pd.Series([False] * len(df), index=df.index)
+
+    # 空值行不参与条件匹配（对齐 SQL NULL 语义）
+    result = result.copy()
+    result[series.isna()] = False
+    return result
+
+
+class TransformRunner(ABC):
+    """@classdesc Transform 运行器抽象基类
+
+    所有具体转换类型必须继承此类并实现 execute 方法。
+
+    使用示例:
+        class StringSplitRunner(TransformRunner):
+            def execute(self, df, input_column, params):
+                delimiter = params.get("delimiter", " ")
+                df["output"] = df[input_column].str.split(delimiter).str[0]
+                return df
+    """
+
+    @abstractmethod
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """@methoddesc 执行数据转换
+
+        参数:
+            df: 输入 DataFrame
+            input_column: 输入列名
+            params: 转换参数
+            output_columns: 输出列名列表
+
+        返回:
+            转换后的 DataFrame（可能包含新列）
+        """
+        ...

app/shared/domain/transforms/cast_type.py

@@ -0,0 +1,120 @@
+# 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 CastType 转换运行器
+
+功能概述:
+- 将列值转换为目标数据类型
+- 支持 int、float、bool、datetime、string 五种目标类型
+
+参数:
+    target_type: 目标类型 ("int"|"float"|"bool"|"datetime"|"string")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner
+
+
+class CastTypeRunner(TransformRunner):
+    """@classdesc 类型转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 类型转换转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        target_type = params.get("target_type", "string")
+
+        if input_column not in df.columns:
+            raise ValueError(f"输入列不存在: {input_column}")
+
+        if not output_columns:
+            raise ValueError("CastType 需要至少一个 output_columns")
+
+        output_col = output_columns[0]
+        series = df[input_column].copy()
+
+        if target_type in ("int", "integer"):
+            # §1.15: fail-fast——原实现 try/except 吞掉 "cannot safely cast" 后静默保留 float，
+            # 用户以为已转整数，下游按整数假设配约束全错。不取截断语义（1.9→1 不允许）。
+            numeric = pd.to_numeric(series, errors="coerce")
+            # 非空但不可转数值（"abc"），或可转但非整数（1.5）→ 报错并带首个代表值
+            bad_mask = series.notna() & (numeric.isna() | (numeric != numeric.round()))
+            bad_indices = series.index[bad_mask]
+            if len(bad_indices) > 0:
+                first = bad_indices[0]
+                raise ValueError(f"无法将值 '{series[first]}'（第 {first} 行）转换为 int：存在非整数或非数值的值")
+            # 转为可空整数类型，避免 NaN 导致 float 强转（整数浮点如 1.0 合法转入）
+            series = numeric.astype("Int64")
+        elif target_type == "float":
+            series = pd.to_numeric(series, errors="coerce")
+        elif target_type == "bool":
+            series = series.apply(self._to_bool)
+        elif target_type == "datetime":
+            series = pd.to_datetime(series, errors="coerce")
+        elif target_type == "string":
+            series = series.astype(str)
+            series = series.where(~pd.isna(df[input_column]), None)
+        else:
+            raise ValueError(f"不支持的目标类型: {target_type}")
+
+        df[output_col] = series
+        return df
+
+    @staticmethod
+    def _to_bool(value: Any) -> Any:
+        """将单个值转换为布尔值。
+
+        支持常见的布尔值字符串表示。
+        空值（None/NaN）透传为 None，不参与类型判定——与 string 分支的
+        `where(~isna, None)` 口径一致，避免 bool(nan)=True 把空值断言为 True。
+        无法识别的值返回 None。
+        """
+        if value is None or (isinstance(value, float) and value != value):
+            return None
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, (int, float)):
+            return bool(value)
+        s = str(value).strip().lower()
+        if s in ("true", "1", "yes", "y", "on"):
+            return True
+        if s in ("false", "0", "no", "n", "off"):
+            return False
+        return None

app/shared/domain/transforms/concat.py

@@ -0,0 +1,103 @@
+# 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 Concat 转换运行器
+
+功能概述:
+- 将多个列的值拼接为一个新列
+- 支持自定义分隔符
+
+参数:
+    columns: 要拼接的列名，支持逗号分隔字符串（如 "first_name,last_name"）或列表（如 ["first_name","last_name"]）
+    separator: 分隔符（默认空字符串）
+    output_column: 输出列名（可选）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, stringify_preserve_null
+
+
+class ConcatRunner(TransformRunner):
+    """@classdesc 列拼接转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 字符串拼接转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        columns_raw = params.get("columns", "")
+        separator = params.get("separator", "")
+        output_column = params.get("output_column", None)
+
+        # 解析列名列表：兼容字符串（逗号分隔）与列表两种格式
+        # 前端 TagsRenderer 产出的是数组，旧配置/手写 YAML 可能是逗号分隔字符串
+        if isinstance(columns_raw, list):
+            column_list = [str(col).strip() for col in columns_raw if str(col).strip()]
+        else:
+            column_list = [col.strip() for col in str(columns_raw).split(",") if col.strip()]
+
+        if not column_list:
+            raise ValueError("Concat 需要 columns 参数（要拼接的列名，逗号分隔）")
+
+        # 验证所有列都存在
+        for col in column_list:
+            if col not in df.columns:
+                raise ValueError(f"列不存在: {col}")
+
+        # 确定输出列名
+        if output_column:
+            output_col = output_column
+        elif output_columns:
+            output_col = output_columns[0]
+        else:
+            output_col = "concat_result"
+
+        # 执行拼接
+        if len(column_list) == 1:
+            # 单列情况：直接复制（空值透传为 None，不产生 "nan"/"None" 字面量）
+            df[output_col] = stringify_preserve_null(df[column_list[0]])
+        else:
+            # 多列情况：向量化拼接。任一源单元格为空 → 结果为 None
+            # （对齐 SQL CONCAT 的 NULL 语义），避免 astype(str) 拼出 "x-None" 之类的污染值
+            null_mask = df[column_list].isna().any(axis=1)
+            joined = df[column_list].astype(str).agg(separator.join, axis=1)
+            joined = joined.where(~null_mask, None)
+            df[output_col] = joined
+
+        return df

app/shared/domain/transforms/conditional_assign.py

@@ -0,0 +1,114 @@
+# 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 ConditionalAssign 转换运行器
+
+功能概述:
+- 根据条件判断对列进行条件赋值
+- 支持多条件组合（AND/OR 逻辑）
+- 支持 eq/ne/gt/gte/lt/lte/contains/startswith/endswith/in/not_in/is_null/is_not_null 操作符
+
+参数:
+    conditions: 条件列表 [{column, op, value}]
+    logic: 条件组合逻辑 ("and"|"or")
+    then_value: 条件满足时的赋值
+    else_value: 条件不满足时的赋值（可选，不提供则保留原值）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from .base import TransformRunner, evaluate_condition
+
+
+class ConditionalAssignRunner(TransformRunner):
+    """@classdesc 条件赋值转换运行器"""
+
+    def execute(
+        self,
+        df: pd.DataFrame,
+        input_column: str,
+        params: dict[str, Any],
+        output_columns: list[str],
+    ) -> pd.DataFrame:
+        """
+        @methoddesc 执行 条件赋值转换
+
+        业务用途:
+        - TransformRunner 协议的标准入口，由 transform 节点调用
+        - 读取 params 中的转换参数，对 input_column 应用转换，输出到 output_columns
+
+        参数:
+            df: 源 DataFrame
+            input_column: 输入列名
+            params: 转换参数字典
+            output_columns: 目标输出列名列表
+
+        返回:
+            转换后的 DataFrame
+        """
+        conditions = params.get("conditions", [])
+        # logic 归一大小写不敏感（"OR"/"And" 均合法），未知值 fail-fast——不再静默按 AND 组合
+        raw_logic = params.get("logic", "and")
+        logic = str(raw_logic).lower()
+        if logic not in ("and", "or"):
+            raise ValueError(f"未知的 logic '{raw_logic}'，支持的值为: and, or")
+        # §1.18: then_value 缺省报配置错误——原实现缺省 "" 把命中行静默写空串。
+        # 显式空串 then_value: '' 是合法赋值（写空串），只拒绝 None。
+        if not output_columns:
+            raise ValueError("ConditionalAssign 需要至少一个 output_columns")
+        then_value = params.get("then_value")
+        if then_value is None:
+            raise ValueError("ConditionalAssign 缺少必填参数 then_value")
+
+        output_col = output_columns[0]
+
+        if not conditions:
+            # 无条件时直接赋 then_value
+            df[output_col] = then_value
+            return df
+
+        # 逐行评估所有条件，生成布尔掩码
+        masks = []
+        for cond in conditions:
+            mask = evaluate_condition(df, cond)
+            masks.append(mask)
+
+        # 组合条件
+        if logic == "or":
+            combined = masks[0]
+            for m in masks[1:]:
+                combined = combined | m
+        else:
+            combined = masks[0]
+            for m in masks[1:]:
+                combined = combined & m
+
+        # 赋值：输出列初始化为 object 类型以支持混合类型赋值（如 int 列赋 str 值）
+        if input_column in df.columns:
+            df[output_col] = df[input_column].copy().astype(object)
+        else:
+            df[output_col] = None
+        df.loc[combined, output_col] = then_value
+        # §1.18: 用键存在性区分"显式 null（置空）"与"未提供（保留原值）"——
+        # params.get 对两者都返回 None，原实现 else 分支永不执行，想置空做不到
+        if "else_value" in params:
+            df.loc[~combined, output_col] = params["else_value"]
+
+        return df