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

This implementation integrates with the ProcessProvider 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. Asynchronous reports are serialized below the application temporary directory and can be retrieved with the process identifier returned when processing starts.

Author:
Viktor Tovstyi

  • Field Details

    • logger

      private static final org.slf4j.Logger logger
      Logger used to report asynchronous guidance-processing failures.

    • GUIDANCE_FOLDER

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

    • PROCESS_ID_KEY

      private static final String PROCESS_ID_KEY
      Response-map key for an asynchronous guidance execution identifier.
      See Also:

    • STATUS_KEY

      private static final String STATUS_KEY
      Response-map key for an asynchronous guidance execution status.
      See Also:

    • mcpPromptBundle

      final ResourceBundle mcpPromptBundle
      Resource bundle that supplies prompt templates exposed through Prompt methods in this tool provider.

  • Constructor Details

    • GuidanceFunctionTools

      public GuidanceFunctionTools()
      Creates a guidance function-tools provider using the default prompt resource bundle.

  • Method Details

    • getGuidanceTaggedFiles

      public Map<File,List<File>> getGuidanceTaggedFiles(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:
      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 absolute path to the root project directory or a folder containing multiple projects. All scanning operations are performed relative to this directory.
      configurator - The configuration object used to resolve the configured model for scanning operations.
      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.

    • saveGuidanceResult

      private void saveGuidanceResult(GuidanceProcessor processor, File projectDir, String path, File tempFile)
      Runs guidance processing in the background and persists its report.

      Any failure is logged because this method runs outside the caller's execution context; callers observe an unavailable result until a report is written.

      Parameters:
      processor - configured guidance processor
      projectDir - project directory to scan
      path - scan path or pattern
      tempFile - file that receives the serialized report

    • writeGuidanceResult

      private void writeGuidanceResult(File tempFile, List<Map<String,Object>> result) throws IOException
      Serializes a guidance-processing report to its temporary result file.
      Parameters:
      tempFile - destination temporary file; its parent directory must exist
      result - report to serialize, including the outcome for every processed file
      Throws:
      IOException - if the report cannot be written

    • processGuidanceTagFiles

      public Object processGuidanceTagFiles(String instructions, Map<String,String> properties, String path, boolean async, File projectDir, 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:
      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}".
      projectDir - The project directory in which to scan for files. The directory must be readable by the process.
      config - The configuration object for property resolution and default values. It is layered with the supplied properties.
      Returns:
      In asynchronous mode, a map containing the unique process_id and a status of "processing"; in synchronous mode, the complete guidance-processing report.
      Throws:
      IOException - If there is an error scanning files or initializing the processing configuration.

    • getProcessGuidanceTagFilesResult

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

      This method reconstructs the path to the temporary file where the result was stored, using the provided process identifier 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 process identifier returned when processing was started; used to identify the result file.
      Returns:
      A map containing the provided process_id, a status, and either the completed result or a message when the result is not yet available.
      Throws:
      IOException - If there is an error reading the result from the temp file.

    • getGuidancePrompt

      public String getGuidancePrompt(String path, File projectDir)
      Provides the prompt template used to process files containing guidance tags.

      The returned template is resolved from the mcp-prompts resource bundle and is intended for use by the guidance-tag processing workflow.

      Parameters:
      path - The scanning path or pattern used to select files. The value is accepted for the prompt contract and is resolved by its caller.
      projectDir - The root folder of the project, or the parent folder containing projects to scan. The value is accepted for the prompt contract and is resolved by its caller.
      Returns:
      The prompt template for processing files with guidance tags.