Compound, fragment and named-reaction library

Choose Templates… in the document toolbar. Search by name or alias, select an entry, review its preview and source links, then choose Insert teaching example or Insert unfinished scaffold. The drawing is appended beside the existing canvas; it does not replace your work. Separated structures outside the reaction’s local component groups are not assigned as participants just because it is the only reaction arrow on the canvas. A lone arrow groups nearby components with gaps up to 3.5 bond lengths; use plus signs to connect more widely spaced participants. Library entries leave a six-bond-length gap from the existing drawing. The picker is also available in the desktop app, which uses the same browser shell.

Use the Show filter to find teaching examples, unfinished scaffolds or reference-only terms. Searching ignores case, accents and punctuation. Use Tab to reach the results, arrow keys to select an entry, and Tab to reach its insert button. Escape closes the picker; focus returns to the toolbar button.

Release availability and paper use

The template library ships in 0.6.1, published on 2026-10-25 from source 5395bd1; the paper requires it. It was added after the published 0.6.0 baseline, so installing 0.6.0 alone does not provide this catalogue. Updating the paper environment and fleet installations remains pending until their checks are recorded. Published 0.6.0 artifacts and the original evaluation evidence remain immutable.

Before using the library as a released feature in the paper:

  • Update the paper environment and supported fleet installations to 0.6.1.

  • Verify the installed Templates… menu, category/search filters, previews and insertion of a compound, an open-R fragment and an unfinished reaction scaffold.

  • Verify the installed SDK, CLI, REST and MCP catalogue and insertion interfaces.

  • Record the exact release version, commit, artifact checksums and deployment checks alongside the paper’s editable sources and outputs.

Describe the 0.6.1 collection as 303 compounds, 87 fragments and 1,018 reaction-index entries covering the selected source snapshots; later additions (below) are not in 0.6.1. Only three reaction entries contain molecular teaching examples; 976 are unfinished scaffolds and 39 are reference-only terms. Do not describe the index as 1,018 verified molecular reaction templates or as an exhaustive survey of the literature. The rendering and calculation version requirements below still apply to paper outputs.

Compounds and fragments

The same offline picker includes 342 compounds, 92 open-attachment fragments and 8 polymer repeat units, with category and type filters (0.6.1 had 303 compounds and 87 fragments). Search names, common aliases (such as THF, DMSO and DMF), molecular formulae or chemical families.

Compounds span hydrocarbons, carbocycles and cages, aromatic and saturated heterocycles, alcohols, ethers, carbonyls, acids and acyl derivatives, amines, sulfur and halogen compounds, boron/silicon/phosphorus compounds, reagents, ligands, macrocycles, amino acids, biomolecules, polymer building blocks and common salts and inorganic molecules. This is a broad starter collection, not an exhaustive list of chemical compounds. PubChem records supply each compound’s molecular graph, formula and linked CID (retrieved 2026-10-25). Protonation, tautomer and stereochemistry follow that record; inspect the preview for the state needed in your work. Salts retain disconnected ions and repeated counterions on the canvas; the species list deduplicates identical ions and is not a formula-unit stoichiometry record.

