dtflow 0.5.5__tar.gz → 0.5.7__tar.gz

{dtflow-0.5.5 → dtflow-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dtflow
-Version: 0.5.5
+Version: 0.5.7
 Summary: A flexible data transformation tool for ML training formats (SFT, RLHF, Pretrain)
 Project-URL: Homepage, https://github.com/yourusername/DataTransformer
 Project-URL: Documentation, https://github.com/yourusername/DataTransformer#readme
@@ -69,8 +69,6 @@ Requires-Dist: tokenizers>=0.15.0; extra == 'full'
 Requires-Dist: toolong>=1.5.0; extra == 'full'
 Provides-Extra: logs
 Requires-Dist: toolong>=1.5.0; extra == 'logs'
-Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Provides-Extra: similarity
 Requires-Dist: datasketch>=1.5.0; extra == 'similarity'
 Requires-Dist: scikit-learn>=0.24.0; extra == 'similarity'
@@ -99,6 +97,17 @@ pip install transformers      # Token 统计（HuggingFace 模型）
 pip install datasets          # HuggingFace Dataset 转换
 ```
 
+## 🤖 Claude Code 集成
+
+dtflow 内置了 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill：
+
+```bash
+dt install-skill      # 安装 skill
+dt skill-status       # 查看状态
+```
+
+安装后在 Claude Code 中输入 `/dtflow`，Claude 将掌握 dtflow 的完整用法，可直接协助你完成数据处理任务。
+
 ## 快速开始
 
 ```python
@@ -423,6 +432,8 @@ dt sample data.csv --num=100 --sample_type=head
 dt sample data.jsonl 1000 --by=category           # 分层采样
 dt sample data.jsonl 1000 --by=meta.source        # 按嵌套字段分层采样
 dt sample data.jsonl 1000 --by=messages.#         # 按消息数量分层采样
+dt sample data.jsonl --where="category=tech"      # 筛选后采样
+dt sample data.jsonl --where="messages.#>=2"      # 多条件筛选
 
 # 数据转换 - 预设模式
 dt transform data.jsonl --preset=openai_chat
@@ -471,6 +482,10 @@ dt concat a.jsonl b.jsonl -o merged.jsonl
 # 数据统计
 dt stats data.jsonl
 
+# Claude Code Skill 安装
+dt install-skill                              # 安装到 ~/.claude/skills/
+dt skill-status                               # 查看安装状态
+
 # 数据验证
 dt validate data.jsonl --preset=openai_chat           # 使用预设 schema 验证
 dt validate data.jsonl --preset=alpaca --verbose      # 详细输出
@@ -496,7 +511,7 @@ CLI 命令中的字段参数支持嵌套路径语法，可访问深层嵌套的
 
 | 命令 | 参数 | 示例 |
 |------|------|------|
-| `sample` | `--by=` | `--by=meta.source`、`--by=messages.#` |
+| `sample` | `--by=`, `--where=` | `--by=meta.source`、`--where=messages.#>=2` |
 | `dedupe` | `--key=` | `--key=meta.id`、`--key=messages[0].content` |
 | `clean` | `--drop-empty=` | `--drop-empty=meta.source` |
 | `clean` | `--min-len=` | `--min-len=messages.#:2` |
@@ -504,6 +519,18 @@ CLI 命令中的字段参数支持嵌套路径语法，可访问深层嵌套的
 | `token-stats` | `--field=` | `--field=messages[-1].content` |
 | `diff` | `--key=` | `--key=meta.uuid` |
 
+`--where` 支持的操作符：
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `=` | 等于 | `--where="category=tech"` |
+| `!=` | 不等于 | `--where="source!=wiki"` |
+| `~=` | 包含 | `--where="content~=机器学习"` |
+| `>` | 大于 | `--where="score>0.8"` |
+| `>=` | 大于等于 | `--where="messages.#>=2"` |
+| `<` | 小于 | `--where="length<1000"` |
+| `<=` | 小于等于 | `--where="turns<=10"` |
+
 示例数据：
 ```json
 {"meta": {"source": "wiki"}, "messages": [{"role": "user", "content": "hi"}, {"role": "assistant", "content": "hello"}]}
@@ -601,6 +628,18 @@ dt history processed.jsonl
 dt history processed.jsonl --json  # JSON 格式输出
 ```
 
+### 日志查看
+
+dtflow 内置了 [toolong](https://github.com/Textualize/toolong) 日志查看器：
+
+```bash
+pip install dtflow[logs]    # 安装日志工具
+
+tl app.log                  # 交互式 TUI 查看
+tl --tail app.log           # 实时跟踪（类似 tail -f）
+dt logs                     # 查看使用说明
+```
+
 ### 大文件流式处理
 
 专为超大文件设计的流式处理接口，内存占用 O(1)，支持 JSONL、CSV、Parquet、Arrow 格式：

{dtflow-0.5.5 → dtflow-0.5.7}/README.md

@@ -13,6 +13,17 @@ pip install transformers      # Token 统计（HuggingFace 模型）
 pip install datasets          # HuggingFace Dataset 转换
 ```
 
+## 🤖 Claude Code 集成
+
+dtflow 内置了 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) skill：
+
+```bash
+dt install-skill      # 安装 skill
+dt skill-status       # 查看状态
+```
+
+安装后在 Claude Code 中输入 `/dtflow`，Claude 将掌握 dtflow 的完整用法，可直接协助你完成数据处理任务。
+
 ## 快速开始
 
 ```python
@@ -337,6 +348,8 @@ dt sample data.csv --num=100 --sample_type=head
 dt sample data.jsonl 1000 --by=category           # 分层采样
 dt sample data.jsonl 1000 --by=meta.source        # 按嵌套字段分层采样
 dt sample data.jsonl 1000 --by=messages.#         # 按消息数量分层采样
+dt sample data.jsonl --where="category=tech"      # 筛选后采样
+dt sample data.jsonl --where="messages.#>=2"      # 多条件筛选
 
 # 数据转换 - 预设模式
 dt transform data.jsonl --preset=openai_chat
@@ -385,6 +398,10 @@ dt concat a.jsonl b.jsonl -o merged.jsonl
 # 数据统计
 dt stats data.jsonl
 
+# Claude Code Skill 安装
+dt install-skill                              # 安装到 ~/.claude/skills/
+dt skill-status                               # 查看安装状态
+
 # 数据验证
 dt validate data.jsonl --preset=openai_chat           # 使用预设 schema 验证
 dt validate data.jsonl --preset=alpaca --verbose      # 详细输出
@@ -410,7 +427,7 @@ CLI 命令中的字段参数支持嵌套路径语法，可访问深层嵌套的
 
 | 命令 | 参数 | 示例 |
 |------|------|------|
-| `sample` | `--by=` | `--by=meta.source`、`--by=messages.#` |
+| `sample` | `--by=`, `--where=` | `--by=meta.source`、`--where=messages.#>=2` |
 | `dedupe` | `--key=` | `--key=meta.id`、`--key=messages[0].content` |
 | `clean` | `--drop-empty=` | `--drop-empty=meta.source` |
 | `clean` | `--min-len=` | `--min-len=messages.#:2` |
@@ -418,6 +435,18 @@ CLI 命令中的字段参数支持嵌套路径语法，可访问深层嵌套的
 | `token-stats` | `--field=` | `--field=messages[-1].content` |
 | `diff` | `--key=` | `--key=meta.uuid` |
 
+`--where` 支持的操作符：
+
+| 操作符 | 含义 | 示例 |
+|--------|------|------|
+| `=` | 等于 | `--where="category=tech"` |
+| `!=` | 不等于 | `--where="source!=wiki"` |
+| `~=` | 包含 | `--where="content~=机器学习"` |
+| `>` | 大于 | `--where="score>0.8"` |
+| `>=` | 大于等于 | `--where="messages.#>=2"` |
+| `<` | 小于 | `--where="length<1000"` |
+| `<=` | 小于等于 | `--where="turns<=10"` |
+
 示例数据：
 ```json
 {"meta": {"source": "wiki"}, "messages": [{"role": "user", "content": "hi"}, {"role": "assistant", "content": "hello"}]}
@@ -515,6 +544,18 @@ dt history processed.jsonl
 dt history processed.jsonl --json  # JSON 格式输出
 ```
 
+### 日志查看
+
+dtflow 内置了 [toolong](https://github.com/Textualize/toolong) 日志查看器：
+
+```bash
+pip install dtflow[logs]    # 安装日志工具
+
+tl app.log                  # 交互式 TUI 查看
+tl --tail app.log           # 实时跟踪（类似 tail -f）
+dt logs                     # 查看使用说明
+```
+
 ### 大文件流式处理
 
 专为超大文件设计的流式处理接口，内存占用 O(1)，支持 JSONL、CSV、Parquet、Arrow 格式：

dtflow-0.5.7/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-0.5.5 → dtflow-0.5.7}/dtflow/__init__.py

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

{dtflow-0.5.5 → dtflow-0.5.7}/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-0.5.5 → dtflow-0.5.7}/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",
 ]