vibesketch.document.model¶

The vibe-sketch document, schema version 1.

A .vsk file is one JSON object. It carries the canvas state verbatim, in the engine’s own format (KET), so a drawing survives a round trip without loss, and a normalized layer the compute side reads: species with their identifiers, charge, multiplicity and 3D conformers; reactions with roles, arrows and conditions; program-neutral job specifications; the figure style; and provenance. The design is roadmap section 3.1; docs/document.md describes every field.

The model is strict. Unknown fields are refused rather than ignored, and the cross-references (a reaction’s species, a job’s species) must resolve, so an agent that writes a document gets told what is wrong instead of having its data silently dropped. schema/vibe-sketch-1.schema.json is generated from these classes (vibe-sketch schema) and must not be edited by hand.

Module Attributes

`SCHEMA_ID`	The value of a version-1 document's `schema` field.
`Arrow`	The arrows a reaction can carry (roadmap WP 3.1).
`Task`	the structure only.

Classes

`Canvas`(*, format[, data])	The drawing as the canvas engine stores it, embedded verbatim.
`Conformer`(*, method, symbols, xyz_angstrom)	One 3D structure of a species: element symbols and Cartesian coordinates.
`Constraint`(*, kind, atoms[, value])	A coordinate an optimisation holds fixed.
`Document`(*[, schema, revision, canvas, ...])	A vibe-sketch document, schema version 1.
`Edit`(*, revision, at, actor[, client])	One revision of the document: who changed it, through what, and why.
`Job`(*, id, species, program, spec[, runs])	A calculation to run on one species with one program.
`JobSpec`(*, task[, method, basis, aux_basis, ...])	A program-neutral description of a calculation.
`Name`(*, value, source, confidence)	A name for a species, with where it came from and how sure it is.
`Provenance`(*, app[, created, edits])	Where the document came from.
`Reaction`(*, id, reactants[, reagents, ...])	One step of a scheme: who reacts, under which conditions, to give what.
`Resources`(*[, nprocs, maxcore_mb])	What a job may use on the machine that runs it.
`Run`(*[, queue, host])	One submission of a job to a queue.
`Solvent`(*, model, name)	An implicit solvation model and the solvent it describes.
`Species`(*, id[, label, smiles, inchikey, ...])	A molecule or ion that appears in the drawing.
`Style`(*[, preset])	How exported figures look.

vibesketch.document.model.SCHEMA_ID: Final = 'vibe-sketch/1'¶: The value of a version-1 document’s schema field.

vibesketch.document.model.Arrow¶

The arrows a reaction can carry (roadmap WP 3.1).

alias of Literal[‘forward’, ‘equilibrium’, ‘retrosynthetic’, ‘resonance’]

class vibesketch.document.model.Canvas(*, format, data=<factory>)¶

Bases: _Strict

The drawing as the canvas engine stores it, embedded verbatim.

Parameters:

format (Literal['ket'])
data (dict[str, JsonValue])

format: Literal['ket']¶

data: dict[str, JsonValue]¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Conformer(*, method, symbols, xyz_angstrom)¶

Bases: _Strict

One 3D structure of a species: element symbols and Cartesian coordinates.

Parameters:

method (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z0-9][a-z0-9_.:+-]{0,63}$, ascii_only=None)])
symbols (Annotated[list[str], MinLen(min_length=1)])
xyz_angstrom (list[list[float]])

method: _Token¶

symbols: list[str]¶

xyz_angstrom: list[list[float]]¶

electron_count(charge)¶

Electrons in the neutral atoms, less the charge.

Parameters:: charge (int)
Return type:: int

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Constraint(*, kind, atoms, value=None)¶

Bases: _Strict

A coordinate an optimisation holds fixed.

Atoms are 0-based indices into the species’ conformer: the drawing’s atoms first, then the hydrogens.

Parameters:

kind (Literal['distance', 'angle', 'dihedral', 'position'])
atoms (list[Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])]])
value (float | None)

kind: Literal['distance', 'angle', 'dihedral', 'position']¶

atoms: list[Annotated[int, Field(ge=0)]]¶

