[NA] [BE][FE][SDK] Rename OPIK_BUILTIN to OPIK_FREE and improve free model UX (#4443)

* [NA] [BE][FE][SDK] Rename OPIK_BUILTIN to OPIK_FREE and improve free model UX

Rename internal terminology from OPIK_BUILTIN to OPIK_FREE and enhance
the user experience for the free model in the Playground.

- Display free model directly in model selector (not in a dropdown/submenu)
- Show model as "gpt-4o-mini (free)" with Opik icon for clear identification
- Dynamic model label from backend config via `model_label` field
- Provider label changed from "Opik Built-in" to "Opik"
- Description updated to "Free model provided by Opik - no API key required"
- API key name changed to "OPIK_FREE_MODEL_API_KEY" in configuration page
- Free model included in search/filter results

- LlmProvider enum: OPIK_BUILTIN → OPIK_FREE (value: "opik-free")
- Package rename: opikbuiltin → freemodel
- Class renames: OpikBuiltin* → FreeModel*
- Config: opikbuiltinProviderEnabled → opikfreeProviderEnabled
- Environment variable: TOGGLE_OPIKBUILTIN_PROVIDER_ENABLED → TOGGLE_OPIKFREE_PROVIDER_ENABLED
- Added model_label to provider configuration for dynamic UI display

- PROVIDER_TYPE.OPIK_BUILTIN → PROVIDER_TYPE.OPIK_FREE
- PROVIDER_MODEL_TYPE.OPIK_BUILTIN_MODEL → PROVIDER_MODEL_TYPE.OPIK_FREE_MODEL
- Feature toggle: OPIKBUILTIN_PROVIDER_ENABLED → OPIKFREE_PROVIDER_ENABLED
- Refactored PromptModelSelect for improved free model presentation

- TypeScript SDK provider types updated
- OpenAPI specs updated

* Address PR feedback: add validation and improve robustness

- FreeModelConfig: Add JavaDoc explaining required fields
- FreeModelConfig: isEnabled() now validates that actualModel, spanProvider,
  and baseUrl are set, ensuring fail-fast on misconfiguration
- PromptModelSelect: Handle empty string for model_label with .trim() check

* Fix camelCase naming for opikFreeProviderEnabled

Rename opikfreeProviderEnabled to opikFreeProviderEnabled to follow
consistent camelCase naming convention in configuration properties.

* Remove opikFreeProviderEnabled feature toggle

The free model visibility is already controlled by freeModel.enabled
backend config, making the feature toggle redundant. This simplifies
the codebase by removing unnecessary toggle checks.

Changes:
- Remove toggle from backend config and ServiceTogglesConfig
- Remove toggle from frontend feature-toggles and DEFAULT_STATE
- Update ProviderSelect and ProviderGrid to explicitly exclude OPIK_FREE
- Update PROVIDER_FEATURE_TOGGLE_MAP type to use Exclude<>
- Regenerate OpenAPI specs and SDKs

* [NA] [FE] Add opik_free_model metadata flag for BI tracking

Add a boolean flag to span metadata when users use the free model,
enabling the BI team to identify and track free model usage in the
analytics database.

* Revision 3: Refactor PromptModelSelect - extract useModelOptions hook

- Extract data transformation logic into useModelOptions hook
- Simplify renderSelectTrigger with getSelectedModelInfo callback
- Fix vertical alignment with py-1 padding on options container
- Reduce component from 484 to ~350 lines

* Revision 4: Fix useModelOptions type errors

- Change ProviderKey to ProviderObject (correct exported type)
- Use ModelOption[] instead of inline type for consistency

* Revision 5: Fix free model row vertical alignment in PromptModelSelect

Author: Lothiraldan

apps/opik-backend/config.yml

@@ -600,9 +600,6 @@ serviceToggles:
   # Default: true
   # Description: Whether or not Custom LLM provider is enabled
   customllmProviderEnabled: ${TOGGLE_CUSTOMLLM_PROVIDER_ENABLED:-"true"}
-  # Default: true
-  # Description: Whether or not Opik Built-in provider is enabled
-  opikbuiltinProviderEnabled: ${TOGGLE_OPIKBUILTIN_PROVIDER_ENABLED:-"true"}
   # Default: false
   # Description: Whether or not Collaborators tab feature is enabled
   collaboratorsTabEnabled: ${TOGGLE_COLLABORATORS_TAB_ENABLED:-"false"}
@@ -753,22 +750,23 @@ webhook:
     # Description: Maximum time to wait for acquiring metrics alert job lock
     metricsAlertJobLockWaitTimeout: ${WEBHOOK_METRICS_ALERT_JOB_LOCK_WAIT_TIMEOUT:-1s}
 
-# Built-in LLM Provider configuration
-# Note: The model name "opik-builtin-model" is hardcoded and cannot be changed.
+# Free Model configuration (admin-configured server-side LLM provider)
+# Note: The model name "opik-free-model" is hardcoded and cannot be changed.
 # This ensures backward compatibility with automation rules that store the model name.
-builtinLlmProvider:
+freeModel:
+  # Description: Whether or not to enable the free model provider
   # Default: false
-  # Description: Whether or not to enable the built-in LLM provider
-  enabled: ${BUILTIN_LLM_PROVIDER_ENABLED:-false}
-  # Default: gpt-4o-mini
+  enabled: ${OPIK_FREE_MODEL_ENABLED:-false}
   # Description: Actual model name sent to the AI server (the underlying LLM)
-  actualModel: ${BUILTIN_LLM_PROVIDER_ACTUAL_MODEL:-gpt-4o-mini}
-  # Default: openai
-  # Description: Provider name stored in spans for cost tracking
-  spanProvider: ${BUILTIN_LLM_PROVIDER_SPAN_PROVIDER:-openai}
   # Default: empty
-  # Description: API key for the OpenAI endpoint
-  apiKey: ${BUILTIN_LLM_PROVIDER_API_KEY:-}
+  actualModel: ${OPIK_FREE_MODEL_ACTUAL_MODEL:-}
+  # Description: Provider name stored in spans for cost tracking (e.g., "openai")
+  # Default: empty
+  spanProvider: ${OPIK_FREE_MODEL_SPAN_PROVIDER:-}
+  # Description: Base URL for OpenAI-compatible endpoint (e.g., "https://api.openai.com/v1")
   # Default: empty
-  # Description: Base URL for OpenAI-compatible endpoint (empty for built-in OpenAI)
-  baseUrl: ${BUILTIN_LLM_PROVIDER_BASE_URL:-}
+  baseUrl: ${OPIK_FREE_MODEL_BASE_URL:-}
+  # Description: API key for the endpoint (optional for auth-less endpoints)
+  # Default: empty
+  apiKey: ${OPIK_FREE_MODEL_API_KEY:-}
+

apps/opik-backend/src/main/java/com/comet/opik/OpikApplication.java

@@ -21,10 +21,10 @@
 import com.comet.opik.infrastructure.llm.LlmModule;
 import com.comet.opik.infrastructure.llm.antropic.AnthropicModule;
 import com.comet.opik.infrastructure.llm.customllm.CustomLlmModule;
+import com.comet.opik.infrastructure.llm.freemodel.FreeModelModule;
 import com.comet.opik.infrastructure.llm.gemini.GeminiModule;
 import com.comet.opik.infrastructure.llm.openai.OpenAIModule;
 import com.comet.opik.infrastructure.llm.openrouter.OpenRouterModule;
-import com.comet.opik.infrastructure.llm.opikbuiltin.OpikBuiltinModule;
 import com.comet.opik.infrastructure.llm.vertexai.VertexAIModule;
 import com.comet.opik.infrastructure.ratelimit.RateLimitModule;
 import com.comet.opik.infrastructure.redis.RedisModule;
@@ -98,7 +98,7 @@ public void initialize(Bootstrap<OpikConfiguration> bootstrap) {
                         new ConfigurationModule(), new CacheModule(), new JobModule(), new AnthropicModule(),
                         new GeminiModule(), new OpenAIModule(), new OpenRouterModule(), new LlmModule(),
                         new AwsModule(), new UsageLimitModule(), new VertexAIModule(), new CustomLlmModule(),
-                        new OpikBuiltinModule())
+                        new FreeModelModule())
                 .installers(JobGuiceyInstaller.class)
                 .listen(new OpikGuiceyLifecycleEventListener(), new EventListenerRegistrar())
                 .enableAutoConfig()

