Add temporal-spring-ai module

TASK_QUEUE.json

@@ -0,0 +1,25 @@
+{
+  "project": "temporal-spring-ai",
+  "tasks": [
+    {
+      "id": "T13",
+      "title": "Remove includeBuild from samples-java",
+      "description": "Once temporal-spring-ai is published to Maven Central, remove the includeBuild('../sdk-java') block from samples-java/settings.gradle and the grpc-util workaround from core/build.gradle.",
+      "severity": "low",
+      "category": "cleanup",
+      "depends_on": [],
+      "status": "blocked",
+      "notes": "Blocked on SDK release. Not actionable yet."
+    },
+    {
+      "id": "T22",
+      "title": "Discuss: temporal-spring-ai-starter artifact for easier onboarding",
+      "description": "Create a temporal-spring-ai-starter artifact (POM-only, no code) that transitively pulls in temporal-spring-ai, temporal-sdk, and temporal-spring-boot-starter. Prevents version mismatches and ClassNotFoundException for users starting from scratch.",
+      "severity": "medium",
+      "category": "discussion",
+      "depends_on": [],
+      "status": "blocked",
+      "notes": "DABH review comment: https://github.com/temporalio/sdk-java/pull/2829/files#r3053808755. Do after merging the main PR \u2014 not urgent for initial landing."
+    }
+  ]
+}

settings.gradle

@@ -6,6 +6,11 @@ include 'temporal-testing'
 include 'temporal-test-server'
 include 'temporal-opentracing'
 include 'temporal-kotlin'
+// temporal-spring-ai requires Java 17+ (Spring AI dependency).
+// Exclude from builds running on older JDKs.
+if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_17)) {
+    include 'temporal-spring-ai'
+}
 include 'temporal-spring-boot-autoconfigure'
 include 'temporal-spring-boot-starter'
 include 'temporal-remote-data-encoder'

temporal-bom/build.gradle