value: float | None¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Document(*, schema='vibe-sketch/1', revision=0, canvas=<factory>, species=<factory>, reactions=<factory>, jobs=<factory>, style=<factory>, provenance)¶

Bases: _Strict

A vibe-sketch document, schema version 1.

Parameters:

schema (Literal['vibe-sketch/1'])
revision (Annotated[int, Ge(ge=0)])
canvas (Canvas)
species (list[Species])
reactions (list[Reaction])
jobs (list[Job])
style (Style)
provenance (Provenance)

model_config = {'extra': 'forbid', 'json_schema_extra': {'description': 'A .vsk file: a drawing and what to compute from it.'}, 'populate_by_name': True, 'title': 'vibe-sketch document', 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

schema_id: Literal['vibe-sketch/1']¶

revision: int¶

canvas: Canvas¶

species: list[Species]¶

reactions: list[Reaction]¶

jobs: list[Job]¶

style: Style¶

provenance: Provenance¶

species_by_id(identifier)¶

The species with identifier; raises KeyError when there is none.

Parameters:: identifier (str)
Return type:: Species

job_by_id(identifier)¶

The job with identifier; raises KeyError when there is none.

Parameters:: identifier (str)
Return type:: Job

to_json_data()¶

The document as JSON-compatible data, in the field order of the schema.

Unset optional fields are left out; the canvas data is kept exactly as it came, nulls included.

Return type:: dict[str, Any]

class vibesketch.document.model.Edit(*, revision, at, actor, client=None, summary)¶

Bases: _Strict

One revision of the document: who changed it, through what, and why.

Parameters:

revision (Annotated[int, Ge(ge=1)])
at (AwareDatetime)
actor (Literal['human', 'agent', 'system'])
client (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z0-9][a-z0-9_.:+-]{0,63}$, ascii_only=None)] | None)
summary (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])

revision: int¶

at: AwareDatetime¶

actor: Literal['human', 'agent', 'system']¶

client: _Token | None¶

summary: _Text¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Job(*, id, species, program, spec, runs=None)¶

Bases: _Strict

A calculation to run on one species with one program.

Parameters:

id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
species (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
program (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z0-9][a-z0-9_.:+-]{0,63}$, ascii_only=None)])
spec (JobSpec)
runs (list[Run] | None)

id: _Identifier¶

species: _Identifier¶

program: _Token¶

spec: JobSpec¶

runs: list[Run] | None¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.JobSpec(*, task, method=None, basis=None, aux_basis=None, approximation=None, dispersion=None, solvent=None, states=None, constraints=None, resources=None)¶

Bases: _Strict

A program-neutral description of a calculation.

Writers translate it into one program’s input and refuse, with a reason, whatever they cannot express (AGENTS.md, ground rule 5). The model only checks that the specification is consistent in itself.

Parameters:

task (Literal['geometry', 'sp', 'opt', 'freq', 'opt+freq', 'tddft', 'nmr'])
method (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9()+*/,_.-]{0,63}$, ascii_only=None)] | None)
basis (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9()+*/_.-]{0,63}$, ascii_only=None)] | None)
aux_basis (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9()+*/_.-]{0,63}$, ascii_only=None)] | None)
approximation (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9()_-]{0,31}$, ascii_only=None)] | None)
dispersion (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9()_-]{0,31}$, ascii_only=None)] | None)
solvent (Solvent | None)
states (Annotated[int | None, Ge(ge=1), Le(le=200)])
constraints (list[Constraint] | None)
resources (Resources | None)

task: Task¶

method: _MethodName | None¶

basis: _BasisName | None¶

aux_basis: _BasisName | None¶

approximation: _Keyword | None¶

dispersion: _Keyword | None¶

solvent: Solvent | None¶

states: int | None¶

constraints: list[Constraint] | None¶

resources: Resources | None¶

static calculation_fields()¶

The fields that only mean something for a calculation.

Return type:: tuple[str, …]

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Name(*, value, source, confidence)¶

Bases: _Strict

A name for a species, with where it came from and how sure it is.

Parameters:

value (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])
source (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z0-9][a-z0-9_.:+-]{0,63}$, ascii_only=None)])
confidence (Literal['high', 'medium', 'low'])

