Metadata-Version: 2.4
Name: jx-react-agent
Version: 0.1.0
Summary: An extensible ReAct judge with native model tool calling.
License-Expression: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: harbor-rewardkit==0.2.0
Provides-Extra: documents
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1; extra == "documents"
Requires-Dist: openpyxl>=3.1; extra == "documents"
Requires-Dist: Pillow>=10; extra == "documents"
Requires-Dist: pymupdf>=1.24; extra == "documents"
Requires-Dist: python-docx>=1.1; extra == "documents"
Requires-Dist: python-pptx>=1.0; extra == "documents"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Provides-Extra: all
Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx]>=0.1; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: Pillow>=10; extra == "all"
Requires-Dist: pymupdf>=1.24; extra == "all"
Requires-Dist: python-docx>=1.1; extra == "all"
Requires-Dist: python-pptx>=1.0; extra == "all"
Requires-Dist: pytest>=8; extra == "all"

# JX ReAct Agent

一个轻量、可扩展的 ReAct judge。Agent 通过模型原生的 `tools/tool_calls`
检查工作目录，在收集证据后调用 `submit_score` 提交结构化评分。

它自带文本、图片、PDF、Word、PowerPoint 和 Excel 检查工具，也支持按任务加载
自定义 Python 工具。默认工具均为只读；shell 需要显式开启，不提供编辑工具。

模型或内部网关需要支持 Chat Completions 风格的 function tools。本项目不要求模型
支持 `response_format=json_schema`。

## 安装

安装包含文档读取能力的版本：

```bash
python3 -m pip install 'jx-react-agent[documents]'
```

只需要文本工具时可安装核心包：

```bash
python3 -m pip install jx-react-agent
```

## RewardKit 集成

安装后，常规 `rewardkit` 命令会直接识别 `judge = "react"`。Reward TOML 示例：

```toml
[judge]
judge = "react"
model = "openai/doubao-seed-2.1-turbo"
timeout = 300
mode = "batched"
```

运行方式不变：

```bash
rewardkit "$reward_dir" \
  --workspace "$workspace" \
  --output /logs/verifier/reward.json
```

模型由 LiteLLM 调用，`OPENAI_API_KEY`、`OPENAI_BASE_URL` 等标准环境变量继续
有效。也可以只为本 Agent 设置：

```bash
export REACT_JUDGE_API_KEY=...
export REACT_JUDGE_API_BASE=...
```

RewardKit 0.2.0 的 agent registry 只存在于当前进程，而且不会自动扫描第三方
agent entry points。这个 wheel 在 Python 的 site-packages 根目录安装
`jx_react_agent_autoload.pth`，新进程启动时执行：

```python
import rewardkit_react
rewardkit_react.install()
```

因此配置被解析前，`react` backend 已经注册，无需修改 RewardKit 源码或换用另一条
命令。`pip` 和 `rewardkit` 必须来自同一个 Python 环境。

## 随任务目录上传

如果不从 PyPI 安装，可以把整个目录上传后，在评分前运行一次 `entry_point.sh`：

```bash
REWARDKIT_PYTHON="$(command -v python3)"
REWARDKIT_PYTHON="$REWARDKIT_PYTHON" /tests/react-judge/entry_point.sh
rewardkit "$reward_dir" --workspace "$workspace"
```

bootstrap 会在指定的 Python 环境中构建、安装并验证注册。默认安装 `documents`
extra；远端镜像已经包含依赖或只检查文本时可关闭：

```bash
REACT_JUDGE_EXTRAS= \
  REWARDKIT_PYTHON="$REWARDKIT_PYTHON" \
  /tests/react-judge/entry_point.sh
```

`REACT_JUDGE_CACHE_DIR` 可调整安装缓存目录。源码、Python 解释器或 extras 变化时会
自动重新安装。

## 轨迹日志

每次 judge attempt 只保存一个轨迹文件。文件中的 `request` 是最后一轮发给模型的
完整请求，包含此前累积的 messages、tools 和图片 data URL/base64；`response` 是
这次请求对应的最终 assistant 响应，包含 `submit_score` tool call 和评分参数；
`events` 记录模型 tool call、工具 observation 和最终提交。这样可以直接查看完整
请求及最终答案，又不会重复保存每一轮请求或图片。API key 和 Authorization 凭证
不会写入文件。

默认目录为：

```text
/logs/verifier/judge_agents_trajs
```

文件名形如 `trajectory.react.batched-1.<uuid>.json`，路径也会写入 RewardKit 的
`reward-details.json`。可用环境变量覆盖目录：

```bash
export REACT_JUDGE_LOG_DIR=/custom/judge/trajs
```

## 内置工具

默认暴露以下工具：

- `view`：查看两层目录或带行号的文本文件窗口。
- `list_files`：按指定深度列出文件和大小。
- `search_files`：在文本文件中搜索并返回文件名、行号和匹配行。
- `inspect_file`：读取文本、图片、PDF、DOCX、PPTX 和 XLSX。
- `render_document`：把 PDF 页面转成图片；安装 LibreOffice 后也能渲染
  PPT/PPTX/DOC/DOCX。
- `submit_score`：根据本次评分 schema 动态生成，用于提交最终结果。

图片会作为真正的 `image_url` content block 送入下一轮模型消息。

`shell` 已内置但默认关闭。需要运行测试或其他命令时显式开启：

```bash
export REACT_JUDGE_TOOLS=view,list_files,search_files,inspect_file,render_document,shell
```

也可以在默认工具基础上开启：

```bash
export REACT_JUDGE_ENABLE_SHELL=1
```

常用限制：

```bash
export REACT_JUDGE_MAX_STEPS=20
export REACT_JUDGE_MAX_TOOL_CHARS=40000
export REACT_JUDGE_MAX_IMAGE_BYTES=8388608
```

## 自定义工具

工具继承公开的 `Tool` 类：

```python
from typing import Any

from rewardkit_react.tool import Tool, ToolContext, ToolResult


class CountFiles(Tool):
    name = "count_files"
    description = "Count files in a workspace directory."
    parameters = {
        "type": "object",
        "properties": {"path": {"type": "string", "default": "."}},
        "additionalProperties": False,
    }

    async def execute(
        self, arguments: dict[str, Any], context: ToolContext
    ) -> ToolResult:
        path = context.resolve_workspace_path(arguments.get("path", "."))
        count = sum(child.is_file() for child in path.rglob("*"))
        return ToolResult(text=str(count), metadata={"count": count})


TOOLS = [CountFiles()]
```

任务本地工具可以直接从文件加载，无需重新构建主包：

```bash
export REACT_JUDGE_TOOL_MODULES=/tests/tools/count_files.py
rewardkit /tests/rewards/t1 --workspace /workspace
```

工具模块可以提供 `TOOLS`、`get_tools()` 或 `register_tools(registry)`。多个路径使用
系统 path separator 或逗号分隔。

可复用工具也可以发布为单独的 wheel：

```toml
[project.entry-points."rewardkit_react.tools"]
count_files = "my_rewardkit_tools:CountFiles"
```

Agent 启动时会通过 `importlib.metadata.entry_points()` 自动加载这个分组。

## 文档依赖

Python extra 可以安装 PyMuPDF、Pillow、python-pptx 等依赖，但无法安装
LibreOffice。需要把 PPTX/DOCX 渲染成图片时，应在运行环境中安装 LibreOffice。
只提取文字和结构时，`python-pptx` 与 `python-docx` 已经足够。

本地构建和测试：

```bash
python3 -m pytest
python3 -m build
python3 -m pip install 'dist/jx_react_agent-0.1.0-py3-none-any.whl[documents]'
```
