Let a deployment add a BYOK provider without naming an SPI type (#1949)

* Let a deployment add a BYOK provider without naming an SPI type

Closes #1945.

* Name the provider first in both endpoint cases, and pin what the tests missed

Two sibling cases took their two Strings in opposite orders, so a Java
caller copying one line onto the other compiled and silently swapped
provider and base URL.

The base URL reaching the client, and the Anthropic resolver path, were
both untested: dropping either left the suite green. Both new tests fail
under that mutation.

* Address review: log the factories, raw-string the warning, say how to add a provider

Sealed so a case and the client that can talk to it stay together; adding
a provider is a resolver returning an existing case, which the KDoc now
says at the type.

Author: jasperblues

embabel-agent-anthropic/src/main/kotlin/com/embabel/agent/anthropic/AnthropicModelFactory.kt

@@ -22,6 +22,7 @@ import com.embabel.agent.spi.LlmService
 import com.embabel.agent.spi.support.springai.SpringAiLlmService
 import com.embabel.chat.UserMessage
 import com.embabel.common.ai.model.LlmOptions
+import com.embabel.common.ai.model.PricingModel
 import com.embabel.common.byok.ByokFactory
 import com.embabel.common.byok.InvalidApiKeyException
 import com.embabel.common.byok.requireUsableApiKey
@@ -35,6 +36,7 @@ import org.springframework.beans.factory.ObjectProvider
 import org.springframework.retry.support.RetryTemplate
 import org.springframework.web.client.RestClient
 import java.time.Duration
+import java.time.LocalDate
 
 /**
  * Builds Anthropic [LlmService] instances from a raw API key.
@@ -114,12 +116,23 @@ open class AnthropicModelFactory(
      * is ignored — retries are handled at the ChatClientLlmOperations layer via spring-retry.
      *
      * @param model Model identifier, e.g. [AnthropicModels.CLAUDE_HAIKU_4_5].
+     * @param provider Provider name the built service reports. Defaults to [AnthropicModels.PROVIDER];
+     * override it when the endpoint is a gateway fronting Anthropic, so cost and metadata lookups
+     * key on the gateway rather than on Anthropic itself.
+     * @param pricingModel What the call costs the deployment. Null - the default - is unknown rather
+     * than free; a BYOK caller passes [com.embabel.common.ai.model.PricingModel.ALL_YOU_CAN_EAT],
+     * since the user's own key is billed.
+     * @param knowledgeCutoffDate Reaches the LLM as a prompt contribution, so state it only if you
+     * know it for this model.
      */
     @JvmOverloads
     fun build(
         model: String,
         @Suppress("UNUSED_PARAMETER")
         retryTemplate: RetryTemplate? = null,
+        provider: String = AnthropicModels.PROVIDER,
+        pricingModel: PricingModel? = null,
+        knowledgeCutoffDate: LocalDate? = null,
     ): LlmService<*> {
         val chatModel = AnthropicChatModel.builder()
             .options(AnthropicChatOptions.builder().model(model).build())
@@ -133,8 +146,10 @@ open class AnthropicModelFactory(
         return SpringAiLlmService(
             name = model,
             chatModel = chatModel,
-            provider = AnthropicModels.PROVIDER,
+            provider = provider,
             optionsConverter = AnthropicOptionsConverter,
+            knowledgeCutoffDate = knowledgeCutoffDate,
+            pricingModel = pricingModel,
             thinkingSupported = true,
         )
     }

embabel-agent-anthropic/src/test/kotlin/com/embabel/agent/anthropic/AnthropicModelFactoryTest.kt

@@ -17,6 +17,8 @@ package com.embabel.agent.anthropic
 
 import com.embabel.agent.api.models.AnthropicModels
 import com.embabel.agent.spi.support.springai.SpringAiLlmService
+import com.embabel.common.ai.model.PricingModel
+import com.embabel.common.ai.prompt.KnowledgeCutoffDate
 import com.embabel.common.byok.BLANK_API_KEY_MESSAGE
 import com.embabel.common.byok.InvalidApiKeyException
 import com.sun.net.httpserver.HttpServer
@@ -28,13 +30,15 @@ import io.mockk.mockk
 import org.junit.jupiter.api.AfterEach
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Assertions.assertNotNull
+import org.junit.jupiter.api.Assertions.assertNull
 import org.junit.jupiter.api.Assertions.assertTrue
 import org.junit.jupiter.api.BeforeEach
 import org.junit.jupiter.api.Test
 import org.junit.jupiter.api.assertThrows
 import org.springframework.beans.factory.ObjectProvider
 import org.springframework.web.client.RestClient
 import java.net.InetSocketAddress
+import java.time.LocalDate
 import java.util.function.Supplier
 
 class AnthropicModelFactoryTest {
@@ -56,6 +60,40 @@ class AnthropicModelFactoryTest {
         assertEquals(AnthropicModels.PROVIDER, service.provider)
     }
 
+    @Test
+    fun `build states the provider, price and cutoff a BYOK caller asks for`() {
+        // A gateway fronting Anthropic reports itself, not Anthropic, so cost and metadata lookups
+        // key on the gateway; and a BYOK call is billed to the user's key, not the deployment's.
+        val factory = AnthropicModelFactory(
+            apiKey = "test-key",
+            observationRegistry = ObservationRegistry.NOOP,
+            restClientBuilder = restClientBuilder,
+        )
+        val service = factory.build(
+            model = AnthropicModels.CLAUDE_HAIKU_4_5,
+            provider = "OurGateway",
+            pricingModel = PricingModel.ALL_YOU_CAN_EAT,
+            knowledgeCutoffDate = LocalDate.of(2026, 1, 31),
+        ) as SpringAiLlmService
+        assertEquals("OurGateway", service.provider)
+        assertEquals(PricingModel.ALL_YOU_CAN_EAT, service.pricingModel)
+        assertEquals(LocalDate.of(2026, 1, 31), service.knowledgeCutoffDate)
+        assertTrue(service.promptContributors.any { it is KnowledgeCutoffDate })
+    }
+
+    @Test
+    fun `build defaults to Anthropic itself, at an unstated price`() {
+        val factory = AnthropicModelFactory(
+            apiKey = "test-key",
+            observationRegistry = ObservationRegistry.NOOP,
+            restClientBuilder = restClientBuilder,
+        )
+        val service = factory.build(model = AnthropicModels.CLAUDE_HAIKU_4_5) as SpringAiLlmService
+        assertEquals(AnthropicModels.PROVIDER, service.provider)
+        assertNull(service.pricingModel)
+        assertNull(service.knowledgeCutoffDate)
+    }
+
     @Test
     fun `build with custom baseUrl constructs without error`() {
         val factory = AnthropicModelFactory(

embabel-agent-api/src/main/kotlin/com/embabel/common/ai/model/ConfigurableModelProvider.kt

@@ -532,7 +532,7 @@ class ConfigurableModelProvider @JvmOverloads constructor(
                 ?.also { credentialLlmServices[key] = it }
         if (llmService == null) {
             logger.warn(
-                "No CredentialLlmServiceFactory handles provider '{}', needed for role '{}'",
+                """Nothing built a service for provider '{}', needed for role '{}'. Register a CredentialEndpointResolver for it, and check that the module speaking its wire protocol is on the classpath""",
                 credential.provider, role,
             )
             return null

embabel-agent-api/src/main/kotlin/com/embabel/common/ai/model/CredentialEndpoint.kt

@@ -0,0 +1,148 @@
+/*
+ * Copyright 2024-2026 Embabel Pty Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.embabel.common.ai.model
+
+import java.time.LocalDate
+
+/**
+ * Where a user's key should be sent, and what the service built from it should say about itself.
+ *
+ * A value rather than a service: the application states which endpoint speaks for a provider, and
+ * the platform builds the client, so nothing here names a type from `com.embabel.agent.spi`. That
+ * is the point - [CredentialLlmServiceFactory] is the other way round, and requires a package the
+ * documentation asks application code not to depend on.
+ *
+ * The case is the wire protocol, because that is what decides which client can talk to the
+ * endpoint. Everything that varies within a protocol is a field.
+ *
+ * Adding a provider therefore does not mean adding a case, and cannot: the interface is sealed, so
+ * only this module can. Nearly every provider speaks one of the protocols below, and reaching it is
+ * a [CredentialEndpointResolver] returning [OpenAiCompatible] or [Anthropic] with your base URL -
+ * no framework change, no new type.
+ *
+ * A case earns its place only when a protocol needs a *client* this framework does not have, and
+ * whoever adds one has to add that client too. Sealed so that the two stay together: an open
+ * hierarchy would let an application define a case nothing here can build, and it would fail at
+ * runtime with a key already in hand. Until such a protocol is shipped, reach it by registering a
+ * [CredentialLlmServiceFactory] and building the service yourself, accepting the SPI dependency
+ * that carries.
+ */
+sealed interface CredentialEndpoint {
+
+    /**
+     * Provider name the built service reports, which is what cost accounting and metadata lookups
+     * key on. Usually the same name the credential carries, but it need not be: a credential holds
+     * whatever spelling the application stored, and this is the framework's own.
+     */
+    val provider: String
+
+    /**
+     * Base URL to talk to, or null for the protocol's default host.
+     *
+     * Non-null is the usual case for a gateway or a proxy - which, along with a provider this
+     * framework does not ship, is the reason to write a resolver at all. Set it. Null on an
+     * [OpenAiCompatible] endpoint means OpenAI's own servers, so a null that reached one by
+     * accident - an unset property, say - would send a gateway's key to OpenAI under the gateway's
+     * name. The one legitimate null is OpenAI itself, which is why the type still permits it.
+     *
+     * [OpenAiCompatible] states it and [Anthropic] defaults it: "Anthropic's protocol" names a
+     * host, "OpenAI-compatible" names none.
+     */
+    val baseUrl: String?
+
+    /**
+     * Defaults to [PricingModel.ALL_YOU_CAN_EAT] - zero - because a BYOK call is billed to the
+     * user's own key rather than to the deployment, so charging it to the deployment's cost
+     * accounting would be wrong in the one direction that matters. Set it only if you are
+     * reselling the call and do want it counted.
+     */
+    val pricingModel: PricingModel
+
+    /**
+     * Null unless you know it for the model the role named. The name comes from configuration and
+     * may be one this framework version has never heard of, so a cutoff stated here would be a
+     * guess, and it reaches the LLM as a prompt contribution.
+     */
+    val knowledgeCutoffDate: LocalDate?
+
+    /**
+     * The OpenAI wire protocol, which most providers now speak: OpenAI itself, DeepSeek, Mistral,
+     * Gemini and Atlas Cloud all reach the platform this way, as does the average self-hosted
+     * gateway.
+     */
+    data class OpenAiCompatible @JvmOverloads constructor(
+        override val provider: String,
+        override val baseUrl: String?,
+        override val pricingModel: PricingModel = PricingModel.ALL_YOU_CAN_EAT,
+        override val knowledgeCutoffDate: LocalDate? = null,
+    ) : CredentialEndpoint
+
+    /**
+     * Anthropic's own protocol, for Anthropic and anything fronting it.
+     */
+    data class Anthropic @JvmOverloads constructor(
+        override val provider: String,
+        override val baseUrl: String? = null,
+        override val pricingModel: PricingModel = PricingModel.ALL_YOU_CAN_EAT,
+        override val knowledgeCutoffDate: LocalDate? = null,
+    ) : CredentialEndpoint
+}
+
+/**
+ * Says where a user's key should be sent, for the providers this application knows about.
+ *
+ * Application API, not SPI: you implement it and register it as a bean, and the platform calls it.
+ * The extension point for BYOK against a provider the framework does not ship. Register as many as
+ * you like: the first non-null answer wins, in [org.springframework.core.Ordered] order, so a
+ * resolver answers for the providers it knows and returns null for the rest. What reads them is
+ * the `embabel-agent-starter-byok` machinery that builds services from user keys, so a deployment
+ * without that starter can register these and never be asked.
+ *
+ * What these beans say is the first word, and the endpoints `embabel-agent-starter-byok` knows for
+ * Anthropic, OpenAI, DeepSeek, Mistral, Gemini and Atlas Cloud are the last: answering for one of
+ * those overrides it, for a proxy or a custom base URL, with no `@Order` needed. The shipped
+ * endpoints are not beans, so they cannot tie with yours - `@Order` decides only which of *your*
+ * resolvers is asked first, and ties between them fall back to bean registration order.
+ *
+ * ```kotlin
+ * @Bean
+ * fun ourGatewayEndpoint() = CredentialEndpointResolver { credential, _ ->
+ *     if (!credential.provider.equals("OurGateway", ignoreCase = true)) null
+ *     else CredentialEndpoint.OpenAiCompatible(provider = "OurGateway", baseUrl = GATEWAY_URL)
+ * }
+ * ```
+ *
+ * Return null rather than an endpoint for a provider you do not handle: a resolver that answers for
+ * everything would point someone else's key at your gateway.
+ *
+ * The platform caches the service it builds, per (provider, key, model), so a resolver is consulted
+ * on a cache miss rather than on every call - though possibly more than once within one, as each
+ * wire protocol's builder gets its turn. Implementations must be thread-safe, and should be pure
+ * and cheap for the same reason.
+ *
+ * That cache is keyed on (provider, key, model) and not on what you return here, so a resolver that
+ * answers differently for the same three - per tenant, say, read from some ambient context - will
+ * have its first answer serve every later caller sharing them.
+ */
+fun interface CredentialEndpointResolver {
+
+    /**
+     * @param credential the user's key, and the provider name it was stored under
+     * @param model the model the role named, which may be one this framework version does not know
+     * @return where to send that key, or null to let the next resolver decide
+     */
+    fun resolve(credential: ProviderCredential, model: String): CredentialEndpoint?
+}

embabel-agent-api/src/main/kotlin/com/embabel/common/ai/model/RoleResolver.kt

@@ -41,7 +41,7 @@ sealed interface RoleResolution {
 
     /**
      * A provider key. The platform looks the role up for that provider and builds the service
-     * through a [CredentialLlmServiceFactory], caching it.
+     * through a [CredentialEndpointResolver], caching it.
      */
     data class Credential(
         val credential: ProviderCredential,
@@ -85,31 +85,23 @@ fun interface RoleResolver {
 }
 
 /**
- * Builds an [LlmService] from a user-supplied key.
+ * Builds an [LlmService] from a user-supplied key, for a wire protocol the framework has no client
+ * for.
  *
- * `embabel-agent-starter-byok` ships these for every provider BYOK supports - Anthropic, OpenAI,
- * DeepSeek, Mistral, Gemini and Atlas Cloud - so per-user keys work with no application code at
- * all; see `com.embabel.agent.config.models.byok.CredentialLlmServiceFactoryConfig`. Register one
- * of your own only for a provider outside that set, or to override a shipped one for a custom base
- * URL or a proxy: the shipped beans stand aside for a bean of the same name.
+ * The second of two tiers, and the one to reach for last: it names [LlmService], which lives in
+ * `com.embabel.agent.spi` - a package application code is asked not to depend on. Adding a provider
+ * that speaks the OpenAI or Anthropic protocol - which is nearly all of them - is a
+ * [CredentialEndpointResolver] returning a value instead, with no SPI type in sight.
  *
- * Without a factory that handles the provider, a role resolving to [RoleResolution.Credential]
- * fails with [NoSuitableModelException] and a log line naming the provider nothing handled. An
- * implementation is a one-liner over the provider's own BYOK factory:
+ * `embabel-agent-starter-byok` ships an implementation per wire protocol, covering every provider
+ * BYOK supports - Anthropic, OpenAI, DeepSeek, Mistral, Gemini and Atlas Cloud - so per-user keys
+ * work with no application code at all; see
+ * `com.embabel.agent.config.models.byok.CredentialEndpointConfig`. The shipped beans stand aside
+ * for a bean of the same name, but replacing one that way also replaces the code that builds what
+ * [CredentialEndpointResolver]s resolve for that protocol.
  *
- * ```kotlin
- * @Bean
- * fun ourGatewayCredentialFactory() = CredentialLlmServiceFactory { credential, model ->
- *     if (!credential.provider.equals("OurGateway", ignoreCase = true)) null
- *     else OpenAiCompatibleModelFactory(baseUrl = GATEWAY_URL, apiKey = credential.apiKey)
- *         .openAiCompatibleLlm(
- *             model = model,
- *             pricingModel = PricingModel.ALL_YOU_CAN_EAT,
- *             provider = "OurGateway",
- *             knowledgeCutoffDate = null,
- *         )
- * }
- * ```
+ * Without a factory that handles the provider, a role resolving to [RoleResolution.Credential]
+ * fails with [NoSuitableModelException] and a log line naming the provider nothing handled.
  *
  * Return null for a provider this factory does not handle, rather than building something: the
  * platform tries each factory in turn, and a factory that answers for everything would hand back a