Skip to content

Commit 8de7252

Browse files
JihaoXinclaude
JihaoXin
and
claude
committed
Add CLI conda env support and update docs for v0.2 features
ark run now auto-detects per-project conda env (matching webapp behavior). Update all three READMEs with: 4-step research pipeline, skills system, environment isolation, anti-simulation enforcement, human intervention protocol, rich Telegram notifications, and phase badges in web portal. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent d6660f6 commit 8de7252

File tree

4 files changed

+152
-25
lines changed

4 files changed

+152
-25
lines changed

‎README.md‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
<a href="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml"><img src="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
1919
<img src="https://img.shields.io/badge/agents-8-orange.svg" alt="8 Agents">
2020
<img src="https://img.shields.io/badge/venues-11+-purple.svg" alt="11+ Venues">
21-
<img src="https://img.shields.io/badge/tests-106-brightgreen.svg" alt="106 Tests">
21+
<img src="https://img.shields.io/badge/tests-115-brightgreen.svg" alt="115 Tests">
2222
</p>
2323

2424
<p align="center">
@@ -59,7 +59,7 @@ ARK runs three phases in sequence. The Review phase loops until the paper reache
5959

6060
| Phase | What Happens |
6161
|:------|:-------------|
62-
| **Research** | Gemini Deep Research runs a literature survey and gathers background knowledge |
62+
| **Research** | 4-step pipeline: Deep Research &rarr; Initializer (bootstrap env &amp; citations) &rarr; Planner &rarr; Experimenter |
6363
| **Dev** | Iterative experiment cycle: plan &rarr; run on Slurm &rarr; analyze &rarr; write initial draft |
6464
| **Review** | Compile &rarr; Review &rarr; Plan &rarr; Execute &rarr; Validate, repeating until score &ge; threshold |
6565

@@ -110,6 +110,40 @@ The loop repeats until the score reaches the acceptance threshold &mdash; or you
110110
| **Formatting** | Broken layouts, LaTeX errors, manual cleanup | Hard-coded LaTeX + venue templates (NeurIPS, ACL, IEEE&hellip;) |
111111
| **Citations** | LLMs fabricate plausible-looking references | Every citation verified against DBLP &mdash; no fake references |
112112
| **Figures** | Default styles, wrong sizes, no page awareness | Nano Banana + venue-aware canvas, column widths, and fonts |
113+
| **Isolation** | Shared env &mdash; projects interfere with each other | Per-project conda env, sandboxed HOME, full multi-tenant isolation |
114+
| **Integrity** | LLMs simulate results instead of running real experiments | Anti-simulation prompts + builtin skills enforce real execution |
115+
116+
---
117+
118+
## Environment Isolation
119+
120+
Each project runs in its own **per-project conda environment**, cloned from a base env at project creation. This ensures full multi-tenant isolation:
121+
122+
- **Sandboxed Python** &mdash; per-project `.env/` directory with its own packages
123+
- **Isolated HOME** &mdash; each orchestrator runs with `HOME` set to the project directory
124+
- **No cross-contamination** &mdash; `PYTHONNOUSERSITE=1` prevents leaking user-site packages
125+
- **Automatic provisioning** &mdash; `ark run` and the Web Portal detect and use the project conda env; the pipeline bootstraps it if missing
126+
127+
```bash
128+
# The conda env is created automatically on first run.
129+
# ark run will detect and use it:
130+
ark run myproject
131+
# Conda env: /path/to/projects/myproject/.env
132+
```
133+
134+
## Skills System
135+
136+
ARK ships with **builtin skills** &mdash; modular instruction sets that agents load at runtime to enforce best practices:
137+
138+
| Skill | Purpose |
139+
|:------|:--------|
140+
| **research-integrity** | Anti-simulation prompts: agents must run real experiments, not fabricate outputs |
141+
| **human-intervention** | Escalation protocol: agents pause and ask via Telegram before irreversible actions |
142+
| **env-isolation** | Enforces per-project environment boundaries |
143+
| **figure-integrity** | Validates figure content matches data; prevents placeholder or hallucinated plots |
144+
| **page-adjustment** | Maintains page limits by adjusting content density, not deleting sections |
145+
146+
Skills live in `skills/builtin/` and are auto-installed during pipeline bootstrap.
113147

114148
---
115149

