AtomisticSkills 2.0.0: uv environments, one launcher, plugin-ready install

.agents/rules/coding-standards.md

@@ -19,8 +19,8 @@ These rules are universally applied across all aspects of this project. **You MU
 10. **URL Validation**: After generating any URLs, always test whether the URL is valid by verifying it directly (e.g., curling).
 
 ## 2. Environment and Dependency Management
-- **Environment Isolation**: You must use the appropriate isolated Conda environment depending on the module or skill being developed (see `@.agents/rules/mcp-environments.md`). The `base-agent` environment serves as the generic fallback for standard processing.
-- **Dependency Versions**: Never globally force arbitrary PyTorch or library versions (e.g., do not globally demand `torch 2.9.1`). PyTorch and critical packages are rigorously managed per-environment by their respective `core_env.yaml` schemas in `conda-envs/*`.
+- **Environment Isolation**: You must use the appropriate environment via the `venv/run` launcher depending on the task: a shared project (`cpu`, `mlip`, `fairchem`) or the research stack a skill declares in `metadata.venv` (see `.agents/rules/mcp-environments.md`). The `cpu` environment serves as the generic fallback for standard processing without torch.
+- **Dependency Versions**: Dependencies are rigorously managed per uv project in `venv/<project>/pyproject.toml` and committed `uv.lock`. Never arbitrarily force or install package versions globally. Optional extras (`openmm`, `docking`, `pymol`, `void`, `transport`) handle system-dependent packages.
 - **Failures**: NEVER implement fallback functions when package imports fail. Debug the root cause and fix the environment configuration.
 
 

.agents/rules/mcp-environments.md

@@ -2,42 +2,81 @@
 trigger: always_on
 ---
 
-# MCP Server Environment Rules
-
-When running scripts or debugging code related to specific MCP servers, you MUST use the corresponding Conda environment defined in `mcp_config.json`.
-
-For general development logic that cuts across tools, usually `base-agent` is sufficient, but when importing specific libraries that are isolated (like `atomate2`, `jobflow_remote`, `mace`, `fairchem`), you must use the correct environment.
-
-## Installation Instructions
-
-For detailed installation instructions, please refer to the `README.md` and `install.sh` located in each environment's directory under `conda-envs/<env_name>/`.
-
-- **base-agent**: `conda-envs/base-agent/` (Core: pymatgen, ase, rdkit, packmol)
-- **mace-agent**: `conda-envs/mace-agent/` (Core: mace-torch, pymatgen, ase)
-- **matgl-agent**: `conda-envs/matgl-agent/` (Core: matgl, pymatgen, dgl)
-- **fairchem-agent**: `conda-envs/fairchem-agent/` (Core: fairchem-core≥2.18, pymatgen, Python 3.12)
-- **atomate2-agent**: `conda-envs/atomate2-agent/` (Core: atomate2, pymatgen)
-- **adit-agent**: `conda-envs/adit-agent/` (Core: ADiT, lightning, hydra, PyG)
-- **diffcsp-agent**: `conda-envs/diffcsp-agent/` (Core: DiffCSP++, hydra, PyG, pyxtal)
-- **mattergen-agent**: `conda-envs/mattergen-agent/` (Core: MatterGen, PyG, lightning)
-- **smol-agent**: `conda-envs/smol-agent/` (Core: smol, pymatgen)
-- **drugdisc-agent**: `conda-envs/drugdisc-agent/` (Core: rdkit, autodock-vina, pdbfixer, meeko)
-- **xrd-agent**: `conda-envs/xrd-agent/` (Core: DARA, pymatgen)
-- **orca-agent**: `conda-envs/orca-agent/` (Core: scine_utilities, scine_readuct, ase). Requires `ORCA_BINARY_PATH` environment variable pointing to the ORCA binary. No MCP server, scripts only.
-- **phasefield-agent**: `conda-envs/phasefield-agent/` (Core: fipy, scipy, numpy, imageio). No MCP server, scripts only.
-- **calphad-agent**: `conda-envs/calphad-agent/` (Core: pycalphad, pymatgen). No MCP server, scripts only.
-- **nmr-agent**: `conda-envs/nmr-agent/` (Core: nmrsim, nmrglue, pot). No MCP server, scripts only.
-- **react-ot-agent**: `conda-envs/react-ot-agent/` (Core: PyTorch). No MCP server, scripts only.
-
-| MCP Server | Conda Environment | Python Path |
+# MCP Server and Environment Runtime Rules
+
+AtomisticSkills runs all skill scripts and MCP servers through the unified launcher `venv/run`. The runtime uses three shared `uv` projects under `venv/` plus one pinned project per research stack, with pre-built container images as an automatic fallback when host requirements are not met.
+
+## 1. Environments Overview
+
+| Environment | Primary Packages | GPU | MCP Servers |
+| :--- | :--- | :--- | :--- |
+| `cpu` | ASE, pymatgen, RDKit, pycalphad, MDAnalysis (no torch) | No | `base`, `atomate2`, `drugdisc`, `smol` |
+| `mlip` | PyTorch 2.14.1, MACE-torch 0.3.16, MatGL 4.1.0, nvalchemi-toolkit 0.2.0 | Yes | `mace`, `matgl` |
+| `fairchem` | PyTorch 2.13.0, fairchem-core 2.23.0, nvalchemi-toolkit 0.2.0 | Yes | `fairchem` |
+
+### Research Stacks
+
+Pinned to the versions they were verified with, rather than tracking the latest releases:
+
+| Environment | Used by | Platforms |
 | :--- | :--- | :--- |
