AI Assistant

The SØAD IDE includes an AI assistant that builds and edits transactions for you from a plain-language description. You tell it what you want — "create a contact CRUD", "add an email field to the signup form", "why is the invoice page throwing an error?" — and it uses the same building blocks you do (transactions, views, the database schema) to do the work.

Nothing it produces is written to your application until you review a diff and click Approve & Execute. The assistant proposes; you decide.

Enabling the assistant

The assistant talks to an OpenAI-compatible chat model that you provide (bring-your-own-key). It works with OpenAI, Azure OpenAI, OpenRouter, and local servers such as Ollama, vLLM and LM Studio — anything that exposes a /chat/completions endpoint.

You configure three things:

Setting	Description	Example
Endpoint	The provider's base URL (`/chat/completions` is appended automatically)	`https://api.openai.com/v1`
API key	Your provider key	`sk-…`
Model	The model name to use	`gpt-4o-mini`

There are two ways to set them.

From the IDE (self-hosted)

Open the assistant panel, go to Provider settings (superadmin only), fill in the endpoint, API key and model, and save. This is the quickest way on a self-hosted instance.

From configuration / environment (managed)

Set them in sufia.properties or as environment variables — the usual way to inject config in a container or Kubernetes deployment.

Property	Environment variable
`ai.provider`	`ai_provider`
`ai.endpoint`	`ai_endpoint`
`ai.api.key`	`ai_api_key`
`ai.model`	`ai_model`

ai.provider is the default provider family (defaults to openai) and can be overridden by the environment or by the in-IDE setting. When the same value is set in more than one place, the order of precedence is:

in-IDE Provider settings → environment variable → sufia.properties → built-in default.

Note

If the assistant reports that it is not configured, no endpoint / key / model has been resolved from any of the sources above.

Opening the assistant

Open a transaction in the editor and click the AI button in the toolbar to slide out the chat panel. You can also click Edit with AI in the editor footer to open the panel pre-focused on the transaction you're viewing.

Type what you want and send (⌘/Ctrl + Enter). The assistant streams its thinking and shows each step it takes ("Reading schema for table contact", "Writing contact.py", and so on).

The approval gate

The assistant never changes your application on its own. When it has prepared its work, the panel shows a review with a before/after diff for every file, and a single control:

Approve & Execute — write the changes to the server (and, for a new transaction, open it in the editor).
Discard — throw the staged work away.

You are always in control

Creating and editing transactions is staged — held in memory and shown as a diff — until you approve it. Approving is the only action that writes to your application. If you close the panel with an unapproved change, it's still there when you reopen it.

What you can ask it to do

Create a transaction

Describe the transaction you want. If you don't say which group and code to use, the assistant asks first rather than guessing — so the URL and file layout are what you expect.

"Create a CRUD for the product table in group catalog."

Build a whole app

Ask for several transactions at once and the assistant builds and wires them together in one go. For a multi-part request it chooses sensible group/code names itself.

"Build a booking app: a room list, a booking form, and a room CRUD."

The review shows each transaction as its own card; Approve & Execute commits them together.

Edit an existing transaction

Open a transaction (or use Edit with AI) and describe the change. The assistant reads the current files first and stages a focused edit.

"Add an email column to the form and validate it."

Rename or move a transaction

Ask it to change a transaction's group and/or code. Because a rename also updates the controller class name and the default view, the assistant states the exact rename and asks you to confirm in chat first — and then applies it immediately.

"Rename orders/cart to shop/basket."

Note

A rename doesn't rewrite your own internal references (links, explicit view names). The assistant will remind you to check those.

Roll back to a previous version

Every save is versioned. If a change didn't work out, ask the assistant to restore an earlier version. It lists the saved versions, you pick one, and it stages that version as a change so you review the diff before approving. Approving snapshots the current state first, so a restore is itself reversible.

"Show me the versions of catalog/product and restore yesterday's."

Diagnose data problems

When something looks wrong (a missing record, an unexpected value), the assistant can run read-only queries to inspect the actual rows before suggesting a fix.

"The dashboard total is wrong — can you check the orders data?"

Debug runtime errors

If a page is throwing or misbehaving, reproduce it, then ask the assistant. It reads the server log to find the real error and stack trace, then proposes a fix based on what actually happened instead of guessing.

"The invoice page returns a 500 — what's wrong?"

