temporal-spring-ai: make per-model options compositional via 'default' catch-all

Address reviewer feedback on #2855: the three-way implicit fallback
(specific entry → library defaults) was ambiguous to readers of
forDefault() / forModel(name) — nothing locally tells the caller which
rung they land on. But a strict either-or (global OR exhaustive
per-model) breaks compositionality when a third-party starter
contributes a ChatModel bean your config didn't enumerate.

Resolution: keep per-model overrides, and reserve
ChatModelTypes.DEFAULT_MODEL_NAME as a user-declared catch-all key in
perModelOptions. Lookup is now map[name] ?? map["default"] ??
library defaults. SpringAiPlugin validates that every perModelOptions
key either matches a registered ChatModel bean or equals the catch-all
name; typos fail at plugin construction, not silently at call time.

Updates javadoc on SpringAiPlugin, ActivityChatModel.forModel(String),
and ChatModelActivityOptions. Collapses the duplicate "Activity
options" README section into one with an example of the catch-all
pattern. Adds tests for the catch-all lookup, specific-wins-over-
catch-all, and typo-key rejection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: donald-pinckney

temporal-spring-ai/README.md

@@ -64,6 +64,22 @@ ActivityChatModel chatModel = ActivityChatModel.forDefault(
                 .build());
 ```
 
+For configuration-driven per-model overrides, declare a `ChatModelActivityOptions` bean and auto-configuration wires the map into the plugin. A key equal to `ChatModelTypes.DEFAULT_MODEL_NAME` (the literal `"default"`) acts as a global catch-all: any chat model that lacks a bean-name-specific entry — including models contributed by third-party starters that your application did not declare directly — picks up that entry.
+
+```java
+@Bean
+ChatModelActivityOptions chatModelActivityOptions() {
+    ActivityOptions fiveMinute = ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+            .setStartToCloseTimeout(Duration.ofMinutes(5))
+            .build();
+    return new ChatModelActivityOptions(Map.of(
+            ChatModelTypes.DEFAULT_MODEL_NAME, fiveMinute,                             // global baseline
+            "claude", ActivityOptions.newBuilder(fiveMinute).setTaskQueue("claude-heavy").build())); // override
+}
+```
+
+Keys that neither match a registered ChatModel bean name nor equal `"default"` cause plugin construction to fail, so a typo surfaces at startup.
+
 `ActivityMcpClient.create()` / `create(ActivityOptions)` work the same way with a 30-second default timeout.
 
 The Temporal UI labels chat and MCP rows with a short Summary (`chat: <model>`, `mcp: <client>.<tool>`). `ActivityChatModel` and `ActivityMcpClient` are constructed only via these factories — there is no public constructor, so users can't accidentally end up in a code path that skips UI labels. Prompt text is deliberately not included in chat summaries to avoid leaking user input (which may contain PII, credentials, or other sensitive data) into workflow history and server logs.
@@ -187,24 +203,6 @@ Raw `byte[]` media gets serialized into every chat activity's input *and* result
 
 Override the cap by setting the system property `io.temporal.springai.maxMediaBytes` before your worker starts (pass a positive integer; `0` disables the check). For anything larger than a small thumbnail, the URI route is the right answer — have an activity write the bytes to blob storage, then pass only the URL into the conversation.
 
-## Activity options and retry behavior
-
-`ActivityChatModel.forDefault()` and `ActivityChatModel.forModel(name)` create the chat activity stub with sensible defaults: a 2-minute start-to-close timeout, 3 attempts, and `org.springframework.ai.retry.NonTransientAiException` + `java.lang.IllegalArgumentException` classified as non-retryable so a bad API key or invalid prompt fails fast.
-
-Override with `ActivityChatModel.forModel(name, ActivityOptions)`:
-
-```java
-ActivityOptions opts = ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
-        .setStartToCloseTimeout(Duration.ofMinutes(10))
-        .setTaskQueue("reasoning-models")
-        .build();
-ActivityChatModel chatModel = ActivityChatModel.forModel("reasoning", opts);
-```
-
-For repeated per-model overrides, declare a `ChatModelActivityOptions` bean and auto-configuration wires the map into the plugin. See that class's javadoc for the pattern.
-
-`ActivityMcpClient.create()` / `create(ActivityOptions)` behave the same way with a 30-second default timeout.
-
 ## Known limitations
 
 - **Streaming (`chatClient.stream(...)`)** — not currently supported. Use `.call()` instead.

temporal-spring-ai/src/main/java/io/temporal/springai/autoconfigure/ChatModelActivityOptions.java

@@ -31,6 +31,12 @@
  * that model. Use {@link ActivityChatModel#defaultActivityOptions()} as the baseline so the
  * plugin's non-retryable-error classification is preserved.
  *
+ * <p>A key equal to {@link io.temporal.springai.model.ChatModelTypes#DEFAULT_MODEL_NAME} (the
+ * literal {@code "default"}) acts as a global catch-all: any chat model that lacks a
+ * bean-name-specific entry — including models contributed by third-party starters that your
+ * application did not declare directly — picks up the {@code "default"} entry. Keys that neither
+ * match a registered ChatModel bean nor equal {@code "default"} cause plugin construction to fail.
+ *
  * @param byModelName per-model-bean-name {@link ActivityOptions} overrides; may be empty
  */
 public record ChatModelActivityOptions(Map<String, ActivityOptions> byModelName) {

temporal-spring-ai/src/main/java/io/temporal/springai/model/ActivityChatModel.java

@@ -152,6 +152,8 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
    * <ol>
    *   <li>An entry registered on {@link SpringAiPlugin} under {@code modelName} in the per-model
    *       {@code ActivityOptions} map, if any.
+   *   <li>An entry registered under {@link ChatModelTypes#DEFAULT_MODEL_NAME} in the per-model map,
+   *       which acts as a user-declared catch-all for models without a specific entry.
    *   <li>The plugin's default {@link ActivityOptions} (2-minute start-to-close, 3 attempts,
    *       clearly permanent AI errors marked non-retryable).
    * </ol>
@@ -168,6 +170,7 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
   public static ActivityChatModel forModel(String modelName) {
     ActivityOptions options =
         SpringAiPluginOptions.optionsFor(modelName)
+            .or(() -> SpringAiPluginOptions.optionsFor(ChatModelTypes.DEFAULT_MODEL_NAME))
             .orElseGet(ActivityChatModel::defaultActivityOptions);
     return forModel(modelName, options);
   }

temporal-spring-ai/src/main/java/io/temporal/springai/plugin/SpringAiPlugin.java

@@ -71,14 +71,19 @@ public SpringAiPlugin(Map<String, ChatModel> chatModels, @Nullable ChatModel pri
    * Creates a new SpringAiPlugin with multiple ChatModels and per-model {@link ActivityOptions}.
    *
    * <p>Entries in {@code perModelOptions} are keyed by chat-model bean name and consulted by {@link
-   * io.temporal.springai.model.ActivityChatModel#forModel(String)} (and by {@link
-   * io.temporal.springai.model.ActivityChatModel#forDefault()} via {@link
-   * ChatModelTypes#DEFAULT_MODEL_NAME}). Callers who pass explicit {@code ActivityOptions} to a
-   * factory bypass this map entirely.
+   * io.temporal.springai.model.ActivityChatModel#forModel(String)} and {@link
+   * io.temporal.springai.model.ActivityChatModel#forDefault()}. An entry whose key equals {@link
+   * ChatModelTypes#DEFAULT_MODEL_NAME} acts as a global catch-all: models without a
+   * bean-name-specific entry pick it up, including models contributed by third-party starters that
+   * the application did not declare directly. Keys that neither match a bean nor equal the
+   * catch-all name cause plugin construction to fail, so a typo'd model name surfaces early.
+   * Callers who pass explicit {@code ActivityOptions} to a factory bypass this map entirely.
    *
    * @param chatModels map of bean names to ChatModel instances
    * @param primaryChatModel the primary chat model (used to determine default), or null
    * @param perModelOptions per-model-name ActivityOptions overrides; may be empty
+   * @throws IllegalArgumentException if a key in {@code perModelOptions} neither matches a
+   *     registered ChatModel bean name nor equals {@link ChatModelTypes#DEFAULT_MODEL_NAME}
    */
   public SpringAiPlugin(
       Map<String, ChatModel> chatModels,
@@ -104,6 +109,20 @@ public SpringAiPlugin(
       this.defaultModelName = chatModels.keySet().iterator().next();
     }
 
+    if (perModelOptions != null) {
+      for (String key : perModelOptions.keySet()) {
+        if (!ChatModelTypes.DEFAULT_MODEL_NAME.equals(key) && !this.chatModels.containsKey(key)) {
+          throw new IllegalArgumentException(
+              "perModelOptions key '"
+                  + key
+                  + "' does not match any ChatModel bean. Registered models: "
+                  + this.chatModels.keySet()
+                  + ". Use '"
+                  + ChatModelTypes.DEFAULT_MODEL_NAME
+                  + "' as a catch-all for models without a specific entry.");
+        }
+      }
+    }
     SpringAiPluginOptions.register(perModelOptions);
 
     if (chatModels.size() > 1) {

temporal-spring-ai/src/test/java/io/temporal/springai/PerModelActivityOptionsTest.java

@@ -10,6 +10,7 @@
 import io.temporal.springai.activity.ChatModelActivityImpl;
 import io.temporal.springai.chat.TemporalChatClient;
 import io.temporal.springai.model.ActivityChatModel;
+import io.temporal.springai.model.ChatModelTypes;
 import io.temporal.springai.plugin.SpringAiPluginOptions;
 import io.temporal.testing.TestWorkflowEnvironment;
 import io.temporal.worker.Worker;
@@ -37,6 +38,7 @@ class PerModelActivityOptionsTest {
   private static final String TASK_QUEUE = "test-spring-ai-per-model-options";
   private static final Duration SLOW_TIMEOUT = Duration.ofMinutes(10);
   private static final Duration EXPLICIT_TIMEOUT = Duration.ofMinutes(7);
+  private static final Duration CATCH_ALL_TIMEOUT = Duration.ofMinutes(4);
   private static final Duration DEFAULT_TIMEOUT = ActivityChatModel.DEFAULT_TIMEOUT;
 
   private TestWorkflowEnvironment testEnv;
@@ -92,6 +94,48 @@ void registryMiss_fallsBackToDefault() {
     runAndAssertScheduledTimeout(UnknownModelWorkflow.class, DEFAULT_TIMEOUT);
   }
 
+  @Test
+  void catchAllKey_appliesToUnknownModel() {
+    // Only the DEFAULT_MODEL_NAME catch-all is registered; a lookup for a model without its own
+    // entry should fall through to it (not to the library defaults).
+    SpringAiPluginOptions.register(
+        Map.of(
+            ChatModelTypes.DEFAULT_MODEL_NAME,
+            ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+                .setStartToCloseTimeout(CATCH_ALL_TIMEOUT)
+                .build()));
+
+    Worker worker = testEnv.newWorker(TASK_QUEUE);
+    worker.registerWorkflowImplementationTypes(UnknownModelWorkflowImpl.class);
+    worker.registerActivitiesImplementations(stubActivityImpl());
+    testEnv.start();
+
+    runAndAssertScheduledTimeout(UnknownModelWorkflow.class, CATCH_ALL_TIMEOUT);
+  }
+
+  @Test
+  void specificEntry_winsOverCatchAll() {
+    // Both the catch-all and a model-specific entry are registered; the model-specific one
+    // must win for that model.
+    SpringAiPluginOptions.register(
+        Map.of(
+            ChatModelTypes.DEFAULT_MODEL_NAME,
+            ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+                .setStartToCloseTimeout(CATCH_ALL_TIMEOUT)
+                .build(),
+            "slow",
+            ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+                .setStartToCloseTimeout(SLOW_TIMEOUT)
+                .build()));
+
+    Worker worker = testEnv.newWorker(TASK_QUEUE);
+    worker.registerWorkflowImplementationTypes(SlowModelWorkflowImpl.class);
+    worker.registerActivitiesImplementations(stubActivityImpl());
+    testEnv.start();
+
+    runAndAssertScheduledTimeout(SlowModelWorkflow.class, SLOW_TIMEOUT);
+  }
+
   @Test
   void explicitOptions_bypassRegistry() {
     SpringAiPluginOptions.register(

temporal-spring-ai/src/test/java/io/temporal/springai/plugin/SpringAiPluginTest.java

@@ -3,9 +3,11 @@
 import static org.junit.jupiter.api.Assertions.*;
 import static org.mockito.Mockito.*;
 
+import io.temporal.activity.ActivityOptions;
 import io.temporal.springai.activity.ChatModelActivityImpl;
 import io.temporal.springai.activity.EmbeddingModelActivityImpl;
 import io.temporal.springai.activity.VectorStoreActivityImpl;
+import io.temporal.springai.model.ActivityChatModel;
 import io.temporal.springai.model.ChatModelTypes;
 import io.temporal.worker.Worker;
 import java.util.*;
@@ -108,6 +110,53 @@ void emptyChatModelsMap_throwsIllegalArgument() {
         IllegalArgumentException.class, () -> new SpringAiPlugin(new LinkedHashMap<>(), null));
   }
 
+  @Test
+  void perModelOptions_keyMatchingBean_accepts() {
+    ChatModel openai = mock(ChatModel.class);
+    ChatModel anthropic = mock(ChatModel.class);
+    Map<String, ChatModel> models = new LinkedHashMap<>();
+    models.put("openai", openai);
+    models.put("anthropic", anthropic);
+
+    // Should not throw — both keys match registered bean names.
+    new SpringAiPlugin(
+        models,
+        null,
+        Map.of(
+            "openai", ActivityChatModel.defaultActivityOptions(),
+            "anthropic", ActivityChatModel.defaultActivityOptions()));
+  }
+
+  @Test
+  void perModelOptions_catchAllKey_accepts() {
+    ChatModel openai = mock(ChatModel.class);
+    Map<String, ChatModel> models = Map.of("openai", openai);
+
+    // DEFAULT_MODEL_NAME is a valid key even when no bean is named "default" — it acts as the
+    // catch-all for models that don't have a specific entry, including third-party additions.
+    new SpringAiPlugin(
+        models,
+        null,
+        Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, ActivityChatModel.defaultActivityOptions()));
+  }
+
+  @Test
+  void perModelOptions_typoKey_throws() {
+    ChatModel openai = mock(ChatModel.class);
+    Map<String, ChatModel> models = Map.of("openai", openai);
+    Map<String, ActivityOptions> typo =
+        Map.of("openia", ActivityChatModel.defaultActivityOptions());
+
+    IllegalArgumentException ex =
+        assertThrows(IllegalArgumentException.class, () -> new SpringAiPlugin(models, null, typo));
+    assertTrue(
+        ex.getMessage().contains("openia"),
+        "message should name the offending key; got: " + ex.getMessage());
+    assertTrue(
+        ex.getMessage().contains(ChatModelTypes.DEFAULT_MODEL_NAME),
+        "message should point users at the catch-all key; got: " + ex.getMessage());
+  }
+
   // --- Optional plugin tests ---
 
   @Test