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 Summary

Fields

Modifier and Type	Field	Description
private static final String	ACT_FOLDER_NAME
private static final org.slf4j.Logger	logger	Logger for shell tool execution and diagnostics.
(package private) final ResourceBundle	mcpPromptBundle	Resource bundle supplying prompt templates for generators.

Constructor Summary

Constructors

Constructor	Description
ActFunctionTools()

Method Summary

Modifier and Type	Method	Description
String	actPrompts(String actName)	AI prompt template that instructs the caller to execute an Act identified by name.
Object	getActDetails(String actName, File projectDir, Configurator configurator)	AI functional tool that loads the details of a specific Act template, including its instructions, input template, and configuration options.
Object	getActResult(String processId)	AI functional tool that retrieves the result of a previously started Act by its GUID.
private String	getFileName(String processId)
Object	performAct(String actName, File projectDir, Map<String,String> properties, boolean async, Configurator config)	AI functional tool that performs the specified Act by name.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

ACT_FOLDER_NAME

private static final String ACT_FOLDER_NAME

See Also:

• Constant Field Values

logger

private static final org.slf4j.Logger logger

Logger for shell tool execution and diagnostics.

mcpPromptBundle

final ResourceBundle mcpPromptBundle

Resource bundle supplying prompt templates for generators.

Constructor Details

ActFunctionTools

public ActFunctionTools()

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, or a message indicating that the Act was not found.

Throws:

IOException - If an error occurs while loading an Act definition.

performAct

public Object performAct(String actName,
 File projectDir,
 Map<String,String> properties,
 boolean async,
 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.

projectDir - The project directory where the Act will be executed.

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.

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)

getActResult

public Object getActResult(String processId)
                    throws IOException

AI functional tool that retrieves the result of a previously started Act by its GUID.

This method reconstructs the path to the temporary file where the Act 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 Act 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 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 temp file.

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.