# AI mode

AI mode helps you create and refine parametric symbols from a written description, drawings or other reference material. You describe the required geometry, dimensions and parameters in the **Symbol assistant** window. The assistant returns a draft, which 3D SymbolDesigner checks before offering **Open in editor**.

Opening a draft creates a new project. You can then inspect its geometry, edit parameters and variants, and use the normal saving and export functions. A validated draft is structurally acceptable to the application; it is not a guarantee that the dimensions, geometry or connections are correct for your intended use.

The screenshots below show the current interface with illustrative example content. Model names shown as placeholders must be replaced with a model available through your chosen service.

![The AI window with the chat area, message field and collapsed Settings panel.](./media/ai-mode-overview.png)

## Opening AI mode

1. Open 3D SymbolDesigner with an AI-enabled licence.
2. On the **Project** tab, select **AI mode** in the **Mode** group.
3. Select **Settings** at the top of the AI window to open the configuration panel on the right.
4. Choose an AI connection and configure it as described below.

Select **Settings** again to hide the panel and give the conversation more space.

If **AI mode** is greyed out, check the active licence mode. The standard **Full** and **Lite** modes do not enable AI construction.

### FullAi and LiteAi

The available construction features follow your licence; the AI window does not override them.

| Mode | Available construction features |
| --- | --- |
| **FullAi** | The supported AI construction features, including specialised ports, connectors and valve operators. |
| **LiteAi** | Supported general geometry and parametric construction, without the specialised objects listed below. |

LiteAi cannot generate cable, cable tray, conduit, foundation, hanger, HVAC or piping **connectors** or **ports**, or a **ValveOperator**. These restrictions apply to objects inside assemblies and repeated geometry as well. You can ask for an alternative made from ordinary solid primitives, but such geometry does not provide the behaviour of a specialised connection object.

## Choosing an AI connection

Two connection methods are available under **Settings → AI connection**.

| Connection | How it works | What you need |
| --- | --- | --- |
| **Direct API** | SymbolDesigner sends your request to the configured model endpoint and displays the response. | A running local model service or access to a compatible API. An API key is required if that service requires one. |
| **MCP (external AI client)** | A local AI client retrieves your prepared task from SymbolDesigner and sends a draft back. | A client that can connect to a local MCP server using Streamable HTTP and a Bearer authorisation header. Its account and usage limits apply. |

Direct API is also the connection method for SymbolDesigner's built-in analysis of zipped OBJ references. In MCP mode, you control the modelling conversation in the external client.

## Setting up Direct API

![Direct API settings on the right, showing protocol, model, endpoint, API key and generation options.](./media/ai-mode-direct-api.png)

1. Set **AI connection** to **Direct API**.
2. Select the **Protocol** supported by your service.
3. Enter the service's exact **Model** identifier. The model must already be available to that service or account.
4. Check the complete **Endpoint** address, including its API path.
5. Enter the **API key** if required. Leave it blank only when your service permits requests without a key.
6. Check **Maximum parts** and **Auto-solve issues**.

Changing **Protocol** also changes the suggested endpoint. Check the address again if you use a custom service.

| Protocol | Example endpoint | Attachment support in this connection |
| --- | --- | --- |
| **Ollama** | `http://localhost:11434/api/chat` | Text and images, provided the chosen model can interpret images. PDF and other document attachments are not supported by this protocol. |
| **OpenAI-compatible** | `http://localhost:1234/v1/chat/completions` | Text, images and PDF requests, subject to the endpoint's and model's capabilities. Other document types require the Responses protocol. |
| **OpenAI Responses** | `https://api.openai.com/v1/responses` | Text, images and document inputs, subject to the endpoint's and model's capabilities. |

These are example addresses, not services installed or started by SymbolDesigner. For a local service, start the service and make the required model available before sending a request. External endpoints must use HTTPS; HTTP is permitted for local loopback services.

Connection and generation settings are saved for reuse. The **API key** is not saved to the configuration file, so enter it again when required after reopening the window.

### Maximum parts

**Maximum parts** limits the size of the generated draft. The default is **200**, and the supported setting is **1–10,000**. Assemblies and expanded repetitions also count towards the construction budget, so a repeated pattern can reach the limit even when the description is short.

Start with a manageable model. If the draft exceeds the limit, ask the assistant to simplify it or reduce the number of repeated items. Increase the setting only when you need the additional detail.

### Auto-solve issues

With **Auto-solve issues** enabled, SymbolDesigner can send validation errors back to the model and request a corrected draft. It attempts up to three corrections and shows the correction messages in the conversation.

Each correction makes another model request and may use additional service quota or incur charges. This option addresses draft-validation problems; it does not repair an invalid API key, an unavailable endpoint or an exhausted service quota. Select **Cancel** to stop the current operation.

## Creating your first symbol

