Migration Guide

Migrating to AI Service 4.x

With version 4 of the AI Service (shipped with App Suite 8.37), configuration is transitioning from the App Suite Middleware to the to the AI service. This change enables configuration to be managed closer to where it’s applied while ensuring strict schema validation and consistency checks.

As a result, the service can no longer start with an invalid configuration — errors like incorrect data types, missing values, or invalid references are prevented.

This configuration can also be changed without restarts via the config map of the AI service. Those edits will also be validated, so always check the log output of the service.

Changes in model configuration

Both defaultModel and privateDefaultModel need to be replaced by selectableModels. The first one is the defaultModel. selectableModels is more flexible and also supports more than one or two models in the future.

# Example
modelsConfig:
  defaultModel: default
  privateDefaultModel: private
# needs to be replaced by
modelsConfig:
  selectableModels:
    - default
    - private

For each model, the displayName can be defined for different language or locales. Therefore, displayName is no longer a string but an object of strings with at least en as the default or fallback language.

# instead of
displayName: 'GPT 4o'
# it is now
displayName:
  en: 'GPT 4o'
# or using yaml shortcuts
displayName: { en: 'GPT 4o' }

The user consent will still be stored in the user settings managed by App Suite MW, e.g. ìo.ox/core//ai/consent/default. To avoid that end-users need to give consent again, you can adjust the consentId of your models to match the previous model Ids. Example: If your defaultModel was default before and assuming it's OpenAI's gpt-4o, you can set the consentId of that model to default (which would otherwise default to "openai"). The consentId will determine under which path the consent will be checked (io.ox/core//ai/consent/$consentId) and which consent dialog to show (see next section).

It is also recommended to remove maxTokens from your configuration unless you really want to set (lower) limits apart from the models own hard limits.

There is now support for multiple consent dialogs (ideally per service that requires user consent). All configuration entries of the pattern io.ox/core//ai/config/default/serviceName must be transformed into a consent dialog config entry (see Models Configuration)

A minimalistic entry looks like this:

modelsConfig:
  consentDialog:
    openai:
      name:
        en: 'OpenAI'
      location:
        en: 'USA'
      aboutURL:
        en: 'https://openai.com/about'
      dataUsagePolicyURL:
        en: 'https://openai.com/policies/api-data-usage-policies'
      title:
        # was: io.ox/core//customStrings/ai/consent/title/en
        en: 'Example'

Feature toggles and chat options

All AI-related features toggles and chat options are consolidated here:

config:
  features:
    autoTranslate: true
    chat: true
    smartTasks: true
    suggestions: true
    typeahead: false
  chat:
    # was: io.ox/core//ai/chat/autoOpenOnFirstRun
    autoOpenOnFirstRun: true
    # was: io.ox/core//ai/chat/showLauncher
    showLauncher: true
    # was: io.ox/core//ai/chat/showTopRightIcon
    showTopRightIcon: true

Error messages

Error message messages can now be customized this way:

config:
  customStrings:
    errors:
      # was: io.ox/core//customStrings/ai/errors/moderation
      moderation:
        en: ''
      # was: io.ox/core//customStrings/ai/errors/unavailable
      unavailable:
        en: ''

Changes in plans configuration

Plans have changed significantly to make them more future proof. The following has been changed:

  • The enabled attribute per plan has been removed. Since everything is configurbale in YAML, you would rather comment out plans while preparing or to keep them as old plans.
  • The plan attribute (free/paid) has also been removed because it had no functionality so far.
  • limit is still there but it's just a shorthand (which might be fine for your use-case though)
  • limits is new to define limits per model
  • Each limit supports interval, days, and requests
  • strategy has been removed and is now covered by interval and days. A monthly strategy can now be achieved by interval: month. A duration strategy can be achieved by using days in combination with a daily, weekly, or monthly interval.
  • Plans now support an upgrade attribute (bool) to define whether a model has an upsell path. In this case, an upgrade button will appear at several locations that will trigger the upsell process.
# Example
- premium:
    name: Premium example
    strategy: month
    limit: 100
    plan: paid
    enabled: true

# turns into
- capability: premium
  name: Premium example
  # shorthand uses a monthly interval for all models
  limit: 100

# or different syntax, same result
- capability: premium
  name: Another example
  limits:
    '*':
      interval: month
      requests: 100

# or if users can use more than one model
- capability: premium
  name: Another example
  limits:
    default:
      interval: month
      requests: 300
    best:
      # allow a 30-days trial phase
      days: 30
      interval: day
      requests: 10

Migrating to AI Service 3.x

AI-Service version 2.6.x is not compatible with App Suite UI versions 8.34 or later. If you plan to upgrade to App Suite 8.34, you must use AI-Service version 3.0.x or higher.

When upgrading to 3.x, there are some mandatory configuration changes that need to be applied.

Info

Also please take a look at the support matrix

Helmchart

Model configuration

You need to add your models to the modelsConfig value in your helm chart, like so:

modelsConfig:
  defaultModel: "gpt-4o"
  models:
    gpt-4o:
      displayName: "ChatGPT 4o"
      service: "openai"
      model: "gpt-4o"
      maxTokens: 128000

This would be a super simple configuration with only one model. For further information check the Models Configuration chapter in the documentation.

Info

You may remove your previous models and/or services configuration as it is obsolete

Database

A database connection is now mandatory and needs to be configured. See database setup or take a look at the Helm Readme

The settings path has changed, the former io.ox/core//ai/config/custom path has changed to io.ox/core//ai/config/default

io.ox/core//ai/config/default/serviceName = 'OpenAI',
io.ox/core//ai/config/default/serviceLink = 'https://openai.com/about',
io.ox/core//ai/config/default/dataUsagePolicy = 'https://openai.com/policies/api-data-usage-policies'

Those links will be used in the consent dialog and should direct the user to the proper documents.

For more complex setups and configurations check the Models Configuration Chapter and the Model selection settings Chapter in the documentation.

Model setting

io.ox/core//ai/model = 'default' or empty

If your io.ox/core//ai/model setting is empty you are already done. Otherwise set it to 'default' or just unset it. See Model selection settings for more information.

Last Updated::