Metadata-Version: 2.4
Name: agent-data-tools
Version: 0.1.0
Summary: Agent 训练数据的校验、转换与批处理工具。
Author: zhengnairong
License: MIT
Keywords: agent,dataset,openai,training-data,tool-calling
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: jinja2>=3.1.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: tqdm>=4.66.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# agent-data-tools

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

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

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

## 项目结构

```text
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/
```

## 安装

```bash
pip install -e .
```

发布到 PyPI 后可直接：

```bash
pip install agent-data-tools
```

## 快速开始

### 1. 直接 import 调用

```python
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. 批量转换

```python
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. 命令行使用

```bash
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/architecture.md)
- 数据格式说明：见 [docs/formats.md](docs/formats.md)
- 模板使用说明：见 [docs/templates.md](docs/templates.md)
- 发布与验收：见 [docs/release.md](docs/release.md)

## 验证

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

```bash
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
```

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

```bash
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
```

## 发布

构建分发包：

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

上传前检查：

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

完整发布说明见 [docs/release.md](docs/release.md)。
