Molecule Design Loop

Open agent skill for constraint-driven molecule and polymer design, for Claude Code and Codex. Combines the user's Zotero library with an active literature search, adversarial chemistry review, novelty checking and result-to-claim auditing, alongside RDKit filtering, visual candidate review and explicit user approval before xTB. Structures and review packets are generated by tested scripts rather than written out by the model.

English | 中文说明 | Changelog | Share Package

Current release: v0.4.0 (2026-11-05). A ranking-integrity release: scripts/ranking_diagnostics.py --pareto-rank-mode protocol keeps every dominated candidate out of the top 3 of pareto_rank (Step 11 uses it), the default mode now flags the conflict instead of writing it silently, and --role-column holds controls (cap-only references, baselines, incumbents) out of the dominance comparison so they cannot empty the front. Builds on v0.3.x, which moved candidate tables, review packets and file inspection into tested scripts. See CHANGELOG.md.
Human approval stays mandatory before xTB. Zotero MCP and Gemini MCP must be configured for the new steps — the skill falls back gracefully when they are unavailable.

AI agents: read AGENT_GUIDE.md first. It is written for LLM consumption rather than human browsing.

Constraint-first molecular design: filter obvious bad structures early, review molecules visually before xTB, and use xTB as evidence instead of as the final judge.

Project Status

• Current release: v0.4.0 — ranking integrity: no dominated candidate in the top 3 of pareto_rank, controls held out of dominance; builds on the v0.3.x token-economy release
• Repo focus: modular agent skill for Zotero-grounded, adversarially reviewed molecular design
• Release notes: CHANGELOG.md | CHANGELOG.zh-CN.md
• Share-package scope: SHARE_PACKAGE.md | SHARE_PACKAGE.zh-CN.md

Release Track

v0.4.0 (2026-11-05) — Fix: with fewer than three non-dominated candidates, pareto_rank handed positions 2 and 3 to dominated candidates while the report's final top set correctly excluded them, so the CSV and the report disagreed and the scoring protocol's no-dominated-in-top-3 rule was broken; the test asserted the broken numbering. --pareto-rank-mode protocol shifts dominated candidates past rank 3 and Step 11 uses it; the default mode keeps old rounds reproducible but now warns and names the conflict. New --role-column reports role=control rows separately so a reference compound cannot dominate every candidate.

v0.3.1 (2026-11-04) — Fix: the Step 9.5 packet builder read the xTB results file under column names candidate_schema.md does not use, so a schema-conformant round file produced an evidence section with no numbers in it; the test fixture used the script's own names, which is why the suite never caught it. Schema names are now authoritative, the older spellings are accepted as aliases, and missing required columns are named rather than dropped.

v0.3.0 (2026-11-04) — Token economy. A full round used to cost far more than the chemistry warranted, because the model hand-wrote derived columns and read whole files back. SKILL.md became a step router with explicit reading rules and handoff points; build_candidates.py, build_gemini_inputs.py and inspect_round.py moved the derived data, the review packets and file inspection into tested code; test_skill_contract.py enforces the SKILL.md line budget, live links, tested scripts and no local paths.

v0.2.6 (2026-11-04) — The v0.2.5 ranking diagnostics become a deterministic, tested script (scripts/ranking_diagnostics.py): dominance, pareto/shadow ranks, concrete exclusion reasons, the Kendall τ-b matrix, and the dominated/assessed count, stdlib-only, with --benchmark-ids recovery of known compounds. Enforces "unknown is non-comparable, never a sentinel" in code.

v0.2.5 (2026-11-03) — The ranking audits itself. Kendall τ-b redundancy matrix over the five ranking axes (τ-b, not Pearson — the axes are ordinal with heavy ties), mandatory candidates_dominated / candidates_assessed reporting so a dominance criterion that dominated nothing cannot pass as a working gate, and a property-only shadow_rank_property_only ablation naming every candidate the practicality constraint excluded and why.

v0.2.4 (2026-08-21) — The loop must now say what it does not know. Claim audit triggers on un-evidenceable objectives (affinity, potency, selectivity, self-assembly…) even when xTB never ran, emitting no_direct_evidence. New loop_calibration block tracks promoted-vs-worked and prediction-vs-outcome, reported honestly in DESIGN_REPORT.md.

v0.2.3 (2026-08-10) — Synthesis practicality became multi-objective and enforcing: new overall_yield_estimate and hazard_toxicity_flag gate columns, optional route_alternatives trade-off profile, and Step 11 ranking by Pareto dominance over {property fit, cost, time, yield, hazard} instead of a tiebreak. Dominated candidates cannot enter the top 3.

v0.2.2 (2026-06-12) — Enforced cross-round failure memory: DESIGN_LOOP_STATE.json schema defined, killed motifs excluded at Steps 3/4. Synthesis cost / time-to-first-sample is now a first-class Pareto axis (Step 11), building-block availability biases generation (Steps 1/3), and experimental + adversarial lab failures flow back into state (Step 12).