@@ -149,7 +183,7 @@ ARK parses the PDF with PyMuPDF + Claude Haiku, pre-fills the wizard, and kicks
149183
| Command | Description |
150184
|:--------|:------------|
151185
| `ark new <name>` | Create project via interactive wizard |
152-
| `ark run <name>` | Launch the autonomous pipeline |
186+
| `ark run <name>` | Launch the pipeline (auto-detects per-project conda env) |
153187
| `ark status [name]` | Score, iteration, phase, cost |
154188
| `ark monitor <name>` | Live dashboard: agent activity, score trend |
155189
| `ark update <name>` | Inject a mid-run instruction |
@@ -167,7 +201,7 @@ ARK parses the PDF with PyMuPDF + Claude Haiku, pre-fills the wizard, and kicks
167201

168202
## Web Portal
169203

170-
ARK includes a web-based portal for managing projects, viewing scores, and steering agents.
204+
ARK includes a web-based portal for managing projects, viewing scores, and steering agents. The portal shows **live phase badges** (Research / Dev / Review), per-project conda env status, and real-time cost tracking.
171205

172206
### Configuration
173207

@@ -220,10 +254,11 @@ ark setup-bot # one-time: paste BotFather token, auto-detect chat ID
220254
```
221255

222256
What you get:
223-
- **Live notifications** &mdash; score changes, phase transitions, errors
224-
- **Send instructions** &mdash; steer the current iteration
257+
- **Rich notifications** &mdash; formatted score changes, phase transitions, agent activity, and errors
258+
- **Send instructions** &mdash; steer the current iteration in real time
225259
- **Request PDFs** &mdash; latest compiled paper sent to chat
226-
- **Proactive confirmations** &mdash; ARK asks before key decisions
260+
- **Human intervention** &mdash; agents escalate decisions to you before irreversible actions
261+
- **HPC-friendly** &mdash; handles self-signed SSL certificates on enterprise/HPC networks
227262

228263
---
229264

‎README_ar.md‎

Lines changed: 43 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
<a href="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml"><img src="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
1919
<img src="https://img.shields.io/badge/agents-8-orange.svg" alt="8 وكلاء">
2020
<img src="https://img.shields.io/badge/venues-11+-purple.svg" alt="+11 مؤتمر">
21-
<img src="https://img.shields.io/badge/tests-106-brightgreen.svg" alt="106 اختبار">
21+
<img src="https://img.shields.io/badge/tests-115-brightgreen.svg" alt="115 اختبار">
2222
</p>
2323

2424
<p align="center">
@@ -59,8 +59,8 @@
5959

6060
| المرحلة | ما يحدث |
6161
|:--------|:--------|
62-
| **Research** | Gemini Deep Research يجمع المعرفة الخلفية والمسح الأدبي |
63-
| **Dev** | دورة تجارب تكرارية: تخطيط &rarr; تشغيل Slurm &rarr; تحليل &rarr; كتابة مسودة أولية |
62+
| **Research** | خط أنابيب من ٤ خطوات: Deep Research &rarr; المُهيّئ (تمهيد البيئة والاستشهادات) &rarr; المخطط &rarr; المُجرِّب |
63+
| **Dev** | دورة تجا��ب تكرارية: تخطيط &rarr; تشغيل Slurm &rarr; تحل��ل &rarr; كتابة مسودة أولية |
6464
| **Review** | تجميع &rarr; مراجعة &rarr; تخطيط &rarr; تنفيذ &rarr; تحقّق، تكرار حتى الدرجة &ge; العتبة |
6565

6666
### دورة المراجعة
@@ -110,6 +110,40 @@
110110
| **التنسيق** | تخطيطات مضطربة، أخطاء LaTeX، إصلاح يدوي | LaTeX مُبرمَج + قوالب مؤتمرات (NeurIPS، ACL، IEEE&hellip;) |
111111
| **الاستشهادات** | LLM يختلق مراجع تبدو معقولة لكنها غير موجودة | كل اقتباس يُتحقَّق عبر DBLP — لا مراجع وهمية |
112112
| **الأشكال** | أنماط افتراضية، أحجام خاطئة، لا مراعاة لقيود الصفحة | Nano Banana + أبعاد لوحة وعرض أعمدة وخطوط دقيقة |
113+
| **العزل** | بيئة مشتركة — المشاريع تتداخل مع بعضها | بيئة conda لكل مشروع، HOME معزول، عزل كامل متعدد المستأجرين |
114+
| **النزاهة** | LLM يحاكي النتائج بدلاً من تشغيل تجارب حقيقية | موجّهات مضادة للمحاكاة + مهارات مدمجة تفرض التنفيذ الحقيقي |
115+
116+
---
117+
118+
## عزل البيئات
119+
120+
يعمل كل مشروع في **بيئة conda مستقلة لكل مشروع**، مُستنسخة من بيئة أساسية عند الإنشاء. هذا يضمن عزلاً كاملاً متعدد المستأجرين:
121+
122+
- **Python معزول** &mdash; مجلد `.env/` لكل مشروع بحزمه الخاصة
123+
- **HOME معزول** &mdash; كل مُنسق يعمل بمجلد المشروع كـ HOME
124+
- **لا تلوث متبادل** &mdash; `PYTHONNOUSERSITE=1` يمنع تسرب حزم المستخدم
125+
- **توفير تلقائي** &mdash; `ark run` وبوابة الويب يكتشفان ويستخدمان بيئة conda للمشروع؛ خط الأنابيب يُنشئها تلقائياً عند الحاجة
126+
127+
```bash
128+
# بيئة conda تُنشأ تلقائياً عند أول تشغيل
129+
# ark run يكتشفها ويستخدمها:
130+
ark run myproject
131+
# Conda env: /path/to/projects/myproject/.env
132+
```
133+
134+
## نظام المهارات
135+
136+
يأتي ARK مع **مهارات مدمجة** &mdash; مجموعات تعليمات نمطية يحمّلها الوكلاء أثناء التشغيل لفرض أفضل الممارسات:
137+
138+
| المهارة | الغرض |
139+
|:--------|:-------|
140+
| **research-integrity** | موجّهات مضادة للمحاكاة: الوكلاء يجب أن يُجروا تجارب حقيقية لا أن يختلقوا نتائج |
141+
| **human-intervention** | بروتوكول التصعيد: الوكلاء يتوقفون ويسألون عبر Telegram قبل الإجراءات غير القابلة للعكس |
142+
| **env-isolation** | فرض حدود البيئة لكل مشروع |
143+
| **figure-integrity** | التحقق من تطابق محتوى الأشكال مع البيانات؛ منع الرسوم البيانية الوهمية |
144+
| **page-adjustment** | الحفاظ على حدود الصفحات بتعديل كثافة المحتوى لا بحذف الأقسام |
145+
146+
المهارات موجودة في `skills/builtin/` وتُثبّت تلقائياً أثناء مرحلة التمهيد.
113147

114148
---
115149

@@ -149,7 +183,7 @@ ark new mma --from-pdf proposal.pdf
149183
| الأمر | الوظيفة |
150184
|:------|:--------|
151185
| `ark new <name>` | إنشاء مشروع عبر معالج تفاعلي |
152-
| `ark run <name>` | بدء الـ pipeline المستقل |
186+
| `ark run <name>` | بدء الـ pipeline (يكتشف تلقائياً بيئة conda للمشروع) |
153187
| `ark status [name]` | التقييم، التكرار، المرحلة، التكلفة |
154188
| `ark monitor <name>` | لوحة مراقبة مباشرة: نشاط الوكلاء، اتجاه التقييم |
155189
| `ark update <name>` | إدخال تعليمات أثناء التشغيل |
@@ -167,7 +201,7 @@ ark new mma --from-pdf proposal.pdf
167201

168202
## بوابة الويب
169203

170-
يتضمن ARK بوابة ويب لإدارة المشاريع وعرض الدرجات وتوجيه الوكلاء.
204+
يتضمن ARK بوابة ويب لإدارة المشاريع وعرض الدرجات وتوجيه الوكلاء. تعرض البوابة **شارات مراحل مباشرة** (Research / Dev / Review)، حالة بيئة conda لكل مشروع، وتتبع التكلفة في الوقت الحقيقي.
171205

172206
### الإعدادات
173207

@@ -220,10 +254,11 @@ ark setup-bot # مرة واحدة: الصق رمز BotFather، كشف تلق
220254
```
221255

