Package org.machanism.machai.gw.tools

Class ProjectContextFunctionTools

java.lang.Object

org.machanism.machai.gw.tools.ProjectContextFunctionTools

All Implemented Interfaces:

FunctionTools

public class ProjectContextFunctionTools
extends Object
implements FunctionTools

Provides function tools for managing project-specific context variables.

This class registers tools for setting, retrieving, pushing, and popping variables in a project context, enabling stateful data sharing across acts and episodes.

Note: This class is fully thread-safe. All compound state checks, mutations, and collection updates are synchronized on the individual project context map instance to prevent race conditions and concurrent modifications.

Author:

Viktor Tovstyi

Field Summary

Fields

Modifier and Type	Field	Description
private static final Map<File,Map<String,Object>>	contextProjectMap	Map of project directories to their context variable maps.

Constructor Summary

Constructors

Constructor	Description
ProjectContextFunctionTools()

Method Summary

Modifier and Type	Method	Description
static String	getProjectContextVariable(String name, File projectDir)	Retrieves the value of a variable from the project-specific context.
static Object	popProjectContextVariable(String name, String mode, File projectDir)	Removes and returns a value from a project context variable.
static Object	pushProjectContextVariable(String name, String value, File projectDir)	Pushes a value to a project context variable.
static void	put(File projectDir, String name, Object value)	Sets or updates a variable in the context map for the specified project directory.
static String	putProjectContextVariable(String name, String value, File projectDir)	Sets or updates a variable in the project-specific context.

Methods inherited from class java.lang.Object

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

Field Details

contextProjectMap

private static final Map<File,Map<String,Object>> contextProjectMap

Map of project directories to their context variable maps.

Constructor Details

ProjectContextFunctionTools

public ProjectContextFunctionTools()

Method Details

putProjectContextVariable

public static String putProjectContextVariable(String name,
 String value,
 File projectDir)

Sets or updates a variable in the project-specific context.

This method stores or updates a named variable associated with a particular project directory, making it available for act execution or prompt templates. It can be used to pass a variable to the next episode of an act or to share state between different steps in a workflow. As an AI functional tool, it exposes project-context state management to an AI workflow.

Parameters:

name - The name of the context variable to set or update.

value - The value to assign to the context variable.

projectDir - The project directory with which the context variable is associated.

Returns:

A message indicating whether the context variable was successfully set or if an error occurred.

put

public static void put(File projectDir,
 String name,
 Object value)
                throws com.fasterxml.jackson.core.JsonProcessingException

Sets or updates a variable in the context map for the specified project directory.

If the value is a String, it is stored as-is. Otherwise, the value is serialized to a JSON string using Jackson's ObjectMapper before being stored. The variable is associated with the given name and made available in the context for the specified projectDir.

This method ensures thread safety by synchronizing the mutation block on the target project's context map instance.

Parameters:

projectDir - The project directory with which the context variable is associated.

name - The name of the context variable to set or update.

value - The value to assign to the context variable; if not a string, it will be serialized to JSON.

Throws:

com.fasterxml.jackson.core.JsonProcessingException - If the value cannot be serialized to JSON.

getProjectContextVariable

public static String getProjectContextVariable(String name,
 File projectDir)

Retrieves the value of a variable from the project-specific context.

This method accesses a named variable associated with a particular project directory, making it available for act execution or prompt templates. If the context or variable does not exist, an appropriate message is returned. As an AI functional tool, it exposes project-context lookup to an AI workflow.

This method synchronizes on the target project's context map to ensure that reading a list-type variable is thread-safe and never yields a partially-modified state.

Parameters:

name - The name of the context variable to retrieve.

projectDir - The project directory with which the context variable is associated.

Returns:

The value of the context variable if found, a message indicating that the variable or context was not found, or an error message if retrieval fails.

pushProjectContextVariable

public static Object pushProjectContextVariable(String name,
 String value,
 File projectDir)

Pushes a value to a project context variable.

If the variable does not exist, a new list is created and the value is added. If the variable exists and is a string, it is converted to a list containing the original string and the new value. If the variable exists and is already a list, the new value is appended to the list. If the variable exists and is of any other type, an error message is returned. As an AI functional tool, it exposes stack-like context updates to an AI workflow.

This operation is atomic and synchronized on the target project's context map.

Parameters:

name - The name of the context variable.

value - The value to push to the context variable.

projectDir - The project directory with which the context variable is associated.

Returns:

A message indicating the result of the operation, or an error message if the operation fails or the variable type is unsupported.

popProjectContextVariable

public static Object popProjectContextVariable(String name,
 String mode,
 File projectDir)

Removes and returns a value from a project context variable.

If the variable is a string, it is removed from the context and returned. If the variable is a list, a value is removed and returned according to the specified mode:

• LIFO (last-in, first-out, default): removes and returns the last element in the list.
• FIFO (first-in, first-out): removes and returns the first element in the list.

If the list becomes empty after removal, the variable is removed from the context. If the list is reduced to a single element, it is converted back to a string for simplicity. If the variable does not exist or is of an unsupported type, an appropriate message is returned. As an AI functional tool, it exposes context-value removal to an AI workflow.

This operation is atomic and synchronized on the target project's context map.

Parameters:

name - The name of the context variable.

mode - Pop mode, either "LIFO" (default) or "FIFO".

projectDir - The project directory with which the context variable is associated.

Returns:

The removed value, or a message if the variable does not exist, is empty, or is of an unsupported type, or if an error occurs.