feat: server default LLM model selectable as "default" in prompts (#3838)

## What

Introduces a **server default model** concept for AI translation:

- New config property `tolgee.llm.default-provider` naming the provider
that serves as the server default. When unset, the first enabled
provider is used (previous behavior preserved).
- The provider name `default` is now a reserved alias. Prompts that
store it resolve to the server default **at call time** (interactive MT
suggestions, batch, playground), so they automatically follow
default-model upgrades without any prompt edits. Resolution goes through
the existing fallback chain, and a real provider actually named
`default` keeps precedence, so existing self-hosted configs relying on
the Spring-default provider name are unaffected.
- The default prompt now carries the `default` alias instead of pinning
the first provider's name, and API responses keep the alias unresolved
so the selection stays stable in the UI.
- `GET .../llm-providers/all-available` prepends a synthetic `default`
entry with a new `resolvesToName` field, and the AI playground model
select renders it as **`default (<model>)`** (new translation key
`ai_prompt_provider_server_default`, uploaded to Tolgee with
screenshot).

## Why

The production default model was pinned positionally (first entry of the
providers list) and users wanting "the best model" had to edit their
prompts whenever a new model came out. With this change, the deployment
automation can repoint `tolgee.llm.default-provider` and every prompt on
the `default` alias follows. Companion PRs in the deployment repo add
the key to values.yaml and teach the weekly model automation to maintain
it.

## Testing

- Unit tests for `getDefaultProviderName`
(configured/renamed-via-fallbacks/dangling/unset/disabled/empty).
- Resolver unit tests: alias resolves to the configured default, real
`default` provider wins, throws with no providers.
- Controller tests: default prompt returns the alias, playground run
works with the alias, saved prompts keep the alias unresolved,
`all-available` contains/suppresses the synthetic entry correctly.
- Verified end-to-end in a dev instance: select shows `default
(gpt-5-mini)`, preselected for new prompts, playground run works.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
  * Added configurable default provider selection for AI/LLM features.
* Added fallback handling when the selected provider is unavailable,
renamed, disabled, or unset.
  * The provider list now shows a clear “default (provider name)” entry.
* Prompts can use the default provider alias while retaining that alias
in saved prompt data.
* **Documentation**
  * Updated the PostgreSQL autostart migration documentation link.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: JanCizmar

backend/api/src/main/kotlin/io/tolgee/hateoas/llmProvider/LlmProviderSimpleModel.kt

@@ -1,5 +1,6 @@
 package io.tolgee.hateoas.llmProvider
 
+import io.swagger.v3.oas.annotations.media.Schema
 import io.tolgee.model.enums.LlmProviderType
 import org.springframework.hateoas.RepresentationModel
 import org.springframework.hateoas.server.core.Relation
@@ -11,4 +12,11 @@ open class LlmProviderSimpleModel(
   var type: LlmProviderType,
   var tokenPriceInCreditsInput: Double?,
   var tokenPriceInCreditsOutput: Double?,
+  @field:Schema(
+    description =
+      "Name of the concrete provider the server default (\"default\" provider) currently resolves to. " +
+        "It is only set on the synthetic \"default\" entry and is always null for concrete providers. " +
+        "Clients can rely on non-null resolvesToName to identify the server-default entry.",
+  )
+  var resolvesToName: String? = null,
 ) : RepresentationModel<LlmProviderModel>()

backend/data/src/main/kotlin/io/tolgee/configuration/tolgee/PostgresAutostartProperties.kt

@@ -26,7 +26,7 @@ class PostgresAutostartProperties {
         "`EMBEDDED` is deprecated. Tolgee v4 removes the bundled PostgreSQL from the " +
         "`tolgee/tolgee` image, so setups using it have to move to an external database " +
         "before upgrading. See " +
-        "[Migrate from the bundled database](/self_hosting/running_with_docker" +
+        "[Migrate from the bundled database](/platform/self_hosting/running_with_docker" +
         "#migrate-from-the-bundled-database).",
   )
   var mode: PostgresAutostartMode = PostgresAutostartMode.DOCKER

backend/data/src/main/kotlin/io/tolgee/configuration/tolgee/machineTranslation/LlmProperties.kt

@@ -54,6 +54,15 @@ class LlmProperties : MachineTranslationServiceProperties {
   )
   var providers: MutableList<LlmProvider> = mutableListOf()
 
+  @DocProperty(
+    description = """
+    Name of the provider used when a prompt selects the `default` provider. The name must match
+    one of the configured providers (the `fallbacks` mapping is applied if the provider was renamed).
+    When unset, the first enabled provider is used.
+  """,
+  )
+  var defaultProvider: String? = null
+
   @DocProperty(
     description = """
     Map of provider defaults keyed by provider name. Use this to separate non-secret configuration

backend/data/src/main/kotlin/io/tolgee/service/LlmPropertiesService.kt

@@ -25,6 +25,29 @@ class LlmPropertiesService(
     return llmProperties.fallbacks[providerName]
   }
 
+  fun getDefaultProviderName(): String? {
+    val providers = getProviders()
+    val configured = resolveConfiguredDefault(providers)
+    return configured ?: providers.firstOrNull()?.name
+  }
+
+  private fun resolveConfiguredDefault(providers: List<LlmProvider>): String? {
+    var current = llmProperties.defaultProvider ?: return null
+    val tried = mutableSetOf<String>()
+    repeat(MAX_FALLBACK_DEPTH) {
+      if (providers.any { it.name == current }) {
+        return current
+      }
+      tried.add(current)
+      val fallback = llmProperties.fallbacks[current]
+      if (fallback == null || fallback in tried) {
+        return null
+      }
+      current = fallback
+    }
+    return null
+  }
+
   fun getProviders(): List<LlmProvider> {
     val result = getMergedProviders().toMutableList()
     if (subscriptionActive()) {
@@ -98,4 +121,9 @@ class LlmPropertiesService(
     }
     return base
   }
+
+  companion object {
+    const val DEFAULT_PROVIDER_ALIAS = "default"
+    private const val MAX_FALLBACK_DEPTH = 10
+  }
 }

backend/data/src/test/kotlin/io/tolgee/unit/LlmPropertiesServiceDefaultProviderTest.kt

@@ -0,0 +1,86 @@
+package io.tolgee.unit
+
+import io.tolgee.configuration.tolgee.machineTranslation.LlmProperties
+import io.tolgee.configuration.tolgee.machineTranslation.LlmProperties.LlmProvider
+import io.tolgee.service.LlmPropertiesService
+import io.tolgee.testing.assert
+import org.junit.jupiter.api.Test
+
+class LlmPropertiesServiceDefaultProviderTest {
+  private fun createService(props: LlmProperties): LlmPropertiesService {
+    return LlmPropertiesService(props, null)
+  }
+
+  private fun props(
+    vararg providerNames: String,
+    defaultProvider: String? = null,
+    fallbacks: Map<String, String> = emptyMap(),
+    disabled: Set<String> = emptySet(),
+  ): LlmProperties {
+    val props = LlmProperties()
+    props.providers =
+      providerNames
+        .map { LlmProvider(name = it, enabled = it !in disabled) }
+        .toMutableList()
+    props.defaultProvider = defaultProvider
+    props.fallbacks = fallbacks.toMutableMap()
+    return props
+  }
+
+  @Test
+  fun `returns configured default when it exists`() {
+    val service = createService(props("gpt-4o", "claude", defaultProvider = "claude"))
+    service.getDefaultProviderName().assert.isEqualTo("claude")
+  }
+
+  @Test
+  fun `resolves renamed default through fallback chain`() {
+    val service =
+      createService(
+        props(
+          "gpt-6",
+          defaultProvider = "gpt-4o",
+          fallbacks = mapOf("gpt-4o" to "gpt-5", "gpt-5" to "gpt-6"),
+        ),
+      )
+    service.getDefaultProviderName().assert.isEqualTo("gpt-6")
+  }
+
+  @Test
+  fun `falls back to first provider when configured default is dangling`() {
+    val service = createService(props("gpt-4o", "claude", defaultProvider = "removed-model"))
+    service.getDefaultProviderName().assert.isEqualTo("gpt-4o")
+  }
+
+  @Test
+  fun `falls back to first provider when fallback chain is circular`() {
+    val service =
+      createService(
+        props(
+          "gpt-4o",
+          defaultProvider = "old-a",
+          fallbacks = mapOf("old-a" to "old-b", "old-b" to "old-a"),
+        ),
+      )
+    service.getDefaultProviderName().assert.isEqualTo("gpt-4o")
+  }
+
+  @Test
+  fun `returns first provider when unset`() {
+    val service = createService(props("gpt-4o", "claude"))
+    service.getDefaultProviderName().assert.isEqualTo("gpt-4o")
+  }
+
+  @Test
+  fun `returns null when no providers exist`() {
+    val service = createService(props())
+    service.getDefaultProviderName().assert.isNull()
+  }
+
+  @Test
+  fun `ignores disabled configured default`() {
+    val service =
+      createService(props("gpt-4o", "claude", defaultProvider = "claude", disabled = setOf("claude")))
+    service.getDefaultProviderName().assert.isEqualTo("gpt-4o")
+  }
+}

ee/backend/app/src/main/kotlin/io/tolgee/ee/api/v2/controllers/LlmProviderController.kt

@@ -13,6 +13,7 @@ import io.tolgee.model.enums.OrganizationRoleType
 import io.tolgee.openApiDocs.OpenApiOrderExtension
 import io.tolgee.security.authorization.RequiresOrganizationRole
 import io.tolgee.security.authorization.UseDefaultPermissions
+import io.tolgee.service.LlmPropertiesService
 import jakarta.validation.Valid
 import org.springframework.hateoas.CollectionModel
 import org.springframework.web.bind.annotation.CrossOrigin
@@ -34,6 +35,7 @@ class LlmProviderController(
   private val providerService: LlmProviderService,
   private val providerModelAssembler: LlmProviderModelAssembler,
   private val providerSimpleModelAssembler: LlmProviderSimpleModelAssembler,
+  private val llmPropertiesService: LlmPropertiesService,
 ) {
   @GetMapping("all-available")
   @UseDefaultPermissions
@@ -60,7 +62,23 @@ class LlmProviderController(
         existing.add(it.name)
       }
     }
-    return providerSimpleModelAssembler.toCollectionModel(result)
+    val models = providerSimpleModelAssembler.toCollectionModel(result)
+    val defaultModel = getServerDefaultModel(existing) ?: return models
+    return CollectionModel.of(listOf(defaultModel) + models)
+  }
+
+  private fun getServerDefaultModel(existingNames: Set<String>): LlmProviderSimpleModel? {
+    if (LlmPropertiesService.DEFAULT_PROVIDER_ALIAS in existingNames) return null
+    val defaultName = llmPropertiesService.getDefaultProviderName() ?: return null
+    val provider = providerService.getAllServerProviders().find { it.name == defaultName } ?: return null
+    return LlmProviderSimpleModel(
+      name = LlmPropertiesService.DEFAULT_PROVIDER_ALIAS,
+      source = "server",
+      type = provider.type,
+      tokenPriceInCreditsInput = provider.tokenPriceInCreditsInput,
+      tokenPriceInCreditsOutput = provider.tokenPriceInCreditsOutput,
+      resolvesToName = defaultName,
+    )
   }
 
   @GetMapping("")

ee/backend/app/src/main/kotlin/io/tolgee/ee/service/LlmProviderResolver.kt

@@ -23,15 +23,22 @@ class LlmProviderResolver(
         return current
       }
       tried.add(current)
-      val fallback = llmPropertiesService.getFallbackProviderName(current)
-      if (fallback == null || fallback in tried) {
+      val next = getNextName(current)
+      if (next == null || next in tried) {
         throw LlmProviderNotFoundException(provider)
       }
-      current = fallback
+      current = next
     }
     throw LlmProviderNotFoundException(provider)
   }
 
+  private fun getNextName(current: String): String? {
+    if (current == LlmPropertiesService.DEFAULT_PROVIDER_ALIAS) {
+      return llmPropertiesService.getDefaultProviderName()
+    }
+    return llmPropertiesService.getFallbackProviderName(current)
+  }
+
   private fun providerExists(
     organizationId: Long,
     name: String,

ee/backend/app/src/main/kotlin/io/tolgee/ee/service/prompt/DefaultPromptHelper.kt

@@ -5,9 +5,7 @@ import io.tolgee.service.LlmPropertiesService
 import org.springframework.stereotype.Component
 
 @Component
-class DefaultPromptHelper(
-  private val llmPropertiesService: LlmPropertiesService,
-) {
+class DefaultPromptHelper {
   fun getDefaultPrompt(): PromptDto {
     return PromptDto(
       name = "",
@@ -41,7 +39,7 @@ class DefaultPromptHelper(
 
         {{fragment.translateJson}}
         """.trimIndent(),
-      providerName = llmPropertiesService.getProviders().getOrNull(0)?.name ?: "default",
+      providerName = LlmPropertiesService.DEFAULT_PROVIDER_ALIAS,
     )
   }
 }