1. Enter a clear request in **Message**.
2. Include the main dimensions and their units, the intended orientation and the dimensions that should remain editable.
3. Add any reference files if needed.
4. Select **Send**, or press **Enter**. Use **Shift+Enter** to insert a new line without sending.
5. Read the response. If the assistant asks for missing information, answer in the same conversation.
6. When a draft is ready, select **Open in editor** and check the new project.

For example:

> Create a vertical cylindrical vessel, 1.8 m high and 1.2 m in diameter. Make the height and diameter editable parameters. Use a blue body. Do not add nozzles or supports. Ask me before assuming any additional dimensions.

For a more controlled result, specify:

- The required solids, openings and assemblies.
- Units, the coordinate origin and the direction of the main axis.
- Which dimensions are fixed and which should be parameters.
- Any required variants, colours or transparency.
- Whether ports or connectors are required, including their dimensions and directions where known.
- What should be left out or reported as uncertain.

Use explicit units such as `mm`, `m` or `deg`. A photograph or an OBJ file alone does not establish a reliable real-world scale.

## Watching progress and cancelling

![An illustrative request with a waiting status, a short assistant update and the live elapsed-time display.](./media/ai-mode-progress.png)

While an operation is running, the status area shows the current activity and **Elapsed** time. After it finishes or is cancelled, **Duration** shows the measured time. Hours are included for longer operations.

The timer measures the whole operation, including network waiting, local reference processing, tool execution and validation. It is not a measurement of the model provider's internal computing time.

The conversation can show time-stamped progress entries for local tools and short intermediate messages supplied by the assistant. These remain in the conversation after the final response. Intermediate messages depend on the model or external client supplying them; responses are not displayed as a continuous word-by-word stream.

Select **Cancel** to stop waiting for the current result. For a cancelled Direct API request, the current input and pending attachments are retained so that you can revise or resend them. Cancellation does not undo a draft that you have already opened in the editor.

## Reviewing and refining a draft

![An illustrative validated vessel draft with editable dimensions and the Open in editor button.](./media/ai-mode-draft.png)

**Open in editor** is offered for a successfully validated draft. A clarification question or an invalid response does not provide an editable draft.

After opening a draft:

1. Check the overall shape, scale, orientation and placement.
2. Inspect the dimensions and formulas in the project tree.
3. Change the main parameters and check that the geometry and parameter handles behave as intended.
4. Check any variants, openings and connection directions relevant to your symbol.
5. Save the project and use the normal export workflow when it is ready.

You can also continue in the AI conversation. For example:

> Increase the vessel height to 2.4 m, keep the diameter unchanged and add a second variant with a height of 1.8 m. Preserve the existing parameter names and colour.

Each revised draft has its own **Open in editor** button. Opening a revision creates another new project rather than replacing an existing document. If you edit a project manually, describe those changes in your next request; the chat does not automatically synchronise edits made in the project tree.

Use **Copy** on a message to copy its text. **New chat** clears the conversation and pending attachments. Start a new chat for an unrelated symbol or when the conversation becomes too long. A chat supports up to **12 requests**. Changing the model, endpoint or construction mode starts a fresh conversation context on the next Direct API request.

## Using drawings and documents

In Direct API mode, select **Add files…** or drag files onto the AI window. Pending attachment names appear below the message field. Use **Remove files** to clear the pending attachments before sending.

The file picker accepts images, PDF files, common office documents, spreadsheets, text files and OBJ ZIP archives. Acceptance by the file picker does not mean that every model or protocol can interpret that file type.

| Limit or requirement | Details |
| --- | --- |
| Pending attachments | Up to four files per message. |
| Ordinary attachment size | Up to 8 MiB per file. OBJ ZIP archives are handled separately. |
| Images | Non-animated PNG, JPEG, WebP or GIF, with no more than 40 megapixels. |
| Document interpretation | Choose a protocol and model that support the document type. Use the Responses protocol for non-PDF documents. |
| Conversation size | Large attachment histories can reach a separate request budget. Start a new chat with only the references needed for the next step. |

Explain how each reference should be used. For example:

> Use the attached drawing for the overall dimensions and the spreadsheet for the three size variants. The dimensions in both files are in millimetres. Report any conflicts before generating the symbol.

## Using a zipped OBJ reference

Prepare a ZIP archive containing at least one `.obj` file. Include its `.mtl` files and textures if they are available, preserving the relative paths used by the OBJ and material files. Attach the ZIP through **Add files…** in Direct API mode; a standalone OBJ is not the attachment format used here.

SymbolDesigner imports this reference locally. The assistant can request rendered views, geometry measurements and selected file information before constructing the symbol. The complete ZIP is not sent as an ordinary file attachment to the model; requested views, measurements and excerpts can be sent to the configured service.

Include the known units and orientation in your request. For example:

> The attached OBJ uses metres, with Z pointing upwards. First reconstruct only the main horizontal vessel and its two supports. Measure the vessel axis and diameter across OBJ groups, report the fit quality and compare the proposed geometry with the reference. Do not infer hidden connections or add unmeasured details.

