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

Constructor Summary

Constructors

Constructor	Description
ActFunctionTools()

Method Summary

Modifier and Type	Method	Description
String	actPrompts(String actName)
Object	getActDetails(String actName, File projectDir, Configurator configurator)	Loads the details of a specific Act template, including instructions, input template, and configuration options.
Object	getActResult(String processId)	Retrieves the result of a previously started Act by its GUID.
Object	performAct(String actName, File projectDir, Map<String,String> properties, boolean async, Configurator config)	Performs the specified Act by name.

Methods inherited from class java.lang.Object

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

Constructor Details

ActFunctionTools

public ActFunctionTools()

Method Details

getActDetails

public Object getActDetails(String actName,
 File projectDir,
 Configurator configurator)
                     throws IOException

Loads the details of a specific Act template, including instructions, input template, and configuration options.

Parameters:

configurator -

Throws:

IOException

performAct

public Object performAct(String actName,
 File projectDir,
 Map<String,String> properties,
 boolean async,
 Configurator config)
                  throws IOException

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.

getActResult

public Object getActResult(String processId)
                    throws IOException

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)