Migrate CGCNN/QRF k-points predictor into the Kmesh backend seam

[junwen94]

Part of #26 (migration epic). Migration block 2: ML k-points.

Current state on staged main

The official pipeline already has a working ML k-mesh backend:

• advisors/kmesh_advisor.py: ml_kmesh_advisor(spec) returns a KMeshAdvisor backend; when no k-hint is set it calls advise_kpoints(structure, spec).
• advise_kpoints: extract_cslr_features → load_model(spec) → predict → build_kmesh_entries → select nearest k-index entry.
• Model is a random forest on CSLR features predicting a k-index (ModelSpec(model_type="random_forest", feature_set="cslr")).
• Wired via Pipeline(kmesh=ml_kmesh_advisor(spec)); CLI exposes --model.

By default recommend uses the heuristic (resolve_kpoints_from_advice, spacing→grid), not ML — confirmed: k-grid comes back with source="default".

What the legacy main has that this lacks

Old main ml/kpoints/ (git-tracked; the on-disk ml/kpoints/ here is only a stale pycache shell) has a richer predictor set:

• CGCNN graph model (cgcnn.py, cgcnn_graph.py, atom_features.py) — graph neural net k-spacing predictor.
• ALIGNN variant (alignn.py, alignn_graph.py).
• KSpacingPredictor (predictor.py) — QRF with confidence intervals (confidence_level), plus a CGCNN metal model.

Goal

Bring the richer legacy predictor(s) in as a Kmesh-stage backend plugged into the existing KMeshAdvisor seam — no pipeline change. Decide scope:

• Minimum: port the CGCNN k-index/k-spacing predictor as a backend selectable via ModelSpec/Pipeline, alongside or replacing the RF/CSLR path.
• Consider whether QRF confidence intervals surface as Provenance.confidence.

Hard constraint — keep these APIs stable

goldilocks-models imports and trains against these; changing signatures forces retraining (AGENTS.md):

• goldilocks_core.kmesh.build_kmesh_entries — kindex schedule.
• feature extraction entry point. NOTE: AGENTS.md names goldilocks_core.infer_features, but on staged main the feature fn is goldilocks_core.ml.features.extract_cslr_features (no infer_features symbol found). Reconcile the name / re-export before/while migrating so goldilocks-models keeps working.

Work

1. Port CGCNN (+ graph/atom-feature helpers) into ml/ following the new layout; keep model loading via ModelSpec/load_model.
2. Add/extend a Kmesh backend in advisors/ that uses it; keep the KMeshAdvisor callable contract.
3. Decide RF/CSLR vs CGCNN default; document how to select via --model/Pipeline.
4. Optionally map QRF confidence → Provenance.confidence.
5. Tests with a small fake model (no local_data/, no network).

Done when

• A CGCNN-backed kmesh backend is selectable and produces source="model" k-points.
• build_kmesh_entries and the feature-extraction entry point remain import-stable for goldilocks-models.
• Tests pass; ruff clean.

---

Written by an agent on behalf of Junwen Yin.