chemvas 0.25.0

English · 한국어

Chemvas is an open-source drawing tool for reaction schemes that you can rebuild. Every figure comes from an editable .chemvas file (JSON, version 9) and one command, so it can be re-rendered at a journal column width after any change. A script or an AI agent can edit the same file through checked patches instead of rewriting it.

What Chemvas is for

Reproducible publication schemes

• render-document exports SVG, PDF, PNG and CDXML without opening a window, fitted to a column width such as 84 mm or 174 mm.
• check-layout reports common label collisions and content outside the sheet before you export. It does not check every pair of objects.
• The publication recipes build finished figures from a script with a fixed bond length and font size, so every scheme in a manuscript has the same scale.

Agent editing you can check

• inspect-document lists every atom with a stable ID and every bond by its two atom IDs, plus the SHA-256 of the file.
• apply-patch takes a JSON patch of graph operations. It refuses a patch written against different file bytes, can check a patch with --dry-run without writing anything, validates the whole document, and writes to a new file only. The input file is never modified.
• Patches are checked for document structure, not for chemistry: element symbols and valence are not validated. Review the rendered figure before you use it.

Drawing by hand

• The desktop app draws structures, reaction arrows and labels, and provides alignment tools, autosave and session recovery. Drawings saved in the app work with every command above, and the reverse.

Current limits

Chemvas does not replace ChemDraw for file exchange. Inputs that Chemvas cannot represent exactly are refused with an error rather than drawn incorrectly.

• Opens: .chemvas; SVG files that Chemvas exported with Editable Chemvas SVG checked (other SVG files cannot be opened); 2D MOL V2000 files within the subset Chemvas writes (bond orders 1–3, wedge and hash bonds, charges, radicals).
• Refused: CDX/CDXML, SDF and RXN files; MOL files with 3D coordinates, isotopes, aromatic bond type 4 or V3000.

Install

Requires Python 3.12+.

pip install chemvas
chemvas

Drawing, figure export and the script quickstart use this install. Chemvas has no optional chemistry extra.

For local Windows packaging, see the Windows packaging guide.

Quickstart: from a script or agent

chemvas compose-document scheme.json --output scheme.chemvas
chemvas inspect-document scheme.chemvas > inspection.json
chemvas apply-patch scheme.chemvas patch.json --dry-run
chemvas apply-patch scheme.chemvas patch.json --output revised.chemvas
chemvas check-layout revised.chemvas
chemvas render-document revised.chemvas --output scheme.svg --width-mm 174

scheme.json describes atoms, bonds, arrows and notes. patch.json carries the source_sha256 from inspection.json and the operations to apply. Each command writes a new file and refuses to overwrite an existing one, and check-layout exits with status 1 when it finds warnings. The formats and a worked example with images are in the Agent CLI guide.

Quickstart: in the desktop app

1. Choose the Ring tool (J) and click the left side of the canvas to place benzene. Choose Bond (X), drag one bond out from a ring atom to a new carbon, then drag a second bond from that carbon to a terminal atom. Hover the terminal atom, press o, then press Enter and set the label to OH.
2. Place a second benzene to the right. Drag one bond out from a ring atom to a new carbon, then drag a second bond from that carbon to a terminal atom. Hover the second bond and press 2 so only that bond becomes a double bond, then hover the terminal atom and press o. Select the Arrow tool, drag between the structures, and double-click the arrow to add condition labels.
3. Select both molecules (Edit ▸ Select All) and align them (Edit ▸ Align ▸ Middle).
4. Save the document (.chemvas). Export via File ▸ Export Figure… → Plain SVG, Fit 2-column (174 mm).

For detailed instructions and example files, see the step-by-step guide.

Documentation

• Browser adapter: experimental web editor available when running from a source checkout (chemvas --ui web); omitted from installable wheel and sdist packages. Web source is experimental for future Leaf integration, not a standalone web product release.

• Headless & Agent CLI · Publication Schemes · Scheme Layout

• Drawing Tools & Shortcuts · MOL interchange · Image Objects · Document compatibility

• Examples: Sample .chemvas documents and the scripts that build the publication figures.

• Architecture · Contributing · Security · Changelog · Releasing · License (MIT)

Feedback and bug reports: GitHub Issues.

How this was built

I'm a chemist, not a programmer. AI coding agents write the code in this repository. I decide what Chemvas should do, record structural decisions as architecture decision records, keep saved drawings under a written compatibility policy, and set the checks a change must pass before it merges.

I don't review the code line by line, so a change is accepted on evidence, not on an agent's report that it works:

• make check runs lint, formatting and type checks, then runs each test file in its own process so Qt state cannot leak from one file into the next. CI runs the same per-file suite.
• Chemvas does not write machine.json. The calculation handoff and its project-local observation snapshot were removed with the chemistry backend (ADR 0055). Another project's decision to adopt a provider is outside this repository.
• High-impact changes, such as the document format, undo and rollback, and figure export, get an independent adversarial review from a separate agent.