dtflow 0.3.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

dtflow/__init__.py

@@ -13,6 +13,7 @@ from .storage import save_data, load_data, sample_file
 from .tokenizers import (
     count_tokens, token_counter, token_filter, token_stats,
     messages_token_counter, messages_token_filter, messages_token_stats,
+    DEFAULT_MODEL, MODEL_ALIASES, OPENAI_MODELS, resolve_model,
 )
 from .converters import (
     to_hf_dataset, from_hf_dataset, to_hf_chat_format,
@@ -23,8 +24,14 @@ from .converters import (
     # ms-swift
     to_swift_messages, to_swift_query_response, to_swift_vlm,
 )
+from .streaming import (
+    StreamingTransformer,
+    load_stream,
+    load_sharded,
+    process_shards,
+)
 
-__version__ = '0.3.0'
+__version__ = '0.3.1'
 
 __all__ = [
     # core
@@ -47,6 +54,10 @@ __all__ = [
     'messages_token_counter',
     'messages_token_filter',
     'messages_token_stats',
+    'DEFAULT_MODEL',
+    'MODEL_ALIASES',
+    'OPENAI_MODELS',
+    'resolve_model',
     # converters
     'to_hf_dataset',
     'from_hf_dataset',
@@ -64,4 +75,9 @@ __all__ = [
     'to_swift_messages',
     'to_swift_query_response',
     'to_swift_vlm',
+    # streaming
+    'StreamingTransformer',
+    'load_stream',
+    'load_sharded',
+    'process_shards',
 ]

dtflow/__main__.py

@@ -2,252 +2,305 @@
 Datatron CLI entry point.
 
 Usage:
-    python -m datatron <command> [options]
     dt <command> [options]
+    dt --install-completion  # 安装 shell 自动补全
 
 Commands:
-    transform  转换数据格式（核心命令）
-    sample     从数据文件中采样
-    head       显示文件的前 N 条数据
-    tail       显示文件的后 N 条数据
-    stats      显示数据文件的统计信息
-    dedupe     数据去重
-    concat     拼接多个数据文件
-    clean      数据清洗
-    mcp        MCP 服务管理（install/uninstall/status）
+    sample       从数据文件中采样
+    head         显示文件的前 N 条数据
+    tail         显示文件的后 N 条数据
+    transform    转换数据格式（核心命令）
+    stats        显示数据文件的统计信息
+    token-stats  Token 统计
+    diff         数据集对比
+    dedupe       数据去重
+    concat       拼接多个数据文件
+    clean        数据清洗
+    run          执行 Pipeline 配置文件
+    history      显示数据血缘历史
+    mcp          MCP 服务管理（install/uninstall/status）
+    logs         日志查看工具使用说明
 """
-import fire
-
-from .cli import clean as _clean, concat as _concat, dedupe as _dedupe, head as _head, sample as _sample, stats as _stats, tail as _tail, transform as _transform
-from .mcp.cli import MCPCommands
-
-
-class Cli:
-    """Datatron CLI - 数据转换工具命令行接口"""
-
-    def __init__(self):
-        self.mcp = MCPCommands()
-
-    @staticmethod
-    def transform(
-        filename: str,
-        num: int = None,
-        preset: str = None,
-        config: str = None,
-        output: str = None,
-    ):
-        """
-        转换数据格式。
-
-        两种使用方式：
-        1. 配置文件模式（默认）：自动生成配置文件，编辑后再次运行
-        2. 预设模式：使用 --preset 直接转换
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            num: 只转换前 N 条数据（可选）
-            preset: 使用预设模板（openai_chat, alpaca, sharegpt, dpo_pair, simple_qa）
-            config: 配置文件路径（可选，默认 .dt/<filename>.py）
-            output: 输出文件路径
-
-        Examples:
-            dt transform data.jsonl                        # 首次生成配置
-            dt transform data.jsonl 10                     # 只转换前 10 条
-            dt transform data.jsonl --preset=openai_chat   # 使用预设
-            dt transform data.jsonl 100 --preset=alpaca    # 预设 + 限制数量
-        """
-        _transform(filename, num, preset, config, output)
-
-    @staticmethod
-    def sample(
-        filename: str,
-        num: int = 10,
-        sample_type: str = "head",
-        output: str = None,
-        seed: int = None,
-        by: str = None,
-        uniform: bool = False,
-    ):
-        """
-        从数据文件中采样指定数量的数据。
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            num: 采样数量，默认 10
-                - num > 0: 采样指定数量
-                - num = 0: 采样所有数据
-                - num < 0: Python 切片风格（如 -1 表示最后 1 条，-10 表示最后 10 条）
-            sample_type: 采样方式，可选 random/head/tail，默认 head
-            output: 输出文件路径，不指定则打印到控制台
-            seed: 随机种子（仅在 sample_type=random 时有效）
-            by: 分层采样字段名，按该字段的值分组采样
-            uniform: 均匀采样模式（需配合 --by 使用），各组采样相同数量
-
-        Examples:
-            dt sample data.jsonl 5
-            dt sample data.csv 100 --sample_type=head
-            dt sample data.xlsx 50 --output=sampled.jsonl
-            dt sample data.jsonl 0   # 采样所有数据
-            dt sample data.jsonl -10 # 最后 10 条数据
-            dt sample data.jsonl 1000 --by=category           # 按比例分层采样
-            dt sample data.jsonl 1000 --by=category --uniform # 均匀分层采样
-        """
-        _sample(filename, num, sample_type, output, seed, by, uniform)
-
-    @staticmethod
-    def head(
-        filename: str,
-        num: int = 10,
-        output: str = None,
-    ):
-        """
-        显示文件的前 N 条数据（dt sample --sample_type=head 的快捷方式）。
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            num: 显示数量，默认 10
-                - num > 0: 显示指定数量
-                - num = 0: 显示所有数据
-                - num < 0: Python 切片风格（如 -10 表示最后 10 条）
-            output: 输出文件路径，不指定则打印到控制台
-
-        Examples:
-            dt head data.jsonl          # 显示前 10 条
-            dt head data.jsonl 20       # 显示前 20 条
-            dt head data.csv 0          # 显示所有数据
-            dt head data.xlsx --output=head.jsonl
-        """
-        _head(filename, num, output)
-
-    @staticmethod
-    def tail(
-        filename: str,
-        num: int = 10,
-        output: str = None,
-    ):
-        """
-        显示文件的后 N 条数据（dt sample --sample_type=tail 的快捷方式）。
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            num: 显示数量，默认 10
-                - num > 0: 显示指定数量
-                - num = 0: 显示所有数据
-                - num < 0: Python 切片风格（如 -10 表示最后 10 条）
-            output: 输出文件路径，不指定则打印到控制台
-
-        Examples:
-            dt tail data.jsonl          # 显示后 10 条
-            dt tail data.jsonl 20       # 显示后 20 条
-            dt tail data.csv 0          # 显示所有数据
-            dt tail data.xlsx --output=tail.jsonl
-        """
-        _tail(filename, num, output)
-
-    @staticmethod
-    def dedupe(
-        filename: str,
-        key: str = None,
-        similar: float = None,
-        output: str = None,
-    ):
-        """
-        数据去重。
-
-        支持两种模式：
-        1. 精确去重（默认）：完全相同的数据才去重
-        2. 相似度去重：使用 MinHash+LSH 算法，相似度超过阈值则去重
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            key: 去重依据字段，多个字段用逗号分隔。不指定则全量去重
-            similar: 相似度阈值（0-1），指定后启用相似度去重模式
-            output: 输出文件路径，不指定则覆盖原文件
-
-        Examples:
-            dt dedupe data.jsonl                            # 全量精确去重
-            dt dedupe data.jsonl --key=text                 # 按字段精确去重
-            dt dedupe data.jsonl --key=text --similar=0.8   # 相似度去重
-            dt dedupe data.jsonl --output=clean.jsonl       # 指定输出文件
-        """
-        _dedupe(filename, key, similar, output)
-
-    @staticmethod
-    def concat(
-        *files: str,
-        output: str = None,
-        strict: bool = False,
-    ):
-        """
-        拼接多个数据文件。
-
-        Args:
-            *files: 输入文件路径列表，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            output: 输出文件路径，必须指定
-            strict: 严格模式，字段必须完全一致，否则报错
-
-        Examples:
-            dt concat a.jsonl b.jsonl -o merged.jsonl
-            dt concat data1.csv data2.csv data3.csv -o all.jsonl
-            dt concat a.jsonl b.jsonl --strict -o merged.jsonl
-        """
-        _concat(*files, output=output, strict=strict)
-
-    @staticmethod
-    def stats(
-        filename: str,
-        top: int = 10,
-    ):
-        """
-        显示数据文件的统计信息（类似 pandas df.info() + df.describe()）。
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            top: 显示频率最高的前 N 个值，默认 10
-
-        Examples:
-            dt stats data.jsonl
-            dt stats data.csv --top=5
-        """
-        _stats(filename, top)
-
-    @staticmethod
-    def clean(
-        filename: str,
-        drop_empty: str = None,
-        min_len: str = None,
-        max_len: str = None,
-        keep: str = None,
-        drop: str = None,
-        strip: bool = False,
-        output: str = None,
-    ):
-        """
-        数据清洗。
-
-        Args:
-            filename: 输入文件路径，支持 csv/excel/jsonl/json/parquet/arrow/feather 格式
-            drop_empty: 删除空值记录（不带值删除任意空，指定字段用逗号分隔）
-            min_len: 最小长度过滤，格式 "字段:长度"（如 text:10）
-            max_len: 最大长度过滤，格式 "字段:长度"（如 text:1000）
-            keep: 只保留指定字段（逗号分隔）
-            drop: 删除指定字段（逗号分隔）
-            strip: 去除所有字符串字段的首尾空白
-            output: 输出文件路径，不指定则覆盖原文件
-
-        Examples:
-            dt clean data.jsonl --drop-empty                    # 删除任意空值记录
-            dt clean data.jsonl --drop-empty=text,answer        # 删除指定字段为空的记录
-            dt clean data.jsonl --min-len=text:10               # text 字段最少 10 字符
-            dt clean data.jsonl --keep=question,answer          # 只保留这些字段
-            dt clean data.jsonl --strip                         # 去除字符串首尾空白
-            dt clean data.jsonl --drop-empty --strip -o out.jsonl
-        """
-        _clean(filename, drop_empty, min_len, max_len, keep, drop, strip, output)
+import os
+import sys
+from typing import List, Optional
+
+import typer
+
+from .cli.commands import (
+    sample as _sample,
+    head as _head,
+    tail as _tail,
+    transform as _transform,
+    dedupe as _dedupe,
+    concat as _concat,
+    stats as _stats,
+    clean as _clean,
+    run as _run,
+    token_stats as _token_stats,
+    diff as _diff,
+    history as _history,
+)
+
+# 创建主应用
+app = typer.Typer(
+    name="dt",
+    help="Datatron CLI - 数据转换工具",
+    add_completion=True,
+    no_args_is_help=True,
+)
+
+
+# ============ 数据预览命令 ============
+
+@app.command()
+def sample(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    num: int = typer.Argument(10, help="采样数量"),
+    type: str = typer.Option("head", "--type", "-t", help="采样方式: random/head/tail"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+    seed: Optional[int] = typer.Option(None, "--seed", help="随机种子"),
+    by: Optional[str] = typer.Option(None, "--by", help="分层采样字段"),
+    uniform: bool = typer.Option(False, "--uniform", help="均匀采样模式"),
+    fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段（逗号分隔）"),
+):
+    """从数据文件中采样指定数量的数据"""
+    _sample(filename, num, type, output, seed, by, uniform, fields)
+
+
+@app.command()
+def head(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    num: int = typer.Argument(10, help="显示数量"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+    fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段"),
+):
+    """显示文件的前 N 条数据"""
+    _head(filename, num, output, fields)
+
+
+@app.command()
+def tail(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    num: int = typer.Argument(10, help="显示数量"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+    fields: Optional[str] = typer.Option(None, "--fields", "-f", help="只显示指定字段"),
+):
+    """显示文件的后 N 条数据"""
+    _tail(filename, num, output, fields)
+
+
+# ============ 数据转换命令 ============
+
+@app.command()
+def transform(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    num: Optional[int] = typer.Argument(None, help="只转换前 N 条数据"),
+    preset: Optional[str] = typer.Option(None, "--preset", "-p", help="使用预设模板"),
+    config: Optional[str] = typer.Option(None, "--config", "-c", help="配置文件路径"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+):
+    """转换数据格式"""
+    _transform(filename, num, preset, config, output)
+
+
+@app.command()
+def run(
+    config: str = typer.Argument(..., help="Pipeline YAML 配置文件"),
+    input: Optional[str] = typer.Option(None, "--input", "-i", help="输入文件路径"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+):
+    """执行 Pipeline 配置文件"""
+    _run(config, input, output)
+
+
+# ============ 数据处理命令 ============
+
+@app.command()
+def dedupe(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    key: Optional[str] = typer.Option(None, "--key", "-k", help="去重依据字段"),
+    similar: Optional[float] = typer.Option(None, "--similar", "-s", help="相似度阈值 (0-1)"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径"),
+):
+    """数据去重"""
+    _dedupe(filename, key, similar, output)
+
+
+@app.command()
+def concat(
+    files: List[str] = typer.Argument(..., help="输入文件列表"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="输出文件路径（必须）"),
+    strict: bool = typer.Option(False, "--strict", help="严格模式，字段必须一致"),
+):
+    """拼接多个数据文件"""
+    _concat(*files, output=output, strict=strict)
+
+
+@app.command()
+def clean(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    drop_empty: Optional[str] = typer.Option(None, "--drop-empty", help="删除空值记录"),
+    min_len: Optional[str] = typer.Option(None, "--min-len", help="最小长度过滤 (字段:长度)"),
+    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="删除指定字段"),
+    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)
+
+
+# ============ 数据统计命令 ============
+
+@app.command()
+def stats(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    top: int = typer.Option(10, "--top", "-n", help="显示 Top N 值"),
+):
+    """显示数据文件的统计信息"""
+    _stats(filename, top)
+
+
+@app.command("token-stats")
+def token_stats(
+    filename: str = typer.Argument(..., help="输入文件路径"),
+    field: str = typer.Option("messages", "--field", "-f", help="统计字段"),
+    model: str = typer.Option("cl100k_base", "--model", "-m", help="分词器: cl100k_base (默认), qwen2.5, llama3, gpt-4 等"),
+    detailed: bool = typer.Option(False, "--detailed", "-d", help="显示详细统计"),
+):
+    """统计数据集的 Token 信息"""
+    _token_stats(filename, field, model, detailed)
+
+
+@app.command()
+def diff(
+    file1: str = typer.Argument(..., help="第一个文件"),
+    file2: str = typer.Argument(..., help="第二个文件"),
+    key: Optional[str] = typer.Option(None, "--key", "-k", help="匹配键字段"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="报告输出路径"),
+):
+    """对比两个数据集的差异"""
+    _diff(file1, file2, key, output)
+
+
+@app.command()
+def history(
+    filename: str = typer.Argument(..., help="数据文件路径"),
+    json: bool = typer.Option(False, "--json", "-j", help="JSON 格式输出"),
+):
+    """显示数据文件的血缘历史"""
+    _history(filename, json)
+
+
+# ============ 工具命令 ============
+
+@app.command()
+def logs():
+    """日志查看工具使用说明"""
+    help_text = """
+日志查看工具 (tl)
+
+dtflow 内置了 toolong 日志查看器，安装后可直接使用 tl 命令：
+
+基本用法:
+    tl app.log              查看日志文件（交互式 TUI）
+    tl app.log error.log    同时查看多个日志
+    tl --tail app.log       实时跟踪模式（类似 tail -f）
+    tl *.log                通配符匹配多个文件
+
+快捷键:
+    /     搜索
+    n/N   下一个/上一个匹配
+    g/G   跳到开头/结尾
+    f     过滤显示
+    q     退出
+
+安装:
+    pip install dtflow[logs]   # 仅安装日志工具
+    pip install dtflow[full]   # 安装全部可选依赖
+"""
+    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)
+
+
+@mcp_app.command()
+def status():
+    """查看 MCP 服务安装状态"""
+    from .mcp.cli import MCPCommands
+    MCPCommands().status()
+
+
+@mcp_app.command()
+def test():
+    """测试 MCP 服务是否正常"""
+    from .mcp.cli import MCPCommands
+    MCPCommands().test()
+
+
+def _show_completion_hint():
+    """首次运行时提示用户可以安装补全"""
+    from pathlib import Path
+
+    # 标记文件
+    marker = Path.home() / ".config" / "dtflow" / ".completion_hinted"
+
+    # 已提示过则跳过
+    if marker.exists():
+        return
+
+    # 检测是否在交互式终端中（检查 stderr，因为 stdout 可能被管道）
+    if not (sys.stderr.isatty() or sys.stdout.isatty()):
+        return
+
+    # 显示提示（使用 stderr 避免干扰管道输出）
+    from rich.console import Console
+    console = Console(stderr=True)
+    console.print(
+        "[dim]💡 提示: 运行 [green]dt --install-completion[/green] 启用命令补全[/dim]"
+    )
+
+    # 记录已提示
+    try:
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.touch()
+    except Exception:
+        pass
 
 
 def main():
-    fire.Fire(Cli)
+    # less 分页器配置（仅 Unix-like 系统）
+    if sys.platform != 'win32':
+        os.environ['PAGER'] = 'less -RXF'
+
+    # _show_completion_hint()
+    app()
 
 
 if __name__ == "__main__":

dtflow/cli/__init__.py

@@ -1,6 +1,12 @@
 """
 CLI module for DataTransformer.
 """
-from .commands import clean, concat, dedupe, head, sample, stats, tail, transform
+from .commands import (
+    clean, concat, dedupe, diff, head, history, run,
+    sample, stats, tail, token_stats, transform
+)
 
-__all__ = ["sample", "head", "tail", "transform", "dedupe", "concat", "stats", "clean"]
+__all__ = [
+    "sample", "head", "tail", "transform", "dedupe", "concat",
+    "stats", "clean", "run", "token_stats", "diff", "history"
+]