222256
ما تحصل عليه:
223-
- **إشعارات مباشرة** &mdash; تغيرات التقييم، انتقالات المراحل، الأخطاء
224-
- **إرسال تعليمات** &mdash; توجيه التكرار الحالي
257+
- **إشعارات غنية** &mdash; تغيرات التقييم المنسقة، انتقالات المراحل، نشاط الوكلاء، والأخطاء
258+
- **إرسال تعليمات** &mdash; توجيه التكرار الحالي في الوقت الحقيقي
225259
- **طلب PDF** &mdash; أحدث ورقة مترجمة تُرسل للمحادثة
226-
- **تأكيدات استباقية** &mdash; يسأل ARK قبل القرارات المهمة
260+
- **تدخل بشري** &mdash; الوكلاء يصعّدون القرارات إليك قبل الإجراءات غير القابلة للعكس
261+
- **متوافق مع HPC** &mdash; يدعم شهادات SSL الموقّعة ذاتياً على شبكات المؤسسات/HPC
227262

228263
---
229264

‎README_zh.md‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
<a href="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml"><img src="https://github.com/kaust-ark/ARK/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
1919
<img src="https://img.shields.io/badge/agents-8-orange.svg" alt="8 Agents">
2020
<img src="https://img.shields.io/badge/venues-11+-purple.svg" alt="11+ Venues">
21-
<img src="https://img.shields.io/badge/tests-106-brightgreen.svg" alt="106 Tests">
21+
<img src="https://img.shields.io/badge/tests-115-brightgreen.svg" alt="115 Tests">
2222
</p>
2323

