dtflow 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

dtflow/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: dtflow
+description: 数据文件处理（JSONL/CSV/Parquet）- 去重/采样/统计/过滤/转换/Schema验证/训练框架导出
+---
+
+# dtflow - 机器学习训练数据格式转换工具
+
+## 设计理念
+
+- **函数式优于类继承**：直接用 lambda/函数做转换，不需要 OOP 抽象
+- **KISS 原则**：一个 `DataTransformer` 类搞定所有操作
+- **链式 API**：`dt.filter(...).to(...).save(...)`
+
+## Python API
+
+```python
+from dtflow import DataTransformer
+
+# 加载数据（支持 JSONL/JSON/CSV/Parquet/Arrow，使用 Polars 引擎）
+dt = DataTransformer.load("data.jsonl")
+
+# 链式操作
+(dt.filter(lambda x: x.score > 0.8)
+   .to(lambda x: {"q": x.question, "a": x.answer})
+   .dedupe("text")
+   .save("output.jsonl"))
+```
+
+### 数据过滤
+
+```python
+dt.filter(lambda x: x.score > 0.8)
+dt.filter(lambda x: x.language == "zh")
+```
+
+### 数据验证
+
+```python
+# 简单验证
+errors = dt.validate(lambda x: len(x.messages) >= 2)
+
+# Schema 验证
+from dtflow import Schema, Field, openai_chat_schema
+
+result = dt.validate_schema(openai_chat_schema)  # 预设 Schema
+valid_dt = dt.validate_schema(schema, filter_invalid=True)  # 过滤无效数据
+```
+
+**预设 Schema**：`openai_chat_schema`、`alpaca_schema`、`sharegpt_schema`、`dpo_schema`
+
+### 数据转换
+
+```python
+# 自定义转换
+dt.to(lambda x: {"question": x.q, "answer": x.a})
+
+# 使用预设模板
+dt.to(preset="openai_chat", user_field="q", assistant_field="a")
+```
+
+**预设模板**：`openai_chat`、`alpaca`、`sharegpt`、`dpo_pair`、`simple_qa`
+
+### Token 统计
+
+```python
+from dtflow import count_tokens, token_counter, token_filter, token_stats
+
+count = count_tokens("Hello world", model="gpt-4")
+dt.transform(token_counter("text")).save("with_tokens.jsonl")
+dt.filter(token_filter("text", max_tokens=2048))
+
+# Messages Token 统计（多轮对话）
+from dtflow import messages_token_counter, messages_token_filter
+dt.transform(messages_token_counter(model="gpt-4", detailed=True))
+dt.filter(messages_token_filter(min_turns=2, max_turns=10))
+```
+
+### 格式转换器
+
+```python
+from dtflow import (
+    to_hf_dataset, from_hf_dataset,      # HuggingFace Dataset
+    to_openai_batch, from_openai_batch,  # OpenAI Batch API
+    to_llama_factory, to_llama_factory_sharegpt,  # LLaMA-Factory
+    to_swift_messages, to_swift_query_response,   # ms-swift
+    messages_to_text,                    # messages 转纯文本
+)
+```
+
+### 训练框架导出
+
+```python
+# 检查兼容性
+result = dt.check_compatibility("llama-factory")
+
+# 一键导出
+files = dt.export_for("llama-factory", "./output/")  # 生成 data.json + dataset_info.json + train_args.yaml
+files = dt.export_for("swift", "./output/")          # 生成 data.jsonl + train_swift.sh
+files = dt.export_for("axolotl", "./output/")        # 生成 data.jsonl + config.yaml
+```
+
+### 大文件流式处理
+
+```python
+from dtflow import load_stream, load_sharded
+
+# O(1) 内存，100GB 文件也能处理
+(load_stream("huge.jsonl")
+    .filter(lambda x: x["score"] > 0.5)
+    .save("output.jsonl"))
+
+# 分片文件加载
+(load_sharded("data/train_*.parquet")
+    .filter(lambda x: len(x["text"]) > 10)
+    .save("merged.jsonl"))
+
+# 分片保存
+load_stream("huge.jsonl").save_sharded("output/", shard_size=100000)
+```
+
+### 其他操作
+
+```python
+dt.sample(100)                    # 随机采样
+dt.head(10) / dt.tail(10)         # 取前/后 N 条
+train, test = dt.split(ratio=0.8) # 分割
+dt.shuffle(seed=42)               # 打乱
+dt.stats()                        # 统计
+```
+
+## CLI 命令
+
+```bash
+# 统计（推荐首先使用）
+dt stats data.jsonl                               # 基本统计（文件大小、条数、字段）
+dt stats data.jsonl --full                        # 完整模式：值分布、唯一值、非空率
+dt stats data.jsonl --full -n 20                  # 显示 Top 20 值分布
+
+# Token 统计
+dt token-stats data.jsonl                         # 默认统计 messages 字段
+dt token-stats data.jsonl -f text                 # 指定统计字段
+dt token-stats data.jsonl -m qwen2.5              # 指定分词器 (cl100k_base/qwen2.5/llama3)
+dt token-stats data.jsonl --detailed              # 显示详细统计
+
+# 采样（支持字段路径语法）
+dt sample data.jsonl 100                          # 随机采样 100 条
+dt sample data.jsonl 100 -t head                  # 取前 100 条 (head/tail/random)
+dt sample data.jsonl 1000 --by=category           # 分层采样
+dt sample data.jsonl 1000 --by=category --uniform # 均匀分层采样
+dt sample data.jsonl --where="messages.#>=2"      # 条件筛选
+dt sample data.jsonl 10 -f input,output           # 只显示指定字段
+dt sample data.jsonl 10 --raw                     # 输出原始 JSON（不截断）
+dt sample data.jsonl 100 --seed=42 -o out.jsonl   # 固定随机种子并保存
+
+# 去重
+dt dedupe data.jsonl --key=text                   # 精确去重
+dt dedupe data.jsonl --key=meta.id                # 按嵌套字段去重
+dt dedupe data.jsonl --key=text --similar=0.8    # 相似度去重
+dt dedupe data.jsonl --key=text -o deduped.jsonl  # 指定输出文件
+
+# 清洗
+dt clean data.jsonl --drop-empty=text,answer      # 删除空值记录
+dt clean data.jsonl --min-len=text:10             # 最小长度过滤
+dt clean data.jsonl --max-len=text:2000           # 最大长度过滤
+dt clean data.jsonl --min-len=messages.#:2        # 最少 2 条消息
+dt clean data.jsonl --keep=question,answer        # 只保留指定字段
+dt clean data.jsonl --drop=metadata               # 删除指定字段
+dt clean data.jsonl --strip                       # 去除字符串首尾空白
+dt clean data.jsonl --strip --drop-empty=input -o cleaned.jsonl  # 组合使用
+
+# 验证
+dt validate data.jsonl --preset=openai_chat       # 预设: openai_chat/alpaca/dpo/sharegpt
+dt validate data.jsonl -p alpaca -f -o valid.jsonl  # 过滤无效数据并保存
+dt validate data.jsonl -p openai_chat -v          # 显示详细信息
+dt validate data.jsonl -p openai_chat --max-errors=50  # 最多显示 50 条错误
+
+# 转换
+dt transform data.jsonl --preset=openai_chat
+dt transform data.jsonl                           # 交互式生成配置文件
+
+# 合并与对比
+dt concat a.jsonl b.jsonl -o merged.jsonl         # 合并文件
+dt concat a.jsonl b.jsonl -o merged.jsonl --strict  # 严格模式（字段必须一致）
+dt diff a.jsonl b.jsonl --key=id                  # 对比差异
+dt diff a.jsonl b.jsonl --key=id -o report.md     # 输出对比报告
+
+# 查看数据
+dt head data.jsonl 10                             # 前 10 条
+dt head data.jsonl 10 -f input,output             # 只显示指定字段
+dt head data.jsonl 10 --raw                       # 输出完整 JSON（不截断）
+dt tail data.jsonl 10                             # 后 10 条
+
+# 其他
+dt run pipeline.yaml                              # Pipeline 执行
+dt history processed.jsonl                        # 数据血缘
+dt install-skill                                  # 安装 Claude Code skill
+```
+
+## 字段路径语法
+
+| 语法 | 含义 | 示例 |
+|------|------|------|
+| `a.b.c` | 嵌套字段 | `meta.source` |
+| `a[0].b` | 数组索引 | `messages[0].role` |
+| `a[-1].b` | 负索引 | `messages[-1].content` |
+| `a.#` | 数组长度 | `messages.#` |
+| `a[*].b` | 展开所有元素 | `messages[*].role` |
+
+## Pipeline 配置
+
+```yaml
+# pipeline.yaml
+version: "1.0"
+seed: 42
+input: raw_data.jsonl
+output: processed.jsonl
+
+steps:
+  - type: filter
+    condition: "score > 0.5"
+  - type: transform
+    preset: openai_chat
+  - type: dedupe
+    key: text
+```