For large or scanned references:

- Begin with one identifiable component or a small area, then work outwards.
- Treat OBJ groups as possible scan tiles, not necessarily separate components.
- Ask for measurements, fit quality and a comparison with the reference rather than a visual approximation alone.
- Ask the assistant to distinguish observed geometry from assumptions and missing scan data.
- Leave ambiguous branches, hidden connections and poorly supported dimensions unresolved until you have better evidence.

The local inspection tools can select spatial regions, fit primitive surfaces, compare proposed geometry with the reference and inspect rendered views. An image-capable model is needed to interpret those views; a text-only model must rely on numerical information.

OBJ ZIP archives are not subject to the ordinary 8 MiB attachment limit. Large archives still require sufficient local memory and processing time, and the model service has its own request and context limits. If an inspection reaches its step or history limit, request a more focused area or start a new chat with a smaller reference.

## Using an external AI client through MCP

![MCP settings, including the local port, Start server button and Prepare task action.](./media/ai-mode-mcp.png)

MCP allows a compatible local AI client to work with the SymbolDesigner window. You do not enter that client's model API key in SymbolDesigner. Access to the model, authentication and usage limits are managed by the external client and its service.

1. Open **Settings** and select **MCP (external AI client)** under **AI connection**.
2. Check **Local MCP port**. The default is **18743**. Choose another available port if necessary.
3. Select **Start server**.
4. Select **Copy connection**. In your AI client, configure an MCP connection using the copied Streamable HTTP URL and Bearer authorisation header.
5. Enter your modelling request in the SymbolDesigner **Message** field and select **Prepare task**.
6. Ask the connected AI client to retrieve the task and return a draft. For example:

   > Use the SymbolDesigner `get_task` tool. Follow the returned task and symbol requirements, report brief progress updates with `report_progress`, then return the complete draft with `submit_draft`.

7. Read the result in the SymbolDesigner window. If validation succeeds, select **Open in editor**.

If SymbolDesigner rejects the draft, the external client can correct and resubmit it for the same active task. If you cancel, replace the task or restart the server, the client must retrieve the current task again. Old submissions and progress messages are rejected.

Attach drawings or documents in the external client when using MCP; **Add files…** is disabled in the SymbolDesigner window in this mode. Such attachments are handled by that client. They do not automatically activate SymbolDesigner's local OBJ inspection workflow.

The server listens on a local loopback address. A cloud-only client cannot connect directly to this address. The client must support access to the local server and the required authorisation header. The copied connection details contain a temporary secret: keep them private and copy fresh details after restarting the server. Closing the AI window stops the server; **Stop server** stops it without closing the window.

## Troubleshooting

| Symptom | What to check or do |
| --- | --- |
| **AI mode** is disabled | Check that the active licence mode includes AI construction. |
| No connection or no response | Check the complete endpoint, selected model and API key. For a local service, check that it is running. Cancel and retry if appropriate. |
| The service rejects a file | Check both the protocol and the model's attachment capabilities. Remove unsupported files or use a compatible connection. |
| An image is rejected | Check its size, pixel count, actual file format and whether it is animated. |
| A ZIP is rejected | Confirm that it contains at least one OBJ file and is a readable ZIP archive. |
| The symbol has the wrong scale or orientation | State the source units, coordinate origin and axis directions explicitly; ask for a corrected draft and inspect it in the editor. |
| Validation fails repeatedly | Read the validation message, simplify the request and clarify dimensions or relationships. Check the part limit and licence restrictions. |
| A request or token rate limit is reported | Wait for the suggested interval where one is provided, or reduce the request and attachment history. |
| API quota or billing is exhausted | Check the account or project limits with your model provider. Repeating the unchanged request will not restore quota. |
| The conversation or reference inspection limit is reached | Start a new chat or narrow the reference area. Copy any important measurements and requirements into the new request. |
| MCP cannot start | Check whether the port is already in use and choose another available local port. |
| The MCP client cannot connect | Check local-server support, Streamable HTTP, the copied URL and the current authorisation header. Cloud-only access is insufficient for a loopback endpoint. |
| An MCP response is no longer accepted | Retrieve the current task again after cancellation, task replacement or server restart. |
| No intermediate AI messages appear | The provider or client may not supply them. In MCP mode, ask the client to use `report_progress`. The elapsed-time display continues independently. |

## Reference data and service usage

Choose a service appropriate for the information you are working with. In Direct API mode, prompts, conversation content and ordinary attachments are sent to the configured endpoint. For locally imported OBJ archives, requested derived views, measurements and excerpts may also be sent. In MCP mode, the external client controls its model connection and any files attached there.

Check your organisation's rules before using confidential drawings or plant data with an external service. Local OBJ processing alone does not mean that all information remains on the computer. Keep API keys and copied MCP connection secrets out of prompts, screenshots and shared documents.

AI drafts still require engineering review. Check the finished symbol against your dimensions, reference material and target-system requirements before using or exporting it.