value: _Text¶

source: _Token¶

confidence: Literal['high', 'medium', 'low']¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Provenance(*, app, created=<factory>, edits=<factory>)¶

Bases: _Strict

Where the document came from.

Parameters:

app (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)])
created (AwareDatetime)
edits (list[Edit])

app: _Text¶

created: AwareDatetime¶

edits: list[Edit]¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Reaction(*, id, reactants, reagents=<factory>, products, arrow='forward', conditions=<factory>, yield_=None)¶

Bases: _Strict

One step of a scheme: who reacts, under which conditions, to give what.

Parameters:

id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
reactants (Annotated[list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)]], MinLen(min_length=1)])
reagents (list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)]])
products (Annotated[list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)]], MinLen(min_length=1)])
arrow (Literal['forward', 'equilibrium', 'retrosynthetic', 'resonance'])
conditions (list[Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)]])
yield_ (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)

id: _Identifier¶

reactants: list[_Identifier]¶

reagents: list[_Identifier]¶

products: list[_Identifier]¶

arrow: Arrow¶

conditions: list[_Text]¶

yield_: _Text | None¶

species_ids()¶

Return type:: list[str]

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Resources(*, nprocs=1, maxcore_mb=None)¶

Bases: _Strict

What a job may use on the machine that runs it.

Parameters:

nprocs (Annotated[int, Ge(ge=1)])
maxcore_mb (Annotated[int | None, Ge(ge=1)])

nprocs: int¶

maxcore_mb: int | None¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Run(*, queue='vibe-queue', host='localhost', id, submitted)¶

Bases: _Strict

One submission of a job to a queue.

Parameters:

queue (Literal['vibe-queue'])
host (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$, ascii_only=None)])
id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9_-]{1,64}$, ascii_only=None)])
submitted (AwareDatetime)

queue: Literal['vibe-queue']¶

host: Annotated[str, StringConstraints(pattern='^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$')]¶

id: Annotated[str, StringConstraints(pattern='^[A-Za-z0-9_-]{1,64}$')]¶

submitted: AwareDatetime¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Solvent(*, model, name)¶

Bases: _Strict

An implicit solvation model and the solvent it describes.

Parameters:

model (Literal['CPCM', 'SMD'])
name (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z0-9][A-Za-z0-9 ,()'-]{0,63}$, ascii_only=None)])

model: Literal['CPCM', 'SMD']¶

name: _SolventName¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Species(*, id, label=None, smiles=None, inchikey=None, charge=0, multiplicity=1, name=None, conformers=<factory>)¶

Bases: _Strict

A molecule or ion that appears in the drawing.

Parameters:

id (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Za-z][A-Za-z0-9_-]{0,63}$, ascii_only=None)])
label (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=1, max_length=500, pattern=None, ascii_only=None)] | None)
smiles (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^\S+$, ascii_only=None)] | None)
inchikey (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[A-Z]{14}-[A-Z]{10}-[A-Z]$, ascii_only=None)] | None)
charge (int)
multiplicity (Annotated[int, Ge(ge=1)])
name (Name | None)
conformers (list[Conformer])

id: _Identifier¶

label: _Text | None¶

smiles: _Smiles | None¶

inchikey: _InChIKey | None¶

charge: int¶

multiplicity: int¶

name: Name | None¶

conformers: list[Conformer]¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class vibesketch.document.model.Style(*, preset='acs-1996')¶

Bases: _Strict

How exported figures look.

Parameters:: preset (Annotated[str, StringConstraints(strip_whitespace=None, to_upper=None, to_lower=None, strict=None, min_length=None, max_length=None, pattern=^[a-z0-9][a-z0-9_.:+-]{0,63}$, ascii_only=None)])

preset: _Token¶

model_config = {'extra': 'forbid', 'populate_by_name': True, 'validate_assignment': True}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibesketch.document.model.Task¶

the structure only.

Type:: What a job computes. geometry is no calculation

alias of Literal[‘geometry’, ‘sp’, ‘opt’, ‘freq’, ‘opt+freq’, ‘tddft’, ‘nmr’]