Merge remote-tracking branch 'origin/master' into d/move-extensions

Author: donald-pinckney

contrib/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.

contrib/temporal-spring-ai/src/main/java/io/temporal/springai/activity/ChatModelActivityImpl.java

@@ -1,15 +1,19 @@
 package io.temporal.springai.activity;
 
+import com.fasterxml.jackson.databind.ObjectMapper;
 import io.temporal.springai.model.ChatModelTypes;
 import io.temporal.springai.model.ChatModelTypes.Message;
 import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.List;
 import java.util.Map;
 import java.util.stream.Collectors;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.ai.chat.messages.*;
 import org.springframework.ai.chat.model.ChatModel;
 import org.springframework.ai.chat.model.ChatResponse;
+import org.springframework.ai.chat.prompt.ChatOptions;
 import org.springframework.ai.chat.prompt.Prompt;
 import org.springframework.ai.content.Media;
 import org.springframework.ai.model.tool.ToolCallingChatOptions;
@@ -30,6 +34,25 @@
  */
 public class ChatModelActivityImpl implements ChatModelActivity {
 
+  private static final Logger log = LoggerFactory.getLogger(ChatModelActivityImpl.class);
+
+  /**
+   * Reads the caller's {@link ChatOptions} back out of the serialized JSON carried on {@link
+   * ChatModelTypes.ModelOptions}. Plain Jackson — the workflow side wrote the blob with a matching
+   * plain {@link ObjectMapper}.
+   */
+  private static final ObjectMapper OPTIONS_MAPPER =
+      new ObjectMapper().addMixIn(ToolCallingChatOptions.class, ToolCallingChatOptionsMixin.class);
+
+  /**
+   * Mirror of the mixin in {@code ActivityChatModel} so deserialization ignores the same tool-bag
+   * properties the workflow side skipped.
+   */
+  @com.fasterxml.jackson.annotation.JsonIgnoreProperties(
+      value = {"toolCallbacks", "toolNames", "toolContext"},
+      ignoreUnknown = true)
+  private abstract static class ToolCallingChatOptionsMixin {}
+
   private final Map<String, ChatModel> chatModels;
   private final String defaultModelName;
 
@@ -77,6 +100,32 @@ private Prompt createPrompt(ChatModelTypes.ChatModelActivityInput input) {
     List<org.springframework.ai.chat.messages.Message> messages =
         input.messages().stream().map(this::toSpringMessage).collect(Collectors.toList());
 
+    List<ToolCallback> toolCallbacks = stubToolCallbacks(input);
+
+    // Primary path: rehydrate the caller's exact ChatOptions subclass from the serialized blob.
+    // Preserves provider-specific fields (OpenAI reasoning_effort, Anthropic thinking budget,
+    // etc.) that aren't representable in the common ModelOptions record.
+    ChatOptions rehydrated = tryRehydrateChatOptions(input.modelOptions());
+    if (rehydrated instanceof ToolCallingChatOptions tcOpts) {
+      tcOpts.setInternalToolExecutionEnabled(false);
+      if (!toolCallbacks.isEmpty()) {
+        tcOpts.setToolCallbacks(toolCallbacks);
+      }
+      return Prompt.builder().messages(messages).chatOptions(tcOpts).build();
+    }
+    if (rehydrated != null) {
+      // Caller's ChatOptions isn't a ToolCallingChatOptions. Accept it as-is; tool callbacks
+      // can't be attached via this path, but most provider options in practice are
+      // ToolCallingChatOptions subclasses so this branch is a rare fallback.
+      log.debug(
+          "Rehydrated ChatOptions {} is not a ToolCallingChatOptions; tool callbacks will be"
+              + " omitted for this call.",
+          rehydrated.getClass().getName());
+      return Prompt.builder().messages(messages).chatOptions(rehydrated).build();
+    }
+
+    // Fallback path: no serialized blob, or rehydration failed. Build a ToolCallingChatOptions
+    // from the common scalar fields.
     ToolCallingChatOptions.Builder optionsBuilder =
         ToolCallingChatOptions.builder()
             .internalToolExecutionEnabled(false); // Let workflow handle tool execution
@@ -93,24 +142,63 @@ private Prompt createPrompt(ChatModelTypes.ChatModelActivityInput input) {
       if (opts.stopSequences() != null) optionsBuilder.stopSequences(opts.stopSequences());
     }
 
-    // Add tool callbacks (stubs that provide definitions but won't be executed
-    // since internalToolExecutionEnabled is false)
-    if (!CollectionUtils.isEmpty(input.tools())) {
-      List<ToolCallback> toolCallbacks =
-          input.tools().stream()
-              .map(
-                  tool ->
-                      createStubToolCallback(
-                          tool.function().name(),
-                          tool.function().description(),
-                          tool.function().jsonSchema()))
-              .collect(Collectors.toList());
+    if (!toolCallbacks.isEmpty()) {
       optionsBuilder.toolCallbacks(toolCallbacks);
     }
 
-    ToolCallingChatOptions chatOptions = optionsBuilder.build();
+    return Prompt.builder().messages(messages).chatOptions(optionsBuilder.build()).build();
+  }
+
+  private List<ToolCallback> stubToolCallbacks(ChatModelTypes.ChatModelActivityInput input) {
+    if (CollectionUtils.isEmpty(input.tools())) {
+      return List.of();
+    }
+    return input.tools().stream()
+        .map(
+            tool ->
+                createStubToolCallback(
+                    tool.function().name(),
+                    tool.function().description(),
+                    tool.function().jsonSchema()))
+        .collect(Collectors.toList());
+  }
 
-    return Prompt.builder().messages(messages).chatOptions(chatOptions).build();
+  /**
+   * Attempts to rehydrate the caller's exact {@link ChatOptions} subclass from the serialized blob
+   * in {@code modelOptions}. Returns {@code null} if the blob is absent or rehydration fails, in
+   * which case the caller should use the common-field fallback.
+   */
+  private ChatOptions tryRehydrateChatOptions(ChatModelTypes.ModelOptions modelOptions) {
+    if (modelOptions == null
+        || modelOptions.chatOptionsClass() == null
+        || modelOptions.chatOptionsJson() == null) {
+      return null;
+    }
+    String className = modelOptions.chatOptionsClass();
+    try {
+      Class<?> cls = Class.forName(className, true, Thread.currentThread().getContextClassLoader());
+      if (!ChatOptions.class.isAssignableFrom(cls)) {
+        log.warn(
+            "Serialized ChatOptions class {} is not a ChatOptions; falling back to common fields.",
+            className);
+        return null;
+      }
+      return (ChatOptions) OPTIONS_MAPPER.readValue(modelOptions.chatOptionsJson(), cls);
+    } catch (ClassNotFoundException e) {
+      log.warn(
+          "Could not load ChatOptions class {} on the activity side; falling back to common"
+              + " fields. This typically means spring-ai-<provider> is not on this worker's"
+              + " classpath.",
+          className);
+      return null;
+    } catch (com.fasterxml.jackson.core.JsonProcessingException e) {
+      log.warn(
+          "Could not deserialize ChatOptions of type {} on the activity side; falling back to"
+              + " common fields. Cause: {}",
+          className,
+          e.getMessage());
+      return null;
+    }
   }
 
   private org.springframework.ai.chat.messages.Message toSpringMessage(Message message) {

contrib/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());
+  }
+}

contrib/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());
   }
 }