Package org.machanism.machai.gw.tools

Class GuidanceFunctionTools

java.lang.Object
org.machanism.machai.gw.tools.GuidanceFunctionTools
All Implemented Interfaces:
FunctionTools
public class GuidanceFunctionTools extends Object implements FunctionTools
Provides function tools for discovering and processing files with guidance tags in project directories.

This class registers tools for:

  • Scanning project directories to find files annotated with guidance tags
  • Processing those files using a configured model, either synchronously or asynchronously
  • Retrieving the results of asynchronous processing by process ID
  • Supplying prompt templates for guidance tag processing

GuidanceFunctionTools integrates with the Genai provider and supports both custom and built-in project workflows. It manages asynchronous execution and result retrieval 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 involving guidance tags.

Author:
Viktor Tovstyi

  • Constructor Details

    • GuidanceFunctionTools

      public GuidanceFunctionTools()

  • Method Details

    • getGuidanceTaggedFiles

      public Map<File,List<File>> getGuidanceTaggedFiles(String rootDir, String path, File projectDir, Configurator configurator) throws IOException
      Scans the specified directory and its subdirectories for files annotated with guidance tags, returning a mapping of project directories to the files that contain such tags.

      The scan is performed relative to the provided root directory and can be filtered using a path or pattern (such as glob or regex). Each discovered file with a guidance tag is grouped under its corresponding project directory in the returned map.

      Parameters:
      rootDir - The absolute path to the root project directory or a folder containing multiple projects. All scanning operations are performed relative to this directory.
      path - Specifies the scanning path or pattern. Use a relative path with respect to the current project directory. If an absolute path is provided, it must be located within the root project directory. Supported patterns: raw directory names, glob patterns (e.g., "glob:*.java"), or regex patterns (e.g., "regex:^.java$"). Default: "glob:*.*"
      projectDir - The project directory to use as the working directory for scanning operations.
      configurator - The configuration object.
      Returns:
      A map where each key is a project directory and each value is a list of files with guidance tags found in that directory.
      Throws:
      IOException - if an I/O error occurs during scanning.

    • processGuidanceTagFiles

      public Object processGuidanceTagFiles(File projectDir, Map<String,String> properties, String path, boolean async, Configurator config) throws IOException
      Asynchronously processes files with guidance tags using the configured model.

      Scans the files in the specified project_dir (and optionally matching the given path pattern) and applies guidance processing to each file found. The processing is performed in a background thread. The method returns immediately with a response containing a unique process ID and a status of "processing". The actual result is serialized to a temporary file for later retrieval using the process ID.

      Parameters:
      projectDir - The project directory in which to scan for files.
      properties - Optional map of Act properties, such as configuration overrides or parameters for the guidance processing. If null, only the main configuration is used.
      path - Specifies the scanning path or pattern. Use a relative path with respect to the current project directory. If an absolute path is provided, it must be located within the root project directory. Supported patterns: raw directory names, glob patterns (e.g., "glob:**.java"), or regex patterns (e.g., "regex:^.[^/]+\\.java$"). Default: "${project_dir}".
      config - The configuration object for property resolution and default values.
      Returns:
      A map containing:
      • process_id: The unique identifier for the asynchronous operation.
      • status: "processing" to indicate the operation is running asynchronously.
      Throws:
      IOException - If there is an error initializing the processor or creating the temp file.

    • getProcessGuidanceTagFilesResult

      public Object getProcessGuidanceTagFilesResult(String processId) throws IOException
      Retrieves the result of a previously started guidance tag file processing by its GUID.

      This method reconstructs the path to the temporary file where the result was stored, using the provided GUID and the system's temporary directory. If the result file exists, it reads and returns the result. If the file does not exist, it returns a status indicating that the result is still processing or unavailable.

      Parameters:
      processId - The GUID returned when the processing was started. Used to identify the result file.
      Returns:
      A map containing:
      • guid: The provided GUID.
      • status: "done" if the result is available, "processing" otherwise.
      • result: The list of file and guidance tag entries if available.
      • message: An informational message if the result is not ready.
      Throws:
      IOException - If there is an error reading the result from the temp file.

    • getGuidancePrompt

      public String getGuidancePrompt(String projectDir, String path)