Core concepts

Seven nouns carry the whole API, and they form one chain:

• Deployment — solver code plus its data, deployed once under a handle.
• Project — a workspace created from a deployment. Where the work happens.
• Conversation — a thread of messages inside a project.
• Turn — one message, and everything the agent does in response.
• Execution — the record of one solver run.
• Snapshot — the workspace, frozen at the end of a run.
• Tag — a movable name for a snapshot worth keeping.

Deployment

A named bundle of solver code and data, owned by your company. Its handle is <company>/<name>, for example acme/vrp, and comes back as handle on every deployment response. Deploy it once and create as many projects from it as you like.

Its layout is fixed:

Path	Holds
run/	The solver package — its own pyproject.toml and a module under src/solver/
data/	The dataset the solver reads, as ../data/ at solve time

checkDeployment / check_deployment runs that contract server-side and answers ok, missing and warnings. Deploying again syncs: remote files absent locally are pruned after the uploads, so a rename leaves nothing stale.

A deployment can also carry agent config — instructions and skills describing how the agent should operate the model. It is not part of that layout and never appears in the workspace; see Instructions and skills.

Project

A workspace created from a deployment, where Aura does the work. A project created with fromDeployment / from_deployment lands directly in run mode, so you can chat with it immediately.

The project workspace is a live file tree — the deployment’s files plus whatever the agent has since written (solutions/out.json, a dashboard, edited inputs). Read it with listFiles / list_files and readFile / read_file, naming the workspace container.

A project also holds its own copy of its deployment’s agent config, plus any it adds itself. That copy is taken when the project is created, so a later edit to the deployment does not reach projects already running until something pulls it in — a checkout, or pullAgentConfig / pull_agent_config.

Conversation

A thread of messages inside a project. A project can hold several; one is active at a time. Every project gets one when it is created.

A turn is pinned to the conversation it was dispatched to, so two callers on two conversations do not wait on each other’s replies.

Turn

One user message plus everything the agent does in response — tool calls, file writes, solves — ending in one assistant message. Turns are the unit of cancellation.

chat() delivers the turn live over the project WebSocket and returns the completed reply. Where a socket cannot be held open it falls back to dispatch-and-poll, which changes the latency, not the result. Either way it matches the reply on the dispatched message’s sequence number, so a busy conversation cannot hand you someone else’s reply.

A turn outlives your wait

Timing out or aborting stops your waiting, not the turn. The agent keeps working server-side until it finishes or you call cancel(). See Errors.

Execution

One run of the solver, recorded: status, execution_time_ms, output_summary, output_data, and the snapshot it froze. listExecutions / list_executions returns them newest-first, so executions[0] is the latest run.

Snapshot and tag

Every completed solve freezes the project workspace into an immutable snapshot of kind solve; you can also capture one on demand, kind manual. A snapshot records the files, the execution it came from, and its solution_path.

A snapshot’s label is its title — the name listings show, describing that one frozen state.

A tag is its address — a movable name inside a project, best-known or baseline, accepted anywhere a snapshot id is, so a downstream reader can ask for a name rather than tracking ids.

A label is not a ref

Only a tag resolves to a snapshot. To fetch one by name, tag it — passing a label where a <ref> or source is expected will not find it.

Snapshots age out. One survives pruning if it is labelled, tagged, of kind manual, or the snapshot a project is currently checked out on; the rest are eventually deleted.

Checkout loads a snapshot’s files back into a project’s live workspace. source can be:

source	Means
a1b2c3… or best-known	A snapshot id, or a tag inside this project
acme/vrp	A deployment handle
acme/vrp-demo/best-known	A tag on another project in your company

A snapshot holds the workspace. A project’s agent config is separate from it, and a checkout of a snapshot leaves that config alone.