For surface chemistry, nanotube functionalization and electroanalysis (#145) there are nanocarbon models (C60, C70, coronene, circumcoronene, perylene, triphenylene), aryldiazonium tetrafluoroborates (4-amino, 4-nitro, 4-carboxy), surface linkers and ligands (11-phosphonoundecanoic acid, 4-aminothiophenol, 1-dodecanethiol, APTES, oleic acid, oleylamine, phosphorylcholine), CVD feedstocks and precursors (CO, ferrocene, Fe(CO)5, Fe(acac)3, aluminium isopropoxide), analytes and redox probes (epinephrine, norepinephrine, melatonin, uric acid, hypoxanthine, NADH, NAD⁺, furosemide, D-glucono-1,5-lactone, dopamine-o-quinone, ferrocenemethanol, MOPS) and epoxy resins (BADGE, TGDDM), retrieved from PubChem on 2026-10-28; each source records that date. Organometallic and coordination compounds (ferrocene, Fe(CO)5, Fe(acac)3, ferrocenemethanol, the hexacyanoferrates, [Ru(NH3)6]³⁺ and [Ru(bpy)3]²⁺) are PubChem’s records with the metal and its ligands as separate ions or atoms, and say so: dative and haptic bonds are not drawn until Phase 5, so they are drawings of the composition, not structures to calculate as the complex.

Fragments include alkyl/aryl groups, functional groups, protecting groups, linkers, and surface anchors: 4-aminophenyl, 4-nitrophenyl and 4-carboxyphenyl groups, a phosphonate anchor and a thiolate anchor. R marks an open attachment point. They insert beside the drawing; they do not automatically fuse to a selected atom. Connect the fragment and replace its R sites manually. They remain generic structures, excluded from concrete calculation species until resolved. Unnumbered R sites cannot reuse an existing R1 definition accidentally. These fragment graphs are authored by the project; they are distinct from whole-molecule compound records.

Polymer repeat units (type polymer) are drawn in brackets with the bonds crossing them ending open, as the IUPAC graphic representation of macromolecules draws them: polyaniline (emeraldine base), Nafion, hydrogenated nitrile butadiene rubber, PEDOT:PSS, parylene C, PVDF, PMMA and polystyrene. They are authored by the project, insert as bracketed generic structures and are never calculation species; end groups and chain length are not represented, and their layout is RDKit’s, so tidy them with Clean up or by hand.

Nanostructures (type nanostructure) store generator parameters rather than SMILES: a (6,6) tube 4 nm long with COOH at both ends, a hydrogen-terminated (10,10) tube 10 nm long, a hydrogen-terminated (5,5)@(10,10)@(15,15) triple-walled tube 4 nm long, a hydrogen-terminated 7-AGNR six periods long, and a hydrogen-terminated 1.5 × 1.5 nm graphene flake. Dimensions resolve to lattice periods. These are idealized finite models, not measured samples. Insertion uses with_nanostructure and adds one editable picture: schematic for tubes, lattice for ribbons and flakes. The atom model and generator record stay with the species through document round trips. C60 and C70 remain PubChem compound entries. Search aliases include SWCNT-COOH, MWCNT, 7-AGNR and nanographene.

Use insert_template for these entries; a bare template_fragment cannot carry their species record and refuses. To preview in the SDK, render the returned document with render_svg. The browser preview uses the same path.

The complete picker contains 1,465 entries including the reaction index below. Filter Category → Named reactions to see the full reaction list. All entries have a preview except reference-only terms. Source links are shown where external data were used. The packaged chemical data are in src/vibesketch/document/data/chemical_templates.json.

Template interfaces

from vibesketch.document import new_document
from vibesketch.document.template_library import list_templates, insert_template

matches = list_templates("THF", kind="compound")
result = insert_template(new_document(), "compound-tetrahydrofuran")
result = insert_template(result.document, "fragment-boc")
result = insert_template(result.document, "appel-reaction", scaffold=True)

vibe-sketcher templates list "THF" --json
vibe-sketcher templates list --kind nanostructure --json
vibe-sketcher templates add drawing.vsk nanostructure-cnt-6-6-cooh
vibe-sketcher templates add drawing.vsk compound-caffeine
vibe-sketcher templates add drawing.vsk fragment-amide-linker
vibe-sketcher templates add drawing.vsk appel-reaction --scaffold

REST operation

Purpose

GET /api/template-library?q=...&category=...&kind=...

Search all templates; category and kind are optional exact filters

GET /api/template-library/{entry}/preview

Editable SVG preview; add scaffold=true for unfinished reactions

POST /api/documents/{id}/template-library

Append with {"revision": 0, "entry": "fragment-boc"}; explicit "scaffold": true for unfinished reactions

The CLI list command also accepts --category and --kind. MCP provides list_templates (optional query, category, kind) and add_template (entry, optional document, optional scaffold). Existing reaction-only interfaces below remain available. All template writes use the same revision checks.

What is included

The bundled, offline catalogue contains 1,018 entries, assembled from all 1,308 listings in the reference library’s source snapshots retrieved on 2026-10-25:

Names sharing a source URL are grouped as aliases, and matching names are combined across sources. Known translations of the teaching examples are also combined. Other translations and synonyms may still appear as separate entries. The count is not a claim of 1,018 distinct named reactions. The broader index also includes general transformations, reagents and rules. Source links and scope remain visible in the picker; the catalogue makes no claim to cover every named reaction in the literature.

Only names, links and retrieval metadata are bundled. Reference-site prose, mechanisms and images are not copied. Opening a source link needs an internet connection; searching, previewing and inserting work offline.

Completion status and the list of work to add

The picker is also the intake list: filter Unfinished scaffolds to find entries still needing molecular templates. The packaged catalogue is src/vibesketch/document/data/named_reactions.json; kind, example_smiles and note record each entry’s status. Preserve stable IDs when improving it.

Status

Included

What insertion creates

Teaching example

3

Editable molecules and a chemical reaction arrow, from the existing Diels–Alder, Fischer–Speier and Suzuki tutorials

Unfinished scaffold

976

The reaction name, explicit unfinished label, reactant/product text placeholders, conditions placeholder and a graphic arrow

Reference only

39

No insertion; reagents, catalysts, rules and similar terms remain reference links

A scaffold contains no molecular structures and creates no species, chemical reaction or calculation job. Its arrow is made of editable line shapes so neighbouring molecules cannot be mistaken for its participants. Replace the placeholders with verified structures and replace the graphic arrow with a chemical reaction arrow when completing the drawing.

Teaching examples are illustrations, not experimental protocols or computed results. The Suzuki example shows only the organic transformation; its catalyst, base and inorganic byproducts are omitted. Do not treat it as a balanced reaction-energy calculation input. The esterification example does not simulate equilibrium or acid catalysis. None includes calculated geometries, energies, orbitals, or a complete electron-pushing mechanism.

For each unfinished entry:

  • Resolve aliases and confirm the reaction and its literature references.

  • Author and verify the molecules, stoichiometry, stereochemistry and conditions.

  • Check canvas insertion, preservation of existing drawings and document round trips.

  • Render publication graphics with vibe-sketcher 0.6.x.

  • Run calculations with vibe-qc 0.17.x or newer, preferably 0.18.x.

  • Render all output orbitals with vibe-viewer 3.0.x.

  • Retain editable sources, inputs, outputs and rendering settings with exact versions.

These production versions are requirements for completed publication assets, not claims about artifacts supplied by the picker. Missing versions or capabilities leave that production work pending. Inserting an entry does not launch calculations or assert that these checks have passed.

SDK, CLI, REST and MCP

from vibesketch.document import new_document, save
from vibesketch.document.reaction_library import list_reactions, insert_reaction

matches = list_reactions("Diels Alder")
result = insert_reaction(new_document(), "diels-alder-reaction")
save(result.document, "reaction.vsk")

# Explicit opt-in to an unfinished scaffold; result.warnings explains its status.
result = insert_reaction(result.document, "appel-reaction", kind="scaffold")
save(result.document, "reaction-with-scaffold.vsk")

vibe-sketcher reactions list "Diels Alder" --json
vibe-sketcher reactions add drawing.vsk diels-alder-reaction -o expanded.vsk
vibe-sketcher reactions add expanded.vsk appel-reaction --scaffold

The CLI updates the supplied document unless --output is given. A missing molecular example is refused (exit status 3) unless --scaffold is explicit.

REST operation

Purpose

GET /api/reaction-library?q=...

Search names, aliases and IDs; returns status, source links and notes

GET /api/reaction-library/{entry}/preview?kind=example

SVG preview; use kind=scaffold explicitly for scaffolds

POST /api/documents/{id}/reaction-library

Append an entry with body {"revision": 0, "entry": "appel-reaction", "kind": "scaffold"}

Writes require the current revision; stale requests return 409 without changing the document. Missing examples, unknown IDs and reference-only insertions return 422. SDK insertion returns a Derivation containing the document and warnings; it does not save a file or increment a server revision.

MCP exposes list_named_reactions (optional query) and add_named_reaction (entry, optional document, and explicit kind: "scaffold" for scaffolds). They use the same REST operations and revision checks as the browser.