2424
<p align="center">
@@ -59,7 +59,7 @@ ARK 按三个阶段依次执行。Review 阶段循环迭代直到论文达到目
5959

6060
| 阶段 | 执行内容 |
6161
|:------|:---------|
62-
| **Research** | Gemini Deep Research 文献调研与背景知识收集 |
62+
| **Research** | 4 步流水线：Deep Research &rarr; 初始化器（环境引导 &amp; 引用准备）&rarr; 规划器 &rarr; 实验者 |
6363
| **Dev** | 迭代实验循环：规划 &rarr; Slurm 运行 &rarr; 分析 &rarr; 撰写初稿 |
6464
| **Review** | 编译 &rarr; 审稿 &rarr; 规划 &rarr; 执行 &rarr; 验证，循环直到分数 &ge; 阈值 |
6565

@@ -110,6 +110,40 @@ ARK 按三个阶段依次执行。Review 阶段循环迭代直到论文达到目
110110
| **排版** | 布局混乱、LaTeX 报错、大量人工修复 | 硬编码 LaTeX + 会议模板（NeurIPS、ACL、IEEE……） |
111111
| **引用** | LLM 编造看似合理但不存在的引用 | 每条引用经 DBLP API 验证，杜绝虚假文献 |
112112
| **图表** | 默认样式、尺寸失控、无视页面约束 | Nano Banana + 会议画布尺寸、栏宽、字号精确匹配 |
113+
| **隔离** | 共享环境，项目之间互相干扰 | 每项目独立 conda 环境、沙盒 HOME、完全多租户隔离 |
114+
| **完整性** | LLM 模拟结果而非运行真实实验 | 反模拟提示 + 内置 Skills 强制真实执行 |
115+
116+
---
117+
118+
## 环境隔离
119+
120+
每个项目运行在独立的 **项目级 conda 环境** 中，在创建时从基础环境克隆。这确保了完全的多租户隔离：
121+
122+
- **沙盒 Python** &mdash; 每项目 `.env/` 目录，拥有独立的包
123+
- **隔离 HOME** &mdash; 每个 orchestrator 以项目目录作为 HOME 运行
124+
- **无交叉污染** &mdash; `PYTHONNOUSERSITE=1` 防止用户级包泄露
125+
- **自动配置** &mdash; `ark run` 和 Web 门户自动检测并使用项目 conda 环境；流水线在缺失时自动引导创建
126+
127+
```bash
128+
# conda 环境在首次运行时自动创建
129+
# ark run 会检测并使用它：
130+
ark run myproject
131+
# Conda env: /path/to/projects/myproject/.env
132+
```
133+
134+
## Skills 系统
135+
136+
ARK 内置 **builtin skills** &mdash; 模块化指令集，智能体在运行时加载以强制执行最佳实践：
137+
138+
| Skill | 用途 |
139+
|:------|:-----|
140+
| **research-integrity** | 反模拟提示：智能体必须运行真实实验，不得伪造输出 |
141+
| **human-intervention** | 升级协议：智能体在执行不可逆操作前通过 Telegram 暂停并请求确认 |
142+
| **env-isolation** | 强制项目级环境边界 |
143+
| **figure-integrity** | 验证图表内容与数据一致；防止占位或虚构的图表 |
144+
| **page-adjustment** | 通过调整内容密度维持页数限制，而非删除章节 |
145+
146+
Skills 位于 `skills/builtin/`，在流水线引导阶段自动安装。
113147

