Metadata-Version: 2.4
Name: rexprun
Version: 0.1.67
Summary: Research Experiment Platform: a recoverable, reproducible experiment worker with SSH MCP integration.
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 是单节点、离线优先的实验 worker，负责项目、队列、调度、运行、检查点、评测、分析和结果存储。实验数据集中放在用户明确指定的 `PLATFORM_ROOT`。实验脚本由控制端准备，通过 SSH MCP 上传。

## 本分支：Handfree SSH MCP 控制端

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

详见 [SSH MCP 接入说明](docs/ssh-mcp-integration.md) 和 [Agent 接入指南](docs/agent-mcp.md)。

## 被控端安装

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

`pip install` 会在所选 Python 环境注册 `rexp` 指令。平台运行环境无需 PyTorch；实验使用的 Python、PyTorch 和 CUDA 由 `rexp node env` 登记与检测。GPU 实验在配置里写 `environment: py312` 等已登记的环境名。

## 运行实验

```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 接口。

完整命令见 [使用说明书](docs/使用说明书.md)，配置与数据结构见 [架构](docs/architecture.md) 和 [Schema](docs/schemas.md)。

## 昇腾 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 真机通过矩阵乘法、反向传播、双逻辑设备隔离与排队自动续跑测试；尚未验证大模型或 NPU Ray Tune。

## 可选 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；GPU 搜索当前仅 CUDA。
完整预算、显卡分配、暂停恢复与存储约定见 [使用说明书](docs/使用说明书.md) 的 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
```

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