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 is merged on main and is required in the next 0.6.x patch release for the paper. It was added after the published 0.6.0 baseline; installing 0.6.0 alone does not provide this catalogue. Release publication and fleet deployment remain pending until their acceptance 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:

  • Qualify and publish the next unused 0.6.x patch version containing the library.

  • Update the paper environment and supported fleet installations to that release.

  • 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 collection as 303 compounds, 87 fragments and 1,018 reaction-index entries covering the selected source snapshots. 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 303 compounds and 87 open-attachment fragments, with category and type filters. 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.

Fragments include alkyl/aryl groups, functional groups, protecting groups and linkers. 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.

The complete picker contains 1,408 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-sketch templates list "THF" --json
vibe-sketch templates add drawing.vsk compound-caffeine
vibe-sketch templates add drawing.vsk fragment-amide-linker
vibe-sketch 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-sketch 0.6.x.

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

  • Render all output orbitals with vibe-view 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-sketch reactions list "Diels Alder" --json
vibe-sketch reactions add drawing.vsk diels-alder-reaction -o expanded.vsk
vibe-sketch 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.