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 String	CONTEXT_VARIABLE_PREFIX	Prefix shared by status messages that identify a context variable.
private static final Map<File,Map<String,Object>>	contextProjectMap	Thread-safe registry that associates each project directory with its mutable context-variable map.

Constructor Summary

Constructors

Constructor	Description
ProjectContextFunctionTools()

Method Summary

Modifier and Type	Method	Description
static Map<String,Object>	getProjectContextVariables(List<String> names, 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 project context variable to save and share data between acts.

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

Thread-safe registry that associates each project directory with its mutable context-variable map. Individual maps are also used as synchronization locks for compound operations on their values.

CONTEXT_VARIABLE_PREFIX

private static final String CONTEXT_VARIABLE_PREFIX

Prefix shared by status messages that identify a context variable.

See Also:

• Constant Field Values

Constructor Details

ProjectContextFunctionTools

public ProjectContextFunctionTools()

Method Details

putProjectContextVariable

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

Sets or updates a project context variable to save and share data between acts.

This method stores or updates a named variable in a special project-specific data holder associated with a particular project directory. It is used to share state between different steps, episodes, or acts in a workflow. Note: This is for workflow state sharing only and cannot be used to set environment variables.

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.

getProjectContextVariables

public static Map<String,Object> getProjectContextVariables(List<String> names,
 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:

names - The names of the context variables to retrieve.

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

Returns:

A map containing an entry for every requested name. Entries whose variables are absent have a null value.

Throws:

IllegalArgumentException - If no context has been created for projectDir.

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 success message, or an error message if the operation fails or the existing variable has an unsupported type.

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 context or variable does not exist, the list is empty, the variable type is unsupported, or an error occurs.