AI Providers & Settings

Set up the AI providers and keys, choose which model each AI feature uses, and configure Gemini and Amazon Bedrock from the AI Settings screen.

The AI Settings Screen

AI Settings is where an architect sets up the platform's AI: which providers are switched on and keyed, which provider and model each AI feature uses, and the logging, image and video, limit and billing settings around them. Before it existed, every one of these was a hand edit of a file on the server.

Where to find it

Architect Panel → Configuration:

AI Settings — every AI setting, grouped into sections, with a Save button per section
Platform Modules — switching the AI module off closes this screen and the other AI screens

Architect Panel → Activity:

AI Usage — where you test a role end to end after changing anything here

The tile is placed in whichever category holds Site Settings.

What it edits

The AI settings live in one file on the server, config/ai-config.php, and the screen names it at the top. Unlike Site Settings there is no database copy, so there is nothing to sync: a saved change takes effect on the next request. The screen is for architects only, and nothing on it ever displays a key.

The status card

The first card, The configuration file, tells you whether the rest of the screen can be trusted to save:

File: the file name and when it last changed.
Can be edited here: Yes or No. When it says No, a red panel explains why and every value below is shown read-only, exactly as the platform reads it.
Takes effect: on the next request.
A provider table: whether each provider is offered in Send to AI, whether its credentials are Set, and its default model.
Section buttons that jump straight to each section below.

The sections

One section per provider, from Claude (Anthropic) to Amazon Bedrock: keys, default models and Send to AI settings.
Which provider each AI feature uses: the roles table, one row per feature.
TypeSafe Jev: Jev's own switch and key. Jev is a decision model rather than a language model, and it is covered in TypeSafe Jev.
AI images and video: generation on the Gemini key. See AI Images & Video.
The run log: what each AI call's log row keeps, and for how long. See AI Usage & Run Log.
Prices, limits and retries: price overrides for the cost estimates, the currency label, the largest PDF sent to a model as a document, and the default number of retries.
AI credit and billing: charging AI use to tenants. Off unless switched on. See AI Credit & Spend Limits.
Command-line delivery: shown, never changed from this screen.
Other settings in the file: anything the screen does not describe, such as a client app's own setting. Add a setting takes a name, a type and a value.

Under every field is the setting's name in the file and a line of help.

Saving a section

Change the values you need in one section. A dot appears after the section's heading while it has unsaved changes.
Press that section's Save. Only that section is sent; other sections keep their unsaved edits.
Read the message beside the button. Saved: lists the settings that changed. Nothing to save means no value in that section differed from what the file already says.
Open AI Usage and test the role your change affects.

Only the values you changed are rewritten, in place, so the comments and every other line of the file are kept. Each save is checked by reading the file back, and is undone if the result is not what was asked for.

Keys and other secrets

A key field never shows its value, not even in part. It says Set or Not set. Leave the field blank to keep the current key, type a new one to replace it, or tick Clear it to empty it.

What the screen will not change

Command-line delivery: these settings let the web server run a program, so they stay a hand edit by the hosting administrator.
A value set by code: a field marked "Set by code in the file - edit it by hand" is left alone.
The whole file, when the web server cannot write it or it is not a plain list of settings. The red panel says why.

What goes wrong, and how to tell

"config/ai-config.php has changed since this screen was opened": another architect saved, or someone edited the file by hand. Reload the screen and make your change again; nobody's edit is silently overwritten.
"Nothing was saved." followed by a reason: a value failed its check, such as a number outside its allowed range or a role name already in use. Correct it and save again.
"There is no config/ai-config.php on this installation.": every AI call is answering "not configured". Saving any section creates the file from the shipped template, which carries no keys.
Can be edited here: No, with "The web server cannot write config/ai-config.php": ask your hosting administrator to change the file's permissions, or to make the change by hand.

Worked example

An architect is asked to move the Report Builder's assistant to a cheaper model. On AI Settings they confirm Can be edited here: Yes, set the provider and model on the biquery row of the roles table, and press Save; the message lists the two settings that changed. On AI Usage they press Test beside biquery and see it answer with the new model. Nobody opened a file on the server.

Recommendations

Save one section at a time, and test the affected role straight afterwards.
Read the status card first. If it says the file cannot be edited, fix that before changing anything else.
Replace keys here rather than by hand, so the value never appears on screen or in an e-mail.
Leave Command-line delivery off on any server that is not a developer's own machine.

Providers and Keys

The platform can call six AI providers. Each has its own section on AI Settings holding its key, the model to use when a feature names the provider but no model, and how the provider is offered in the Send to AI menu. A provider is usable as soon as its credentials are set; which features actually use it is decided by the roles.

Where to find it

Architect Panel → Configuration:

AI Settings — one section per provider, and a provider table on the status card

Architect Panel → Activity:

AI Usage — Test a role, to prove a key works

The six providers

Claude (Anthropic): Anthropic's own API. The richest route: documents go as PDFs, answers can carry citations, and structured answers are asked for natively.
ChatGPT (OpenAI): OpenAI's own API. OpenAI models reached through AWS are the Amazon Bedrock provider, not this one.
Gemini (Google): Google's Gemini. Its key is also the one AI images and video use.
GitHub Models: authenticated with a personal access token rather than an API key.
Grok (xAI): xAI's API.
Amazon Bedrock: Claude, OpenAI's GPT-6 family and other models through your AWS account. It has its own article, because region and credentials matter there.

OpenAI, Gemini, GitHub Models and Grok are reached in prompt mode: the instructions, any documents (as text) and the question are folded into one prompt, and a structured answer is checked by the platform after it comes back. These providers report no token counts, so their calls show as not priced on AI Usage, and where AI billing is on they are charged on an estimate from the characters sent and received. They cannot return citations.

The fields in each provider section

API key (GitHub Models: Personal access token): never shown. Leave blank to keep, type to replace, tick Clear it to remove.
Default model: the model a role gets when it names this provider and no model. Leave it empty and such a role has no model at all. For Claude the shipped value is claude-opus-5-5; the others ship empty. Never paste a Claude Code id ending in "[1m]": it is not an API model id.
Offer in Send to AI: shows the provider in the Send to AI menu. The platform's own AI features do not look at this switch: they need only the credentials.
Send to AI delivery: the menu's default way of delivering a prompt. api calls the provider; clipboard copies the prompt and costs nothing; cli (Claude and GitHub Models) runs a command-line tool; claude_desktop (Claude) opens Claude Code. The command-line options also need settings that only the hosting administrator can switch on.
Display name: an optional label to show instead of the provider's own name.

