Package org.machanism.machai.gw.tools

Class ActFunctionTools

java.lang.Object
org.machanism.machai.gw.tools.ActFunctionTools
All Implemented Interfaces:
FunctionTools
public class ActFunctionTools extends Object implements FunctionTools
Provides function tools for managing and executing Ghostwriter Acts within a project.

This class exposes methods for:

  • Loading Act template details (including instructions, input templates, and configuration options)
  • Asynchronously performing an Act and storing the result for later retrieval
  • Retrieving the result of a previously started Act by process ID
  • Supplying prompt templates for Act execution

Acts are reusable, named workflows or actions defined in the project or classpath. This class supports both custom and built-in Act definitions, and handles asynchronous execution and result management using temporary files and process IDs.

Methods in this class are typically invoked by an AI provider or workflow engine to enable dynamic, tool-augmented project automation.

Author:
Viktor Tovstyi

  • Field Details

    • ACT_FOLDER_NAME

      private static final String ACT_FOLDER_NAME
      Directory below the runtime temporary directory that stores Act results.
      See Also:

    • STATUS_KEY

      private static final String STATUS_KEY
      Response-map key that identifies the asynchronous Act execution status.
      See Also:

    • logger

      private static final org.slf4j.Logger logger
      Logger for Act execution lifecycle events and diagnostics.

    • mcpPromptBundle

      final ResourceBundle mcpPromptBundle
      Resource bundle that supplies MCP prompt templates for Act execution.

  • Constructor Details

    • ActFunctionTools

      public ActFunctionTools()
      Creates an Act-function tool and initializes its MCP prompt-template bundle.

  • Method Details

    • getActDetails

      public Object getActDetails(String actName, File projectDir, Configurator configurator) throws IOException
      AI functional tool that loads the details of a specific Act template, including its instructions, input template, and configuration options. It searches both project-specific and built-in Act definitions and reports the matching definitions to the caller.
      Parameters:
      actName - The name of the Act to load.
      projectDir - The project directory containing custom Act definitions.
      configurator - The configuration used to locate custom Act definitions.
      Returns:
      A map containing the matching custom and/or built-in Act details.
      Throws:
      IOException - If an error occurs while loading an Act definition.
      FileNotFoundException - If no custom or built-in definition matches the requested Act name.

    • saveAsyncActResult

      private void saveAsyncActResult(ActProcessor actProcessor, File projectDir, String path, String actName, File tempFile)
      Runs an Act in the background and persists its result for later polling.
      Parameters:
      actProcessor - processor configured for the Act
      projectDir - project directory to scan
      path - scan path supplied to the processor
      actName - Act name used in completion logging
      tempFile - file that receives the serialized result
      Throws:
      IllegalArgumentException - If the result file cannot be created or written.

    • logActCompletion

      private void logActCompletion(String actName)
      Writes the Act completion banner when INFO logging is enabled.
      Parameters:
      actName - completed Act name; used in the lifecycle log message

    • performAct

      public Object performAct(String actName, Map<String,String> properties, boolean async, File projectDir, Configurator config) throws IOException
      AI functional tool that performs the specified Act by name.

      Use this tool to trigger a predefined action or workflow identified by the given Act name. This method supports both synchronous and asynchronous execution modes based on the async parameter.

      Parameters:
      actName - The name of the Act to perform.
      properties - Act properties to override default configuration values; may be null.
      async - If true, the Act will be executed asynchronously, and the method will return immediately with a process ID. If false, the Act will be executed synchronously, and the method will return the Act's result.
      projectDir - The project directory where the Act will be executed.
      config - The configuration object.
      Returns:
      A response object containing the Act's result (for synchronous execution) or a process ID and status (for asynchronous execution).
      Throws:
      IOException - If an error occurs during Act processing.

    • getFileName

      private String getFileName(String processId)
      Builds the project-temporary relative file name for an Act result.
      Parameters:
      processId - asynchronous execution identifier
      Returns:
      result file name relative to the temporary directory

    • getActResult

      public Map<String,Object> getActResult(String processId) throws IOException, ClassNotFoundException
      AI functional tool that retrieves the result of a previously started Act by its process identifier.

      This method reconstructs the path to the temporary file where the Act result was stored, using the provided process identifier and the project's temporary directory. If the result file has been created but is still being written, it returns a processing status. Once the serialized result is available, it returns a completed status and the result. A missing result file causes a FileNotFoundException.

      Parameters:
      processId - The process identifier returned when the Act was started and used to identify the result file.
      Returns:
      A map containing:
      • status: "done" if the result is available, "processing" otherwise.
      • result: The Act result object if available.
      • message: An informational message if the result is not ready.
      Throws:
      IOException - If there is an error reading the result from the temporary file.
      ClassNotFoundException - If the serialized result contains an unavailable class.

    • actPrompts

      public String actPrompts(String actName)
      AI prompt template that instructs the caller to execute an Act identified by name. The returned template is resolved from the MCP prompt resource bundle.
      Parameters:
      actName - The name of the Act to perform.
      Returns:
      The prompt template used to perform the Act. The template is loaded from the process_act resource-bundle entry.