Loading

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

  1. Change the values you need in one section. A dot appears after the section's heading while it has unsaved changes.
  2. Press that section's Save. Only that section is sent; other sections keep their unsaved edits.
  3. 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.
  4. 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.