dtflow/__init__.py

@@ -60,7 +60,7 @@ from .tokenizers import (
     token_stats,
 )
 
-__version__ = "0.5.5"
+__version__ = "0.5.7"
 
 __all__ = [
     # core

dtflow/__main__.py

@@ -6,21 +6,21 @@ Usage:
     dt --install-completion  # 安装 shell 自动补全
 
 Commands:
-    sample       从数据文件中采样
-    head         显示文件的前 N 条数据
-    tail         显示文件的后 N 条数据
-    transform    转换数据格式（核心命令）
-    stats        显示数据文件的统计信息
-    token-stats  Token 统计
-    diff         数据集对比
-    dedupe       数据去重
-    concat       拼接多个数据文件
-    clean        数据清洗
-    run          执行 Pipeline 配置文件
-    history      显示数据血缘历史
-    validate     使用 Schema 验证数据格式
-    mcp          MCP 服务管理（install/uninstall/status）
-    logs         日志查看工具使用说明
+    sample        从数据文件中采样
+    head          显示文件的前 N 条数据
+    tail          显示文件的后 N 条数据
+    transform     转换数据格式（核心命令）
+    stats         显示数据文件的统计信息
+    token-stats   Token 统计
+    diff          数据集对比
+    dedupe        数据去重
+    concat        拼接多个数据文件
+    clean         数据清洗
+    run           执行 Pipeline 配置文件
+    history       显示数据血缘历史
+    validate      使用 Schema 验证数据格式
+    logs          日志查看工具使用说明
+    install-skill 安装 dtflow skill 到 Claude Code
 """
 
 import os
@@ -35,12 +35,15 @@ from .cli.commands import dedupe as _dedupe
 from .cli.commands import diff as _diff
 from .cli.commands import head as _head
 from .cli.commands import history as _history
+from .cli.commands import install_skill as _install_skill
 from .cli.commands import run as _run
 from .cli.commands import sample as _sample
+from .cli.commands import skill_status as _skill_status
 from .cli.commands import stats as _stats
 from .cli.commands import tail as _tail
 from .cli.commands import token_stats as _token_stats
 from .cli.commands import transform as _transform
+from .cli.commands import uninstall_skill as _uninstall_skill
 from .cli.commands import validate as _validate
 
 # 创建主应用
@@ -67,10 +70,11 @@ def sample(
     uniform: bool = typer.Option(False, "--uniform", help="均匀采样模式"),
     fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段（逗号分隔）"),
     raw: bool = typer.Option(False, "--raw", "-r", help="输出原始 JSON（不截断）"),
+    where: Optional[List[str]] = typer.Option(None, "--where", "-w", help="筛选条件 (可多次使用)"),
 ):
     """从数据文件中采样指定数量的数据"""
     actual_num = num_arg if num_arg is not None else num
-    _sample(filename, actual_num, type, output, seed, by, uniform, fields, raw)
+    _sample(filename, actual_num, type, output, seed, by, uniform, fields, raw, where)
 
 
 @app.command()
@@ -262,48 +266,25 @@ dtflow 内置了 toolong 日志查看器，安装后可直接使用 tl 命令：
     print(help_text)
 
 
-# ============ MCP 子命令 ============
+# ============ Skill 命令 ============
 
-mcp_app = typer.Typer(help="MCP 服务管理")
-app.add_typer(mcp_app, name="mcp")
 
+@app.command("install-skill")
+def install_skill():
+    """安装 dtflow skill 到 Claude Code"""
+    _install_skill()
 
-@mcp_app.command()
-def install(
-    name: str = typer.Option("datatron", "--name", "-n", help="MCP 服务名称"),
-    target: str = typer.Option("code", "--target", "-t", help="安装目标: desktop/code/all"),
-):
-    """安装 Datatron MCP 服务"""
-    from .mcp.cli import MCPCommands
-
-    MCPCommands().install(name, target)
-
-
-@mcp_app.command()
-def uninstall(
-    name: str = typer.Option("datatron", "--name", "-n", help="MCP 服务名称"),
-    target: str = typer.Option("all", "--target", "-t", help="移除目标: desktop/code/all"),
-):
-    """移除 Datatron MCP 服务"""
-    from .mcp.cli import MCPCommands
-
-    MCPCommands().uninstall(name, target)
-
-
-@mcp_app.command()
-def status():
-    """查看 MCP 服务安装状态"""
-    from .mcp.cli import MCPCommands
-
-    MCPCommands().status()
 
+@app.command("uninstall-skill")
+def uninstall_skill():
+    """卸载 dtflow skill"""
+    _uninstall_skill()
 
-@mcp_app.command()
-def test():
-    """测试 MCP 服务是否正常"""
-    from .mcp.cli import MCPCommands
 
-    MCPCommands().test()
+@app.command("skill-status")
+def skill_status():
+    """查看 skill 安装状态"""
+    _skill_status()
 
 
 def _show_completion_hint():

dtflow/cli/commands.py

@@ -13,25 +13,27 @@ CLI 命令统一导出入口
 """
 
 # 采样命令
-from .sample import head, sample, tail
-
-# 转换命令
-from .transform import transform
-
-# 统计命令
-from .stats import stats, token_stats
-
 # 清洗命令
 from .clean import clean, dedupe
 
 # IO 操作命令
 from .io_ops import concat, diff
 
+# 血缘追踪命令
+from .lineage import history
+
 # Pipeline 命令
 from .pipeline import run
+from .sample import head, sample, tail
 
-# 血缘追踪命令
-from .lineage import history
+# Skill 命令
+from .skill import install_skill, skill_status, uninstall_skill
+
+# 统计命令
+from .stats import stats, token_stats
+
+# 转换命令
+from .transform import transform
 
 # 验证命令
 from .validate import validate
@@ -58,4 +60,8 @@ __all__ = [
     "history",
     # 验证
     "validate",
+    # Skill
+    "install_skill",
+    "uninstall_skill",
+    "skill_status",
 ]

dtflow/cli/sample.py

@@ -2,8 +2,9 @@
 CLI 采样相关命令
 """
 
+import re
 from pathlib import Path
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Callable, Dict, List, Literal, Optional
 
 import orjson
 
@@ -16,6 +17,122 @@ from .common import (
     _print_samples,
 )
 
+# where 条件解析正则：field op value
+_WHERE_PATTERN = re.compile(r"^(.+?)(!=|~=|>=|<=|>|<|=)(.*)$")
+
+
+def _parse_where(condition: str) -> Callable[[dict], bool]:
+    """
+    解析 where 条件字符串，返回筛选函数。
+
+    支持的操作符:
+        =   等于
+        !=  不等于
+        ~=  包含（字符串）
+        >   大于
+        >=  大于等于
+        <   小于
+        <=  小于等于
+
+    Examples:
+        _parse_where("category=tech")
+        _parse_where("meta.source!=wiki")
+        _parse_where("content~=机器学习")
+        _parse_where("messages.#>=2")
+    """
+    match = _WHERE_PATTERN.match(condition)
+    if not match:
+        raise ValueError(f"无效的 where 条件: {condition}")
+
+    field, op, value = match.groups()
+
+    # 尝试转换 value 为数值
+    def parse_value(v: str) -> Any:
+        if v.lower() == "true":
+            return True
+        if v.lower() == "false":
+            return False
+        try:
+            return int(v)
+        except ValueError:
+            try:
+                return float(v)
+            except ValueError:
+                return v
+
+    parsed_value = parse_value(value)
+
+    def filter_fn(item: dict) -> bool:
+        field_value = get_field_with_spec(item, field)
+
+        if op == "=":
+            # 字符串比较或数值比较
+            if field_value is None:
+                return value == "" or value.lower() == "none"
+            return str(field_value) == value or field_value == parsed_value
+        elif op == "!=":
+            if field_value is None:
+                return value != "" and value.lower() != "none"
+            return str(field_value) != value and field_value != parsed_value
+        elif op == "~=":
+            # 包含
+            if field_value is None:
+                return False
+            return value in str(field_value)
+        elif op in (">", ">=", "<", "<="):
+            # 数值比较
+            if field_value is None:
+                return False
+            try:
+                num_field = float(field_value)
+                num_value = float(value)
+                if op == ">":
+                    return num_field > num_value
+                elif op == ">=":
+                    return num_field >= num_value
+                elif op == "<":
+                    return num_field < num_value
+                else:  # <=
+                    return num_field <= num_value
+            except (ValueError, TypeError):
+                return False
+        return False
+
+    return filter_fn
+
+
+def _apply_where_filters(data: List[Dict], where_conditions: List[str]) -> List[Dict]:
+    """应用多个 where 条件（AND 关系）"""
+    if not where_conditions:
+        return data
+
+    filters = [_parse_where(cond) for cond in where_conditions]
+    return [item for item in data if all(f(item) for f in filters)]
+
+
+def _sample_from_list(
+    data: List[Dict],
+    num: int,
+    sample_type: str,
+    seed: Optional[int] = None,
+) -> List[Dict]:
+    """从列表中采样"""
+    import random
+
+    if seed is not None:
+        random.seed(seed)
+
+    total = len(data)
+    if num <= 0 or num > total:
+        num = total
+
+    if sample_type == "random":
+        return random.sample(data, num)
+    elif sample_type == "head":
+        return data[:num]
+    else:  # tail
+        return data[-num:]
+
 
 def sample(
     filename: str,
@@ -27,6 +144,7 @@ def sample(
     uniform: bool = False,
     fields: Optional[str] = None,
     raw: bool = False,
+    where: Optional[List[str]] = None,
 ) -> None:
     """
     从数据文件中采样指定数量的数据。
@@ -44,6 +162,7 @@ def sample(
         uniform: 均匀采样模式（需配合 --by 使用），各组采样相同数量
         fields: 只显示指定字段（逗号分隔），仅在预览模式下有效
         raw: 输出原始 JSON 格式（不截断，完整显示所有内容）
+        where: 筛选条件列表，支持 =, !=, ~=, >, >=, <, <= 操作符
 
     Examples:
         dt sample data.jsonl 5
@@ -54,6 +173,9 @@ def sample(
         dt sample data.jsonl 1000 --by=category           # 按比例分层采样
         dt sample data.jsonl 1000 --by=category --uniform # 均匀分层采样
         dt sample data.jsonl --fields=question,answer     # 只显示指定字段
+        dt sample data.jsonl --where="category=tech"      # 筛选 category 为 tech 的数据
+        dt sample data.jsonl --where="meta.source~=wiki"  # 筛选 meta.source 包含 wiki
+        dt sample data.jsonl --where="messages.#>=2"      # 筛选消息数量 >= 2
     """
     filepath = Path(filename)
 
@@ -69,23 +191,46 @@ def sample(
         print("错误: --uniform 必须配合 --by 使用")
         return
 
+    # 处理 where 筛选
+    where_conditions = where or []
+    filtered_data = None
+    original_count = None
+
+    if where_conditions:
+        # 有 where 条件时，先加载全部数据再筛选
+        try:
+            all_data = load_data(str(filepath))
+            original_count = len(all_data)
+            filtered_data = _apply_where_filters(all_data, where_conditions)
+            print(f"🔍 筛选: {original_count} → {len(filtered_data)} 条")
+            if not filtered_data:
+                print("⚠️  筛选后无数据")
+                return
+        except ValueError as e:
+            print(f"错误: {e}")
+            return
+
     # 分层采样模式
     if by:
         try:
-            sampled = _stratified_sample(filepath, num, by, uniform, seed, type)
+            sampled = _stratified_sample(filepath, num, by, uniform, seed, type, data=filtered_data)
         except Exception as e:
             print(f"错误: {e}")
             return
     else:
         # 普通采样
         try:
-            sampled = sample_file(
-                str(filepath),
-                num=num,
-                sample_type=type,
-                seed=seed,
-                output=None,  # 先不保存，统一在最后处理
-            )
+            if filtered_data is not None:
+                # 已筛选的数据，直接采样
+                sampled = _sample_from_list(filtered_data, num, type, seed)
+            else:
+                sampled = sample_file(
+                    str(filepath),
+                    num=num,
+                    sample_type=type,
+                    seed=seed,
+                    output=None,  # 先不保存，统一在最后处理
+                )
         except Exception as e:
             print(f"错误: {e}")
             return
@@ -117,6 +262,7 @@ def _stratified_sample(
     uniform: bool,
     seed: Optional[int],
     sample_type: str,
+    data: Optional[List[Dict]] = None,
 ) -> List[Dict]:
     """
     分层采样实现。
@@ -133,6 +279,7 @@ def _stratified_sample(
         uniform: 是否均匀采样（各组相同数量）
         seed: 随机种子
         sample_type: 采样方式（用于组内采样）
+        data: 预筛选的数据（可选，如果提供则不从文件加载）
 
     Returns:
         采样后的数据列表
@@ -143,8 +290,9 @@ def _stratified_sample(
     if seed is not None:
         random.seed(seed)
 
-    # 加载数据
-    data = load_data(str(filepath))
+    # 加载数据（如果没有预筛选数据）
+    if data is None:
+        data = load_data(str(filepath))
     total = len(data)
 
     if num <= 0 or num > total: