Metadata-Version: 2.4
Name: rexprun
Version: 0.2.2
Summary: Research experiment orchestration with resource-aware scheduling, isolated environments, checkpoint recovery, and Ray Tune searches on GPUs and Ascend NPUs.
Author: REXP contributors
License: MIT
Keywords: research,experiment,scheduler,mcp,agent,dlm
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: pydantic>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: mcp<2,>=1.0
Requires-Dist: packaging>=24
Provides-Extra: tune
Requires-Dist: ray[tune]<3,>=2.40; extra == "tune"
Requires-Dist: optuna<5,>=4; extra == "tune"
Provides-Extra: research
Requires-Dist: numpy; extra == "research"
Requires-Dist: torch; extra == "research"
Requires-Dist: transformers; extra == "research"
Requires-Dist: accelerate; extra == "research"
Requires-Dist: datasets; extra == "research"
Requires-Dist: huggingface_hub; extra == "research"
Requires-Dist: safetensors; extra == "research"
Requires-Dist: einops; extra == "research"
Requires-Dist: tqdm; extra == "research"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Research Experiment Platform (REXP)

REXP（发行包 rexprun）是面向科研实验的调度与管理平台，提供资源排队、独立环境、断点恢复、评测分析和 Ray Tune 参数搜索，支持 NVIDIA GPU 与昇腾 NPU。实验脚本、日志和结果集中保存在用户指定的数据根目录，可通过终端、Agent 或 Web 使用。

## SSH 与 Agent 接入

