Project layout — this bundle contains five stage directories from the AI-Designer pipeline: research/ (literature survey), architect/ (blueprint + ModelConfig), coder/ (PyTorch implementation), validator/ (tests + benchmarks), and documenter/ (this README plus docs/ and CHANGELOG.md). An optional paper/ directory holds the NeurIPS-format writeup when the paper-generation step was triggered.

The original research request that produced this bundle is preserved verbatim in prompt.md — if any URLs in the prompt were fetched server-side for additional context, their cleaned contents are appended there too.

---

MolFM-Guide: Manifold-Preserving Guidance for Discrete Graph Flow Matching

Inference-time guidance for discrete graph flow matching that combines lightweight property predictors with manifold-projection steps to generate valid, property-optimized molecular graphs.

Discrete graph flow matching (DeFoG, ICML 2025 Oral) achieves state-of-the-art unconditional molecular generation but lacks a guidance mechanism for conditional generation — its authors explicitly leave this as future work. MolFM-Guide fills this gap by composing gradients from QED, SA, and LogP property predictors trained on partially noised graphs, then projecting the guided distribution back toward the valid molecular manifold via valency and ring-strain constraints. No existing method applies manifold-preserving guidance to discrete graph flow matching. Empirical results are pending trained models — all listed claims are verified at the implementation level (shape correctness, gradient flow, numerical stability) but require trained weights for quantitative validation.

Highlights

• Novel guidance framework for discrete flow matching — property predictor gradients perturb clean logits during CTMC sampling, enabling post-hoc conditional generation without retraining the backbone (see docs/ARCHITECTURE.md#guidance-interface)
• Manifold projection via greedy logit correction — valency, ring-strain, sanity, and charge-neutrality constraints projected onto probability distributions with a ramped schedule (weak at high noise, strong at low noise) (see docs/ARCHITECTURE.md#32-manifold-projection)
• Composable multi-objective guidance — weighted-sum composition with per-gradient L2 normalization prevents any single property from dominating (see docs/ARCHITECTURE.md#33-guidance-composer)
• Correctness-verified — 20/20 smoke tests pass; 30+ pytest tests validate shapes, gradients, permutation invariance, numerical stability, and bf16 compatibility

Quick start

pip install -r requirements.txt
python coder/smoke_test.py        # 20 smoke tests, prints param counts
pytest validator/test_model.py -v # full unit-test suite

Repository layout

coder/
  config.py          — FullModelConfig and sub-configs (GraphConfig, DeFoGConfig, etc.)
  layers.py          — SinusoidalTimestepEmbedding, EdgeBiasedMultiheadAttention,
                       SwiGLUFFN, GraphTransformerBlock, global_pooling
  backbone.py        — DeFoGDenoiser backbone (graph transformer denoiser)
  flow_matching.py   — CTMC noising, flow_matching_loss, flow_update_probability
  predictor.py       — MLPOnBackbonePredictor, SeparateGNNPredictor, MultiPropertyPredictor
  guidance.py        — ManifoldProjection, GuidanceComposer, apply_guidance_to_logits
  sampler.py         — GuidedSampler (unconditional, guided, guided+projected)
  model.py           — FullModel (end-to-end training + sampling orchestration)
  eval.py            — MetricsCollector, RDKit decoding, validity/property metrics
  smoke_test.py      — 20 smoke tests for shape, gradient, and numerical correctness
validator/
  test_model.py      — 30+ pytest tests (7 test classes)
  run_ablations.py   — 9 named ablations (requires trained weights)
  profile_model.py   — torch.profiler for forward/train/guided_sampling modes
  research_eval/     — scorecard, claim_grounding, experiment_coverage, rubric

Documentation

• docs/ARCHITECTURE.md — design, inductive biases, and domain-specific considerations
• docs/TRAINING.md — how to train, recipe, troubleshooting
• docs/BENCHMARKS.md — benchmarks, ablations, profiling, research-quality evaluation
• docs/API.md — module-level API reference

Citation

@misc{mol-fm-guide,
  title  = {MolFM-Guide: Manifold-Preserving Guidance for Discrete Graph Flow
            Matching},
  author = {<TODO>},
  year   = {2026},
  note   = {Generated via ml-designer pipeline}
}