mat — agent-first materials CLI

mat 是一个写给 AI agent 用的材料结构 CLI。它把构造、扰动、解释 2D 材料和催化界面所需的全部原子级操作，压缩到 1–4 个 token 的命令里，并且每次操作都自动产出 .png 渲染图 + .summary.md 摘要，方便多模态 agent 直接看图判断"这一步做对了没"。

设计灵感来自 GitHub gh：用 /resource verb 把长尾能力 RESTful 化，用顶层 command 表达高层意图，用 --json / --jq / -q 统一裁剪输出，避免污染 LLM 的 context。

---

30 秒上手

pip install -e .

mat init -q                              # 起一个 run 目录
mat build mos2 -q                        # 造一个 MoS2 单层
mat motifs                               # 看配位 motif
mat strain 2% -q                         # 施 2% 双轴应变
mat perturb vacancy=S:1 -q               # 抠掉 1 个 S 原子
mat                                      # 看当前 context + 下一步建议

每条会改/造结构的命令完成后，run 目录里自动多出三个文件：

runs/001-run/mos2.vasp           ← 结构
runs/001-run/mos2.png            ← 自动渲染
runs/001-run/mos2.summary.md     ← 摘要（formula / lattice / motifs / sites）

---

为什么是 agent-first

痛点（普通 CLI）	mat 的设计
命令爆炸，agent 要记 50+ 个子命令	顶层只 ~20 个高层命令 + /resource verb 路径覆盖长尾
输出动辄上千 token，污染 context	默认人类可读、--json --jq 精确裁剪
每个命令都要重传文件路径	隐式 context：上一步的输出自动是下一步的输入
操作完不知道做对没	每次自动出 .png 让多模态 agent 自检
没有可复现的日志	run 目录 + .summary.md 自动落盘

---

命令家族（一句话各自做什么）

命令	作用
mat	0 参数 = 当前 context 状态 + 下一步建议（像 git status）
mat init	起一个编号 run 目录
`mat build <kind	alias>`
mat get [file]	看结构信息（智能路由：file / mp-id / run-id 都行）
mat list <thing>	列资源（motifs / runs / recipes / ...）
mat motifs	列当前结构的配位 motif
mat sites	列当前结构的原子 (idx, element, cart, frac)
mat strain <spec>	对当前结构施应变（2% / a:1%,b:-0.5%）
mat vacuum <Å>	改 2D 真空层厚度
mat recenter	把 slab 重新居中
mat perturb <ops...>	复合编辑（vacancy / substitute / displace / shift / rotate / interlayer / strain / vacuum，可链式）
mat verify rules.yaml	按规则校验结构
mat explain profile.yaml	按 profile 解释结构
mat reproduce x.recipe.yaml	跑一篇论文的复现 recipe
mat materials	列内置 material 别名表
mat status	看当前 run 的进度

资源（长尾能力）：mat /<path> <verb>，5 个动词收敛：list / get / create / update / delete（recipes 多一个 run）。

mat /motifs list center=Mo ligand=S
mat /lattice update strain=2%
mat /sites update set=0=z:7.5
mat /vasp-inputs create profile=mp-relax-pbe
mat /mp/mp-2815 get

单字母缩写：/m /s /l /r /a /d /b /si /v /rec。

---

自动产物（写给 agent 看）

每个会写结构的命令完成后，CLI 在结构文件旁边生成 2 个附属文件：

文件	给谁看	内容
*.vasp	下游 DFT 计算	标准 POSCAR
*.png	多模态 agent / 人	3D 科学渲染（Blender 优先，自动回退 matplotlib），含原子球、键、晶胞线框
*.summary.md	文本 agent	formula / lattice / 2D slab+vacuum / motifs / sites 表

*.summary.md 长这样（示例为 mos2.summary.md）：

# mos2.vasp

*Produced by* `build.monolayer` *at* `2026-05-25 07:06:10`

![structure](mos2.png)

## Composition
- formula: **MoS2**
- sites: 3  (2 species)
- elements: Mo S

## Lattice
- a, b, c: `3.1600  3.1600  15.0000` Å
- angles : α=`90.00` β=`90.00` γ=`120.00`°
- volume : `129.7167` ų

