Metadata-Version: 2.4
Name: batch-swallow
Version: 0.1.0
Summary: 批量推理 JSONL 文件生成工具，快速构建阿里云批量推理请求，支持 API 调用和 CLI 命令行。
Author-email: Chandler <275737875@qq.com>
License-Expression: MIT
Keywords: batch,swallow,jsonl,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0

# batch-swallow

批量推理 JSONL 文件生成工具 —— 快速构建阿里云批量推理请求。

同时支持作为 **Python 库导入** 和 **命令行工具（CLI）** 两种方式使用。

---

## 安装

```bash
pip install batch-swallow
```

或从源码安装：

```bash
git clone https://github.com/your-username/batch-swallow.git
cd batch-swallow
pip install -e .
```

---

## 作为 Python 库使用

### 生成 Prompt

```python
from batch_swallow import generate_prompt, generate_prompt_safe

# 标准模式
prompt = generate_prompt("你好，{user}！今天天气{weather}。", user="小明", weather="晴朗")
print(prompt)  # 你好，小明！今天天气晴朗。

# 安全模式：缺失占位符不会抛出异常
prompt = generate_prompt_safe("Hello, {name}! You are {age} years old.", name="Alice")
print(prompt)  # Hello, Alice! You are  years old.
```

### 构造批量请求并生成 JSONL

```python
from batch_swallow import generate_requests_data, generate_batch_jsonl

# 1. 构造请求数据
questions = ["什么是人工智能？", "What is 2+2?"]
requests_data = generate_requests_data(
    questions,
    system_prompt="You are a helpful assistant."
)

# 2. 生成 JSONL 文件
jsonl_str = generate_batch_jsonl(
    requests=requests_data,
    model="qwen-max",
    output_file="batch.jsonl",
    enable_thinking=False,
)

print(f"已生成 {len(jsonl_str.splitlines())} 条请求")
```

### 高级用法：自定义消息模板

```python
from batch_swallow import generate_requests_data, generate_batch_jsonl

# 多轮对话场景
template = [
    {"role": "system", "content": "你是一个翻译助手。"},
    {"role": "user", "content": "请翻译：你好"},
    {"role": "assistant", "content": "Hello"},
    {"role": "user", "content": "请翻译：再见"},
]
requests_data = generate_requests_data(
    questions=["placeholder"],  # 占位，数量由 questions 长度决定
    message_template=template,
)

jsonl_str = generate_batch_jsonl(requests_data, model="qwen-max", output_file="multi-turn.jsonl")
```

---

## 命令行工具（CLI）

安装后可直接在终端使用 `batch-swallow` 命令。

### 查看帮助

```bash
batch-swallow --help
```

### 生成 JSONL 文件

首先准备输入文件 `questions.json`：

```json
{
  "questions": [
    "什么是人工智能？",
    "What is the capital of France?",
    "请用 Python 实现快速排序"
  ]
}
```

然后运行：

```bash
batch-swallow generate-jsonl \
  --input questions.json \
  --model qwen-max \
  --output batch.jsonl \
  --system-prompt "You are a helpful assistant."
```

支持开启思考模式：

```bash
batch-swallow generate-jsonl \
  --input questions.json \
  --model qwen-max \
  --output batch.jsonl \
  --enable-thinking \
  --thinking-budget 1024
```

输入文件也支持直接传入请求列表格式：

```json
[
  {"messages": [{"role": "user", "content": "你好"}]},
  {"messages": [{"role": "user", "content": "再见"}]}
]
```

### 生成 Prompt

```bash
batch-swallow generate-prompt \
  --template "请翻译以下内容为{lang}：{text}" \
  -p lang=英文 \
  -p text=你好世界
```

使用安全模式（缺失占位符替换为空字符串）：

```bash
batch-swallow generate-prompt \
  --template "Hello, {name}! Age: {age}" \
  -p name=Alice \
  --safe
```

---

## API 参考

| 函数 | 说明 |
|---|---|
| `generate_prompt(template, **kwargs)` | 根据模板生成 prompt，缺失占位符抛出异常 |
| `generate_prompt_safe(template, default, **kwargs)` | 安全版本，缺失占位符使用默认值 |
| `render_template(template, context)` | 使用字典上下文渲染模板 |
| `generate_requests_data(questions, system_prompt, message_template)` | 构造批量推理请求数据 |
| `generate_batch_jsonl(requests, model, output_file, ...)` | 生成 JSONL 格式文件 |

### 异常类

| 异常 | 说明 |
|---|---|
| `BatchInferenceError` | 模块基础异常 |
| `ValidationError` | 参数校验失败 |

---

## 许可证

MIT License
