jx-react-agent 0.1.0__tar.gz

jx_react_agent-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include src/jx_react_agent_autoload.pth

jx_react_agent-0.1.0/PKG-INFO

@@ -0,0 +1,231 @@
+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]'
+```

jx_react_agent-0.1.0/README.md

@@ -0,0 +1,205 @@
+# 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]'
+```

jx_react_agent-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "jx-react-agent"
+version = "0.1.0"
+description = "An extensible ReAct judge with native model tool calling."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "Apache-2.0"
+dependencies = [
+    "harbor-rewardkit==0.2.0",
+]
+
+[project.optional-dependencies]
+documents = [
+    "markitdown[pdf,docx,pptx,xlsx,xls]>=0.1",
+    "openpyxl>=3.1",
+    "Pillow>=10",
+    "pymupdf>=1.24",
+    "python-docx>=1.1",
+    "python-pptx>=1.0",
+]
+dev = [
+    "pytest>=8",
+]
+all = [
+    "markitdown[pdf,docx,pptx,xlsx,xls]>=0.1",
+    "openpyxl>=3.1",
+    "Pillow>=10",
+    "pymupdf>=1.24",
+    "python-docx>=1.1",
+    "python-pptx>=1.0",
+    "pytest>=8",
+]
+
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

jx_react_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jx_react_agent-0.1.0/setup.py

@@ -0,0 +1,17 @@
+"""Build hook that installs the Python startup registration file."""
+
+from pathlib import Path
+from shutil import copyfile
+
+from setuptools import setup
+from setuptools.command.build_py import build_py
+
+
+class BuildPyWithAutoload(build_py):
+    def run(self) -> None:
+        super().run()
+        source = Path(__file__).parent / "src" / "jx_react_agent_autoload.pth"
+        copyfile(source, Path(self.build_lib) / source.name)
+
+
+setup(cmdclass={"build_py": BuildPyWithAutoload})