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
Section titled “Deployment”A named bundle of solver code and data, owned by your company. Its handle is <company>/<name>,
for example acme/vrp. 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 runs that contract server-side and answers { ok, missing, warnings }.
Deploying again syncs: remote files absent locally are pruned after the uploads, so a rename
leaves nothing stale.
Project
Section titled “Project”A workspace created from a deployment, where Aura does the work. A project created with
fromDeployment 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 (run/output/solution.json, a dashboard, edited inputs). Read it with listFiles /
readFile, naming the workspace container.
Conversation
Section titled “Conversation”A thread of messages inside a project. A project can hold several; one is active at a time. Every project seeded from a deployment gets one on first use.
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.
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.
Execution
Section titled “Execution”One run of the solver, recorded: status, execution_time_ms, output_summary,
output_data, and the snapshot it froze. listExecutions returns them newest-first, so
executions[0] is the latest run.
Snapshot and tag
Section titled “Snapshot and tag”Every completed solve freezes the project workspace into an immutable snapshot (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 tag is a movable name for a snapshot inside a project — best-known, baseline — so a
downstream reader can ask for a name rather than tracking ids.
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 |