Python API¶

The SDK the browser, the CLI, the REST API and the MCP server are built on. The main modules cover the document model with its file formats, the derivation of species and reactions from the drawing and its clean-up (vibesketch.document.clean), the chemistry services, naming, rendering, the input writers and the server.

Prepare a molecule and an input¶

Run this in the Python environment that has vibe-sketcher installed. It creates a new output directory, so rerunning it cannot replace earlier outputs. No queue or calculation program is needed to prepare these files.

from pathlib import Path

from vibesketch.document import JobSpec, save, write_output
from vibesketch.document.embed import embed
from vibesketch.document.formats import import_into
from vibesketch.inputs import write_input
from vibesketch.render import render_svg

output = Path("ethanol-sdk")
output.mkdir(exist_ok=False)
imported = import_into(None, "CCO", "smiles")
for warning in imported.warnings:
    print(warning)
document, report = embed(imported.document)
for warning in report.warnings:
    print(warning)
if report.failed:
    raise RuntimeError(f"Cannot generate 3D: {report.failed}")

bundle = write_input(
    document,
    species=document.species[0].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"))

The generated Python input requires vibe-qc when you execute it. Writing it neither runs a calculation nor records a queue submission. See runnable examples for a downloadable script.

Choose the operation¶

Task	SDK entry point	Result
Read a native document	`vibesketch.document.load(path)`	A validated `Document` from VSK or QVF
Import chemistry or append it	`vibesketch.document.formats.import_into(document, data, fmt)`	A derivation with `.document` and `.warnings`; pass `None` for a new document
Generate 3D	`vibesketch.document.embed.embed(document)`	An updated document and an `EmbedReport`
Export an exchange format	`vibesketch.document.formats.export(document, fmt)`	A payload with `.content` bytes and `.media_type`
Prepare one input	`vibesketch.inputs.write_input(...)`	An `InputBundle` with text files
Prepare several species	`vibesketch.inputs.write_inputs(...)`	A `Batch` with `.bundles` and per-species `.refused` reasons
Save a native document	`vibesketch.document.save(document, path)`	The written path; the suffix selects QVF or VSK
Save exported bytes	`vibesketch.document.write_output(path, content)`	An atomic write with QVF overwrite protection

Keep the document returned by import, cleanup and embedding operations; do not assume the original object was changed. Embedding keeps existing conformers unless replace=True; inspect both report.failed and report.warnings. Species IDs come from the document, so select an actual ID rather than assuming that a particular molecule is always m1.

SDK functions operate on local objects. They do not update an open browser’s document or automatically advance a server revision. To collaborate with a human in the same drawing, use the REST API or MCP.

Load a document or interpret its drawing¶

load(path) reads and validates a native document. For a VSK file it does not rebuild species from the canvas. Use this when you need the stored model as written, for example when examining saved job records.

import_into(None, data, "vsk") opens a whole document through the chemistry import path. If it has canvas data, that path derives species and reactions again and returns warnings. With an existing document, the default append mode adds the imported drawing; it does not merge the other document’s jobs and provenance. mode="replace" replaces the drawing and its supported chemical contents while retaining the receiving document’s provenance and revision. See species identity for how repeated molecules and removed jobs are handled.

For programmatic drawing changes, use derive and keep its returned document:

from vibesketch.document import Canvas
from vibesketch.document.derive import derive

# `document` is your existing Document; `ket` is the replacement KET object.
updated = document.model_copy(update={"canvas": Canvas(format="ket", data=ket)})
result = derive(updated)
document = result.document
for warning in result.warnings:
    print(warning)

Pydantic’s model_copy(update=...) alone skips validation. Derivation rebuilds and validates the resulting document; use Document.model_validate(...) for other complete model updates. Editing a standalone SDK object still does not publish the change to a running browser session.

Handle failures¶

DocumentError.errors describes invalid native documents; ImportFailed and ExportRefused from vibesketch.document.formats describe unsupported imports and exports. WriterRefusal.reasons explains a refused input; unknown writer or species IDs raise UnknownWriter or UnknownReference. Batch input generation can return usable files alongside refusals, so check .refused even when no exception is raised. For a dry check of a valid specification against one species, call get_writer(name).refusals(species, spec); see capability checks.

SaveRefused protects existing QVF results and unsupported archive content. Choose a different destination rather than discarding the original result. For ordinary VSK outputs, use the expect digest argument to detect external changes; atomic replacement alone does not do so. See file-writing guarantees. See file formats and input writers for the supported chemistry and writer limits.

Module reference¶

`vibesketch.document`	The vibe-sketch document: model, file I/O and JSON schema.
`vibesketch.chem`	Chemistry services on RDKit: reading the canvas, conversion, properties.
`vibesketch.naming`	Names for drawn species, through vibe-qc's naming engine when it is there.
`vibesketch.render`	Publication graphics from the document's drawing.
`vibesketch.inputs`	Input writers: from a document's job to a program's input files.
`vibesketch.queue`	Running calculations through vibe-queue (roadmap WP 2.5).
`vibesketch.viewer`	Showing a species in vibe-view, the family's 3D viewer.
`vibesketch.server`	The FastAPI application behind `vibe-sketch serve`.
`vibesketch.agent`	vibe-sketch for agents: the MCP server and the REST client under it.
`vibesketch.codenames`	Release codename catalogue.
`vibesketch.elements`	Chemical element symbols and atomic numbers, 1 to 118.
`vibesketch.units`	Physical constants for unit conversion.

Returning a viewer geometry¶

Use species_qvf(document, species_id, document_id="drawing-key") to send an origin-bearing structure, then return_geometry(document, returned_bytes, document_id="drawing-key") from vibesketch.document.geometry_return to append its verified conformer. The function returns a new document and raises QvfError on a conflict. See the geometry-return contract for atom mapping and stale revision rules.

Named reactions¶

See the compound, fragment and named-reaction library for the searchable picker, editable examples, explicit unfinished scaffolds, source coverage and matching SDK, CLI, REST and MCP operations.