Runnable examples¶

These examples turn CCO into an ethanol document, a vector figure and a vibe-qc B3LYP/def2-SVP single-point script. They prepare files without submitting or running a calculation. Use an installed vibe-sketch environment; no naming engine, QVF package, vibe-qc installation or queue is needed to prepare them. Executing the generated scripts requires a working vibe-qc installation.

Download a starting document¶

Example	Editable sketch	Figure
Ethanol, including a generated 3D geometry	ethanol.vsk	ethanol.svg
Acetic acid + ethanol → ethyl acetate + water	esterification.vsk	esterification.svg
Cyclohexene + hydrogen → cyclohexane, with starting 3D geometries	hydrogenation.vsk	hydrogenation.svg

Open a VSK using Open…, or pass it to vibe-sketch serve FILE --open. The tutorials walk through creating these sketches yourself.

The reaction-to-publication tutorial uses the hydrogenation example for a full manual drawing, SVG export and vibe-qc submission through vq, with equivalent CLI commands. Its downloadable VSK contains no queue jobs or run records. Those calculations require the separately installed queue and vibe-qc described in that tutorial.

Named reactions and all-feature examples¶

Download named-reactions.zip for editable Diels–Alder, Fischer and Suzuki sketches, a linked two-step scheme, stereo/radical worksheets, every exchange format, and input examples for every supported task. It also includes the scripts below. Inputs are examples of writer behavior; no calculation result is implied by their presence.

Download	Run	What it verifies
named_reactions.py	`python named_reactions.py NEW_DIRECTORY`	Chemistry identities, formats, V3000, geometry cache and writer task/options/refusals
reaction_cli.sh	`bash reaction_cli.sh NEW_DIRECTORY`	CLI preparation and three vibe-qc inputs
reaction_rest.py	`python reaction_rest.py SERVER NEW_DIRECTORY`	Stored/stateless API, revision conflicts, exports and binary QVF
reaction_mcp.py	`python reaction_mcp.py SERVER NEW_DIRECTORY`	Real MCP protocol and browser-visible shared edits
queue_lifecycle.py	See queue tutorial	Explicitly enabled real submission, cancellation, reopened run records and viewer handoff

For the last script, keep the REST and MCP clients beside it. Use a new output directory for each run. The feature map links these examples to the illustrated tutorial for every implemented capability.

Command line¶

Activate the environment created by the installer:

source .venv/bin/activate

Download ethanol.sh, then run:

bash ethanol.sh ethanol-cli

Choose a new output directory. The script creates ethanol.vsk, ethanol.svg and inputs/m1_b3lyp_def2-svp.py. It prints the species report and embeds the geometry before writing inputs.

vibe-sketch convert CCO --from smiles -o "$1/ethanol.vsk"
vibe-sketch info "$1/ethanol.vsk"
vibe-sketch embed "$1/ethanol.vsk"
vibe-sketch render "$1/ethanol.vsk" -o "$1/ethanol.svg"
vibe-sketch input "$1/ethanol.vsk" --all --program vibeqc --task sp \
    --method B3LYP --basis def2-SVP --output-dir "$1/inputs"

For a reaction, use a reaction SMILES rather than CCO:

vibe-sketch convert 'CC(=O)O.CCO>>CC(=O)OCC.O' --from smiles -o esterification.vsk
vibe-sketch render esterification.vsk -o esterification.svg

Quote reaction SMILES in a shell: > is otherwise a redirection operator. See the CLI reference for species selection, return codes and writer options.

Python SDK¶

Download ethanol.py, then run it in the same environment:

python ethanol.py ethanol-sdk

The script creates a new output directory, imports ethanol, generates 3D, checks for embedding failures, and writes the document, SVG and input. It uses the document’s actual species id instead of assuming a fixed id.

    document = import_into(None, "CCO", "smiles").document
    document, report = embed(document)
    if report.failed:
        raise SystemExit(f"Cannot generate 3D: {report.failed}")
    for warning in report.warnings:
        print(warning)
    species = document.species[0]
    bundle = write_input(
        document,
        species=species.id,
        program="vibeqc",
        spec=JobSpec(task="sp", method="B3LYP", basis="def2-SVP"),
    )
    save(document, output / "ethanol.vsk")
    write_output(output / "ethanol.svg", render_svg(document))
    for file in bundle.files:
        write_output(output / file.name, file.content.encode("utf-8"))
        print(f"Wrote {file.name}")
    print("Saved ethanol.vsk and ethanol.svg. No calculation was submitted.")

The SDK’s save and write_output helpers refuse destructive replacement of QVF results. The example also requires a new directory so an earlier run is not overwritten. Writer refusals raise WriterRefusal with the reasons; see the input writer reference for handling them.

REST API¶

Start a server in one terminal:

vibe-sketch serve

Download ethanol_rest.py. In another terminal, pass the address printed by the server and a new output directory:

python ethanol_rest.py http://127.0.0.1:8766 ethanol-rest

This client uses only Python’s standard library. It creates a document, embeds it using its current revision, requests input files and downloads the VSK and SVG. It prints a link to the shared drawing so you can inspect it in the browser. The server does not receive a local output path; the client writes the responses to its own directory.

To inspect just the first request with curl:

curl --fail-with-body http://127.0.0.1:8766/api/documents \
  -H 'Content-Type: application/json' \
  -d '{"format":"smiles","data":"CCO"}'

The response includes an id and revision. Edits such as /embed require the current revision; if another editor changes the drawing, fetch it again instead of silently retrying a stale write. The REST reference lists the routes and conflict responses.

An agent using MCP¶

Create a new ethanol document from SMILES CCO. Report its formula, charge and multiplicity. Generate its 3D geometry, then write a vibe-qc single-point script with B3LYP and def2-SVP into a new example directory. Save the sketch as ethanol.vsk and export ethanol.svg there. Do not submit a calculation.

The corresponding tools are new_document, report, embed_3d, write_inputs, save_document and export. An expected result is C2H6O, charge 0, multiplicity 1 and a nine-atom geometry. The agent should report any refusal or embedding warning before treating the files as ready.

For an optional ORCA input, use --program orca in the CLI or set program to orca in the SDK/REST request. The output then has an .inp extension. The calculation tutorial explains both output formats, with vibe-qc as the main workflow.