Schema changes and SQL

The assistant can read your database schema and suggest SQL, but it does not run schema or data changes itself. When a task needs one, it writes the statement as a SQL block in the chat with an Execute button:

Review the SQL.
Click Execute to run it against your application database.
After a structural change the models are refreshed automatically, so new columns and tables are immediately available.

Warning

You run the SQL, not the assistant. Read it before clicking Execute — destructive statements (for example DROP) are blocked, but you are still the one applying the change.

Project memory (`AGENTS.md`)

The assistant already knows the SØAD framework, but it doesn't know your project's conventions. You can teach it by keeping notes in a file at WEB-INF/AGENTS.md. Anything in that file — design decisions, naming conventions, UI guidelines, domain rules — is treated as authoritative guidance on every request.

Two ways to maintain it:

Edit it yourself in the File Manager (it's a normal Markdown file).
Ask the assistant to remember something — say "remember this" or "save to memory" and it appends the note for you.

"Remember: all money amounts are stored in cents, and we always soft-delete."

AGENTS.md is optional. When it's empty, the assistant just uses its built-in framework knowledge.

Designing larger apps with a planner

The assistant is a builder — it's at its best turning a clear, focused request into transactions you approve. For a larger app — many screens, a real data model, cross-cutting conventions — it pays to design first, then build.

A workflow that works well:

Plan with a capable "frontier" AI. Use a strong general-purpose model (the kind you'd reach for to architect and design) to turn your idea into a concrete plan: the data model, the list of transactions, how they link, and your conventions.
Give the planner SØAD's context. So its plan uses SØAD conventions rather than generic ones, provide it with SØAD's coding context (the framework documentation) and the planning guide below — the guide tells it how to shape a plan the assistant can build cleanly.
Split the result into two streams:
- Durable conventions (naming, money handling, soft-delete, UI standards) go into your project's AGENTS.md once — they then apply to every request.
- The build plan (data model + transactions) goes into the chat, fed phase by phase.
Build in order: run the schema SQL first (Execute), then paste the transactions a batch at a time, approving each before moving on.

This split isn't arbitrary: AGENTS.md is always in the assistant's context, while chat history is finite and trims older turns. Put "always true" in AGENTS.md and "what to build now" in chat.

Planning guide

Give this to your planning AI, alongside SØAD's coding context, so it produces plans shaped for the assistant to build:

Download the SØAD Coding Context →

Download the SØAD Planning Guide →

Conversations

The panel keeps your chat history per transaction, so you can close it and come back later. Use New chat to start a fresh conversation (clearing the context), and All conversations to browse past chats.

Safety and scope

The assistant is deliberately constrained:

It cannot delete, deploy, release, or roll back, and it cannot run schema/data changes. Those tools simply aren't available to it — the limit is built in, not just requested in a prompt.
It only writes to your application after you approve a diff (rename is the one immediate action, and it asks for confirmation in chat first).
Its queries are read-only. Any data or schema change is a statement you Execute.

What is sent to the model

To do its work, the assistant sends relevant context to your configured model provider — your request, the transaction files it's working on, schema details, and, when debugging, log excerpts. Choose a provider you trust with your project data, and be aware that anything present in the server log (which the log tool may read) can be included when you ask it to debug.

Tips for good results

Be specific about names. Give the group and code when you have a preference; otherwise the assistant will ask.
Mention the tables and columns involved — the assistant reads the schema, but naming them removes ambiguity.
Work in small steps and approve as you go; it's easier to review a focused diff than a sweeping one.
Reproduce an error first, then ask — the assistant reads the log, so a fresh error trail helps it find the cause.
Capture conventions in AGENTS.md once, instead of repeating them in every chat.
Plan big apps first. For anything large, design it with a planner and feed it in phases — see Designing larger apps with a planner.

Troubleshooting

Symptom	Likely cause / fix
"AI assistant is not configured"	No endpoint / key / model resolved — set them in Provider settings or via the `ai.*` properties/environment variables.
Requests fail with an auth error	Wrong API key, or the model name isn't valid for your provider.
Nothing happens / provider error	Check the endpoint base URL and that the provider exposes `/chat/completions`.
A change didn't take effect	Confirm you clicked Approve & Execute — staged changes aren't written until you do.
The model doesn't see a new column/table	Run the suggested SQL with Execute (which refreshes the models), or Introspect the datasource.