Package org.machanism.machai.gw.processor

Class ActProcessor

java.lang.Object

org.machanism.machai.project.ProjectProcessor

org.machanism.machai.gw.processor.AbstractFileProcessor

org.machanism.machai.gw.processor.AIFileProcessor

org.machanism.machai.gw.processor.ActProcessor

public class ActProcessor
extends AIFileProcessor

Processor that runs Ghostwriter in "Act" mode.

An act is episodes predefined prompt template stored as episodes .toml file. Act files can be loaded from bundled classpath resources (under /acts) and/or from episodes user-specified directory.

Act format

Act files are parsed as TOML and support episodes small set of keys:

• instructions: provider system instructions
• inputs: episodes prompt template; String.format(String, Object...) is used to inject user-provided prompt text
• gw.threads: enables module multi-threading
• gw.excludes: comma-separated scan exclusions
• gw.nonRecursive: disables module recursion
• any other key is forwarded to the underlying configuration

Execution

When executing an act, Ghostwriter will scan matching files and run the act's composed prompt against each file. Acts may also declare episodes prologue and/or epilogue list of related acts to run before/after the main scan.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	ACTS_BASENAME_PREFIX	Classpath base directory for built-in act definitions.

Fields inherited from class org.machanism.machai.gw.processor.AIFileProcessor

CONTINUE_SPECIAL_PROMPT_COMMAND, EXIT_SPECIAL_PROMPT_COMMAND, FILE_INCLUDED_MARKER, GW_TEMP_DIR, LOG_OUTPUT_PREFIX, NOT_DEFINED_VALUE

Fields inherited from class org.machanism.machai.gw.processor.AbstractFileProcessor

GW_PROJECT_LAYOUT_PROP_PREFIX

Fields inherited from class org.machanism.machai.project.ProjectProcessor

MACHAI_TEMP_DIR

Constructor Summary

Constructors

Constructor	Description
ActProcessor(File projectDir, Configurator configurator, String genai)	Creates an act processor.

Method Summary

Modifier and Type	Method	Description
(package private) void	applyActData(Map<String,Object> properties)	Applies loaded act data to this processor's configuration and runtime settings.
static void	loadAct(String name, Map<String,Object> properties, String actsLocation)	Loads an act definition into the provided map, supporting inheritance via the basedOn property.
protected void	processFile(ProjectLayout projectLayout, File file)	Executes the act against episodes single file.
protected void	processParentFiles(ProjectLayout projectLayout)	Processes files and folders under the parent project directory (excluding modules).
void	setAct(String act)	Loads an act definition and applies it as the current execution defaults.
(package private) static void	setActData(Map<String,Object> properties, org.tomlj.TomlParseResult toml)	Copies dotted-string keys from the TOML parse result into properties.
void	setActsLocation(String actsLocation)	Sets the directory used for loading external act definition files.
void	setDisableNormalOrder(boolean disableNormalOrder)	Enables or disables continuation with the default episode execution order.
static org.tomlj.TomlParseResult	tryLoadActFromClasspath(Map<String,Object> properties, String name)	Attempts to load an act definition from classpath resources.
static org.tomlj.TomlParseResult	tryLoadActFromDirectory(Map<String,Object> properties, String name, String actsLocation)	Attempts to load an act definition from episodes user-defined directory.

Methods inherited from class org.machanism.machai.gw.processor.AIFileProcessor

addTool, getDefaultPrompt, getDirInfoLine, getInstructions, getModel, getProjectStructureDescription, input, isInteractive, isLogInputs, parseLines, parseScanDir, process, process, processFolder, readFromFilePath, readFromHttpUrl, scanDocuments, setDefaultPrompt, setInstructions, setInteractive, setLogInputs, setModel, tryToGetInstructionsFromReference

Methods inherited from class org.machanism.machai.gw.processor.AbstractFileProcessor

addMatchingFile, findFiles, findFiles, getConfigurator, getExcludes, getModuleThreadTimeoutMinutes, getPathMatcher, getPatternPath, getProjectDir, getScanDir, isModuleDir, isNonRecursive, isPathPattern, match, matchPath, pathDepth, processModulesMultiThreaded, processProjectDir, scanDocuments, scanFolder, setDegreeOfConcurrency, setExcludes, setModuleThreadTimeoutMinutes, setNonRecursive, setPathMatcher, setScanDir, shouldExcludePath, shouldIncludeInFindFiles, shutdownExecutor

