Merge branch 'master' into spring-ai/provider-options-passthrough

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

@@ -0,0 +1,52 @@
+package io.temporal.springai.autoconfigure;
+
+import io.temporal.activity.ActivityOptions;
+import io.temporal.springai.model.ActivityChatModel;
+import io.temporal.springai.plugin.SpringAiPlugin;
+import java.util.Map;
+
+/**
+ * Spring-bean wrapper for the per-model {@link ActivityOptions} map consumed by {@link
+ * SpringAiPlugin}. Inject this type into your config by declaring a bean that returns an instance
+ * of it:
+ *
+ * <pre>{@code
+ * @Bean
+ * ChatModelActivityOptions chatModelActivityOptions() {
+ *     return new ChatModelActivityOptions(Map.of(
+ *         "reasoning", ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+ *             .setStartToCloseTimeout(Duration.ofMinutes(15))
+ *             .build()));
+ * }
+ * }</pre>
+ *
+ * <p>The wrapper exists so auto-configuration can inject your options by <em>type</em>, not by bean
+ * name. Spring's default behavior for {@code Map<String, T>} injection is to collect every bean of
+ * type {@code T} into a map keyed by bean name — which for a generic type like {@code Map<String,
+ * ActivityOptions>} would sweep in any unrelated {@link ActivityOptions} bean you have in the
+ * context. Having a dedicated wrapper type avoids that collision entirely.
+ *
+ * <p>Keys are chat-model bean names; values are the full {@link ActivityOptions} to use when {@link
+ * ActivityChatModel#forModel(String)} / {@link ActivityChatModel#forDefault()} build the stub for
+ * 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) {
+
+  public ChatModelActivityOptions {
+    byModelName = byModelName == null ? Map.of() : Map.copyOf(byModelName);
+  }
+
+  /** Returns an empty registry. */
+  public static ChatModelActivityOptions empty() {
+    return new ChatModelActivityOptions(Map.of());
+  }
+}

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

@@ -1,5 +1,6 @@
 package io.temporal.springai.autoconfigure;
 
+import io.temporal.activity.ActivityOptions;
 import io.temporal.springai.plugin.SpringAiPlugin;
 import java.util.Map;
 import org.springframework.ai.chat.model.ChatModel;
@@ -28,9 +29,32 @@
     name = {"org.springframework.ai.chat.model.ChatModel", "io.temporal.worker.Worker"})
 public class SpringAiTemporalAutoConfiguration {
 
+  /**
+   * Builds the {@link SpringAiPlugin}. Picks up an optional {@link ChatModelActivityOptions} bean
+   * and forwards its map to the plugin as per-model {@link ActivityOptions} overrides. The wrapper
+   * type exists so this auto-config can inject user options <em>by type</em> — trying to inject
+   * {@code Map<String, ActivityOptions>} directly would trigger Spring's collection-of-beans
+   * autowiring and sweep in any unrelated {@link ActivityOptions} bean in the context.
+   *
+   * <p>Example user config:
+   *
+   * <pre>{@code
+   * @Bean
+   * ChatModelActivityOptions chatModelActivityOptions() {
+   *     return new ChatModelActivityOptions(Map.of(
+   *         "reasoning", ActivityOptions.newBuilder(ActivityChatModel.defaultActivityOptions())
+   *             .setStartToCloseTimeout(Duration.ofMinutes(15))
+   *             .build()));
+   * }
+   * }</pre>
+   */
   @Bean
   public SpringAiPlugin springAiPlugin(
-      @Autowired Map<String, ChatModel> chatModels, ObjectProvider<ChatModel> primaryChatModel) {
-    return new SpringAiPlugin(chatModels, primaryChatModel.getIfUnique());
+      @Autowired Map<String, ChatModel> chatModels,
+      ObjectProvider<ChatModel> primaryChatModel,
+      ObjectProvider<ChatModelActivityOptions> perModelOptions) {
+    ChatModelActivityOptions options =
+        perModelOptions.getIfAvailable(ChatModelActivityOptions::empty);
+    return new SpringAiPlugin(chatModels, primaryChatModel.getIfUnique(), options.byModelName());
   }
 }

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

@@ -5,6 +5,8 @@
 import io.temporal.activity.ActivityOptions;
 import io.temporal.common.RetryOptions;
 import io.temporal.springai.activity.ChatModelActivity;
+import io.temporal.springai.plugin.SpringAiPlugin;
+import io.temporal.springai.plugin.SpringAiPluginOptions;
 import io.temporal.workflow.Workflow;
 import java.net.URI;
 import java.net.URISyntaxException;
