Metadata-Version: 2.4
Name: pyruns
Version: 0.0.7
Summary: Lightweight web UI for managing, running, and monitoring Python experiments.
Author-email: LthreeC <lanshiL3C@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Pyruns Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Keywords: experiment-management,hyperparameter-tuning,task-runner,monitoring,nicegui,machine-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nicegui>=1.4
Requires-Dist: pyyaml>=5.4
Requires-Dist: psutil>=5.9
Dynamic: license-file

# Pyruns — Python 实验管理与监控 Web UI

**[English](README-en.md) | 简体中文**

<p align="center">
  <img src="https://img.shields.io/pypi/v/pyruns.svg" alt="PyPI version">
  <img src="https://img.shields.io/pypi/pyversions/pyruns.svg" alt="Python Versions">
  <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License">
</p>

<p align="center">
  <b>🧪 一个极简、轻量级且强大的 Web UI，用于管理、批量运行和监控你的 Python 实验。</b><br>
  <i>无需繁琐的配置，即插即用，让机器学习和科学计算的调参过程优雅而高效。</i>
</p>


---

## 📦 安装

```bash
pip install pyruns
```

**运行要求:** Python ≥ 3.8  
**依赖项:** *NiceGUI, PyYAML, psutil*

---

## 🚀 快速开始

- 模式1：无需修改现有代码！Pyruns 开箱即用，自动兼容你的 `argparse` 脚本；

- 模式2：自行写一个config.yaml对应pyruns.load来实现加载参数、

### CLI 命令用法

```bash
# 模式 1：零配置启动 (自动解析您的 Argparse 脚本构建 UI)
pyr train.py

# 模式 2：导入自定义 YAML 配置启动 (将 YAML 作为本脚本的配置基础)
pyr train.py my_config.yaml

# 辅助命令
pyr help
pyr version
```

---

## ✨ 核心功能与界面演示

我们在 `examples/` 目录下提供了简单易懂的教程。Pyruns 通过三个核心页面为您管理实验生命周期。

### 1. Generator: 参数配置与批量生成

解析 YAML 配置或 `argparse`，并在结构化表单中优雅地编辑超参数。使用强大的**批量生成语法**瞬间创建数百个实验配置！

![Generator UI - 展示参数表单和批量语法](docs/assets/批量生成任务参数.png)

**基础用法：自动解析 Argparse（无需修改代码）**
参考 `examples/1_argparse_script/main.py`。Pyruns 会自动读取你的 `argparse` 定义，并为你构建 Generator 表单界面。
> 💡 **提示**: 当你同时定义了短参数和长参数（如 `-b, --batch_size`）时，Pyruns 会优先使用长参数名作为变量！

### 2. Manager: 任务网格与并行控制

以清晰的卡片网格形式展现所有生成的任务。按状态过滤，按名称搜索，一键选中目标任务，并利用后台工作进程池实现**多实验并行运行**！

![Manager UI - 展示任务网格与卡片](docs/assets/任务卡片页面3.png)

可查看任务详情配置：

![Manager UI - 展示任务详情配置](docs/assets/任务详情task.png)

![Manager UI - 展示任务详情配置](docs/assets/任务详情config.png)

![Manager UI - 展示任务详情配置](docs/assets/任务详情notes.png)

![Manager UI - 展示任务详情配置](docs/assets/任务详情env.png)

### 3. Monitor: 实时日志与指标记录

点击任意运行中的任务，即可在浏览器直接查看像 VSCode 终端一样的**实时 ANSI 彩色日志**！
此外，在代码中调用 `pyruns.add_monitor()` 即可记录训练指标，实验结束后支持一键导出 CSV 报告。

![Monitor UI - 展示彩色终端和指标导出](docs/assets/日志监测2.png)

**进阶用法：记录任务的最终指标**
参考 `examples/3_metrics_logging/train.py`。只需在训练结束后添加一行代码：

```python
import pyruns

# 训练过程...
loss, accuracy = 0.2, 0.95

# 记录当前运行(Run)的最终指标，便于在 UI 批量导出 CSV/JSON 报告
pyruns.add_monitor(loss=loss, accuracy=accuracy)
```

---

## 📋 进阶：批量生成语法

你可以直接在 Generator 表单中快速排队成百上千的交叉实验。

![]()

**笛卡尔积 (Product) `|`**  
生成 $3 \times 2 = 6$ 种组合。
```yaml
learning_rate: 0.001 | 0.01 | 0.1
batch_size: 32 | 64
```

**配对组合 (Zip) `(|)`**  
必须长度一致，这会精确生成 3 种组合。
```yaml
seed: (1 | 2 | 3)
experiment_name: (exp_a | exp_b | exp_c)
```

---

## ⚙️ 工作区配置 `_pyruns_`

启动时，`pyr train.py` 会自动与您的脚本同级目录下创建一个 `_pyruns_` 统一工作区文件夹。
所有 UI 核心设置共享于 `_pyruns_/_pyruns_settings.yaml`，而每个脚本都会拥有自己独立的子命名空间（如 `_pyruns_/train/config_default.yaml` 与 `_pyruns_/train/tasks/`），彻底杜绝多脚本配置冲突！

![]()

您还可以通过 CLI 显式导入自己的 YAML 作为初始配置：
```bash
# 自动复制 my_config.yaml 至 _pyruns_/train/config_default.yaml
pyr train.py my_config.yaml
```

您可以编辑设置（`_pyruns_/_pyruns_settings.yaml`）来深度定制您的 UI 交互体验：
```yaml
ui_port: 8099                      # Web UI 服务端口号
generator_form_columns: 2          # Generator 参数表单默认列数
manager_max_workers: 4             # Manager 页面并行执行允许的最大 Worker 数
manager_execution_mode: thread     # 运行模式: 线程 (thread) 或 进程 (process)
log_enabled: false                 # 是否启用文件日志
```

---

## 📚 详细文档 (Documentation)

想要发掘 Pyruns 的全部潜力？请查阅我们的官方文档：

- 🚀 [安装与快速开始](docs/getting-started.md) — 5 分钟上手指南
- ⚙️ [配置详解](docs/configuration.md) — 理解 `_pyruns_` 结构与工作区设置
- 🧪 [批量生成语法](docs/batch-syntax.md) — Product / Zip 语法详解
- 🖥️ [UI 操作指南](docs/ui-guide.md) — 掌握三大核心页面的所有细节
- 🛠️ [API 参考](docs/api-reference.md) — 在脚本内深度集成 `pyruns`
- 📐 [架构设计](docs/architecture.md) — 了解底层原理（适用于开发者）

---

## 📄 License
MIT License.