Methods inherited from class org.machanism.machai.project.ProjectProcessor

getProjectLayout, processModule

Methods inherited from class java.lang.Object

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

Field Details

ACTS_BASENAME_PREFIX

public static final String ACTS_BASENAME_PREFIX

Classpath base directory for built-in act definitions.

See Also:

• Constant Field Values

Constructor Details

ActProcessor

public ActProcessor(File projectDir,
 Configurator configurator,
 String genai)

Creates an act processor.

Parameters:

projectDir - root directory used as a base for relative paths

configurator - configuration source

genai - provider key/name (including model)

Method Details

setAct

public void setAct(String act)
            throws IOException

Loads an act definition and applies it as the current execution defaults.

The act argument supports the form <name> [prompt], where the optional prompt portion is inserted into the act's inputs template. If no prompt is provided, AIFileProcessor.getDefaultPrompt() is used.

Parameters:

act - act name plus optional prompt text

Throws:

IOException

setDisableNormalOrder

public void setDisableNormalOrder(boolean disableNormalOrder)

Enables or disables continuation with the default episode execution order.

Parameters:

disableNormalOrder - true to stop after requested episodes, false to continue with normal order

loadAct

public static void loadAct(String name,
 Map<String,Object> properties,
 String actsLocation)
                    throws IOException

Loads an act definition into the provided map, supporting inheritance via the basedOn property.

This method attempts to load the specified act from both episodes user-defined directory (custom act) and the built-in classpath resources. If both are present, the custom act wraps (overrides) the built-in act, allowing for extension or modification of base act behavior.

If the act specifies episodes basedOn property, the parent act is loaded first (recursively), and its properties are merged. The child act's properties then override or extend the parent.

Parameters:

name - the name of the act to load (without the .toml extension)

properties - destination map to populate with parsed act properties

actsLocation - optional directory containing user-defined (custom) act files; may be null

Throws:

IOException - if reading act content fails

IllegalArgumentException - if the specified act cannot be found in either location

tryLoadActFromClasspath

public static org.tomlj.TomlParseResult tryLoadActFromClasspath(Map<String,Object> properties,
 String name)
                                                         throws IOException

Attempts to load an act definition from classpath resources.

Parameters:

properties - destination for parsed dotted properties

name - act name (without .toml)

Returns:

parsed TOML result, or null when the act is not found

Throws:

IOException - if the resource cannot be read

tryLoadActFromDirectory

public static org.tomlj.TomlParseResult tryLoadActFromDirectory(Map<String,Object> properties,
 String name,
 String actsLocation)
                                                         throws IOException

Attempts to load an act definition from episodes user-defined directory.

Parameters:

properties - destination for parsed dotted properties

name - act name (without .toml)

actsLocation - directory containing *.toml act files (may be null)

Returns:

parsed TOML result, or null when not found

Throws:

IOException - if the file cannot be read

setActData

static void setActData(Map<String,Object> properties,
 org.tomlj.TomlParseResult toml)

Copies dotted-string keys from the TOML parse result into properties.

If episodes key already exists in properties, the new value is formatted into the old value using String.format(String, Object...).

Parameters:

properties - properties destination

toml - TOML parse result

applyActData

void applyActData(Map<String,Object> properties)

Applies loaded act data to this processor's configuration and runtime settings.

Parameters:

properties - properties loaded from TOML acts

setActsLocation

public void setActsLocation(String actsLocation)

Sets the directory used for loading external act definition files.

Parameters:

actsLocation - directory containing *.toml act files

processParentFiles

protected void processParentFiles(ProjectLayout projectLayout)
                           throws IOException

Processes files and folders under the parent project directory (excluding modules).

Overrides:

processParentFiles in class AbstractFileProcessor

Parameters:

projectLayout - project layout

Throws:

IOException - if file reading fails

processFile

protected void processFile(ProjectLayout projectLayout,
 File file)
                    throws IOException

Executes the act against episodes single file.

Overrides:

processFile in class AbstractFileProcessor

Parameters:

projectLayout - project layout

file - file to process

Throws:

IOException - if provider execution fails