code refactoring

Author: alexcheng1982

README.md

@@ -5,4 +5,9 @@
 
 Reference implementation of [Agentic Patterns](https://javaaidev.com/docs/agentic-patterns/intro/)
 
-This reference implementation is designed to be reusable.
+This reference implementation is designed to be reusable.
+
+Requirements:
+
+- Java 21
+- Spring AI 

evaluator-optimizer/pom.xml

@@ -11,6 +11,7 @@
 
   <artifactId>agentic-patterns-evaluator-optimizer</artifactId>
   <name>Agentic Patterns :: Evaluator-Optimizer</name>
+  <description>Evaluator-Optimizer agent</description>
 
   <properties>
     <maven.compiler.source>21</maven.compiler.source>

examples/src/main/java/com/javaaidev/agenticpatterns/examples/parallelizationworkflow/AlgorithmArticleGenerationAgent.java

@@ -6,6 +6,8 @@
 import com.javaaidev.agenticpatterns.examples.parallelizationworkflow.SampleCodeGenerationAgent.SampleCodeGenerationRequest;
 import com.javaaidev.agenticpatterns.examples.parallelizationworkflow.SampleCodeGenerationAgent.SampleCodeGenerationResponse;
 import com.javaaidev.agenticpatterns.parallelizationworkflow.PromptBasedAssembling;
+import com.javaaidev.agenticpatterns.parallelizationworkflow.SubtaskCreationRequest;
+import com.javaaidev.agenticpatterns.parallelizationworkflow.TaskExecutionResults;
 import io.micrometer.observation.ObservationRegistry;
 import java.util.List;
 import java.util.Map;
@@ -37,7 +39,7 @@ protected String getPromptTemplate() {
   }
 
   @Override
-  protected @Nullable Map<String, Object> getParentPromptContext(
+  protected @Nullable Map<String, Object> getRequestPromptContext(
       @Nullable AlgorithmArticleGenerationRequest request) {
     return Map.of("algorithm",
         AgentUtils.safeGet(request, AlgorithmArticleGenerationRequest::algorithm, ""));

parallelization-workflow/pom.xml

@@ -11,6 +11,7 @@
 
   <artifactId>agentic-patterns-parallelization-workflow</artifactId>
   <name>Agentic Patterns :: Parallelization Workflow</name>
+  <description>Parallelization Workflow agent</description>
 
   <properties>
     <maven.compiler.source>21</maven.compiler.source>

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/DirectAssembling.java

@@ -9,8 +9,8 @@
  * A {@linkplain ParallelizationWorkflowAgent} which directly assembles subtask execution results
  * without using LLM
  *
- * @param <Request>
- * @param <Response>
+ * @param <Request>  Task input type
+ * @param <Response> Task output type
  */
 public abstract class DirectAssembling<Request, Response> extends
     ParallelizationWorkflowAgent<Request, Response> {

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/ParallelizationWorkflowAgent.java

@@ -7,95 +7,26 @@
 import java.lang.reflect.Type;
 import java.time.Duration;
 import java.util.List;
-import java.util.Map;
-import java.util.Map.Entry;
-import java.util.Objects;
 import java.util.concurrent.CopyOnWriteArrayList;
-import java.util.concurrent.ExecutionException;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
-import java.util.concurrent.Future;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.TimeoutException;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.ai.chat.client.ChatClient;
 
+/**
+ * Parallelization Workflow agent, refer to <a
+ * href="https://javaaidev.com/docs/agentic-patterns/patterns/parallelization-workflow">doc</a>
+ *
+ * @param <Request>
+ * @param <Response>
+ */
 public abstract class ParallelizationWorkflowAgent<Request, Response> extends
     TaskExecutionAgent<Request, Response> {
 
-  public record SubtaskCreationRequest<Request>(
-      String taskId,
-      TaskExecutionAgent<?, ?> task,
-      Function<Request, ?> requestTransformer
-  ) {
-
-  }
-
-  public record TaskExecutionContext(
-      Future<?> job,
-      Duration maxWaitTime,
-      @Nullable Object result,
-      @Nullable Throwable error
-  ) {
-
-    public TaskExecutionContext(Future<?> job, Duration maxWaitTime) {
-      this(job, maxWaitTime, null, null);
-    }
-
-    public TaskExecutionContext collectResult() {
-      try {
-        var result = job().get(maxWaitTime().toSeconds(), TimeUnit.SECONDS);
-        return new TaskExecutionContext(job(), maxWaitTime(), result, null);
-      } catch (InterruptedException | ExecutionException | TimeoutException e) {
-        return new TaskExecutionContext(job(), maxWaitTime(), null, job().exceptionNow());
-      }
-    }
-  }
-
-  public record SubtaskContext<Request>(
-      SubtaskCreationRequest<Request> creationRequest,
-      @Nullable TaskExecutionContext taskExecutionContext
-  ) {
-
-    public static <Request, TaskRequest, TaskResponse> SubtaskContext<Request> create(String taskId,
-        TaskExecutionAgent<TaskRequest, TaskResponse> task,
-        Function<Request, TaskRequest> requestTransformer) {
-      return create(new SubtaskCreationRequest<>(taskId, task, requestTransformer));
-    }
-
-    public static <Request> SubtaskContext<Request> create(
-        SubtaskCreationRequest<Request> creationRequest) {
-      return new SubtaskContext<>(creationRequest, null);
-    }
-
-    public SubtaskContext<Request> taskStarted(Future<?> job, Duration maxWaitTime) {
-      return new SubtaskContext<>(this.creationRequest(),
-          new TaskExecutionContext(job, maxWaitTime));
-    }
-
-    public SubtaskContext<Request> collectResult() {
-      return new SubtaskContext<>(creationRequest(),
-          Objects.requireNonNull(taskExecutionContext(), "task execution context cannot be null")
-              .collectResult());
-    }
-
-    public String taskId() {
-      return creationRequest().taskId();
-    }
-
-    public @Nullable Object result() {
-      return taskExecutionContext() != null ? taskExecutionContext().result() : null;
-    }
-
-    public @Nullable Throwable error() {
-      return taskExecutionContext() != null ? taskExecutionContext().error() : null;
-    }
-  }
-
   public ParallelizationWorkflowAgent(ChatClient chatClient,
       @Nullable ObservationRegistry observationRegistry) {
     super(chatClient, observationRegistry);
@@ -111,40 +42,49 @@ public ParallelizationWorkflowAgent(ChatClient chatClient,
 
   private static final Logger LOGGER = LoggerFactory.getLogger(ParallelizationWorkflowAgent.class);
 
+  /**
+   * Add new subtask
+   *
+   * @param taskId             Task id
+   * @param subtask            Subtask implemented as {@linkplain TaskExecutionAgent}
+   * @param requestTransformer Transform request to task's input
+   * @param <TaskRequest>      Task input type
+   * @param <TaskResponse>     Task output type
+   */
   protected <TaskRequest, TaskResponse> void addSubtask(String taskId,
       TaskExecutionAgent<TaskRequest, TaskResponse> subtask,
       Function<Request, TaskRequest> requestTransformer) {
     subtasks.add(SubtaskContext.create(taskId, subtask, requestTransformer));
   }
 
+  /**
+   * Max duration of a subtask execution
+   *
+   * @return Max duration
+   */
   protected Duration getMaxTaskExecutionDuration() {
     return Duration.ofMinutes(3);
   }
 
+  /**
+   * Create a list of subtasks from request. Subtasks added by
+   * {@linkplain #addSubtask(String, TaskExecutionAgent, Function)} will be merged into this list.
+   *
+   * @param request Request
+   * @return Subtasks
+   */
   @Nullable
   protected List<SubtaskCreationRequest<Request>> createTasks(@Nullable Request request) {
     return List.of();
   }
 
-  public record PartialResult(@Nullable Object result, @Nullable Throwable error) {
-
-    public boolean hasResult() {
-      return result() != null;
-    }
-
-    public boolean hasError() {
-      return error() != null;
-    }
-  }
-
-  public record TaskExecutionResults(Map<String, PartialResult> results) {
-
-    public Map<String, Object> allSuccessfulResults() {
-      return results().entrySet().stream().filter(entry -> entry.getValue().hasResult())
-          .collect(Collectors.toMap(Entry::getKey, entry -> entry.getValue().result()));
-    }
-  }
-
+  /**
+   * Create the {@linkplain ExecutorService} to execute subtasks.
+   * <p>
+   * The default executor service uses virtual threads.
+   *
+   * @return executor service
+   */
   protected ExecutorService getTaskExecutorService() {
     var executor = Executors.newThreadPerTaskExecutor(
         Thread.ofVirtual().name("agent-task-", 1).factory());
@@ -170,7 +110,7 @@ protected TaskExecutionResults runSubtasks(@Nullable Request request) {
       LOGGER.info("All subtasks completed, assembling the results");
       var results = jobs.stream().map(SubtaskContext::collectResult)
           .collect(Collectors.toMap(SubtaskContext::taskId,
-              (task -> new PartialResult(task.result(), task.error())), (a, b) -> b));
+              (task -> new SubtaskResult(task.result(), task.error())), (a, b) -> b));
       return new TaskExecutionResults(results);
     }
   }

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/PromptBasedAssembling.java

@@ -7,6 +7,13 @@
 import org.jspecify.annotations.Nullable;
 import org.springframework.ai.chat.client.ChatClient;
 
+/**
+ * A {@linkplain ParallelizationWorkflowAgent} which uses an LLM to generate the final result using
+ * results from subtasks
+ *
+ * @param <Request>  Task input type
+ * @param <Response> Task output type
+ */
 public abstract class PromptBasedAssembling<Request, Response> extends
     ParallelizationWorkflowAgent<Request, Response> {
 
@@ -21,16 +28,28 @@ public PromptBasedAssembling(ChatClient chatClient,
     super(chatClient, responseType, observationRegistry);
   }
 
+  /**
+   * Get values for prompt template variables from results of subtasks
+   *
+   * @param results Subtask execution results
+   * @ Values of template variables
+   */
   protected abstract @Nullable Map<String, Object> getSubtasksPromptContext(
       TaskExecutionResults results);
 
-  protected @Nullable Map<String, Object> getParentPromptContext(@Nullable Request request) {
+  /**
+   * Get values for prompt template variables from request
+   *
+   * @param request Request
+   * @return Values of template variables
+   */
+  protected @Nullable Map<String, Object> getRequestPromptContext(@Nullable Request request) {
     return Map.of();
   }
 
   @Override
   protected @Nullable Map<String, Object> getPromptContext(@Nullable Request request) {
-    return AgentUtils.mergeMap(getParentPromptContext(request),
+    return AgentUtils.mergeMap(getRequestPromptContext(request),
         getSubtasksPromptContext(runSubtasks(request)));
   }
 

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/SubtaskContext.java

@@ -0,0 +1,55 @@
+package com.javaaidev.agenticpatterns.parallelizationworkflow;
+
+import com.javaaidev.agenticpatterns.taskexecution.TaskExecutionAgent;
+import java.time.Duration;
+import java.util.Objects;
+import java.util.concurrent.Future;
+import java.util.function.Function;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Subtask context for management
+ *
+ * @param creationRequest  Subtask creation request
+ * @param executionContext Subtask execution context
+ * @param <Request>        Request type
+ */
+public record SubtaskContext<Request>(
+    SubtaskCreationRequest<Request> creationRequest,
+    @Nullable SubtaskExecutionContext executionContext
+) {
+
+  public static <Request, TaskRequest, TaskResponse> SubtaskContext<Request> create(String taskId,
+      TaskExecutionAgent<TaskRequest, TaskResponse> task,
+      Function<Request, TaskRequest> requestTransformer) {
+    return create(new SubtaskCreationRequest<>(taskId, task, requestTransformer));
+  }
+
+  public static <Request> SubtaskContext<Request> create(
+      SubtaskCreationRequest<Request> creationRequest) {
+    return new SubtaskContext<>(creationRequest, null);
+  }
+
+  public SubtaskContext<Request> taskStarted(Future<?> job, Duration maxWaitTime) {
+    return new SubtaskContext<>(this.creationRequest(),
+        new SubtaskExecutionContext(job, maxWaitTime));
+  }
+
+  public SubtaskContext<Request> collectResult() {
+    return new SubtaskContext<>(creationRequest(),
+        Objects.requireNonNull(executionContext(), "task execution context cannot be null")
+            .collectResult());
+  }
+
+  public String taskId() {
+    return creationRequest().taskId();
+  }
+
+  public @Nullable Object result() {
+    return executionContext() != null ? executionContext().result() : null;
+  }
+
+  public @Nullable Throwable error() {
+    return executionContext() != null ? executionContext().error() : null;
+  }
+}

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/SubtaskCreationRequest.java

@@ -0,0 +1,20 @@
+package com.javaaidev.agenticpatterns.parallelizationworkflow;
+
+import com.javaaidev.agenticpatterns.taskexecution.TaskExecutionAgent;
+import java.util.function.Function;
+
+/**
+ * Request to create a subtask
+ *
+ * @param taskId             Task id
+ * @param task               Task, see {@linkplain TaskExecutionAgent}
+ * @param requestTransformer Transform request to task inpu
+ * @param <Request>          Request type
+ */
+public record SubtaskCreationRequest<Request>(
+    String taskId,
+    TaskExecutionAgent<?, ?> task,
+    Function<Request, ?> requestTransformer
+) {
+
+}

parallelization-workflow/src/main/java/com/javaaidev/agenticpatterns/parallelizationworkflow/SubtaskExecutionContext.java

@@ -0,0 +1,37 @@
+package com.javaaidev.agenticpatterns.parallelizationworkflow;
+
+import java.time.Duration;
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.Future;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Task execution context
+ *
+ * @param job         Job
+ * @param maxWaitTime Max wait time for the task to finish
+ * @param result      Successful result
+ * @param error       error
+ */
+public record SubtaskExecutionContext(
+    Future<?> job,
+    Duration maxWaitTime,
+    @Nullable Object result,
+    @Nullable Throwable error
+) {
+
+  public SubtaskExecutionContext(Future<?> job, Duration maxWaitTime) {
+    this(job, maxWaitTime, null, null);
+  }
+
+  public SubtaskExecutionContext collectResult() {
+    try {
+      var result = job().get(maxWaitTime().toSeconds(), TimeUnit.SECONDS);
+      return new SubtaskExecutionContext(job(), maxWaitTime(), result, null);
+    } catch (InterruptedException | ExecutionException | TimeoutException e) {
+      return new SubtaskExecutionContext(job(), maxWaitTime(), null, job().exceptionNow());
+    }
+  }
+}