114148
---
115149

@@ -149,7 +183,7 @@ ARK 使用 PyMuPDF + Claude Haiku 解析 PDF，预填向导，从提取的规格
149183
| 命令 | 功能 |
150184
|:-----|:-----|
151185
| `ark new <name>` | 通过交互式向导创建项目 |
152-
| `ark run <name>` | 启动自主 pipeline |
186+
| `ark run <name>` | 启动 pipeline（自动检测项目级 conda 环境） |
153187
| `ark status [name]` | 分数、迭代、阶段、成本 |
154188
| `ark monitor <name>` | 实时仪表板：智能体活动、分数趋势 |
155189
| `ark update <name>` | 注入运行中指令 |
@@ -167,7 +201,7 @@ ARK 使用 PyMuPDF + Claude Haiku 解析 PDF，预填向导，从提取的规格
167201

168202
## Web 门户
169203

170-
ARK 提供基于 Web 的门户，用于管理项目、查看评分和控制智能体。
204+
ARK 提供基于 Web 的门户，用于管理项目、查看评分和控制智能体。门户展示 **实时阶段徽章**（Research / Dev / Review）、项目级 conda 环境状态和实时成本追踪。
171205

172206
### 配置
173207

@@ -220,10 +254,11 @@ ark setup-bot # 一次性配置：粘贴 BotFather token，自动检测 chat
220254
```
221255

222256
功能：
223-
- **实时通知** &mdash; 分数变化、阶段转换、错误报告
224-
- **发送指令** &mdash; 引导当前迭代方向
257+
- **富��本通知** &mdash; 格式化的分数变化、阶段转换、智能体活动和��误报告
258+
- **发送指令** &mdash; 实时引导当前迭代方向
225259
- **请求 PDF** &mdash; 获取最新编译论文
226-
- **主动确认** &mdash; 关键决策前主动询问
260+
- **人工干预** &mdash; 智能体在执行不可逆操作前向你请求确认
261+
- **HPC 友好** &mdash; 支持企业/HPC 网络的自签名 SSL ��书
227262

228263
---
229264

‎ark/cli.py‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1890,9 +1890,28 @@ def cmd_run(args):
18901890
except Exception:
18911891
pass
18921892

1893-
# Launch orchestrator in background
1894-
cmd = [
1895-
sys.executable, "-m", "ark.orchestrator",
1893+
# Launch orchestrator in background, preferring per-project conda env
1894+
try:
1895+
from ark.webapp.jobs import (
1896+
find_conda_binary, project_env_ready, project_env_prefix,
1897+
)
1898+
conda_bin = find_conda_binary()
1899+
if conda_bin and project_env_ready(project_dir):
1900+
python_prefix = [conda_bin, "run", "--no-capture-output",
1901+
"--prefix", str(project_env_prefix(project_dir)),
1902+
"python"]
1903+
print(f" Conda env: {project_env_prefix(project_dir)}")
1904+
elif conda_bin and config.get("conda_env"):
1905+
python_prefix = [conda_bin, "run", "--no-capture-output",
1906+
"-n", config["conda_env"], "python"]
1907+
print(f" Conda env: {config['conda_env']}")
1908+
else:
1909+
python_prefix = [sys.executable]
1910+
except ImportError:
1911+
python_prefix = [sys.executable]
1912+
1913+
cmd = python_prefix + [
1914+
"-m", "ark.orchestrator",
18961915
"--project", name,
18971916
"--mode", mode,
18981917
"--model", model,
@@ -1906,6 +1925,9 @@ def cmd_run(args):
19061925

19071926
# Strip CLAUDECODE so orchestrator can call claude CLI freely
19081927
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
1928+
# Ensure orchestrator can find the ark package in a project-local conda env
1929+
ark_root = str(Path(__file__).resolve().parents[1].parent)
1930+
env["PYTHONPATH"] = ark_root + ((":" + env["PYTHONPATH"]) if env.get("PYTHONPATH") else "")
19091931

19101932
with open(log_file, "w") as lf:
19111933
process = subprocess.Popen(

0 commit comments

Comments
 (0)
⚡