dtflow 0.5.6__py3-none-any.whl → 0.5.8__py3-none-any.whl

dtflow/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: dtflow
+description: >
+  当用户需要处理 JSONL/CSV/Parquet/JSON/Arrow 数据文件时使用此 skill。
+  提供 CLI 工具 `dt` 和 Python API `DataTransformer`。
+  适用场景：(1) 查看数据：dt sample/head/tail 采样预览，dt stats 统计字段分布；
+  (2) 数据清洗：dt clean 支持 --drop-empty/--min-len/--max-len 过滤行，--keep/--drop/--rename/--promote/--add-field/--fill/--reorder 操作字段；
+  (3) 去重：dt dedupe 精确去重或 --similar 相似度去重；
+  (4) 格式转换：dt transform 预设模板(openai_chat/alpaca/sharegpt/dpo)或自定义配置；
+  (5) Schema 验证：dt validate --preset 验证数据格式；
+  (6) ML 训练框架导出：export_for("llama-factory"/"swift"/"axolotl") 一键生成训练配置；
+  (7) 大文件流式处理：load_stream() O(1) 内存处理 100GB+ 文件。
+  注意：此工具专注数据文件的结构化处理，不涉及 LLM 调用（LLM 调用请用 flexllm）。
+---
+
+# 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 值分布
+dt stats data.jsonl --field=meta.source           # 只统计指定字段（支持嵌套路径，可多次使用）
+dt stats data.jsonl --expand=tags                 # 展开 list 字段统计（可多次使用）
+
+# 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 token-stats data.jsonl -w 4                    # 多进程加速（数据量>=1000时自动启用）
+
+# 采样（支持字段路径语法）
+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 --rename=question:instruction,answer:output  # 重命名字段
+dt clean data.jsonl --promote=meta.label          # 提升嵌套字段到顶层
+dt clean data.jsonl --promote=meta.label:tag      # 提升并自定义名称
+dt clean data.jsonl --add-field=source:web        # 添加常量字段
+dt clean data.jsonl --fill=label:unknown          # 填充空值/缺失字段
+dt clean data.jsonl --reorder=id,text,label       # 控制字段输出顺序
+dt clean data.jsonl --strip                       # 去除字符串首尾空白
+dt clean data.jsonl --promote=meta.label --drop=meta --fill=label:unknown  # 组合使用
+
+# 验证
+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 validate data.jsonl -p openai_chat -w 4        # 多进程加速
+
+# 转换
+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.6"
+__version__ = "0.5.8"
 
 __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
 
 # 创建主应用
@@ -161,11 +164,34 @@ def clean(
     max_len: Optional[str] = typer.Option(None, "--max-len", help="最大长度过滤 (字段:长度)"),
     keep: Optional[str] = typer.Option(None, "--keep", help="只保留指定字段"),
     drop: Optional[str] = typer.Option(None, "--drop", help="删除指定字段"),
+    rename: Optional[str] = typer.Option(None, "--rename", help="重命名字段 (old:new,old2:new2)"),
+    promote: Optional[str] = typer.Option(
+        None, "--promote", help="提升嵌套字段到顶层 (meta.label 或 meta.label:tag)"
+    ),
+    add_field: Optional[str] = typer.Option(None, "--add-field", help="添加常量字段 (key:value)"),
+    fill: Optional[str] = typer.Option(None, "--fill", help="填充空值 (field:default_value)"),
+    reorder: Optional[str] = typer.Option(
+        None, "--reorder", help="控制字段顺序 (field1,field2,...)"
+    ),
     strip: bool = typer.Option(False, "--strip", help="去除字符串首尾空白"),
     output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
 ):
     """数据清洗"""
-    _clean(filename, drop_empty, min_len, max_len, keep, drop, strip, output)
+    _clean(
+        filename,
+        drop_empty,
+        min_len,
+        max_len,
+        keep,
+        drop,
+        rename,
+        promote,
+        add_field,
+        fill,
+        reorder,
+        strip,
+        output,
+    )
 
 
 # ============ 数据统计命令 ============
@@ -176,9 +202,15 @@ def stats(
     filename: str = typer.Argument(..., help="输入文件路径"),
     top: int = typer.Option(10, "--top", "-n", help="显示 Top N 值"),
     full: bool = typer.Option(False, "--full", "-f", help="完整模式：统计值分布、唯一值等详细信息"),
+    field: Optional[List[str]] = typer.Option(
+        None, "--field", help="指定统计字段（可多次使用），支持嵌套路径"
+    ),
+    expand: Optional[List[str]] = typer.Option(
+        None, "--expand", help="展开 list 字段统计（可多次使用）"
+    ),
 ):
     """显示数据文件的统计信息"""
-    _stats(filename, top, full)
+    _stats(filename, top, full, field, expand)
 
 
 @app.command("token-stats")
@@ -189,9 +221,12 @@ def token_stats(
         "cl100k_base", "--model", "-m", help="分词器: cl100k_base (默认), qwen2.5, llama3, gpt-4 等"
     ),
     detailed: bool = typer.Option(False, "--detailed", "-d", help="显示详细统计"),
+    workers: Optional[int] = typer.Option(
+        None, "--workers", "-w", help="并行进程数 (默认自动, 1 禁用并行)"
+    ),
 ):
     """统计数据集的 Token 信息"""
-    _token_stats(filename, field, model, detailed)
+    _token_stats(filename, field, model, detailed, workers)
 
 
 @app.command()
@@ -227,9 +262,12 @@ def validate(
     filter: bool = typer.Option(False, "--filter", "-f", help="过滤无效数据并保存"),
     max_errors: int = typer.Option(20, "--max-errors", help="最多显示的错误数量"),
     verbose: bool = typer.Option(False, "--verbose", "-v", help="显示详细信息"),
+    workers: Optional[int] = typer.Option(
+        None, "--workers", "-w", help="并行进程数 (默认自动, 1 禁用并行)"
+    ),
 ):
     """使用预设 Schema 验证数据格式"""
-    _validate(filename, preset, output, filter, max_errors, verbose)
+    _validate(filename, preset, output, filter, max_errors, verbose, workers)
 
 
 # ============ 工具命令 ============
@@ -263,48 +301,25 @@ dtflow 内置了 toolong 日志查看器，安装后可直接使用 tl 命令：
     print(help_text)
 
 
-# ============ MCP 子命令 ============
-
-mcp_app = typer.Typer(help="MCP 服务管理")
-app.add_typer(mcp_app, name="mcp")
-
-
-@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)
+# ============ Skill 命令 ============
 
 
-@mcp_app.command()
-def status():
-    """查看 MCP 服务安装状态"""
-    from .mcp.cli import MCPCommands
+@app.command("install-skill")
+def install_skill():
+    """安装 dtflow skill 到 Claude Code"""
+    _install_skill()
 
-    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():