Metadata-Version: 2.4
Name: pyruns
Version: 0.0.8
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

**[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>轻量级 Python 实验管理 Web UI —— 调参、批量运行、实时监控，一站式解决 🚀</b>
</p>

Pyruns 为你的 Python 脚本提供一个**开箱即用**的浏览器界面：自动解析 `argparse` 参数生成可视化表单，通过内置语法一键展开参数网格并批量生成任务，统一调度并行执行，在浏览器中实时追踪 ANSI 彩色日志，最后导出跨任务的指标报告。

**不需要改动任何业务代码。**

```bash
pip install pyruns
pyr train.py          # 就这一行
```

---

## ✨ 核心能力

| 能力 | 说明 |
|------|------|
| 🔌 **零侵入接入** | 自动解析 `argparse` 定义，渲染为 Web 表单。也支持直接导入 YAML/JSON 配置文件 |
| 🧮 **批量参数网格** | `lr: 0.001 \| 0.01 \| 0.1` 一行声明，自动展开笛卡尔积或配对组合，秒级生成数百任务 |
| ⚡ **并行调度执行** | 内置任务队列 + 线程/进程工作池，可控并发数，一键批量运行 |
| 📋 **任务全生命周期管理** | 卡片式看板：状态过滤、搜索、置顶、笔记、环境变量、参数快照、运行日志，一目了然 |
| 🖥️ **实时彩色终端** | 浏览器内流式查看 ANSI 着色日志（兼容 `tqdm`、`colorama`），增量推送零卡顿 |
| 📊 **指标采集与导出** | 脚本中调用 `pyruns.add_monitor(loss=0.23)` 记录关键指标，跨任务聚合导出 CSV/JSON 报告 |
| 💻 **系统资源面板** | 顶部实时显示 CPU / RAM / 多 GPU 利用率与显存 |
| 📁 **工作区隔离** | 按脚本名自动隔离（`_pyruns_/train/` vs `_pyruns_/test/`），互不干扰，软删除可恢复 |

---

## 🚀 快速开始

### 模式 1：Argparse 脚本（零配置）

无需修改你的代码。Pyruns 通过 AST 静态分析自动提取 `argparse` 参数并生成 UI。

```bash
pyr train.py
```

首次运行时，Pyruns 会在脚本同级目录下创建 `_pyruns_/train/config_default.yaml`（包含所有参数的默认值），并启动 Web UI。

### 模式 2：自定义 YAML 配置

对于使用 `config = pyruns.load()` 读取配置的脚本，首次运行时传入 YAML 文件：

```bash
pyr train.py my_config.yaml   # → 复制为 _pyruns_/train/config_default.yaml
```

之后直接运行即可，Pyruns 自动加载已保存的配置：

```bash
pyr train.py                   # → 自动读取 _pyruns_/train/config_default.yaml
```

> 再次传入新的 YAML 会覆盖旧模板。

```bash
pyr help      # CLI 帮助
pyr version   # 查看版本
```

---

## 🎯 功能概览

### 🔧 Generator — 参数配置与批量生成

加载参数模板，在结构化表单或 YAML 编辑器中调整参数。使用批量语法一次性生成参数搜索网格。

![Generator UI](docs/assets/multi_gen.png)

> 解析 `argparse` 时，若同时存在短参数和长参数（如 `-b, --batch_size`），自动采用长参数名作为配置键。

### 📦 Manager — 任务控制台

卡片网格展示所有任务。支持按状态过滤、模糊搜索、批量选中运行。点击卡片查看完整元数据：

![Manager UI](docs/assets/tab_manager.png)

| | |
|:---:|:---:|
| **任务信息总览**<br>![Task Details Info](docs/assets/taskinfo.png) | **配置快照查看**<br>![Task Details Config](docs/assets/config.png) |
| **实验笔记记录**<br>![Task Details Notes](docs/assets/notes.png) | **环境变量详情**<br>![Task Details Env](docs/assets/env.png) |

### 📈 Monitor — 实时日志与指标导出

浏览器内实时流式查看 ANSI 彩色终端输出。顶部面板持续展示 CPU / RAM / GPU 资源状态。

![Monitor UI](docs/assets/tab_monitor.png)

在脚本末尾调用 `pyruns.add_monitor()` 记录评估指标，跨任务聚合导出 CSV/JSON：

```python
pyruns.add_monitor(last_loss=last_loss)
```

![Export Report](docs/assets/export_report.png)

---

## 🧪 批量生成语法

在 Generator 页面中直接使用管道语法进行参数网格搜索。

![]()

**笛卡尔积 `|`** — 全排列组合（3 × 2 = 6 个任务）：
```yaml
learning_rate: 0.001 | 0.01 | 0.1
batch_size: 32 | 64
```

**配对组合 `(|)`** — 按位置一一对应（3 个任务）：
```yaml
seed: (1 | 2 | 3)
experiment_name: (exp_a | exp_b | exp_c)
```

两种语法可混合使用。详见 [批量语法指南](docs/batch-syntax.md)。

---

## 📂 工作区结构

首次运行 `pyr train.py` 时，自动创建以下结构：

```text
your_project/
├── train.py
└── _pyruns_/
    ├── _pyruns_settings.yaml      # 全局设置（端口、并发数、执行模式等）
    └── train/                     # 按脚本名隔离
        ├── config_default.yaml    # 参数模板（自动生成或导入）
        └── tasks/
            ├── my-exp-[1-of-6]/
            │   ├── task_info.json # 元数据（状态、时间、PID、笔记等）
            │   ├── config.yaml    # 本次运行的参数快照
            │   └── run_logs/
            │       └── run1.log   # 控制台输出
            └── .trash/            # 软删除（可恢复）
```

![]()

不同脚本完全隔离（`_pyruns_/train/` 与 `_pyruns_/test/` 互不影响）。

可通过 `_pyruns_settings.yaml` 自定义设置：

```yaml
ui_port: 8099                      # Web UI 端口
generator_form_columns: 2          # 表单列数
manager_max_workers: 4             # 最大并发数
manager_execution_mode: thread     # 执行模式: thread | process
log_enabled: false                 # 调试日志
```

---

## 📖 文档

| 文档 | 说明 |
|------|------|
| [📗 安装与快速开始](docs/getting-started.md) | 5 分钟上手完整工作流 |
| [📙 配置系统](docs/configuration.md) | `_pyruns_` 目录结构、配置优先级、类型推断 |
| [📘 批量语法](docs/batch-syntax.md) | 笛卡尔积 / 配对组合 / 嵌套参数展开 |
| [📕 界面操作](docs/ui-guide.md) | Generator、Manager、Monitor 三页面详细操作 |
| [📓 API 参考](docs/api-reference.md) | `read()` / `load()` / `add_monitor()` 及工具函数 |
| [📒 架构设计](docs/architecture.md) | 三层架构、数据流、调度机制（面向贡献者） |

---

## License

MIT