-| matgl | `matgl-agent` | `<conda_base>/envs/matgl-agent/bin/python` |
-| mace | `mace-agent` | `<conda_base>/envs/mace-agent/bin/python` |
-| fairchem | `fairchem-agent` | `<conda_base>/envs/fairchem-agent/bin/python` |
-| materials_tools | `base-agent` | `<conda_base>/envs/base-agent/bin/python` |
-| atomate2 | `atomate2-agent` | `<conda_base>/envs/atomate2-agent/bin/python` |
-| smol | `smol-agent` | `<conda_base>/envs/smol-agent/bin/python` |
-| adit | `adit-agent` | `<conda_base>/envs/adit-agent/bin/python` |
-| diffcsp | `diffcsp-agent` | `<conda_base>/envs/diffcsp-agent/bin/python` |
-| mattergen | `mattergen-agent` | `<conda_base>/envs/mattergen-agent/bin/python` |
-| drugdisc | `drugdisc-agent` | `<conda_base>/envs/drugdisc-agent/bin/python` |
+| `adit`, `diffcsp`, `mattergen` | the generative MCP servers and skills | x86_64 natively with glibc ≥ 2.32 (CUDA 12.6 or 13 by driver); elsewhere the `generative` image |
+| `msms` | `chem-msms-predict` (ICEBERG 2.1, CPU) | x86_64 only, glibc ≥ 2.31 and GCC 9's libstdc++ |
+| `reactot` | `chem-react-ot` | x86_64 and aarch64 |
+| `scd` | `ml-property-predict-scd` | x86_64 only, glibc ≥ 2.32 |
+
+### Why Three Shared Environments?
+1. **Package conflicts**: `mace-torch` pins `e3nn==0.4.4`, whereas `fairchem-core` requires `e3nn>=0.5`.
+2. **PyTorch versions**: `fairchem-core` 2.23 requires `torch~=2.13`, while `mlip` runs PyTorch 2.14.1.
+3. **NumPy constraints**: `nvalchemi-toolkit` 0.2 requires `numpy<2.4`, so GPU environments use NumPy 2.3.5 while `cpu` uses NumPy 2.5+.
+
+### Optional Extras
+Environments support optional extras specified as `<venv>+<extra>` (e.g., `cpu+openmm`, `cpu+docking`):
+- `openmm`: OpenMM and PDBFixer (requires glibc ≥ 2.34).
+- `pymol`: PyMOL open-source (x86_64 only).
+- `docking`: AutoDock Vina (builds against Boost on aarch64).
+- `void`: VOID guest docking (installed from git).
+- `transport`: AMSET and BoltzTraP2 (requires git and cmake).
+
+## 2. Server Runtime Mapping
+
+| MCP Server | venv | Image | GPU | Description |
+| :--- | :--- | :--- | :--- | :--- |
+| `base` | `cpu` | `cpu` | No | Materials Project query, structure manipulation, literature |
+| `atomate2` | `cpu` | `cpu` | No | Atomate2 and Jobflow calculation workflows |
+| `drugdisc` | `cpu` | `cpu` | No | Small-molecule standardization, descriptors, fingerprints |
+| `smol` | `cpu` | `cpu` | No | Cluster expansion and Monte Carlo simulations |
+| `mace` | `mlip` | `mlip` | Yes | MACE foundation models (relax, MD, features) |
+| `matgl` | `mlip` | `mlip` | Yes | MatGL models (CHGNet, TensorNet, M3GNet) |
+| `fairchem` | `fairchem` | `fairchem` | Yes | FairChem models (UMA, eSEN) |
+| `adit` | `adit` | `generative` | Yes | ADiT all-atom diffusion transformer |
+| `diffcsp` | `diffcsp` | `generative` | Yes | DiffCSP++ crystal structure generation |
+| `mattergen` | `mattergen` | `generative` | Yes | MatterGen generative diffusion model |
+
+The generative servers run from their uv projects on x86_64 hosts with glibc ≥ 2.32 (PyG's wheels need it); elsewhere `venv/run` uses the `generative` container image (linux/amd64 and linux/arm64; on arm64 it compiles the PyG extensions from source, since PyG publishes no aarch64 wheels).
+
+## 3. No Conda
+
+Since 2.0.0 nothing runs from conda. Stacks that cannot share an environment get their own pinned uv project (the research stacks above); host builds use a uv extra (`mlip+lammps` provides what `mat-lammps-md` needs to compile LAMMPS against the `mlip` environment, `fairchem+lammps` the LAMMPS wheel and `fairchem-lammps`).
+
+## 4. Runtime Selection and Launcher Backend
+
+All skills and servers execute through the `venv/run` launcher:
+- `venv/run <venv>[+<extra>] <command> [args...]`
+- `venv/run --server <name>`
+- `venv/run --setup` (prepares environments)
+- `venv/run --doctor` (checks runtime status and diagnostics)
+
+The runtime backend is controlled by `ATOMISTIC_RUNTIME` (or `~/.config/atomistic_skills.yaml`):
+- `auto` (default): Uses native `uv` if the machine is Linux x86_64/aarch64 with compatible glibc (per `venv/platforms.tsv`) and a C compiler (`gcc`). Otherwise, automatically falls back to container images (`ghcr.io/learningmatter-mit/atomisticskills-<name>:2.0.0`).
+- `uv`: Enforces host `uv` execution.
+- `docker`, `podman`, `apptainer`, `singularity`: Enforces container execution with host paths mounted at identical locations.
+
+## 5. Shell CLI Fallback for MCP Tools
+
+When an MCP server is not connected via stdio, any MCP tool can be executed directly from the shell:
+```bash
+venv/run <venv> python -m src.mcp_server.cli <server> <tool> key=value ...
+```
+- Pass `--list` to view all available tools for a server.
+- Multiple tool calls chained in one command share process memory (e.g., `load_model` followed by `relax_structure`).

.agents/rules/release-standards.md

@@ -17,13 +17,43 @@ Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`
 
 ## Pre-Tag Checklist
 
-1. Rebuild the doc site to get accurate public counts:
+0. Bump the version and propagate it to every published manifest. `VERSION` at
+   the repository root is the single source; `.claude-plugin/plugin.json`,
+   `.claude-plugin/marketplace.json` and `server.json` are derived from it.
+   The tag must match `VERSION` exactly.
    ```bash
-   conda run -n base-agent python site/build_skills.py
+   venv/run cpu python tools/sync_version.py --set 1.x.y
+   venv/run cpu python tools/sync_version.py --check
    ```
-2. Read counts from `site/skills_index.js` and git (source of truth):
+   > CI runs `--check` on every push, so a tag can never ship with the four
+   > files disagreeing.
+
+   If `docker/images.json` changed in this release, re-render the plugin's MCP
+   wiring as well, since the image tags follow the version:
+   ```bash
+   python docker/render.py plugin-mcp
+   ```
+
+1. Verify derived files, platform locks, and migrations:
+   ```bash
+   python docker/render.py servers --check
+   python docker/render.py plugin-mcp --check
+   venv/run cpu python tools/lock_platforms.py --check
+   venv/run cpu python tools/migrate_skill_commands.py --check
+   ```
+
+2. Run the test suites:
+   ```bash
+   venv/run cpu python -m pytest tests/test_launcher.py tests/test_skill_runtime.py tests/test_uv_projects.py tests/test_images_and_manifests.py tests/test_tool_cli.py -q
+   ```
+
+3. Rebuild the doc site to get accurate public counts:
+   ```bash
+   venv/run cpu python site/build_skills.py
+   ```
+4. Read counts from `site/skills_index.js` and git (source of truth):
    ```bash
-   # skills, tools, servers (= conda-env dirs) — from rebuilt index
+   # skills, tools, servers — from rebuilt index
    python3 -c "
    import re
    content = open('site/skills_index.js').read()
@@ -37,8 +67,8 @@ Use [Semantic Versioning](https://semver.org/): `vMAJOR.MINOR.PATCH`
    ```
 
    > **Note**: Workflows live as plain `*.md` files in `.agents/workflows/` (e.g. `drug-hit-finding-htvs.md`), **not** as `WORKFLOW.md`. Always use `ls .agents/workflows/*.md | wc -l` for the current count and `git ls-tree -r <tag> --name-only | grep "workflows/.*\.md" | wc -l` for the previous-tag count.
-3. Ensure all pre-commit hooks pass on HEAD.
-4. Confirm the MCP server does not expose built-in agent tools (e.g. `task_boundary`, `notify_user`).
+5. Ensure all pre-commit hooks pass on HEAD.
+6. Confirm the MCP server does not expose built-in agent tools (e.g. `task_boundary`, `notify_user`).
 
 ## Tag Message Format