v0.2.1 (2026-06-06) — Structure image input (Step 0.5) and NMR prediction/verification (Step 9.7). Duplicate candidate-generation-schema.md merged into candidate_schema.md. AGENT_GUIDE and README updated.

v0.2.0 (2026-05-31) — Complete redesign. SKILL.md restructured from 1041 → 360 lines; ten protocol reference files extracted. Dual Zotero + active-search literature streams. Three new mandatory gates: adversarial chemistry review (Step 3.5), novelty check (Step 5.5), result-to-claim audit (Step 9.5). Gemini and Zotero MCPs are now named first-class roles.

v0.1.3 (2026-05-19) — Polymer-design documentation and package notes.

v0.1.2 (2026-05-18) — Repository landing-page refresh. No workflow logic changed.

v0.1.1 (2026-05-12) — Sanitized stage-runner source package (molecule-design-stage-src/).

v0.1.0 (2026-05-10) — Initial public open-source packaging.

Why this repo exists

Many "LLM for molecule design" workflows fail in predictable ways:

• they generate molecules without grounding them in the field's known scaffolds and SAR
• they let the same model that designed a candidate also score it — no adversarial check
• they push xTB numbers into design conclusions without auditing what the numbers actually prove
• they spend most of their budget on the model retyping data a script could derive

molecule-design-loop is a structured loop against those failure modes.

Scripts

Every script takes --help, writes to a file you name, and has tests next to it.

Start from examples/example_candidates_config.yaml:

python3 molecule-design-loop/scripts/build_candidates.py \
  --config examples/example_candidates_config.yaml --check-only

Run the tests with:

python3 -m pytest molecule-design-loop/scripts

What's New

• 2026-11-04 — v0.3.0: token economy — router SKILL.md, generated candidate tables and review packets, bounded file inspection, and a contract test that keeps it that way. See CHANGELOG.md.
• 2026-11-04 — v0.2.6: the ranking diagnostics become a deterministic, tested script (scripts/ranking_diagnostics.py). See CHANGELOG.md.
• 2026-11-03 — v0.2.5: the ranking audits itself — axis-redundancy check, dominated-count reporting, and a practicality ablation that shows what the constraint actually cost. See CHANGELOG.md.
• 2026-08-21 — v0.2.4: un-evidenced design objectives must be declared (claim audit no longer requires xTB to fire), and the loop keeps score of its own hit rate. See CHANGELOG.md.
• 2026-08-10 — v0.2.3: synthesis practicality is a dominance criterion, not a tiebreaker; yield and hazard axes added; route trade-offs recorded instead of collapsed into one cost number. See CHANGELOG.md.
• 2026-06-12 — v0.2.2: enforced cross-round failure memory (DESIGN_LOOP_STATE.json schema; killed motifs excluded at Steps 3/4), synthesis-cost ranking axis, availability-biased generation, and lab-failure feedback. See CHANGELOG.md.
• 2026-06-06 — v0.2.1: structure image input and NMR prediction/verification. Schema files consolidated. See CHANGELOG.md.
• 2026-05-31 — v0.2.0: complete redesign. Modular reference files, dual literature streams, Gemini adversarial reviewer, novelty gate, result-to-claim audit.
• 2026-05-19 — v0.1.3: polymer-design scope and share-package notes.
• 2026-05-12 — v0.1.1: sanitized molecule-design-stage-src/ package.
• 2026-05-10 — v0.1.0: initial public release.

What the skill does

Structure image input (Step 0.5): Users can provide journal figures, ChemDraw screenshots, or hand-drawn sketches instead of typing SMILES. Claude extracts structures directly from images, validates with RDKit, and feeds confirmed seeds into the design spec.

Literature intelligence: Zotero personal library (Steps 1.5-A) and active field search (Step 1.5-B) run in parallel. Both are mandatory. LIT_PACKET.md merges the two streams; contradictions are flagged, not silently resolved.

Candidate generation: Every proposal must trace to a scaffold, SAR rule, or design principle from LIT_PACKET.md. Unsourced exploratory candidates are capped at 10% of each round.

Adversarial review (Step 3.5): Gemini reads the raw candidate CSV with a chemistry-skeptic prompt before RDKit filtering. Challenges each candidate's design logic, synthesis plausibility, and expected proxy effect. Claude does not review its own candidates.

Deterministic triage (Step 4): RDKit validity, MW/logP/TPSA, PAINS/Brenk alerts, Murcko scaffold deduplication. Synthesis feasibility gate (Step 5) requires a plausible make/buy route before gallery promotion.

Novelty check (Step 5.5): prior_art_search flags already-reported structures before the visual gallery. known candidates are automatically demoted to control role.

Human-in-the-loop (Step 6–7): RDKit-rendered HTML gallery with structure depictions, filter decisions, and design rationale. Explicit user approval required before any xTB run.

Result-to-claim audit (Step 9.5): After xTB, Gemini maps each computed number to exactly what it proves and what it cannot prove. overclaim flag blocks a score ≥ 4 in Step 11.