@@ -130,16 +132,29 @@ private ActivityChatModel(
   }
 
   /**
-   * Creates an ActivityChatModel for the default chat model with the plugin's default {@link
-   * ActivityOptions} (2-minute start-to-close timeout, 3 attempts, clearly permanent AI errors
-   * marked non-retryable).
+   * Creates an ActivityChatModel for the default chat model.
+   *
+   * <p>Options resolution order:
+   *
+   * <ol>
+   *   <li>An entry registered on {@link SpringAiPlugin} under {@link
+   *       ChatModelTypes#DEFAULT_MODEL_NAME} in the per-model {@code ActivityOptions} map, if any.
+   *   <li>The plugin's default {@link ActivityOptions} (2-minute start-to-close, 3 attempts,
+   *       clearly permanent AI errors marked non-retryable).
+   * </ol>
+   *
+   * <p>Callers who want to set explicit options should use {@link #forDefault(ActivityOptions)} —
+   * explicit options bypass the registry entirely.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
    * @return an ActivityChatModel for the default chat model
    */
   public static ActivityChatModel forDefault() {
-    return forDefault(defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
+    ActivityOptions options =
+        SpringAiPluginOptions.optionsFor(ChatModelTypes.DEFAULT_MODEL_NAME)
+            .orElseGet(ActivityChatModel::defaultActivityOptions);
+    return forDefault(options);
   }
 
   /**
@@ -158,8 +173,21 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
   }
 
   /**
-   * Creates an ActivityChatModel for a specific chat model by bean name with the plugin's default
-   * {@link ActivityOptions}.
+   * Creates an ActivityChatModel for a specific chat model by bean name.
+   *
+   * <p>Options resolution order:
+   *
+   * <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>
+   *
+   * <p>Callers who want to set explicit options should use {@link #forModel(String,
+   * ActivityOptions)} — explicit options bypass the registry entirely.
    *
    * <p><strong>Must be called from workflow code.</strong>
    *
@@ -168,7 +196,11 @@ public static ActivityChatModel forDefault(ActivityOptions options) {
    * @throws IllegalArgumentException if no model with that name exists (at activity runtime)
    */
   public static ActivityChatModel forModel(String modelName) {
-    return forModel(modelName, defaultActivityOptions(DEFAULT_TIMEOUT, DEFAULT_MAX_ATTEMPTS));
+    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

@@ -1,5 +1,6 @@
 package io.temporal.springai.plugin;
 
+import io.temporal.activity.ActivityOptions;
 import io.temporal.common.SimplePlugin;
 import io.temporal.springai.activity.ChatModelActivityImpl;
 import io.temporal.springai.model.ChatModelTypes;
@@ -53,9 +54,7 @@ public class SpringAiPlugin extends SimplePlugin {
    * @param chatModel the Spring AI chat model to wrap as an activity
    */
   public SpringAiPlugin(ChatModel chatModel) {
-    super("io.temporal.spring-ai");
-    this.chatModels = Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, chatModel);
-    this.defaultModelName = ChatModelTypes.DEFAULT_MODEL_NAME;
+    this(Map.of(ChatModelTypes.DEFAULT_MODEL_NAME, chatModel), null, Map.of());
   }
 
   /**
@@ -65,6 +64,31 @@ public SpringAiPlugin(ChatModel chatModel) {
    * @param primaryChatModel the primary chat model (used to determine default), or null
    */
   public SpringAiPlugin(Map<String, ChatModel> chatModels, @Nullable ChatModel primaryChatModel) {
+    this(chatModels, primaryChatModel, Map.of());
+  }
+
+  /**
+   * 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 {@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,
+      @Nullable ChatModel primaryChatModel,
+      Map<String, ActivityOptions> perModelOptions) {
     super("io.temporal.spring-ai");
 
     if (chatModels == null || chatModels.isEmpty()) {
@@ -85,13 +109,35 @@ public SpringAiPlugin(Map<String, ChatModel> chatModels, @Nullable ChatModel pri
       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) {
       log.info(
           "Registered {} chat models: {} (default: {})",
           chatModels.size(),
           chatModels.keySet(),
           defaultModelName);
     }
+    if (perModelOptions != null && !perModelOptions.isEmpty()) {
+      log.info(
+          "Registered per-model ActivityOptions overrides for {} model(s): {}",
+          perModelOptions.size(),
+          perModelOptions.keySet());
+    }
   }
 
   @Override

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

@@ -0,0 +1,54 @@
+package io.temporal.springai.plugin;
+
+import io.temporal.activity.ActivityOptions;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.atomic.AtomicReference;
+
+/**
+ * Process-scoped registry of per-chat-model {@link ActivityOptions}, populated by {@link
+ * SpringAiPlugin} at worker construction and consulted by {@link
+ * io.temporal.springai.model.ActivityChatModel#forModel(String)} when building the activity stub.
+ *
+ * <p>The registry is a static singleton because the plugin is a worker-side object but the lookup
+ * happens in workflow code that runs on the same JVM. Populating a shared static map before any
+ * workflow executes is the cleanest way to bridge that without teaching workflow code about plugin
+ * instances.
+ *
+ * <p>Limitations:
+ *
+ * <ul>
+ *   <li>Only one set of per-model options per JVM. Running multiple plugins in the same worker
+ *       process with different per-model options is not supported — the last registration wins.
+ *   <li>Callers who invoke {@link io.temporal.springai.model.ActivityChatModel#forModel(String,
+ *       ActivityOptions)} or {@link
+ *       io.temporal.springai.model.ActivityChatModel#forDefault(ActivityOptions)} bypass the
+ *       registry — explicit options always win.
+ * </ul>
+ */
+public final class SpringAiPluginOptions {
+
+  private static final AtomicReference<Map<String, ActivityOptions>> REGISTRY =
+      new AtomicReference<>(Map.of());
+
+  private SpringAiPluginOptions() {}
+
+  /**
+   * Installs the given per-model-name {@link ActivityOptions}, replacing any previous entries.
+   * Called by {@link SpringAiPlugin}. A null or empty map clears the registry.
+   */
+  public static void register(Map<String, ActivityOptions> options) {
+    REGISTRY.set(options == null || options.isEmpty() ? Map.of() : Map.copyOf(options));
+  }
+
+  /**
+   * Returns the options registered for the given model name, or empty if none. A null {@code
+   * modelName} always returns empty.
+   */
+  public static Optional<ActivityOptions> optionsFor(String modelName) {
+    if (modelName == null) {
+      return Optional.empty();
+    }
+    return Optional.ofNullable(REGISTRY.get().get(modelName));
+  }
+}