## 2D layer (along c)
- slab z range: `[5.94, 9.06]` Å
- slab thickness: `3.12` Å
- vacuum (c − slab): `11.88` Å

## Motifs
- `SMo3_trigonal` × 2
- `MoS6_octahedral` × 1

## Sites (first 20) ...

CI / 批处理中关闭：export MAT_NO_ARTIFACTS=1。

渲染后端

PNG 渲染默认优先使用 Blender（publisher-grade 科学渲染：Eevee 引擎、emission-only 材质、正交投影、Jmol 元素配色）。若 Blender 不可用则自动回退 matplotlib。

安装 Blender（可选，强烈推荐）：

# macOS（推荐）
brew install --cask blender

# macOS（手动）
# 从 https://www.blender.org/download/ 下载 DMG，双击挂载后拖入 /Applications

# Linux
sudo snap install blender --classic

安装后运行一次配置脚本：

bash setup_blender.sh

该脚本自动检测 Blender 路径并写入 ~/.zshenv（MAT_BLENDER_BIN）。后续所有 mat 命令的 PNG 产物即自动使用 Blender 渲染。

---

文档

详细文档在 docs/site/（12 页，每页配示意图）：

1. Overview — 为什么是 agent-first
2. Quickstart — 5 分钟跑完一个完整流程
3. Implicit context — 一次设定全程跟随
4. Build — 8 种 builder + 9 种 material 别名
5. Motifs — 配位环境抽象 + connectivity graph
6. Lattice ops — strain / vacuum / recenter
7. Perturb — 缺陷、掺杂、错位、层间
8. Resource layer — 长尾能力的 RESTful 路径
9. Auto-artifacts — PNG + summary.md 机制
10. Agent recipes — 给 agent 的可复用调用模式
11. VASP inputs & paper recipes — 上游连接 DFT
12. Reference — 全部命令、资源、flag 速查
13. Complex gallery — 10 个真实复杂界面 / 表面 / 缺陷案例

---

安装

git clone <repo> vasp-cli
cd vasp-cli
python -m venv .venv && source .venv/bin/activate
pip install -e .
mat --help

依赖：Python ≥ 3.10、pymatgen、numpy、matplotlib（渲染图用）、PyYAML。

---

环境变量

变量	作用
MAT_STRUCTURE	强制覆盖"当前结构"（任何命令都优先用它）
MAT_RUN_DIR	覆盖"当前 run 目录"（auto-out 路径会落在这里）
MAT_NO_ARTIFACTS=1	跳过 PNG + summary.md 生成（CI 用）
MP_API_KEY	Materials Project API key（/mp 资源用）

---

License

nku-vasp-cli is dual-licensed:

• AGPL-3.0-or-later for academic, personal, research, non-profit, and open-source use — see LICENSE.
• Commercial license for closed-source / SaaS / proprietary integration — see COMMERCIAL.md or email aiden.novak.ai@gmail.com.

If you use nku-vasp-cli in any way (including AGPL community use), you must preserve the NOTICE file and the citation block below.

---

Citation

If nku-vasp-cli contributed to a paper, preprint, thesis, technical report, or any other published work, please cite it:

@software{novak2026nkuvaspcli,
  author       = {Novak, Aiden},
  title        = {nku-vasp-cli: agent-first materials CLI},
  year         = {2026},
  version      = {0.3.3},
  url          = {https://github.com/AidenNovak/nku-vasp-cli},
  note         = {Agent-first command-line tool for 2D materials and
                  catalytic interfaces with auto-rendered PNG / Markdown
                  artifacts for multimodal-agent self-verification.}
}

GitHub also surfaces a "Cite this repository" button driven by CITATION.cff — click it for APA / BibTeX / RIS exports.

---

Commercial use

The AGPL-3.0 license requires that any derivative work, including software offering nku-vasp-cli functionality over a network (SaaS), be released under the AGPL with full source available.

If that does not fit your business — e.g. you want to embed nku-vasp-cli in a closed-source product, internal commercial pipeline, or hosted service without open-sourcing your own code — please get a commercial license by emailing aiden.novak.ai@gmail.com with subject [nku-vasp-cli] commercial license inquiry. Details and what to include in the email: COMMERCIAL.md.