The Claude section has three more: API address (blank means Anthropic's own; a company proxy goes here, and the key is sent to whatever address is entered), Strict tool schemas and Server-side fallbacks. Leave those two on unless Anthropic support advises otherwise.

What Send to AI is

Send to AI is a menu a custom app can add to its own screens: it lists the providers marked Offer in Send to AI, lets a person pick a model, and sends a prompt that the app's own code has built. No standard platform screen carries the menu, so on most installations these two switches change nothing. While AI billing is on, the api and cli deliveries are refused and dropped from the menu, because they are not metered, unless Unmetered Send to AI deliveries in the billing section allows them.

Setting up a provider

Create the key in the provider's own console, under an organisational account rather than a person's.
Open AI Settings, go to the provider's section, paste the key into API key, and enter a Default model id taken from the provider's documentation.
Press Save. The status card's provider table should now say Set under Credentials.
Point at least one role at the provider (see the roles article), or set it as the builder provider to make it the default for everything.
On AI Usage, press Test beside that role and check it answers.

What goes wrong, and how to tell

The role says "not configured" on AI Usage: its provider has no usable credentials. Check the key was saved in the right section.
The test fails with auth: the provider refused the key. It was mistyped, revoked, or belongs to another account.
The test fails with not_found: the model id is not one this provider knows. Check the spelling against the provider's model list.
"no model set" beside a role: the role names a provider whose Default model is empty. Fill it in, or give the role a model of its own.
Costs show as not priced: expected for the prompt-mode providers, and for a model the price table does not know. Add a row under Price overrides in Prices, limits and retries if you want an estimate.

Worked example

An organisation already pays for OpenAI under a business agreement and wants the Report Builder's assistant to use it while everything else stays on Claude. An architect pastes the OpenAI key into the ChatGPT (OpenAI) section, sets a default model, and saves. In the roles table they set the biquery provider to ChatGPT (OpenAI) and save again. The test call on AI Usage answers, and the architect notes that these calls will show as not priced, so the monthly spend for that role is read from OpenAI's own billing page.

Recommendations

Use organisational keys, so AI does not stop working when a person leaves.
Always set a Default model for every provider you key.
Prefer Claude or Bedrock for document-heavy work, where PDFs and citations are supported.
Leave Offer in Send to AI off unless a custom app on this installation uses the menu.
Test after every key change, not when a user first reports a failure.

Roles: Which Model Each Feature Uses

Every AI feature on the platform asks for a role rather than a particular model. The roles table on AI Settings decides which provider and model each role uses, and any limits on it, so you can put a strong model where quality matters and a cheaper one where it does not, without touching the features themselves.

Where to find it

Architect Panel → Configuration:

AI Settings — the section Which provider each AI feature uses

Architect Panel → Activity:

AI Usage — Test a role, and usage grouped by feature

The platform's roles

builder: the default. Every role that names no provider of its own uses this one.
onboarding: the sign-up wizard, which turns a description of a business into an app blueprint. It runs for anonymous visitors.
aibuilder: the AI Builder, which turns a request into a change set for the app.
ide: App Code, which writes extension source. A stronger model here means fewer repair rounds.
biquery: the Report Builder's assistant (the screen calls it the Query Builder assistant). It is sent field names and labels, never a record value.
ocr: AI reading of scanned images for the document index. The image leaves the installation.
erpfeed: coding suggestions on the ERP Feed Queue, one request per uncoded row, only when a user asks.
a2a: the planner behind Agent Access (A2A).

Image and video generation use two further roles, image and video, whose models are set in the AI images and video section instead. TypeSafe Jev is not a role at all: it has its own section.

How a role finds its model

Provider and model both set: that pair is used.
Provider set, model blank: the provider's Default model from its own section.
Provider blank (Inherit): the builder provider and the builder model. The model always travels with its provider, so a role can never be handed one provider's model id on another.

Under each role's name, a Uses: line shows what it resolves to right now, so you can see the effect of inheritance without working it out.

The other columns

Effort: how hard a reasoning model thinks (low to max; none on OpenAI models only). A blank effort inherits the builder's only while the role also runs the builder's model, because some models refuse an effort setting.
Max tokens: the most the model may write in one answer.
Timeout (s): seconds allowed per attempt.
Retries: how many times a failed connection is retried; 0 means one try.
Schema mode: how a structured answer is asked for. Leave it at Default unless support advises otherwise.
Fallback model: a second model on the same provider, tried when the first refuses to answer.

Blank means inherit. The sign-up wizard, AI Builder, App Code and Report Builder assistant run while a person waits, so they keep their own limit of about 100 seconds per call with no retry; a role's Timeout can shorten that but never lengthen it. Feed Queue suggestions are held to 60 seconds a call the same way.

Changing a feature's model

Open AI Settings and find the role's row.
Choose a Provider whose credentials are Set, and enter a Model id, or leave it blank to take that provider's default.
Press the section's Save, and check the Uses: line now shows what you intended.
On AI Usage, press Test beside the role.

Adding a role for a client app

A custom feature on your installation asks for a role by name, chosen by whoever wrote it. To give that role a provider, fill in Add a role under the table: the role name, a provider (or Inherit from builder), and optionally a model, then Save. A name is 2 to 40 lower-case letters, digits and underscores, starting with a letter, and cannot be a provider's name. A role you added can later be ticked Remove; the platform's own roles cannot. A role the file has never named simply behaves like builder.

What goes wrong, and how to tell

A role is missing from Test a role on AI Usage: that list shows builder and every role the file names a provider entry for. Set the role's provider on AI Settings and it appears.
Every call on a role fails straight after you set Effort: the model does not take an effort setting. Set Effort back to Default.
A role changed model when you only changed builder: it was inheriting. Give it a provider of its own to pin it.
"There is already a role called..." when adding: pick another name, or edit the existing row.

Worked example

An organisation runs everything on one Claude model. Developers say App Code needs several repair rounds per extension, so the architect sets the ide row to the same provider with a stronger model. Scanned post is read by the ocr role, which is moved to a smaller, cheaper model that can still read images, and its Max tokens left blank. Both rows are tested on AI Usage, and a month later the usage table grouped by feature shows the saving on ocr paid for the extra cost on ide.

Recommendations

Set builder first and let everything inherit until there is a reason not to.
Pin a role explicitly once its quality or cost matters, so a later change to builder does not move it.
Change provider and model together, and read the Uses: line before saving.
Leave Schema mode at Default unless advised otherwise.
Test each role after a change, and compare its cost on AI Usage a few weeks later.

Setting Up Gemini

Google's Gemini does two separate jobs on the platform. It can answer for any AI feature, like the other providers, and it is the only provider for AI image and video generation. One key, entered once on AI Settings, serves both; what Gemini is then used for depends on the roles you point at it and on whether you switch image and video generation on.

Where to find it

Architect Panel → Configuration:

AI Settings — the Gemini (Google) section for the key, the roles table, and the AI images and video section

Architect Panel → Activity:

AI Usage — Test a role, and every Gemini call with its cost

The two uses

As a language model. Any role can be pointed at Gemini: the sign-up wizard, the AI Builder, App Code, the Report Builder assistant, AI reading of scans, Feed Queue suggestions, or a client app's own role. Gemini is reached in prompt mode: documents go as text, there are no citations, and because it reports no token counts its calls show as not priced on AI Usage.
For images and video. AI image and video generation calls Google directly with the same key. Every call is a priced run on AI Usage. Nothing generates anything until Who may generate is set to something other than off.

Setting the key does neither of these on its own. A role must name Gemini before any feature uses it as a language model, and image and video generation stays off until you open it up.

Switching Gemini on as a language model

Create an API key for the Gemini API in Google's console, under your organisation's Google account.
On AI Settings, in Gemini (Google), paste it into API key.
Enter a Default model: the Gemini text model id you want roles to use. This ships empty, and a role pointed at Gemini with no model of its own has nothing to call until it is filled in.
Press Save. The status card's provider table should show Gemini's credentials as Set.
In Which provider each AI feature uses, set Provider to Gemini (Google) on each role that should use it, and Save.
On AI Usage, press Test beside each of those roles.

Offer in Send to AI only matters if a custom app on your installation has a Send to AI menu; the platform's own features ignore it.

Switching on images and video

Enter the key as above. No role or default text model is needed for images and video.
In AI images and video, set Who may generate to Architects, Administrators or Everyone signed in, and adjust the daily allowances.
Read AI Images & Video for the rest: the models, the video background worker, and what the MCP tools need.

Settings that matter

API key: one key for both uses. Replacing it here changes both at once.
Default model: the text model only. Image and video models are chosen separately (Default image model, Default video model), and each has a built-in default.
Display name: changes how Gemini is labelled on the screens that list providers.

What goes wrong, and how to tell

A Gemini role shows "no model set": the Default model is empty and the role has no model of its own.
The test fails with not_found or bad_request: the model id is not one Google's API offers to this key. Check the id against Google's model list.
Images report "AI image and video generation is switched off on this system": the key is set but Who may generate is still off.
Images report "not set up on this system": there is no Gemini key.
A structured answer from Gemini is rejected: in prompt mode the answer is checked after it arrives, and a reply that does not match is refused rather than passed on. Try a stronger Gemini model for that role.

Worked example

A marketing team wants product images generated from the MCP tools, while every other AI feature stays on Claude. The architect adds a Gemini key in Gemini (Google) and saves, but points no role at Gemini, so nothing else moves. In AI images and video they set Who may generate to Administrators, cut Videos per person per day to 1, and switch on Offer to MCP clients. The team's first generated image appears on AI Usage under the image feature with its cost, and the language-model features carry on unchanged.

Recommendations

Treat the key as two permissions: anyone who can change it changes both text and media.
Always fill in Default model before pointing a role at Gemini.
Prefer Claude for document-heavy roles; Gemini receives documents as text only.
Open image and video generation deliberately, starting with a narrow audience.
Check Google's billing as well as AI Usage for Gemini text roles, which AI Usage cannot price.

Setting Up Amazon Bedrock

Amazon Bedrock runs AI models inside your own AWS account: Anthropic's Claude, OpenAI's GPT-6 family, and others such as Amazon Nova. Choosing it keeps AI billing with AWS and lets you decide which AWS Region processes your requests, but it asks more of the setup than a single API key.

Where to find it

Architect Panel → Configuration:

AI Settings — the Amazon Bedrock section, and the roles table

Architect Panel → Activity:

AI Usage — Test a role, with a hint per error that names the missing AWS permission

The model id decides the route

You do not pick an endpoint for each model: the platform reads it from the model id.

Claude: an id such as anthropic.claude-opus-5-5 goes to Bedrock's Messages endpoint; a geographic or versioned id, or an ARN, goes to the runtime endpoint.
OpenAI GPT-6: an id such as global.openai.gpt-6-luna always goes to Bedrock's OpenAI endpoint. Documents go to these models as text, without citations.
Any other provider (Nova, Llama, Mistral): always goes in prompt mode, with no citations, and is not priced on AI Usage.

Leave Endpoint on Automatic, from the model id. It only ever decides for an id that is neither OpenAI nor another provider's.

Region and where data is processed

Region blank means the platform's own AWS region. A model id starting eu., us. or another geography is a cross-Region profile: AWS may serve it from any Region in that geography, and the platform refuses one named from a Region outside it before anything is sent. An id starting global. may be processed in any commercial AWS Region. From UK and EU Regions the GPT-6 models are offered only through their global profile, so choosing them is a data-residency decision to make before go-live, not after.

Credentials

The first of these that is set is used:

Bedrock API key: a bearer key. Works for Claude on the Messages endpoint and for GPT-6, not for the other routes.
Access key ID and Secret access key (with Session token for temporary credentials).
Named profile: a profile in the web server user's AWS configuration, set up by your hosting administrator.
The platform's own AWS keys, unless Use the platform's AWS keys is No.
The server's environment or instance role, only when Use the AWS default chain is on.

Give AI its own AWS user or role with only the Bedrock permissions it needs, and set Use the platform's AWS keys to No, so the keys that reach your file storage never sign an AI request. With that set to Default it means Yes, except while AI billing is on.

Setting it up

In the AWS console, enable the model for your account in your chosen Region and note the exact id it takes there.
Create a dedicated IAM user or role allowed to invoke that model, and its keys if it is a user.
On AI Settings, in Amazon Bedrock, set Region, the credentials, Use the platform's AWS keys = No, and a Default model. Save.
Point roles at Amazon Bedrock in the roles table, or make it the builder provider. Save.
On AI Usage, test each role. Note the provider request id: it is what AWS support asks for.

Other settings in the section

Let Bedrock store OpenAI requests: off by default. Bedrock's own default for GPT-6 is to keep input and output for 30 days in whichever Region served them; leaving this off asks it not to.
Structured outputs (Claude) and Strict tool schemas: off by default, because Bedrock's Claude endpoints do not accept them everywhere. Change them only on advice.
Price multiplier: scales the cost estimates for every Bedrock model except GPT-6, for a regional premium or a negotiated rate.
OpenAI reasoning summary: off by default. Run a test call with it on before relying on it; if Bedrock rejects it, switch it off again.
Mantle address and OpenAI endpoint address: leave blank unless you reach Bedrock through a VPC endpoint.

What goes wrong, and how to tell

auth: AWS refused the credentials. Check the key pair, session token or profile.
permission: the credentials are valid but may not call this model in this Region. The test result names the grants needed.
not_found: the id is wrong for this Region, or the model is not enabled on the account.
invalid_request naming a geography: the id's prefix is outside the Region's geography. Use the id AWS offers in your Region.
A "stream ... denied" warning on a real run: long answers are streamed, which needs a further permission the small test call does not use. Grant it, or the call is re-sent without streaming.

Worked example

A UK organisation must keep processing in the UK where it can. Its architect enables Claude in eu-west-2, creates an IAM user allowed only to invoke that model, and enters its keys with Use the platform's AWS keys set to No. The builder provider becomes Amazon Bedrock with the eu. Claude id. GPT-6 is considered and rejected for now, because from London it is offered only through its global profile. Every role is tested on AI Usage before users are told.

Recommendations

Decide where requests may be processed first, then choose model ids that respect it.
Use a dedicated, least-privilege AWS principal, never the storage keys.
Copy model ids from the AWS console for your Region, not from another account's notes.
Prove GPT-6 on your own account with a test call before any feature depends on it.
Keep Let Bedrock store OpenAI requests off unless you have a reason to change it.