Snapshots and tags

Every completed solve freezes the project workspace into an immutable snapshot, so the state that produced a given result stays available after the next turn changes things.

Listing history

Newest first, and each row carries what it came from.

TypeScript
Python

const snapshots = await aura.listSnapshots(project.id);

for (const snapshot of snapshots) {
  console.log(snapshot.id, snapshot.kind, snapshot.label ?? "—", snapshot.solution_summary);
}

snapshots = await aura.list_snapshots(project.id)

for snapshot in snapshots:
    print(snapshot.id, snapshot.kind, snapshot.label or "—", snapshot.solution_summary)

kind is "solve" for the automatic ones and "manual" for a snapshot someone captured on demand. solution_path names the file inside the snapshot that holds the solution; execution_id links back to the execution that produced it.

Fetching one, by id or tag

getSnapshot takes either — a raw id, or a tag name defined in the same project.

TypeScript
Python

const byId = await aura.getSnapshot(project.id, "3f1c…");
const byTag = await aura.getSnapshot(project.id, "best-known");

console.log(byTag.file_count, byTag.total_size_bytes);
for (const file of byTag.files) console.log(file.path, file.size);

by_id = await aura.get_snapshot(project.id, "3f1c…")
by_tag = await aura.get_snapshot(project.id, "best-known")

print(by_tag.file_count, by_tag.total_size_bytes)
for file in by_tag.files:
    print(file.path, file.size)

The detail response includes files; the list response does not — list is a summary.

Naming a good run

A tag is a movable name for a snapshot inside a project. Point it at a new snapshot and the name follows.

TypeScript
Python

const [latest] = await aura.listSnapshots(project.id);
await aura.setTag(project.id, "best-known", latest.id);

const tags = await aura.listTags(project.id);

latest = (await aura.list_snapshots(project.id))[0]
await aura.set_tag(project.id, "best-known", latest.id)

tags = await aura.list_tags(project.id)

A nightly job can re-solve, compare, and move best-known only when it improves; everything downstream asks for the name rather than tracking ids.

Loading one back — checkout

Checkout replaces a project’s live workspace with the files from a source. source can be:

`source`	Resolves to
`3f1c…`	A snapshot id in this project
`best-known`	A tag in this project
`acme/vrp`	A deployment handle — reset to the deployed starting point
`acme/vrp-demo/best-known`	A tag on another project in your company

TypeScript
Python

// go back to the best run so far
const basis = await aura.checkout(project.id, "best-known", conversationId);
console.log(basis.kind, basis.file_count);   // "snapshot", 42

// or start over from the deployment
await aura.checkout(project.id, "acme/vrp", conversationId);

basis = await aura.checkout(project.id, "best-known", conversation_id=conversation_id)
print(basis.kind, basis.file_count)          # "snapshot", 42

await aura.checkout(project.id, "acme/vrp", conversation_id=conversation_id)

Pass the conversation id to attribute the checkout to that conversation, so the agent sees the workspace change in context.

Capturing a snapshot on demand, renaming one, and reading or deleting a tag by name are REST endpoints you can call directly.