apps/opik-backend/src/main/java/com/comet/opik/api/LlmProvider.java

@@ -16,7 +16,7 @@ public enum LlmProvider {
     OPEN_ROUTER("openrouter"),
     VERTEX_AI("vertex-ai"),
     CUSTOM_LLM("custom-llm"),
-    OPIK_BUILTIN("opik-builtin"),
+    OPIK_FREE("opik-free"),
     ;
 
     @JsonValue

apps/opik-backend/src/main/java/com/comet/opik/api/resources/v1/priv/ChatCompletionsResource.java

@@ -86,7 +86,7 @@ public Response create(
         }
 
         // Include actual model and provider in response headers for frontend span tracking.
-        // For OPIK_BUILTIN provider, the user-facing model name (e.g., "opik-builtin-model") differs
+        // For OPIK_FREE provider, the user-facing model name (e.g., "opik-free-model") differs
         // from the actual model used (e.g., "gpt-4o-mini"), and these headers allow correct cost calculation.
         var response = Response.ok()
                 .type(type)

apps/opik-backend/src/main/java/com/comet/opik/domain/LlmProviderApiKeyService.java

@@ -25,7 +25,7 @@
 import java.util.UUID;
 
 import static com.comet.opik.api.LlmProvider.CUSTOM_LLM;
-import static com.comet.opik.infrastructure.BuiltinLlmProviderConfig.BUILTIN_PROVIDER_ID;
+import static com.comet.opik.infrastructure.FreeModelConfig.FREE_MODEL_PROVIDER_ID;
 import static com.comet.opik.infrastructure.db.TransactionTemplateAsync.READ_ONLY;
 import static com.comet.opik.infrastructure.db.TransactionTemplateAsync.WRITE;
 
@@ -73,13 +73,17 @@ public ProviderApiKey.ProviderApiKeyPage find(@NonNull String workspaceId) {
 
         var content = new ArrayList<>(providerApiKeys);
 
-        // Inject virtual built-in provider if enabled
-        var builtinConfig = configuration.getBuiltinLlmProvider();
-        if (builtinConfig.isEnabled()) {
+        // Inject virtual free model provider if enabled
+        var freeModelConfig = configuration.getFreeModel();
+        if (freeModelConfig.isEnabled()) {
+            // Model label shows actual model name (e.g., "gpt-4o-mini")
+            // Frontend will append "(free)" suffix
             var virtualProvider = ProviderApiKey.builder()
-                    .id(BUILTIN_PROVIDER_ID)
-                    .provider(LlmProvider.OPIK_BUILTIN)
-                    .configuration(Map.of("models", builtinConfig.getModel()))
+                    .id(FREE_MODEL_PROVIDER_ID)
+                    .provider(LlmProvider.OPIK_FREE)
+                    .configuration(Map.of(
+                            "models", freeModelConfig.getModel(),
+                            "model_label", freeModelConfig.getActualModel()))
                     .readOnly(true)
                     .build();
             // Add at the end so user-configured providers are auto-selected by default in the Playground

apps/opik-backend/src/main/java/com/comet/opik/domain/llm/structuredoutput/StructuredOutputStrategy.java

@@ -43,7 +43,7 @@ static StructuredOutputStrategy getStrategy(LlmProvider provider, String modelNa
                     .map(StructuredOutputSupported::isStructuredOutputSupported).orElse(false);
             case VERTEX_AI -> VertexAIModelName.byQualifiedName(modelName)
                     .map(StructuredOutputSupported::isStructuredOutputSupported).orElse(false);
-            case ANTHROPIC, CUSTOM_LLM, OPIK_BUILTIN -> false; // TODO: Should we pick a model that supports structured output?
+            case ANTHROPIC, CUSTOM_LLM, OPIK_FREE -> false; // TODO: Should we pick a model that supports structured output?
         };
 
         return isStructuredOutputSupported ? new ToolCallingStrategy() : new InstructionStrategy();

apps/opik-backend/src/main/java/com/comet/opik/infrastructure/BuiltinLlmProviderConfig.java

@@ -0,0 +1,80 @@
+package com.comet.opik.infrastructure;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import lombok.Getter;
+import lombok.Setter;
+import lombok.ToString;
+
+import java.util.UUID;
+
+@Getter
+@Setter
+@ToString
+public class FreeModelConfig {
+
+    /**
+     * Fixed UUID for the free model provider. This is a virtual provider that doesn't exist in the database.
+     */
+    public static final UUID FREE_MODEL_PROVIDER_ID = UUID.fromString("00000000-0000-0000-0000-000000000001");
+
+    /**
+     * Fixed model name for the free model provider. This must remain constant because automation rules
+     * store this model name in their configuration. Changing it would break existing rules.
+     */
+    public static final String FREE_MODEL = "opik-free-model";
+
+    /**
+     * Whether the free model provider is enabled in configuration.
+     * Note: Use {@link #isEnabled()} to check if the provider is actually usable,
+     * as it also validates that required fields are configured.
+     */
+    @JsonProperty
+    private boolean enabled = false;
+
+    /**
+     * The actual model name sent to the AI server (e.g., "gpt-4o-mini").
+     * Required when enabled=true. If empty, the provider will not be registered.
+     */
+    @JsonProperty
+    private String actualModel = "";
+
+    /**
+     * Provider name stored in spans for cost tracking (e.g., "openai").
+     * Required when enabled=true. If empty, the provider will not be registered.
+     */
+    @JsonProperty
+    private String spanProvider = "";
+
+    /**
+     * Base URL for the OpenAI-compatible endpoint (e.g., "https://api.openai.com/v1").
+     * Required when enabled=true. If empty, the provider will not be registered.
+     */
+    @JsonProperty
+    private String baseUrl = "";
+
+    /**
+     * API key for the endpoint. Optional for auth-less endpoints.
+     */
+    @JsonProperty
+    @ToString.Exclude
+    private String apiKey = "";
+
+    /**
+     * Returns true if the free model provider is enabled AND all required fields are configured.
+     * This ensures fail-fast behavior - the provider won't register with missing configuration.
+     */
+    public boolean isEnabled() {
+        return enabled
+                && actualModel != null && !actualModel.isBlank()
+                && spanProvider != null && !spanProvider.isBlank()
+                && baseUrl != null && !baseUrl.isBlank();
+    }
+
+    /**
+     * Returns the fixed model name. This is not configurable to ensure backward compatibility
+     * with stored automation rules.
+     */
+    public String getModel() {
+        return FREE_MODEL;
+    }
+}

apps/opik-backend/src/main/java/com/comet/opik/infrastructure/FreeModelConfig.java

@@ -102,5 +102,5 @@ public class OpikConfiguration extends JobConfiguration {
     private AttachmentsConfig attachmentsConfig = new AttachmentsConfig();
 
     @Valid @NotNull @JsonProperty
-    private BuiltinLlmProviderConfig builtinLlmProvider = new BuiltinLlmProviderConfig();
+    private FreeModelConfig freeModel = new FreeModelConfig();
 }

apps/opik-backend/src/main/java/com/comet/opik/infrastructure/OpikConfiguration.java

@@ -47,7 +47,5 @@ public class ServiceTogglesConfig {
     @JsonProperty
     @NotNull boolean customllmProviderEnabled;
     @JsonProperty
-    @NotNull boolean opikbuiltinProviderEnabled;
-    @JsonProperty
     @NotNull boolean collaboratorsTabEnabled;
 }