[preetibayasMS]

Summary

Harden Psi4 screening and charged-state workflows, and add explicit, executable UMAP support to molToolkit. These changes prevent incomplete scientific outputs from being reported as fully successful and prevent a different dimensionality-reduction algorithm from being mislabeled as UMAP.

• Psi4: validate spin references, reuse a shared wavefunction for property extraction, isolate working/scratch directories, run four-point states in fresh processes, preserve diagnostics and partial results, and propagate launcher/artifact-copy failures.
• molToolkit: add umap-learn to the existing Python 3.11 mamba environment transaction and run a real ten-candidate Tanimoto-distance embedding during image builds.
• Synchronize agent guidance with the packaged helpers/dependencies and document before/after behavior, verification limitations, and coordinated image/agent rollout.

Type of change

• New agent (under agents/<name>/)
• Update to an existing agent
• New starter kit (under starter-kits/<name>/)
• Update to an existing starter kit
• Schema change (docs/schemas/**)
• Workflow / script change (.github/**)
• Documentation only
• Other (describe below)

Tool-runtime implementation, dependency, regression-test, and smoke-check updates under the existing Psi4 and molToolkit agents.

Related issue / tracking

n/a

Schema impact

• No schema changes
• Schema changes are backward compatible
• Schema changes are breaking — add the breaking-change label and link the rollout plan below

No catalog schema change. The updated Psi4 tool command requires the matching image's new launcher and workflow helpers; update the image before the deployed tool/agent. Likewise, do not deploy molToolkit instructions claiming UMAP support against an older image without that dependency.

Validation checklist

• Documentation (README.md, schemas) is updated to match the change.
• No hand-edits to .auto-registry/** (it is generated post-merge).
• No OS / editor artefacts committed (.DS_Store, .env, *.swp, .idea/, .vs/, etc.).
• If model-weight files are added, they are Git-LFS tracked, ≤5 GB each, and in an allowed format.
• No secrets, customer data, or internal-only URLs are committed.
• All Markdown links resolve.

No model weights are added. Existing README links have not been comprehensively revalidated; this change adds no external Markdown links.

Reviewer notes (optional)

Recorded focused checks:

• From agents/psi4/tools/psi4, python -m unittest -v test_psi4_reliability — passed earlier: 23 mocked-Psi4 tests. A final publication-time rerun was blocked by the local command-approval gate; no new successful rerun is claimed.
• python agents/mol-toolkit/tools/mol-toolkit/app/smoke_umap.py in an isolated UMAP-capable environment (the executed command used absolute interpreter/checkout paths) — passed, reporting UMAP_SMOKE_OK, umap-learn=0.5.12, and ten finite 2D coordinates.
• python -m pip_audit --progress-spinner off --format json --output umap-dependency-audit.json (the executed output path was in the local session directory) — passed: no known vulnerabilities in that isolated environment.
• git --no-pager diff origin/main...HEAD --check — passed after normalizing the new molToolkit/Psi4 scripts' CRLF line endings to LF. The normalization-only follow-up commit changes no script behavior.

The local UMAP execution used Python 3.14.8 with NumPy 2.5.4, SciPy 1.18.1, Numba 0.68.0, and scikit-learn 1.9.1. It is not verification of the full conda-resolved Python 3.11 container. The new Dockerfile gate must pass in the approved target build.

Not run: container builds, real Psi4 numerical smoke, or end-to-end scientific candidate workflows. Mocked Psi4 tests do not establish numerical convergence, basis availability, resource sufficiency, or the cause of an earlier PSIO failure. No subprocess wall-clock timeout was added.

No image was built, published, retagged, replaced, or deployed during this preparation. Obtain deployment approval, build and scan matching images, execute the documented real-runtime checks, then update deployed tools and agents together.