Metadata-Version: 2.4
Name: agent-data-tools
Version: 0.1.5
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

项目路径：[https://github.com/NairongZheng/agent_data_tools](https://github.com/NairongZheng/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
│       ├── 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
```

## 快速开始

### 使用 cli

```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-config ./templates.json
agent-data-tools list-templates
```

传入 `--template-config` 时，仅使用配置文件中的模板；未传时默认使用内置模板，其中默认实际生效的是 `qwen3.5_35ba3b_think_xml.jinja`。

### 使用代码

```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_config_path="./templates.json",
)
print(meta_path)
```

## 公开 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`
- `list_builtin_template_names`
- `resolve_template_specs`

结果对象：

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

## 验证

```bash
PYTHONPATH=src python -m unittest tests/test_api.py
PYTHONPATH=src python -m agent_data_tools.cli list-templates
PYTHONPATH=src python -m agent_data_tools.cli --help
```

## 发布

构建分发包：

```bash
python -m pip install build
python -m build
```

上传前检查：

```bash
python -m pip install twine
python -m twine check dist/*
```

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