# How the AI works

A closer look at the prompts, tools and review loops behind the floor-plan controls.

Source: https://docs.champagne.dev-ukab.fr/fr/ai-flows/how-the-ai-works

Each AI feature combines your input with instructions supplied by Champagne.
For brush editing and plan import, an **agent** works in turns: it chooses an
action, receives the result and decides what to do next.

This page adds a little technical detail to the [user guides](/fr/ai-flows).
The prompt examples are shortened summaries of the instructions used by the app.
The tool examples use illustrative data.

## Prompts: the instructions behind a click [#prompts-the-instructions-behind-a-click]

A **prompt** describes the task and its constraints. Champagne assembles it from
three parts:

* **App instructions:** the drawing style, permitted actions and review requirements.
* **Your input:** the object name, brush guide or uploaded plan image.
* **Current context:** the latest drawing, available resources and results from earlier steps.

Images and labels are treated as reference data. The app supplies the instructions
that control the workflow.

### Generate object [#generate-object]

For an object named "Lounger", the instructions can be summarized as:

> Draw one lounger in a strict top-down view. Preserve its essential structure.
> Use flat light-blue surfaces and thin navy outlines. Keep solid surfaces opaque.
> Use the reserved green background around the object and through genuine gaps.

The image service returns a PNG picture. Champagne removes the green background,
trims the margins and [vectorizes the drawing](/fr/ai-flows/vectorizing) into SVG:
a format that describes shapes with lines and curves. That conversion runs through
image-processing software on the server.

**Generate object** follows this fixed sequence. The brush and import features
use tool-calling loops to make and inspect successive changes.

### Apply changes [#apply-changes]

For a brush guide around a tabletop edge, the instructions can be summarized as:

> Interpret the red guide as an adjustment to the current object. Move the marked
> edge to the suggested outline. Preserve the unmarked details, colors and position.
> Apply the change to the existing shapes, then inspect the rendered result.

The brush agent receives the current SVG, an image of the original object and
the red guide. When **Classify brush intent** is enabled, a separate model first
chooses the operation: inward cut, outward fill, removal, broad reshape or a
combined cut and fill. That decision selects more specific editing instructions.

### Start import [#start-import]

The import instructions can be summarized as:

> Find the drawing area and preserve its proportions. Rebuild the main structure,
> inspect it, then add furniture and fixtures. Use the built-in shapes where they
> fit. Compare the draft with close-up reference views. Record uncertain details
> and submit the result for human review.

The agent also receives the original image dimensions, existing object templates
and reservation resources with their assignment status. This context helps it
place objects and respect existing resource assignments.

## Tools: the actions an agent can request [#tools-the-actions-an-agent-can-request]

A **tool call** is a structured request to Champagne, such as "remove this shape"
or "show me the draft". Each tool accepts a defined set of fields. Champagne
checks the request, carries out the action and supplies the result to the agent.

### Magic brush tools [#magic-brush-tools]

| Tool         | Purpose                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `update_svg` | Change the current drawing using element IDs: set or remove attributes, add a shape, or remove an element and its children |
| `finish`     | Accept the current drawing after its rendered preview has been supplied for inspection                                     |

An **element ID** is a stable name for a part of the drawing, such as an arm or
outline. It lets the agent identify exactly which part to change.

### Plan import tools [#plan-import-tools]

| Tool                | Purpose                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- |
| `register_source`   | Choose the drawing crop and map its image coordinates onto the plan                          |
| `view_reference`    | Inspect a close-up of the original image                                                     |
| `scene_transaction` | Add, update, remove or reorder plan objects, and adjust individual chairs attached to tables |
| `list_objects`      | Read the current objects, scene version, resources and warnings                              |
| `view_objects`      | Render the draft for inspection, optionally overlaid on the reference                        |
| `create_template`   | Generate a library object from its name and an optional shape description                    |
| `finish`            | Submit the draft and review notes for your review                                            |

Image crops use pixels from the original upload. Object positions use coordinates
on the plan canvas. Registration establishes the mapping between those two spaces.

## A brush edit, step by step [#a-brush-edit-step-by-step]

Suppose you scribble over a lounger arm and choose **Apply changes**. The current
SVG contains a group of shapes with the example ID `left-arm`.

1. Champagne prepares the instructions, current SVG, original image and brush guide.
2. The agent identifies the targeted feature and requests `update_svg`.
3. Champagne validates the entire batch, applies it and renders a PNG preview.
4. The next request supplies the updated SVG and PNG alongside the original references.
5. The agent inspects the result. It can request a correction or accept it with `finish`.
6. The accepted version appears in your preview, ready for you to review.

Here are the arguments for the example `update_svg` call:

```json
{
  "operations": [{ "op": "remove", "id": "left-arm" }]
}
```

The result is an updated SVG and its rendered image. Removing the group also
removes its child shapes. The surrounding geometry stays in place.

If validation fails, the batch is rolled back. The next request includes the
unchanged drawing and a description of the failed operation, so the agent can
send a complete corrected batch.

```mermaid
sequenceDiagram
  accTitle: A Magic brush tool call
  accDescr: The user supplies a guide. Champagne gives it to the agent, validates the requested edit and returns a preview for inspection before showing the accepted result.
  actor U as You
  participant C as Champagne
  participant A as Brush agent
  U->>C: Red guide and Apply changes
  C->>A: Instructions, current SVG and reference images
  A->>C: update_svg with removal operation
  C->>C: Validate the batch and render a preview
  alt Edit is valid
    C->>A: Updated SVG and rendered PNG
    A->>C: finish with empty arguments
    C-->>U: Updated preview
  else Edit is rejected
    C->>A: Unchanged SVG and validation error
    A->>C: Corrected update_svg batch
  end
```

The brush agent rebuilds its context around the latest valid drawing at each
step. It has up to eight model calls, including repairs and review, with at most
two successful corrective batches after the initial edit.

## How the import loop progresses [#how-the-import-loop-progresses]

The import agent takes one tool action per turn. A typical sequence is:

1. **Register:** `register_source` returns the drawing crop and coordinate mapping.
2. **Build:** `scene_transaction` adds the main structure and returns object IDs
   and a new scene version.
3. **Inspect:** `view_objects` renders that structure over the reference.
4. **Refine:** `view_reference` reveals smaller details; further transactions add
   furniture and correct placement. The agent checks each table's chair count,
   seating on each side and empty spaces against the source.
5. **Review:** regional views and a final full-scene view support the last checks.
6. **Submit:** `finish` supplies review notes and makes **Use draft** available.

For example, `view_objects` can request a full-scene comparison with these arguments:

```json
{
  "region": null,
  "scale": 1,
  "labels": "none",
  "overlay": true
}
```

Champagne renders the scene, adds a tool response with view information and
remaining time/turns, then supplies the PNG in an image message. The agent can
compare the actual pixels before choosing its next action. These calls and
results accumulate in the import conversation.

Edits include an `expected_version`: the scene version the agent used to prepare
them. Champagne checks it before applying a batch. A successful batch advances
the version and returns stable object IDs for later edits.

For seating adjustments, a `move_chair` operation identifies the table and chair,
then supplies a desired position relative to the table. Champagne finds a safe
position along the table outline and returns the resulting chair positions for
the agent to inspect.

The import has a ten-minute budget and up to 32 tool turns. It requires an early
structural inspection, at least two distinct regional inspections and a final
full view of the latest scene. Your review completes the workflow: check the
notes, choose **Use draft**, adjust the layout and select **Save plan**.