agent-data-tools 0.1.0

Agent 训练数据的校验、转换与批处理工具。

agent-data-tools

一个面向 Agent 训练数据的 Python 包，提供三类核心能力：

• 校验 openai messages 中间格式
• 转换为 conversations 训练格式
• 转换为 swift messages 训练格式

这个仓库已经重构为标准的 src 布局，可以直接发布到 PyPI，也可以本地通过 pip install -e . 使用。

项目结构

agent_data_tools/
├── pyproject.toml
├── README.md
├── docs/
│   ├── architecture.md
│   ├── formats.md
│   └── templates.md
├── src/
│   └── agent_data_tools/
│       ├── __init__.py
│       ├── builtin_templates/
│       ├── cli.py
│       ├── converters.py
│       ├── models.py
│       ├── renderers.py
│       ├── schemas.py
│       ├── template_loader.py
│       ├── utils.py
│       ├── validators.py
│       └── py.typed
├── tests/
│   └── test_api.py
└── data_examples/

安装

pip install -e .

发布到 PyPI 后可直接：

pip install agent-data-tools

快速开始

1. 直接 import 调用

import json

from agent_data_tools import (
    convert_record_to_conversations,
    convert_record_to_swift_messages,
    resolve_template_specs,
    validate_openai_messages_record,
)

with open("data_examples/data_01_openai_format.jsonl", "r", encoding="utf-8") as f:
    sample = json.loads(f.readline())

result = validate_openai_messages_record(sample)
print(result.is_valid)

conv_record = convert_record_to_conversations(sample)
swift_record = convert_record_to_swift_messages(sample)

custom_templates = resolve_template_specs(
    [
        {
            "name": "my_template.jinja",
            "path": "./my_templates/qwen_like.jinja",
            "weight": 1,
        }
    ],
    use_builtin_templates=False,
)

custom_conv_record = convert_record_to_conversations(
    sample,
    template_specs=custom_templates,
    use_builtin_templates=False,
)

2. 批量转换

from agent_data_tools import batch_convert_from_meta

meta_path = batch_convert_from_meta(
    "datasets/meta.json",
    "outputs/conversations",
    target="conversations",
    max_workers=4,
    template_dir="./my_templates",
    use_builtin_templates=False,
)
print(meta_path)

3. 命令行使用

agent-data-tools validate-openai --data-list datasets/meta.json --log-dir logs
agent-data-tools convert-conversations --data-list datasets/meta.json --output-dir outputs/convs
agent-data-tools convert-swift-messages --data-list datasets/meta.json --output-dir outputs/messages
agent-data-tools convert-conversations --data-list datasets/meta.json --output-dir outputs/convs --template-dir ./my_templates --no-builtin-templates
agent-data-tools list-templates

公开 API

常用函数：

• validate_function_definition
• validate_openai_messages_record
• validate_openai_messages_file
• validate_meta_file
• convert_record_to_conversations
• convert_record_to_swift_messages
• convert_jsonl_file
• batch_convert_from_meta
• resolve_template_specs
• load_builtin_template_specs
• list_builtin_template_names

配置类：

• TemplateSpec：描述模板内容、来源与权重
• RenderConfig：保留给手动渲染扩展场景

结果对象：

• ValidationResult
• ConversionStats

设计原则

• 以 openai messages 作为统一中间格式
• 将“校验”“模板加载”“转换”“批处理”拆分为独立模块
• 默认内置模板开箱即用，同时允许用户传入自定义模板目录、模板文件或模板配置 JSON
• conversations 与 swift messages 共用同一套模板渲染入口

文档

• 结构设计：见 docs/architecture.md
• 数据格式说明：见 docs/formats.md
• 模板使用说明：见 docs/templates.md
• 发布与验收：见 docs/release.md

验证

推荐直接使用你的 Conda dev 环境进行验收：

conda run -n dev env PYTHONPATH=src python -m unittest tests/test_api.py
conda run -n dev env PYTHONPATH=src python -m agent_data_tools.cli list-templates
conda run -n dev env PYTHONPATH=src python -m agent_data_tools.cli --help

如果想快速做一次最小转换验证：

conda run -n dev env PYTHONPATH=src python - <<'PY'
import json
from pathlib import Path
from agent_data_tools import convert_record_to_conversations

sample = json.loads(Path('data_examples/data_01_openai_format.jsonl').read_text(encoding='utf-8').splitlines()[0])
result = convert_record_to_conversations(sample)
print('conversations' in result, len(result.get('conversations', [])))
PY

发布

构建分发包：

conda run -n dev python -m pip install build
conda run -n dev python -m build

上传前检查：

conda run -n dev python -m pip install twine
conda run -n dev python -m twine check dist/*

完整发布说明见 docs/release.md。