Metadata-Version: 2.4
Name: nku-vasp-cli
Version: 0.3.3
Summary: Agent-first materials CLI. Build, edit and inspect 2D materials and catalytic interfaces with 1-4 token commands. Auto-renders PNG + Markdown summary after every operation for multimodal-agent self-verification.
Author-email: Aiden Novak <aiden.novak.ai@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/AidenNovak/nku-vasp-cli
Project-URL: Repository, https://github.com/AidenNovak/nku-vasp-cli
Project-URL: Issues, https://github.com/AidenNovak/nku-vasp-cli/issues
Project-URL: Documentation, https://github.com/AidenNovak/nku-vasp-cli/tree/main/docs/site
Keywords: agent,ai-cli,llm,2D materials,TMD,MoS2,bilayer,supercell,heterostructure,vasp,pymatgen,materials-project,motif,crystal-structure
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: pymatgen>=2024.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Requires-Dist: scipy>=1.10
Requires-Dist: ase>=3.22
Provides-Extra: docx
Requires-Dist: python-docx>=1.1; extra == "docx"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: python-docx>=1.1; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# 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 秒上手

```bash
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）
```

![mos2](docs/site/img/mos2.png)

---

## 为什么是 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>` | 造结构（`mos2 / graphene / hbn / bi / monolayer / bilayer / slab / ...`） |
| `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`）。

```bash
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 / 人 | VESTA 风格 3D 渲染，含 motif 多面体、cell box、元素图例 |
| `*.summary.md` | 文本 agent | formula / lattice / 2D slab+vacuum / motifs / sites 表 |

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

```markdown
# 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`。

---

## 文档

详细文档在 [`docs/site/`](docs/site/README.md)（12 页，每页配示意图）：

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

---

## 安装

```bash
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`](LICENSE).
- **Commercial license** for closed-source / SaaS / proprietary integration —
  see [`COMMERCIAL.md`](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:

```bibtex
@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`](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`](COMMERCIAL.md).
