Add loop DSL

Signed-off-by: Ricardo Zanini <[email protected]>

Author: ricardozanini

fluent/agentic/src/main/java/io/serverlessworkflow/fluent/agentic/AgentAdapters.java

@@ -20,8 +20,10 @@
 import dev.langchain4j.agentic.Cognisphere;
 import dev.langchain4j.agentic.internal.AgentExecutor;
 import dev.langchain4j.agentic.internal.AgentInstance;
+import io.serverlessworkflow.impl.expressions.LoopPredicateIndex;
 import java.util.List;
 import java.util.function.Function;
+import java.util.function.Predicate;
 import java.util.stream.Stream;
 
 public final class AgentAdapters {
@@ -34,4 +36,8 @@ public static List<AgentExecutor> toExecutors(Object... agents) {
   public static Function<Cognisphere, Object> toFunction(AgentExecutor exec) {
     return exec::invoke;
   }
+
+  public static LoopPredicateIndex<Object, Object> toWhile(Predicate<Cognisphere> exit) {
+    return (model, item, idx) -> !exit.test((Cognisphere) model);
+  }
 }

fluent/agentic/src/main/java/io/serverlessworkflow/fluent/agentic/AgentDoTaskFluent.java

@@ -16,6 +16,7 @@
 package io.serverlessworkflow.fluent.agentic;
 
 import java.util.UUID;
+import java.util.function.Consumer;
 
 public interface AgentDoTaskFluent<SELF extends AgentDoTaskFluent<SELF>> {
 
@@ -30,4 +31,10 @@ default SELF agent(Object agent) {
   default SELF sequence(Object... agents) {
     return sequence("seq-" + UUID.randomUUID(), agents);
   }
+
+  SELF loop(String name, Consumer<LoopAgentsBuilder> builder);
+
+  default SELF loop(Consumer<LoopAgentsBuilder> builder) {
+    return loop("loop-" + UUID.randomUUID(), builder);
+  }
 }

fluent/agentic/src/main/java/io/serverlessworkflow/fluent/agentic/AgentTaskItemListBuilder.java

@@ -15,8 +15,11 @@
  */
 package io.serverlessworkflow.fluent.agentic;
 
+import io.serverlessworkflow.api.types.Task;
+import io.serverlessworkflow.api.types.TaskItem;
 import io.serverlessworkflow.fluent.func.FuncTaskItemListBuilder;
 import io.serverlessworkflow.fluent.spec.BaseTaskItemListBuilder;
+import java.util.function.Consumer;
 
 public class AgentTaskItemListBuilder extends BaseTaskItemListBuilder<AgentTaskItemListBuilder>
     implements AgentDoTaskFluent<AgentTaskItemListBuilder> {
@@ -50,6 +53,14 @@ public AgentTaskItemListBuilder sequence(String name, Object... agents) {
     return self();
   }
 
+  @Override
+  public AgentTaskItemListBuilder loop(String name, Consumer<LoopAgentsBuilder> consumer) {
+    final LoopAgentsBuilder builder = new LoopAgentsBuilder();
+    consumer.accept(builder);
+    this.addTaskItem(new TaskItem(name, new Task().withForTask(builder.build())));
+    return self();
+  }
+
   @Override
   public AgentTaskItemListBuilder self() {
     return this;

fluent/agentic/src/main/java/io/serverlessworkflow/fluent/agentic/DelegatingAgentDoTaskFluent.java

@@ -17,6 +17,7 @@
 
 import io.serverlessworkflow.fluent.func.DelegatingFuncDoTaskFluent;
 import io.serverlessworkflow.fluent.spec.HasDelegate;
+import java.util.function.Consumer;
 
 public interface DelegatingAgentDoTaskFluent<SELF extends DelegatingAgentDoTaskFluent<SELF>>
     extends AgentDoTaskFluent<SELF>, DelegatingFuncDoTaskFluent<SELF>, HasDelegate {
@@ -39,4 +40,10 @@ default SELF sequence(String name, Object... agents) {
     d().sequence(name, agents);
     return (SELF) this;
   }
+
+  @SuppressWarnings("unchecked")
+  default SELF loop(String name, Consumer<LoopAgentsBuilder> consumer) {
+    d().loop(name, consumer);
+    return (SELF) this;
+  }
 }

fluent/agentic/src/main/java/io/serverlessworkflow/fluent/agentic/LoopAgentsBuilder.java

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * 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 io.serverlessworkflow.fluent.agentic;
+
+import dev.langchain4j.agentic.Cognisphere;
+import dev.langchain4j.agentic.internal.AgentExecutor;
+import io.serverlessworkflow.api.types.ForTaskConfiguration;
+import io.serverlessworkflow.api.types.func.ForTaskFunction;
+import io.serverlessworkflow.fluent.func.FuncTaskItemListBuilder;
+import java.util.List;
+import java.util.UUID;
+import java.util.function.ObjIntConsumer;
+import java.util.function.Predicate;
+import java.util.stream.IntStream;
+
+public class LoopAgentsBuilder {
+
+  private final FuncTaskItemListBuilder funcDelegate;
+  private final ForTaskFunction forTask;
+
+  LoopAgentsBuilder() {
+    this.forTask = new ForTaskFunction();
+    this.forTask.setFor(new ForTaskConfiguration());
+    this.funcDelegate = new FuncTaskItemListBuilder();
+  }
+
+  private static <E> void forEachIndexed(List<E> list, ObjIntConsumer<E> consumer) {
+    IntStream.range(0, list.size()).forEach(i -> consumer.accept(list.get(i), i));
+  }
+
+  public LoopAgentsBuilder subAgents(String baseName, Object... agents) {
+    List<AgentExecutor> execs = AgentAdapters.toExecutors(agents);
+    forEachIndexed(
+        execs,
+        (exec, idx) ->
+            funcDelegate.callFn(
+                baseName + "-" + idx, fn -> fn.function(AgentAdapters.toFunction(exec))));
+    return this;
+  }
+
+  public LoopAgentsBuilder subAgents(Object... agents) {
+    return this.subAgents("agent-" + UUID.randomUUID(), agents);
+  }
+
+  public LoopAgentsBuilder maxIterations(int maxIterations) {
+    this.forTask.withCollection(ignored -> IntStream.range(0, maxIterations).boxed().toList());
+    return this;
+  }
+
+  public LoopAgentsBuilder exitCondition(Predicate<Cognisphere> exitCondition) {
+    this.forTask.withWhile(AgentAdapters.toWhile(exitCondition));
+    return this;
+  }
+
+  public ForTaskFunction build() {
+    this.forTask.setDo(this.funcDelegate.build());
+    return this.forTask;
+  }
+}

fluent/agentic/src/test/java/io/serverlessworkflow/fluent/agentic/AgentTaskItemListBuilderTest.java

@@ -0,0 +1,86 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * 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 io.serverlessworkflow.fluent.agentic;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import io.serverlessworkflow.api.types.Task;
+import io.serverlessworkflow.api.types.TaskItem;
+import io.serverlessworkflow.api.types.func.CallTaskJava;
+import io.serverlessworkflow.api.types.func.ForTaskFunction;
+import java.util.List;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+/** Structural tests for AgentTaskItemListBuilder. */
+class AgentTaskItemListBuilderTest {
+
+  @Test
+  @DisplayName("agent(name,obj) adds a CallTaskJava-backed TaskItem")
+  void testAgentAddsCallTask() {
+    AgentTaskItemListBuilder b = new AgentTaskItemListBuilder();
+    Agents.MovieExpert agent = AgentsUtils.newMovieExpert();
+
+    b.agent("my-agent", agent);
+
+    List<TaskItem> items = b.build();
+    assertThat(items).hasSize(1);
+    TaskItem item = items.get(0);
+    assertThat(item.getName()).isEqualTo("my-agent");
+
+    Task task = item.getTask();
+    assertThat(task.getCallTask()).isInstanceOf(CallTaskJava.class);
+  }
+
+  @Test
+  @DisplayName("sequence(name, agents...) expands to N CallTask items, in order")
+  void testSequence() {
+    AgentTaskItemListBuilder b = new AgentTaskItemListBuilder();
+    Agents.MovieExpert a1 = AgentsUtils.newMovieExpert();
+    Agents.MovieExpert a2 = AgentsUtils.newMovieExpert();
+    Agents.MovieExpert a3 = AgentsUtils.newMovieExpert();
+
+    b.sequence("seq", a1, a2, a3);
+
+    List<TaskItem> items = b.build();
+    assertThat(items).hasSize(3);
+    assertThat(items.get(0).getName()).isEqualTo("seq-0");
+    assertThat(items.get(1).getName()).isEqualTo("seq-1");
+    assertThat(items.get(2).getName()).isEqualTo("seq-2");
+
+    // All must be call tasks
+    items.forEach(it -> assertThat(it.getTask().getCallTask().get()).isNotNull());
+  }
+
+  @Test
+  @DisplayName("loop(name, builder) produces a ForTaskFunction with inner call tasks")
+  void testLoop() {
+    AgentTaskItemListBuilder b = new AgentTaskItemListBuilder();
+    Agents.MovieExpert scorer = AgentsUtils.newMovieExpert();
+    Agents.MovieExpert editor = AgentsUtils.newMovieExpert();
+
+    b.loop("rev-loop", loop -> loop.subAgents("inner", scorer, editor));
+
+    List<TaskItem> items = b.build();
+    assertThat(items).hasSize(1);
+
+    TaskItem loopItem = items.get(0);
+    ForTaskFunction forFn = (ForTaskFunction) loopItem.getTask().getForTask();
+    assertThat(forFn).isNotNull();
+    assertThat(forFn.getDo()).hasSize(2); // scorer + editor inside
+    assertThat(forFn.getDo().get(0).getTask().getCallTask().get()).isNotNull();
+  }
+}

fluent/agentic/src/test/java/io/serverlessworkflow/fluent/agentic/AgenticWorkflowBuilderTest.java

@@ -15,6 +15,7 @@
  */
 package io.serverlessworkflow.fluent.agentic;
 
+import static io.serverlessworkflow.fluent.agentic.AgentsUtils.newMovieExpert;
 import static io.serverlessworkflow.fluent.agentic.Models.BASE_MODEL;
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -23,9 +24,14 @@
 import static org.mockito.Mockito.spy;
 
 import dev.langchain4j.agentic.AgentServices;
+import dev.langchain4j.agentic.Cognisphere;
+import io.serverlessworkflow.api.types.Task;
+import io.serverlessworkflow.api.types.TaskItem;
 import io.serverlessworkflow.api.types.Workflow;
 import io.serverlessworkflow.api.types.func.CallJava;
-import org.junit.jupiter.api.DisplayName;
+import io.serverlessworkflow.api.types.func.ForTaskFunction;
+import java.util.concurrent.atomic.AtomicInteger;
+import java.util.function.Predicate;
 import org.junit.jupiter.api.Test;
 
 public class AgenticWorkflowBuilderTest {
@@ -69,7 +75,6 @@ void sequenceAgents() {
   }
 
   @Test
-  @DisplayName("Mix spec verbs with agent()")
   void mixSpecAndAgent() {
     Workflow wf =
         AgenticWorkflowBuilder.workflow("mixFlow")
@@ -86,11 +91,55 @@ void mixSpecAndAgent() {
     assertThat(wf.getDo().get(2).getTask().getSetTask()).isNotNull();
   }
 
-  private Agents.MovieExpert newMovieExpert() {
-    return spy(
-        AgentServices.agentBuilder(Agents.MovieExpert.class)
-            .outputName("movies")
-            .chatModel(BASE_MODEL)
-            .build());
+  @Test
+  void loopOnlyAgents() {
+    Agents.MovieExpert expert = newMovieExpert();
+
+    Workflow wf =
+        AgenticWorkflowBuilder.workflow().tasks(d -> d.loop(l -> l.subAgents(expert))).build();
+
+    assertNotNull(wf);
+    assertThat(wf.getDo()).hasSize(1);
+
+    TaskItem ti = wf.getDo().get(0);
+    Task t = ti.getTask();
+    assertThat(t.getForTask()).isInstanceOf(ForTaskFunction.class);
+
+    ForTaskFunction fn = (ForTaskFunction) t.getForTask();
+    assertNotNull(fn.getDo());
+    assertThat(fn.getDo()).hasSize(1);
+    assertNotNull(fn.getDo().get(0).getTask().getCallTask().get());
+  }
+
+  @Test
+  void loopWithMaxIterationsAndExitCondition() {
+    Agents.MovieExpert expert = newMovieExpert();
+
+    AtomicInteger max = new AtomicInteger(4);
+    Predicate<Cognisphere> exit =
+        cog -> {
+          // stop when we already have at least one movie picked in state
+          var movies = cog.readState("movies", null);
+          return movies != null;
+        };
+
+    Workflow wf =
+        AgenticWorkflowBuilder.workflow("loop-ctrl")
+            .tasks(
+                d ->
+                    d.loop(
+                        "refineMovies",
+                        l ->
+                            l.maxIterations(max.get())
+                                .exitCondition(exit)
+                                .subAgents("picker", expert)))
+            .build();
+
+    TaskItem ti = wf.getDo().get(0);
+    ForTaskFunction fn = (ForTaskFunction) ti.getTask().getForTask();
+
+    assertNotNull(fn.getCollection(), "Synthetic collection should exist for maxIterations");
+    assertNotNull(fn.getWhilePredicate(), "While predicate set from exitCondition");
+    assertThat(fn.getDo()).hasSize(1);
   }
 }

fluent/agentic/src/test/java/io/serverlessworkflow/fluent/agentic/Agents.java

@@ -26,11 +26,11 @@ interface MovieExpert {
 
     @UserMessage(
         """
-            You are a great evening planner.
-            Propose a list of 3 movies matching the given mood.
-            The mood is {mood}.
-            Provide a list with the 3 items and nothing else.
-            """)
+                        You are a great evening planner.
+                        Propose a list of 3 movies matching the given mood.
+                        The mood is {mood}.
+                        Provide a list with the 3 items and nothing else.
+                        """)
     @Agent
     List<String> findMovie(@V("mood") String mood);
   }

fluent/agentic/src/test/java/io/serverlessworkflow/fluent/agentic/AgentsUtils.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020-Present The Serverless Workflow Specification Authors
+ *
+ * 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 io.serverlessworkflow.fluent.agentic;
+
+import static io.serverlessworkflow.fluent.agentic.Models.BASE_MODEL;
+import static org.mockito.Mockito.spy;
+
+import dev.langchain4j.agentic.AgentServices;
+
+public final class AgentsUtils {
+
+  private AgentsUtils() {}
+
+  public static Agents.MovieExpert newMovieExpert() {
+    return spy(
+        AgentServices.agentBuilder(Agents.MovieExpert.class)
+            .outputName("movies")
+            .chatModel(BASE_MODEL)
+            .build());
+  }
+}