vibesketch.document.campaign

Compile a saved recipe into a vibe-queue campaign, and follow it (#42).

A recipe (vibesketch.document.model.Recipe) becomes a vq.campaign/1 file in a directory of its own, with every node’s sources pinned, which vq campaign run runs: vibe-queue’s controller owns submission, idempotency, attempts, retries and verified artifacts, and its journal is the record of what ran (see vibe-queue’s docs/campaigns.md).

Per species and per numerical stage there are two nodes:

  • <species>-<stage>-run, a compute node: the stage’s pending QVF job container (vibesketch.document.qvf.stage_container()) and the stage driver (vibesketch.stages.driver), which starts from start/geometry.json and runs vibe-qc’s container runner. Its outputs are result.qvf and runner.log.

  • <species>-<stage>-check, a validate node: the validator (vibesketch.stages.validator) judges result.qvf and publishes accepted/ (verdict.json, the accepted result.qvf and, for an optimisation, geometry.json), or fails.

A stage that starts from an earlier stage’s geometry takes the accepted artifact of that stage’s check node as its start input, a success edge, so it can only ever start from a validated geometry of a succeeded producer attempt, bound by vibe-queue to that attempt and manifest. A stage whose parent is not its geometry source also waits for the parent’s check node to succeed. A stage that starts from the sketch’s prepared conformer finds it in its sources, written here; the prepare stage itself is the sketch’s own preparation and compiles to no node.

The campaign is immutable: it is compiled into a new directory, never over an existing one, and its record on the recipe names the directory, vibe-queue’s digest of it and which node is which. A MACE model’s licence is acknowledged here, by the operator compiling the campaign; the acknowledgement goes into the compiled stage containers, never into the recipe.

Module Attributes

DEFAULT_PYTHON

The run command's interpreter on a node's host, and vibe-qc's container runner.

Functions

campaign_report(document, recipe_id, campaign_id)

Where a compiled campaign stands: process state and scientific acceptance, apart.

compile_campaign(document, recipe_id, ...[, ...])

Compile recipe_id into a vibe-queue campaign in directory.

discard_output(target, existed)

Undo a failed write into target, which was checked new or empty beforehand.

inside(root, relative, what)

root / relative, refused unless it stays inside root.

retry_node(document, recipe_id, campaign_id, ...)

Authorise the next attempt of a failed node; returns its attempt number.

source_digest(root)

vibe-queue's pin of a node's sources directory (vq.campaign-sources/1).

Classes

Compiled(document, record[, warnings])

A compiled campaign: its record, the document that keeps it, and notes.

Exceptions

CampaignRefused(reasons)

The recipe cannot be compiled as asked; the reasons say why.

CampaignUnavailable

vibe-queue is not installed here, so its journal cannot be read.

UnknownCampaign

The recipe has no campaign with that id.
exception vibesketch.document.campaign.CampaignRefused(reasons)[source]

Bases: ValueError

The recipe cannot be compiled as asked; the reasons say why.

Parameters:

reasons (list[str])

Return type:

None

exception vibesketch.document.campaign.CampaignUnavailable[source]

Bases: RuntimeError

vibe-queue is not installed here, so its journal cannot be read.

class vibesketch.document.campaign.Compiled(document, record, warnings=<factory>)[source]

Bases: object

A compiled campaign: its record, the document that keeps it, and notes.

Parameters:
document: Document
record: CampaignRecord
warnings: list[str]
property run_command: str[source]
exception vibesketch.document.campaign.UnknownCampaign[source]

Bases: KeyError

The recipe has no campaign with that id.

vibesketch.document.campaign.campaign_report(document, recipe_id, campaign_id)[source]

Where a compiled campaign stands: process state and scientific acceptance, apart.

Per species and stage: the run node’s and the check node’s state in vibe-queue’s journal (waiting, ready, running, succeeded, failed, blocked …), their attempts with what each retried, and acceptance: accepted with the verdict (review notes, energy, frequencies, the software that ran) once the check node’s artifact is verified, rejected when the check failed, not run when the run itself failed, else pending. Raises CampaignUnavailable without vibe-queue.

Parameters:
Return type:

dict[str, Any]

vibesketch.document.campaign.compile_campaign(document, recipe_id, directory, *, campaign_id=None, host=None, program='vibeqc', python='python3', runner=None, cpus=1, mem_mb=None, accept_model_license=False)[source]

Compile recipe_id into a vibe-queue campaign in directory.

directory must not exist or be empty. host and program are the vibe-queue host and program the compute nodes run on (the program whose interpreter python is); runner is the container runner’s command, {python} standing for the node’s interpreter. A recipe with a MACE stage needs accept_model_license: the operator compiling the campaign acknowledges the model’s licence. Raises CampaignRefused with every reason the recipe cannot run: refused stages, species without a prepared conformer, an unacknowledged licence, ids too long for vibe-queue, a directory in use.

Parameters:
Return type:

Compiled

vibesketch.document.campaign.retry_node(document, recipe_id, campaign_id, node)[source]

Authorise the next attempt of a failed node; returns its attempt number.

vibe-queue records the attempt as retrying the failed one, staged from the producers’ verified artifacts and under its own idempotency key; the next vq campaign run sends it. Raises CampaignRefused when the node is not a failed node of the campaign, and CampaignUnavailable without vibe-queue.

Parameters:
Return type:

int

vibesketch.document.campaign.source_digest(root)[source]

vibe-queue’s pin of a node’s sources directory (vq.campaign-sources/1).

Every entry’s relative path and type, and each file’s size and SHA-256, in name order, digested as canonical JSON: the algorithm of vibe-queue’s vq.campaign.source_digest, which a contract test checks when vibe-queue is installed. Links and special files are refused.

Parameters:

root (Path)

Return type:

str