ee/backend/app/src/main/kotlin/io/tolgee/ee/service/prompt/PromptServiceEeImpl.kt

@@ -23,6 +23,7 @@ import io.tolgee.model.Prompt
 import io.tolgee.model.enums.BasicPromptOption
 import io.tolgee.model.enums.LlmProviderPriority
 import io.tolgee.repository.PromptRepository
+import io.tolgee.service.LlmPropertiesService
 import io.tolgee.service.PromptService
 import io.tolgee.service.key.KeyService
 import io.tolgee.service.machineTranslation.MtServiceConfigService
@@ -295,9 +296,14 @@ class PromptServiceEeImpl(
    *
    * The entity is detached before mutation to prevent OSIV from flushing the resolved name
    * back to the DB — the stored value must remain the original.
+   *
+   * The "default" alias is intentionally NOT resolved — it must stay stable in API responses
+   * so the frontend keeps showing the alias option instead of the concrete provider it
+   * currently points to.
    */
   private fun withResolvedProviderName(prompt: Prompt): Prompt {
     if (prompt.providerName.isEmpty()) return prompt
+    if (prompt.providerName == LlmPropertiesService.DEFAULT_PROVIDER_ALIAS) return prompt
     // Access lazy association while still managed
     val organizationId = prompt.project.organizationOwner.id
     val resolvedName =

ee/backend/tests/src/test/kotlin/io/tolgee/ee/api/v2/controllers/LlmProviderControllerTest.kt

@@ -49,6 +49,7 @@ class LlmProviderControllerTest : AuthorizedControllerTest() {
   fun resetSsrfProperties() {
     internalProperties.disableUrlSsrfProtection = true
     webhookProperties.allowLocalAddresses = false
+    llmProperties.defaultProvider = null
   }
 
   @Test
@@ -63,6 +64,63 @@ class LlmProviderControllerTest : AuthorizedControllerTest() {
     }
   }
 
+  @Test
+  fun `all-available contains synthetic default entry resolving to configured default`() {
+    llmProperties.providers =
+      mutableListOf(
+        LlmProperties.LlmProvider(
+          name = "gpt-6",
+          type = LlmProviderType.OPENAI,
+          apiUrl = "http://test.com",
+        ),
+        LlmProperties.LlmProvider(
+          name = "claude",
+          type = LlmProviderType.ANTHROPIC,
+          apiUrl = "http://test.com",
+        ),
+      )
+    llmProperties.defaultProvider = "claude"
+    performAuthGet(
+      "/v2/organizations/${testData.organization.self.id}/llm-providers/all-available",
+    ).andIsOk.andAssertThatJson {
+      node("_embedded.providers").isArray.hasSize(4)
+      node("_embedded.providers[0].name").isEqualTo("default")
+      node("_embedded.providers[0].source").isEqualTo("server")
+      node("_embedded.providers[0].resolvesToName").isEqualTo("claude")
+      node("_embedded.providers[0].type").isEqualTo("ANTHROPIC")
+    }
+  }
+
+  @Test
+  fun `synthetic default entry resolves to first provider when not configured`() {
+    llmProperties.providers =
+      mutableListOf(
+        LlmProperties.LlmProvider(
+          name = "gpt-6",
+          type = LlmProviderType.OPENAI,
+          apiUrl = "http://test.com",
+        ),
+      )
+    performAuthGet(
+      "/v2/organizations/${testData.organization.self.id}/llm-providers/all-available",
+    ).andIsOk.andAssertThatJson {
+      node("_embedded.providers[0].name").isEqualTo("default")
+      node("_embedded.providers[0].resolvesToName").isEqualTo("gpt-6")
+    }
+  }
+
+  @Test
+  fun `real provider named default suppresses the synthetic entry`() {
+    // the setup's server provider keeps the Spring-default name "default"
+    performAuthGet(
+      "/v2/organizations/${testData.organization.self.id}/llm-providers/all-available",
+    ).andIsOk.andAssertThatJson {
+      node("_embedded.providers").isArray.hasSize(2)
+      node("_embedded.providers[1].name").isEqualTo("default")
+      node("_embedded.providers[1].resolvesToName").isEqualTo(null)
+    }
+  }
+
   @Test
   fun `prevents viewing other organization providers`() {
     this.userAccount = testData.projectReviewer.self