[Handfree SSH MCP](https://github.com/Ironboxplus/handfree-ssh-mcp) 选择目标主机，REXP 插件通过同一条 SSH 连接调用该主机的 `rexp`，通过 SFTP 上传项目和取回结果。插件中的 `platformRoot` 是固定的数据根目录，`rexpPath` 是该主机的 `rexp` 程序位置；没有独立的 REXP 客户端包或 `rexp client` 命令。多台 SSH 主机沿用 Handfree 的 `connectionName`，各主机的路径保存在私人插件 registry 的 `connections.<SSH别名>` 中。

详见 SSH MCP 接入说明 和 Agent 接入指南。

## 被控端安装

```bash
pip install rexprun
rexp init --root /绝对路径/平台根目录
rexp doctor
rexp node env list
```

`pip install` 注册全局 `rexp` 命令。初始化会绑定环境管理器，准备独立的平台运行环境与轻量 `default` 实验环境。已有 uv/Conda 时优先 uv；都没有则询问是否安装，拒绝安装时使用 Python venv。平台无需 PyTorch；GPU/NPU 实验使用单独登记的兼容环境。

```bash
# 无交互并明确允许安装 uv（仅在缺失时安装）
rexp init --root /绝对路径/平台根目录 --install-manager uv --yes
# 不安装管理器，使用已有 Python 的 venv
rexp init --root /绝对路径/平台根目录 --env-manager venv --yes
# 按绑定管理器创建并登记实验环境
rexp node env create py311 --python 3.11 --description "实验基线环境，依赖按项目要求安装"
```

环境统一存放在 `<根目录>/env/`，平台为 `platform`，默认分析环境为 `default`。venv 的 `--python` 需要已安装解释器，uv/Conda 可指定 Python 版本。先检查已有环境是否可复用，再创建新环境。升级已有平台不需要重新初始化；使用 `rexp doctor --json` 返回的平台 Python 执行 `-m pip install --upgrade rexprun`。

## 运行实验

```bash
rexp project create demo --version v1
rexp submit demo v1 --config /绝对路径/平台根目录/research/demo/v1/configs/smoke.yaml
rexp start                           # 前台运行调度器
rexp status
rexp queue
rexp runs
rexp run show run_001
rexp run logs run_001
rexp run eval run_001
rexp run analyze run_001
```

控制端通过通用 `plugin-list` / `plugin-activate` / `plugin-skill` 发现插件并获取当前版本说明，
然后用 `plugin-run` 执行 rexp 命令（args 不含 rexp）。上传项目和取回结果使用 SSH MCP 原有
SFTP 工具；传输前先查询平台事实，确认固定根目录。

## 服务端接口

- `rexp`：被控端本地命令，Handfree 插件通过 SSH 调用。
- `rexp mcp`：服务端本机的原生 MCP stdio 接口。

完整命令见 使用说明书，配置与数据结构见 架构 和 Schema。

## 昇腾 NPU（普通实验已通过 A3 真卡验证）

支持读取 Linux `npu-smi` 整卡拓扑、检查实验环境的 `torch_npu` 能力，并按运行时逻辑卡号分卡。
实验配置增加 `resources.accelerator_backend: npu`；原 `gpu_count` / `min_vram_gb`
字段在 NPU 节点代表逻辑设备数量 / 每个逻辑设备的 HBM，保留名称以兼容已有配置。
一张 A3 物理卡可暴露两个逻辑设备，硬件摘要区分物理卡数与逻辑设备数，不把它们计作两张物理卡。
平台不自动安装驱动、CANN 或转换 CUDA 实验代码。实验自身需兼容昇腾 PyTorch。

用 `rexp project create ascend_check --version v1 --template ascend_smoke` 创建不下载模型的
真卡数值测试；详见生成项目的 README。已在 A3 / TorchNPU 2.10.0 真机通过矩阵乘法、反向传播、双逻辑设备隔离与排队自动续跑测试；尚未验证大模型。

## 可选 Ray Tune 搜索

支持用一个平台 run 管理一轮参数搜索，父任务预留资源，内部 trial 分别运行。
`rexp project create search_demo --template ray_tune` 获取 CPU 示例，实验环境需安装 `rexprun[tune]`。
通过普通 `rexp submit` 提交，`rexp tune list` / `rexp tune show run_XXX` 查看结果。
支持 Random/Grid、Optuna TPE、FIFO/ASHA 与多目标 Pareto；支持 CPU、CUDA 与昇腾 NPU 参数搜索。
完整预算、显卡分配、暂停恢复与存储约定见 使用说明书 的 Ray Tune 章节。

## CLI 命名（0.1.66 起）

全局入口统一为 `rexp`；源码目录或指定解释器也可使用 `python -m rexp`。
按下方步骤迁移后只提供新入口，不再提供旧命令别名。发行包名为 `rexprun`，Python 导入名仍为 `rexp`。
SSH 插件使用 `rexpPath` 指向 Linux/macOS 的 `bin/rexp` 或 Windows 的 `Scripts/rexp.exe`。
修改命令名不改变平台根目录、`~/.rexp` 配置、环境注册或实验记录。

## 从旧测试包迁移

正式发行包名为 `rexprun`；`rexp-server` 是旧 TestPyPI 包。两者提供同一个 `rexp` Python 模块，
不要在同一环境中同时保留。正式包发布后，在平台所用 Python 环境先下载新版，再卸载旧包并安装：

```bash
python -m pip download --no-deps --dest /已确认的安装包目录 'rexprun==0.1.66'
python -m pip uninstall rexp-server
python -m pip install /已确认的安装包目录/rexprun-0.1.66-py3-none-any.whl
rexp version
```

迁移前确认实验与调度器已停止；保留原平台根目录和实验环境，无需重新初始化。


### Ray Tune 的昇腾设备约定（0.1.68）

`resources.accelerator_backend: npu` 指定昇腾，`resources.gpu_count` 是搜索池逻辑设备数，
`tune.gpus_per_trial` 是每个尝试的逻辑 NPU 数；名称保留兼容。A3 的 1 张物理卡可能提供两个逻辑设备。
`rexp project create npu_search --template ray_tune_npu` 提供真实 NPU 运算与梯度校验示例，实验环境需有兼容的 TorchNPU/CANN 和 `rexprun[tune]`。
控制器不预占卡；trial 在用户模块导入前领取租约，按 `ASCEND_RT_VISIBLE_DEVICES` 隔离，使用本进程可见的 `npu:0`，不写物理卡号。
不得覆盖容器 `ASCEND_VISIBLE_DEVICES`。控制器保留宿主允许的范围，禁用 Ray 对 NPU mask 的自动覆盖；私有 Ray runtime 的 GPU/NPU 资源均为 0，实际卡归平台队列管理，不使用 `ray.get_gpu_ids()` 判断分配。
`config['_rexp']` 提供 `accelerator_backend` 与 `allocated_device_ids`；轻量 runtime 快照的 `visible_devices` 随后端记录对应 mask。
CPU/CUDA/NPU 共用优先级、动态让位、资源释放与暂停恢复；不抢占正在执行的尝试。模型续算必须保存原生 Ray checkpoint，频率按计算代价决定。
`tune list --json` 的 `accelerator_backends` 列出当前插件支持的后端，网页用它判断 NPU 搜索能力；旧节点不因网页升级而被误认为已支持。