NMR prediction and verification (Step 9.7, optional): Claude predicts 1H/13C NMR spectra for top candidates using its internal chemistry knowledge. When experimental NMR data is available, a predicted-vs-experimental comparison produces a structural verification status. Based on Anthropic's "Making Claude a Chemist" research (±0.079 ppm 1H accuracy).

Iterative scoring (Step 11): Gemini reads design spec + adversarial review + novelty check + claim audit + NMR verification in a fresh thread. Pareto ranking across hard-constraint pass, synthesis feasibility, evidence level, and soft preferences.

Ranking diagnostics (Step 11): the ranking cannot audit itself, so two checks do. An axis-redundancy matrix (Kendall τ-b) asks whether the five ranking axes carry independent information or whether the trade-off is narrower than it looks, and reports how many candidates were actually dominated — if none were, the practicality gate did not bind and the round says so. A practicality ablation re-ranks on property fit alone and names every high-scoring candidate the constraint kept off the bench, with the concrete values responsible. Both are reported even when the answer is "practicality changed nothing".

Both small-molecule and polymer/material design are supported. Polymer candidates use finite capped oligomers for RDKit/xTB; polymer-level properties that cannot be inferred from surrogates are listed as non-xTB targets.

Workflow

[structure images → IMAGE_EXTRACTED_SMILES.csv]       ← Step 0.5 (optional)
→ design_spec.md
→ [Zotero extraction (1.5-A) || active search (1.5-B)]  ← parallel
→ LIT_PACKET.md (merged)
→ ROUND_N_CANDIDATES.csv
→ ROUND_N_GEMINI_ADVERSARIAL_REVIEW.md              ← Step 3.5
→ ROUND_N_FILTERED.csv (RDKit)
→ ROUND_N_SYNTHESIS_FEASIBILITY.csv
→ ROUND_N_NOVELTY_CHECK.md                           ← Step 5.5
→ ROUND_N_CANDIDATE_GALLERY.html
→ user approval checkpoint                           ← mandatory
→ ROUND_N_XTB_RESULTS.csv
→ ROUND_N_CLAIM_AUDIT.md                             ← Step 9.5
→ ROUND_N_NMR_PREDICTIONS.csv                       ← Step 9.7 (optional)
→ ROUND_N_DECISION.md (Gemini + Pareto)
→ next round or DESIGN_REPORT.md

Quick Start

Install the main skill:

bash install_molecule_design_loop.sh

Install the main skill plus the optional literature helper:

bash install_molecule_design_loop.sh --install-research-lit

Invoke the skill in Codex:

/molecule-design-loop "/path/to/design_spec.md"

Example input files:

• examples/example_design_spec.md
• molecule-design-loop/templates/design_spec_template.md

Default install target:

$CODEX_HOME/skills/molecule-design-loop

Fallback when CODEX_HOME is unset:

~/.codex/skills/molecule-design-loop

Reusable Stage Runner

This repo also includes a sanitized source-only stage runner extracted from a private molecule-design-stage/ working directory:

• molecule-design-stage-src/
• main entrypoint: molecule-design-stage-src/run_design.py
• Gemini handoff artifact preserved as ROUND_N_GEMINI_INPUT.md

Example:

python3 molecule-design-stage-src/run_design.py \
  --config molecule-design-stage-src/inputs/example_run.yaml \
  --step prepare

What is included

• molecule-design-loop/
• molecule-design-stage-src/
• examples/example_design_spec.md
• optional-skills/research-lit/SKILL.md
• install_molecule_design_loop.sh

Bundled helpers inside molecule-design-loop/:

• scripts/rdkit_filter_candidates.py
• scripts/render_candidate_gallery.py
• references/candidate_schema.md — CSV contracts + generation rules
• references/structure-image-input-protocol.md — Step 0.5
• references/nmr-prediction-protocol.md — Step 9.7
• 10 additional protocol files in references/ (see AGENT_GUIDE.md)
• templates/design_spec_template.md
• templates/xtb_approval_template.md

Packaging details are documented in SHARE_PACKAGE.md.

Design Principles

• Constraints first, novelty second
• xTB is evidence, not the final decision-maker
• Human structural review happens before xTB
• Rejected candidates and rejection reasons are kept for later refinement
• Candidate rounds should test interpretable design moves, not near-duplicate noise

Requirements

• Codex with access to a local skills directory
• Python 3
• RDKit installed in the Python environment

Optional:

• xTB for the quantum-screening stage
• research-lit as a companion literature skill
• gemini-research if your Codex setup supports it

Repository Layout

.
├── AGENT_GUIDE.md
├── CONTRIBUTING.md
├── CONTRIBUTING_CN.md
├── examples/
├── molecule-design-stage-src/
├── molecule-design-loop/
├── optional-skills/
├── README.md
├── README.zh-CN.md
├── SHARE_PACKAGE.md
├── SHARE_PACKAGE.zh-CN.md
└── install_molecule_design_loop.sh

Contributing

See CONTRIBUTING.md or CONTRIBUTING_CN.md.

Changelog

See CHANGELOG.md or CHANGELOG.zh-CN.md.

License

MIT