@@ -12,6 +12,9 @@ dependencies {
         api project(':temporal-sdk')
         api project(':temporal-serviceclient')
         api project(':temporal-shaded')
+        if (JavaVersion.current().isCompatibleWith(JavaVersion.VERSION_17)) {
+            api project(':temporal-spring-ai')
+        }
         api project(':temporal-spring-boot-autoconfigure')
         api project(':temporal-spring-boot-starter')
         api project(':temporal-test-server')

temporal-spring-ai/README.md

@@ -0,0 +1,111 @@
+# temporal-spring-ai
+
+Integrates [Spring AI](https://docs.spring.io/spring-ai/reference/) with [Temporal](https://temporal.io/) workflows, making AI model calls, tool execution, vector store operations, embeddings, and MCP tool calls durable Temporal primitives.
+
+## Compatibility
+
+| Dependency | Minimum Version |
+|---|---|
+| Java | 17 |
+| Spring Boot | 3.x |
+| Spring AI | 1.1.0 |
+| Temporal Java SDK | 1.33.0 |
+
+## Quick Start
+
+Add the dependency (Maven):
+
+```xml
+<dependency>
+    <groupId>io.temporal</groupId>
+    <artifactId>temporal-spring-ai</artifactId>
+    <version>${temporal-sdk.version}</version>
+</dependency>
+```
+
+You also need `temporal-spring-boot-starter` and a Spring AI model starter (e.g. `spring-ai-starter-model-openai`).
+
+The plugin auto-registers `ChatModelActivity` with all Temporal workers. In your workflow:
+
+```java
+@WorkflowInit
+public MyWorkflowImpl(String goal) {
+    ActivityChatModel chatModel = ActivityChatModel.forDefault();
+
+    WeatherActivity weather = Workflow.newActivityStub(WeatherActivity.class, opts);
+
+    this.chatClient = TemporalChatClient.builder(chatModel)
+            .defaultSystem("You are a helpful assistant.")
+            .defaultTools(weather, new MyTools())
+            .build();
+}
+
+@Override
+public String run(String goal) {
+    return chatClient.prompt().user(goal).call().content();
+}
+```
+
+## Tool Types
+
+Tools passed to `defaultTools()` are handled based on their type:
+
+### Activity stubs
+
+Interfaces annotated with both `@ActivityInterface` and `@Tool` methods. Auto-detected and executed as durable Temporal activities with retries and timeouts.
+
+```java
+@ActivityInterface
+public interface WeatherActivity {
+    @Tool(description = "Get weather for a city") @ActivityMethod
+    String getWeather(String city);
+}
+```
+
+### `@SideEffectTool`
+
+Classes annotated with `@SideEffectTool`. Each `@Tool` method is wrapped in `Workflow.sideEffect()` — the result is recorded in history on first execution and replayed from history on subsequent replays. Use for cheap non-deterministic operations (timestamps, UUIDs).
+
+```java
+@SideEffectTool
+public class TimestampTools {
+    @Tool(description = "Get current time")
+    public String now() { return Instant.now().toString(); }
+}
+```
+
+### Plain tools
+
+Any class with `@Tool` methods that isn't a stub or `@SideEffectTool`. Executes directly in the workflow thread. The user is responsible for determinism — call activities, `Workflow.sideEffect()`, child workflows, etc. as needed.
+
+```java
+public class MyTools {
+    @Tool(description = "Process data")
+    public String process(String input) {
+        SomeActivity act = Workflow.newActivityStub(SomeActivity.class, opts);
+        return act.doWork(input);
+    }
+}
+```
+
+### Nexus service stubs
+
+Auto-detected and executed as Nexus operations, similar to activity stubs.
+
+## Optional Integrations
+
+Auto-configured when their dependencies are on the classpath:
+
+| Feature | Dependency | What it registers |
+|---|---|---|
+| Vector Store | `spring-ai-rag` | `VectorStoreActivity` |
+| Embeddings | `spring-ai-rag` | `EmbeddingModelActivity` |
+| MCP | `spring-ai-mcp` | `McpClientActivity` |
+
+These can also be set up programmatically without auto-configuration:
+
+```java
+new VectorStorePlugin(vectorStore)
+new EmbeddingModelPlugin(embeddingModel)
+new McpPlugin()
+```

temporal-spring-ai/build.gradle

@@ -0,0 +1,62 @@
+description = '''Temporal Java SDK Spring AI Plugin'''
+
+ext {
+    springAiVersion = '1.1.0'
+    // Spring AI requires Spring Boot 3.x / Java 17+
+    springBootVersionForSpringAi = "$springBoot3Version"
+}
+
+// Spring AI requires Java 17+, override the default Java 8 target from java.gradle.
+// When edgeDepsTest is set, use 21 to match other modules (avoids Gradle JVM compatibility rejection).
+ext {
+    springAiJavaVersion = project.hasProperty("edgeDepsTest") ? JavaVersion.VERSION_21 : JavaVersion.VERSION_17
+    springAiRelease = project.hasProperty("edgeDepsTest") ? '21' : '17'
+}
+
+java {
+    sourceCompatibility = springAiJavaVersion
+    targetCompatibility = springAiJavaVersion
+}
+
+compileJava {
+    options.compilerArgs.removeAll(['--release', '8'])
+    options.compilerArgs.addAll(['--release', springAiRelease])
+}
+
+compileTestJava {
+    options.compilerArgs.removeAll(['--release', '8'])
+    options.compilerArgs.addAll(['--release', springAiRelease])
+}
+
+dependencies {
+    api(platform("org.springframework.boot:spring-boot-dependencies:$springBootVersionForSpringAi"))
+    api(platform("org.springframework.ai:spring-ai-bom:$springAiVersion"))
+
+    // this module shouldn't carry temporal-sdk with it, especially for situations when users may be using a shaded artifact
+    compileOnly project(':temporal-sdk')
+    compileOnly project(':temporal-spring-boot-autoconfigure')
+
+    api 'org.springframework.boot:spring-boot-autoconfigure'
+    api 'org.springframework.ai:spring-ai-client-chat'
+
+    implementation 'org.springframework.boot:spring-boot-starter'
+
+    // Optional: Vector store support
+    compileOnly 'org.springframework.ai:spring-ai-rag'
+
+    // Optional: MCP (Model Context Protocol) support
+    compileOnly 'org.springframework.ai:spring-ai-mcp'
+
+    testImplementation project(':temporal-sdk')
+    testImplementation project(':temporal-testing')
+    testImplementation "org.mockito:mockito-core:${mockitoVersion}"
+    testImplementation 'org.springframework.boot:spring-boot-starter-test'
+    testImplementation 'org.springframework.ai:spring-ai-rag'
+
+    testRuntimeOnly group: 'ch.qos.logback', name: 'logback-classic', version: "${logbackVersion}"
+    testRuntimeOnly "org.junit.platform:junit-platform-launcher"
+}
+
+tasks.test {
+    useJUnitPlatform()
+}

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

@@ -0,0 +1,25 @@
+package io.temporal.springai.activity;
+
+import io.temporal.activity.ActivityInterface;
+import io.temporal.activity.ActivityMethod;
+import io.temporal.springai.model.ChatModelTypes;
+
+/**
+ * Temporal activity interface for calling Spring AI chat models.
+ *
+ * <p>This activity wraps a Spring AI {@link org.springframework.ai.chat.model.ChatModel} and makes
+ * it callable from within Temporal workflows. The activity handles serialization of prompts and
+ * responses, enabling durable AI conversations with automatic retries and timeout handling.
+ */
+@ActivityInterface
+public interface ChatModelActivity {
+
+  /**
+   * Calls the chat model with the given input.
+   *
+   * @param input the chat model input containing messages, options, and tool definitions
+   * @return the chat model output containing generated responses and metadata
+   */
+  @ActivityMethod
+  ChatModelTypes.ChatModelActivityOutput callChatModel(ChatModelTypes.ChatModelActivityInput input);
+}